TiffImageView class

A pannable, zoomable view of one page of a TIFF/BigTIFF file of any size — the counterpart to package:svs's SvsImageView.

Only the tiles needed for the current viewport and zoom are decoded, and decoded tiles are kept in a byte-bounded LRU cache (cacheBytes):

  • The page's own pyramid (every other page that is a smaller copy of page pageIndex) and, optionally, a sidecar of extra rungs (pyramidLevelsPath) are used, always loading only the one rung that matches the zoom. Rungs already cached — or a box-filtered overview — are painted underneath while it loads, so zooming sharpens a preview instead of flashing blank.
  • A zoomed-out view of a page with too shallow a pyramid loads composites of many tiles, downscaled in the worker, so the tile count and texture memory follow the screen size rather than the page size.
  • A strip-organized page is served as strip-aligned bands, so no strip is decompressed more often than it has to be.
  • Painting happens in screen space and visits only on-screen tiles.

The view state lives in a TransformationController (controller, or an internal one) holding a uniform scale plus translation: image point p shows at screen point p * scale + translation. Read it to build overlays (a scale bar, a zoom readout), or set it to navigate — TiffMinimap works with it directly.

Two ways to open the file:

  • TiffImageView.new takes a filePath and decodes on a pool of background isolates, each reading the file with dart:io — native platforms only.
  • TiffImageView.source takes a TiffAsyncByteSource and decodes on the current isolate, loading only what the view needs — on the web, a file picked by the user (BlobByteSource) or one on a server (HttpRangeByteSource) from package:tiff/tiff_web.dart, of any size. Decoding is split into short steps between frames, and JPEG tiles go to the browser's own decoder, so the page stays responsive — but a heavily compressed, non-JPEG page loads slower than on isolates.

Needs bounded constraints (e.g. a SizedBox or Expanded).

Inheritance

Constructors

TiffImageView({Key? key, required String filePath, int pageIndex = 0, String? pyramidLevelsPath, void setUpIsolate()?, TransformationController? controller, TiffImageViewStart initialView = TiffImageViewStart.fit, double maxScale = 40, double maxUpsample = 1.3, double brightness = 0, double contrast = 1, double gamma = 1, int cacheBytes = 256 * 1024 * 1024, int? workerCount, bool showMinimap = true, bool showLoadingIndicator = true, Color backgroundColor = const Color(0xFFE0E0E0), ValueChanged<Object>? onError})
Shows page pageIndex of the file at filePath, decoded on worker isolates — native platforms only (see the class doc comment).
const
TiffImageView.source({Key? key, required TiffAsyncByteSource source, int pageIndex = 0, TiffAsyncByteSource? pyramidLevelsSource, void setUpIsolate()?, TransformationController? controller, TiffImageViewStart initialView = TiffImageViewStart.fit, double maxScale = 40, double maxUpsample = 1.3, double brightness = 0, double contrast = 1, double gamma = 1, int cacheBytes = 256 * 1024 * 1024, int? workerCount, bool showMinimap = true, bool showLoadingIndicator = true, Color backgroundColor = const Color(0xFFE0E0E0), ValueChanged<Object>? onError})
Shows page pageIndex of the file source reads, decoded on the current isolate and loaded piece by piece — works on every platform, including the web (see the class doc comment).
const

Properties

backgroundColor → Color
Fills everything not covered by image pixels.
final
brightness → double
Brightness/contrast/gamma applied to every decoded pixel — see ImageAdjustments.apply. Changing them re-decodes what's on screen; the old pixels stay visible until the new ones arrive.
final
cacheBytes → int
Decoded-pixel byte budget of the tile cache.
final
contrast → double
See brightness.
final
controller → TransformationController?
Holds the view transform; see the class doc comment. Left null, the view owns one internally.
final
filePath → String?
Path of the TIFF/BigTIFF file. Every worker isolate opens its own handle on it. Null for a view made with TiffImageView.source.
final
gamma → double
See brightness.
final
hashCode → int
The hash code for this object.
no setterinherited
initialView → TiffImageViewStart
Which part of the page the view opens on.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
maxScale → double
Screen pixels per base pixel the user may zoom in to.
final
maxUpsample → double
How far a rung's texels may be stretched on screen before the next, sharper rung is loaded instead.
final
onError → ValueChanged<Object>?
Called when the file can't be opened or shown. Nothing is painted in that case besides backgroundColor.
final
pageIndex → int
The page to show — its full-resolution base rung.
final
pyramidLevelsPath → String?
Optional sidecar TIFF whose pages are extra, smaller rungs of the page — e.g. the output of TiffDisplayOptimizer.optimizeLargeSourcePyramidLevels for a page with no pyramid of its own. Pages whose aspect ratio doesn't match are ignored.
final
pyramidLevelsSource → TiffAsyncByteSource?
pyramidLevelsPath, for a view made with TiffImageView.source.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
setUpIsolate → void Function()?
Called once in every worker isolate before it decodes anything — pass TiffImageAdapter.enableJpegSupport for JPEG-compressed files. Must be a static or top-level function (a closure over local state can't cross an isolate boundary). For a view made with TiffImageView.source, it's called once on the current isolate.
final
showLoadingIndicator → bool
Whether a small progress indicator shows in the top-left corner while tiles are loading.
final
showMinimap → bool
Whether a TiffMinimap shows in the bottom-right corner.
final
source → TiffAsyncByteSource?
Where the file is read from, for a view made with TiffImageView.source; null for one made with a filePath.
final
workerCount → int?
Worker isolates decoding tiles; null picks one per CPU core minus one, capped at 4. For a view made with TiffImageView.source, how many tiles load at once (default 4) — their reads overlap, while decoding shares the one thread.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<TiffImageView>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited