opentile

README

opentile-go

A Go library for reading raw compressed tiles from whole-slide imaging (WSI) files used in digital pathology, including TIFF dialects (Aperio SVS, Hamamatsu NDPI, Philips TIFF, OME-TIFF, Ventana BIF, Leica SCN), the bleeding-edge non-TIFF Iris File Extension, and the ZIP-wrapped Microsoft Deep Zoom-based Smart Zoom Image format. Direct port of the Python opentile library for the four TIFF formats it supports, with byte-identical output. BIF (v0.7), IFE (v0.8), generic-TIFF (v0.10), Leica SCN (v0.11), and SZI (v0.16) are opentile-go's own additions beyond upstream's coverage. Memory-mapped tile reads + pool-friendly TileInto API since v0.9; bandwidth-deduplication TilePrefix / TileBodyInto API since v0.13 — see docs/perf.md.

import (
    opentile "github.com/wsilabs/opentile-go"
    _ "github.com/wsilabs/opentile-go/formats/all"
)

t, err := opentile.OpenFile("slide.svs")
if err != nil { /* ... */ }
defer t.Close()

base, _ := t.Level(0)
tile, err := base.Tile(0, 0) // raw compressed JPEG / JP2K / etc. bytes

Tile(x, y) returns the raw compressed bitstream as stored on disk — opentile-go is a tile-extraction library, not a decoder. Decode the returned bytes with whatever JPEG / JPEG 2000 / etc. library suits your downstream pipeline.

v0.22+ decoded-pixel access (preview): A decoder/ package and 9 codec subpackages are now available for callers that want decoded image.RGBA-equivalent pixels rather than raw bytes. Add a blanket side-effect import to opt in:

import (
    opentile "github.com/wsilabs/opentile-go"
    _ "github.com/wsilabs/opentile-go/formats/all"
    _ "github.com/wsilabs/opentile-go/decoder/all" // enables decoded-tile access in v1.0+
)

The decoded-tile *Slide methods that consume this layer are planned for v1.0. See decoder/ and resample/ for the current public API.

Supported formats

Format	Extension	Levels	Associated	Compression	Parity bar	Detail
Aperio SVS	.svs	tiled	label, overview, thumbnail	JPEG, JP2K (passthrough)	byte-parity vs. Python opentile	docs/formats/svs.md
Hamamatsu NDPI	.ndpi	tiled (striped + OneFrame)	overview, synthesised label*, Map*	JPEG	byte-parity vs. Python opentile	docs/formats/ndpi.md
Philips TIFF	.tiff	tiled, with sparse-tile fill	label, overview, thumbnail	JPEG	byte-parity vs. Python opentile	docs/formats/philipstiff.md
OME-TIFF	.ome.tiff	tiled (SubIFD) + OneFrame	overview, label, thumbnail	JPEG (uint8 RGB only)	byte-parity vs. Python opentile + tifffile	docs/formats/ometiff.md
Ventana BIF	.bif	tiled, serpentine remap, with overlap metadata* + ScanWhitePoint blank-tile fill	overview, probability*, thumbnail	JPEG	tifffile (DP 200) + sampled-tile SHAs (both fixtures)	docs/formats/bif.md
Iris IFE*	.iris	tiled (256×256, native-first inversion) with sparse-tile sentinel	label, overview, thumbnail, macro, map, probability + free-form titles + ICC profile + free-form attribute map	JPEG, AVIF (passthrough), Iris-proprietary (passthrough)	sampled-tile SHAs + synthetic-writer + per-fixture geometry pin	docs/formats/ife.md
Generic TIFF*	.tiff, .tif	tiled pyramidal (≥1 level, geometric scale chain)	classifier-assigned: label, overview, thumbnail, or "associated" fallback	JPEG, JP2K, LZW, Deflate, None, WebP, JPEG XL, AVIF, HTJ2K (all passthrough)	sampled-tile SHAs + per-fixture geometry pin + cross-backing parity	docs/formats/generictiff.md
Leica SCN*	.scn	tiled BigTIFF; multi-region "discontinuous scanning"; multi-channel fluorescence	classifier-assigned: overview per auxiliary <image>	JPEG	sampled-tile SHAs + per-fixture geometry pin + bio-formats CLI parity oracle	docs/formats/leicascn.md
Smart Zoom Image (SZI)*	.szi	ZIP-wrapped Microsoft Deep Zoom pyramid; per-level dim halving; sparse images not supported per spec	label, overview (from macro.jpg), thumbnail	JPEG / PNG (all passthrough)	sampled-tile SHAs + per-fixture geometry pin	docs/formats/szi.md
COG-WSI*	.tiff	strict GDAL Cloud Optimized GeoTIFF + WSI private tags (65080-87) + COG_WSI_VERSION ghost-area marker	label, overview (from macro or overview WSIImageType), thumbnail	source-format preserving (JPEG, JP2K, LZW, …)	per-fixture geometry pin + cross-fixture parity vs source format + ErrNotConformantCOGWSI spec validation	docs/formats/cogwsi.md

* Marks Go-side extensions beyond upstream Python opentile; see Deviations below.

Detection is automatic. opentile.OpenFile walks the registered factories — first asking each for SupportsRaw(r, size) against the raw byte stream, then falling through to TIFF-parsed Supports(file) — and dispatches the first match. The two-stage dispatch lets non-TIFF formats (IFE) short-circuit before tiff.Open. The generic-TIFF reader registers LAST so vendor format detectors get first crack at any TIFF; it activates as a catch-all only when no vendor factory claims the file. Format packages register at import time via _ "github.com/wsilabs/opentile-go/formats/all".

Format coverage: opentile-go ports the four TIFF formats Python opentile 0.20.0 supports for tile extraction. 3DHistech TIFF (the fifth upstream format) is parked at #2. Ventana BIF — the first beyond upstream's coverage — landed in v0.7. Iris IFE — the first non-TIFF format — landed in v0.8. Generic TIFF — a catch-all reader for tiled pyramidal TIFFs without vendor metadata — landed in v0.10. Leica SCN — the legacy SCN400/SCN400F format, including the first multi-channel fluorescence support — landed in v0.11. Smart Zoom Image (SZI) — a ZIP-wrapped Microsoft Deep Zoom pyramid backed by a shared internal/dzi/ core — landed in v0.16. Sakura SVSlide is parked at #3.

Prerequisites

• Go 1.23+ (uses iter.Seq2).
• libjpeg-turbo 2.1+ for tile-domain JPEG operations (NDPI edge-tile fill, Philips sparse-tile fill, OME OneFrame extraction).
  • macOS: brew install jpeg-turbo
  • Debian / Ubuntu: apt-get install libturbojpeg0-dev
• pkg-config to resolve libturbojpeg at build time.

opentile-go is mostly Go with one cgo dependency — internal/jpegturbo/ wraps libjpeg-turbo's tjTransform for lossless DCT-domain crops. Building without cgo (-tags nocgo or CGO_ENABLED=0) is supported: SVS works fully, NDPI striped levels work, but NDPI OneFrame / NDPI edge-tile fill / Philips sparse-tile fill / OME OneFrame return ErrCGORequired.

Install

go get github.com/wsilabs/opentile-go

Pin to v0.5.1 or later (v0.5.0 shipped with a wrong module path; see CHANGELOG).

API

Opening a slide

t, err := opentile.OpenFile("slide.tiff")
if err != nil { /* ErrUnsupportedFormat or open error */ }
defer t.Close()

fmt.Println("format:", t.Format())                 // "svs", "ndpi", "philips-tiff", "ome-tiff", "bif", "ife", "generic-tiff", "leica-scn", "szi", "cog-wsi"
fmt.Println("levels:", len(t.Levels()))

Pass options to override defaults:

t, err := opentile.OpenFile("slide.ndpi",
    opentile.WithTileSize(1024, 1024),                     // virtual tile size for OneFrame levels
    opentile.WithNDPISynthesizedLabel(false),              // disable the v0.2 NDPI label synthesis
)

For an io.ReaderAt source (S3, in-memory, etc.) instead of a filename:

t, err := opentile.Open(reader, size, opts...)

Reading tiles

base, _ := t.Level(0)

// Per-tile metadata.
fmt.Printf("base: %v tiles of %v pixels, compression %s, mpp %v\n",
    base.Grid(), base.TileSize(), base.Compression(), base.MPP())

// Get one tile's raw compressed bytes.
tile, err := base.Tile(0, 0)

Stream a tile via io.ReadCloser:

rc, err := base.TileReader(0, 0)
defer rc.Close()
io.Copy(dst, rc)

Iterate every tile in row-major order:

for pos, res := range base.Tiles(ctx) {
    if res.Err != nil { /* ... */ }
    process(pos.X, pos.Y, res.Bytes)
}

Multi-image files

OME-TIFF can carry multiple main pyramids in a single file. Tiler.Images() returns them all; Tiler.Levels() is a shortcut to Images()[0].Levels() for callers that don't need to distinguish.

for _, img := range t.Images() {
    fmt.Printf("Image %d (%q): %d levels, %v µm/px\n",
        img.Index(), img.Name(), len(img.Levels()), img.MPP())
    base, _ := img.Level(0)
    tile, _ := base.Tile(0, 0)
    // ...
}

For SVS, NDPI, and Philips, Images() always returns a one-element slice — Levels() / Level(i) work as before.

Associated images

Tiler.Associated() returns label / overview / thumbnail / map images where the format provides them:

for _, a := range t.Associated() {
    b, err := a.Bytes()
    if err != nil { continue }
    fmt.Printf("%s: %v, %s, %d bytes\n", a.Type(), a.Size(), a.Compression(), len(b))
}

a.Bytes() returns a self-contained, decoder-ready blob in whatever codec the source TIFF carries (typically JPEG or LZW). a.Type() is "label", "overview", "thumbnail", or "map" (NDPI only).

Format-specific metadata

Cross-format fields (manufacturer, scanner serial, acquisition datetime, magnification) are surfaced via t.Metadata(). Format-specific fields are accessible by type-asserting through a per-format helper:

import (
    svs "github.com/wsilabs/opentile-go/formats/svs"
    ndpi "github.com/wsilabs/opentile-go/formats/ndpi"
    philips "github.com/wsilabs/opentile-go/formats/philips"
    ome "github.com/wsilabs/opentile-go/formats/ome"
)

if md, ok := svs.MetadataOf(t); ok {
    fmt.Println("MPP (SVS):", md.MPP, "µm/px")
}
if md, ok := ndpi.MetadataOf(t); ok {
    fmt.Println("source lens (NDPI):", md.SourceLens, "x")
}
if md, ok := philips.MetadataOf(t); ok {
    fmt.Println("PixelSpacing (Philips):", md.PixelSpacing, "mm")
}
if md, ok := ome.MetadataOf(t); ok {
    fmt.Println("OME images:", len(md.Images))
}

MetadataOf walks any number of wrapper Tilers (e.g., *fileCloser from OpenFile) before asserting on the concrete type, so the helper works regardless of how the Tiler was obtained.

Concurrency

Level.Tile, Level.TileInto, Level.TileAt, and Level.TileReader are safe to call concurrently from multiple goroutines. SVS / Philips / OME tiled / BIF / IFE have no internal locks on the tile hot path. NDPI's striped reader takes a per-page mutex on its assembled-frame cache; concurrent reads of different pages run in parallel, concurrent reads of the same page serialize. OME OneFrame is similar.

All internal caches (parsed IFDs, per-tile offset / length tables, metadata) are populated at Open() time and then immutable — no locks on the tile hot path. Format packages with shared lazy caches use sync.Once and produce byte-deterministic output regardless of which goroutine populates them first.

Close() must not race with in-flight tile reads — drain before closing. Under the v0.9 default mmap backing, this is non-negotiable: closing unmaps the file, and subsequent reads through the mapping raise SIGBUS.

Performance

opentile-go's tile reads are designed for high-RPS HTTP serving and per-frame desktop viewers. See docs/perf.md for the full guide. Quick summary:

• OpenFile is mmap-backed by default since v0.9. Tile reads become userspace memcpy; no pread(2) syscall per call. Opt out via opentile.WithBacking(opentile.BackingPread).
• Use Level.TileInto(x, y, dst) (int, error) with a sync.Pool of []byte buffers sized to Level.TileMaxSize() for zero-allocation tile reads. Cervix serial: 152 ns/op, 0 allocs (vs v0.8's 22µs).
• Tiler.WarmLevel(i) error pre-warms the page cache for predictable warm-cache latency.
• Bandwidth deduplication (v0.13): Level.TilePrefix() returns the constant JPEG prefix; Level.TileBodyInto(x, y, dst) returns on-disk bytes without the prefix. Client-server consumers can send the prefix once per session and body bytes per tile. opentile.SpliceJPEGTile(prefix, body) reconstitutes a complete JPEG on the client side. Savings are fixture-author-dependent — see docs/perf.md for details.

Deviations from upstream Python opentile

opentile-go aims for byte-parity with Python opentile 0.20.0. A small number of deviations exist where matching upstream would encode an upstream oversight or where opentile-go provides a strictly more useful affordance:

Deviation	Format	Since	Opt-out / API	Why
Synthesised label	NDPI	v0.2	WithNDPISynthesizedLabel(false)	Upstream doesn't surface NDPI labels at all; we crop the left 30% of the overview to provide an Aperio-style label affordance.
Map pages exposed	NDPI	v0.4	not opt-out-able (silent absence)	tifffile already classifies them as series.name == 'Map'; surfacing matches the underlying TIFF carrying.
Multi-image OME pyramids	OME	v0.6	use Tiler.Levels() instead of Tiler.Images() for first-image-only behaviour	Upstream's base Tiler loop silently drops 3 of 4 main pyramids in multi-image files via an unintentional last-wins assignment. We expose all of them via Tiler.Images().
Probability map exposed as kind="probability"	BIF	v0.7	iterate Associated() and skip the kind	Upstream doesn't read BIF; openslide drops the probability map. We surface it for downstream tools that want it.
Level.TileOverlap() image.Point interface evolution	BIF + all	v0.7	non-BIF formats return image.Point{} (zero) — no caller change needed	BIF level-0 stores tiles with horizontal overlap; consumer needs the value to position raw tile bytes correctly.
Non-strict ScannerModel acceptance	BIF	v0.7	not opt-out-able	The BIF spec mandates rejecting any slide whose ScannerModel != "VENTANA DP 200"; we accept any iScan-tagged BigTIFF and route via HasPrefix("VENTANA DP") so legacy iScan slides aren't worse-than-openslide.
Multi-dimensional WSI API addition (TileCoord + Level.TileAt + Image.SizeZ/SizeC/SizeT/ChannelName/ZPlaneFocus)	All formats	v0.7	additive — 2D-only formats inherit SingleImage defaults	Modern WSI consumers (fluorescence, focal-plane viewers, time series) need explicit multi-dim addressing. BIF reads multi-Z natively; OME surfaces dimensions honestly + defers TileAt(z != 0) to a future format-package milestone.
Non-TIFF dispatch path (FormatFactory.SupportsRaw + OpenRaw + RawUnsupported base)	All formats	v0.8	additive — TIFF factories embed RawUnsupported and inherit defaults	Iris IFE is the first non-TIFF format opentile-go reads. Table-driven dispatch lets each format own its detection; future non-TIFF formats drop in additively.
TILE_TABLE.x_extent / y_extent ignored	IFE	v0.8	not opt-out-able	The IFE v1.0 spec doc claims these fields carry image pixel dims, but the cervix fixture stores tile counts (matching LAYER_EXTENTS.x_tiles). Reader derives image dims from LAYER_EXTENTS × 256 instead — unambiguous either way.
Default mmap-backed OpenFile	All formats	v0.9	WithBacking(BackingPread)	Universal perf win on the hot path (8–145× speedup; cervix serial Tile dropped from 22µs to 0.75µs). Auto-fallback to pread on mmap failure; SIGBUS on file truncation documented in the OpenFile docstring.
Level.TileInto + Level.TileMaxSize interface evolution	All formats	v0.9	additive — existing Tile() unchanged	Pool-friendly tile-read API. With sync.Pool of []byte buffers sized to TileMaxSize(), the caller does zero allocations per tile on every TIFF format and IFE. NDPI / OME OneFrame still allocate internal scratch.
Tiler.WarmLevel(i) interface evolution	All formats	v0.9	additive — hint operation, callers can ignore	Page-cache pre-warm for predictable warm-cache latency. Useful for slide-server pre-warm at startup.
Generic-TIFF reader for non-vendor tiled pyramidal TIFFs	Generic TIFF	v0.10	not opt-out-able once registered; any TIFF that no vendor factory claims AND that passes the validator routes here	Real-world WSI authoring outside Aperio / Hamamatsu / Philips is common (Grundium, Roche legacy iScan, vendor-stripped derivatives, libtiff-encoded research outputs). A catch-all reader makes opentile-go consume any structurally valid pyramid TIFF without per-vendor reverse-engineering.
"associated" AssociatedImage Kind value addition	Generic TIFF	v0.10	iterate Associated() and skip the kind	Generic TIFFs may carry non-pyramid IFDs the heuristic classifier can't confidently match to label / macro / thumbnail; surfacing them as "associated" lets the consumer access Bytes() / Size() without a wrong-but-plausible kind label.
Leica SCN reader for legacy SCN400 / SCN400F output	Leica SCN	v0.11	not opt-out-able once registered	First real-fixture exercise of Image.SizeC() > 1 (Leica-Fluorescence-1.scn's separated-channel data); also the first multi-region "discontinuous scanning" reader. Architecturally valuable beyond just SCN coverage.
Level.TilePrefix / TileBodyInto / TileBodyMaxSize + opentile.SpliceJPEGTile interface evolution	All formats (JPEG splice formats benefit)	v0.13	additive — existing Tile() / TileInto() unchanged	Bandwidth-deduplication API for client-server consumers: send the per-level prefix once, send per-tile body bytes per request, reconstitute on client. Savings fixture-author-dependent (only slides with shared JPEGTables benefit).
Smart Zoom Image (SZI) reader	Smart Zoom Image	v0.16	not opt-out-able once registered	First ZIP-backed format opentile-go reads; first format to surface CompressionPNG. Spec-mandated uncompressed-stored ZIP entries preserve the v0.9 mmap-aliased fast path. Backed by a new shared internal/dzi/ core designed for additive bare-DZI support in v0.17+.
COG-WSI reader + integer-multiple pyramid ratio acceptance	COG-WSI + generic-TIFF	v0.19	not opt-out-able once registered	First spec-validated COG-profile reader opentile-go ships; pairs WSI-domain private tags 65080-87 + COG_WSI_VERSION ghost-area marker with the GDAL Cloud Optimized GeoTIFF base structure. Closes Issues #5 + #6. Generic-TIFF standalone benefit: relaxed strict-drift check now accepts clean integer-multiple pyramid ratios (Aperio / Grundium SVS-style 4×/2×/2× chains).

Full reasoning + per-deviation commit references are in docs/deferred.md.

Testing

make test     # go test ./... -race -count=1
make vet      # go vet ./...
make cover    # ≥80% per package; needs OPENTILE_TESTDIR
make parity   # batched parity oracle vs Python opentile 0.20.0 + tifffile
make bench    # NDPI per-tile throughput regression gate

Integration tests and the parity oracle require real slide files at $OPENTILE_TESTDIR. Fixture JSONs (committed) are at tests/fixtures/. Slides themselves are not redistributable and are gitignored.

OPENTILE_TESTDIR="$PWD/sample_files" go test ./tests/... -v

For parity testing against Python opentile + tifffile, set the Python interpreter and run with the parity build tag:

pip install -r tests/oracle/requirements.txt
OPENTILE_ORACLE_PYTHON=$(which python) \
OPENTILE_TESTDIR="$PWD/sample_files" \
  go test ./tests/oracle/... -tags parity -v

The default run samples ~100 tile positions per level per slide. A persistent stdin / stdout protocol keeps one Python subprocess resident per slide; full sweep on the v0.6 13-slide oracle slate completes in under 10 seconds.

License + attribution

Apache 2.0. Independent Go port of the Python opentile library (Copyright 2021–2024 Sectra AB); see NOTICE for attribution. Not affiliated with or endorsed by Sectra AB or the BigPicture project.

Documentation

Overview

Package opentile provides utilities to read tiles from whole-slide imaging (WSI) TIFF files. See the repository README for a high-level overview.

Index

• Constants
• Variables
• func CompressionToTIFFTag(c Compression) uint16
• func SetOpenAnyHook(...)
• func SpliceJPEGTile(prefix, body []byte) ([]byte, error)
• type AssociatedImage
• type Backing
• type Compression
  • func (c Compression) String() string
• type Config
  • func NewTestConfig(tileSize Size, policy CorruptTilePolicy) *Config
  • func (c *Config) Backing() Backing
  • func (c *Config) CorruptTilePolicy() CorruptTilePolicy
  • func (c *Config) NDPISynthesizedLabel() bool
  • func (c *Config) TileSize() (Size, bool)
• type CorruptTilePolicy
• type DecodeOption
  • func WithFormat(f decoder.PixelFormat) DecodeOption
  • func WithResampleKernel(k resample.Kernel) DecodeOption
  • func WithScale(s int) DecodeOption
• type Format
• type Image
• type Level
• type Metadata
  • func (m *Metadata) SetMPPSymmetric()
  • func (m *Metadata) SetProperty(key, value string)
• type Option
  • func WithBacking(b Backing) Option
  • func WithCorruptTilePolicy(p CorruptTilePolicy) Option
  • func WithNDPISynthesizedLabel(enable bool) Option
  • func WithTileSize(w, h int) Option
• type Point
  • func (p Point) String() string
• type Region
  • func (r Region) Contains(p Point) bool
• type Size
  • func (s Size) Area() int
  • func (s Size) String() string
• type SizeMm
  • func (s SizeMm) IsZero() bool
• type Slide
  • func Open(r io.ReaderAt, size int64, opts ...Option) (*Slide, error)
  • func OpenFile(path string, opts ...Option) (*Slide, error)
  • func (s *Slide) Associated() []AssociatedImage
  • func (s *Slide) BestLevelForDownsample(downsample float64) int
  • func (s *Slide) Close() error
  • func (s *Slide) DecodedTile(level, tx, ty int, opts ...DecodeOption) (*decoder.Image, error)
  • func (s *Slide) DecodedTileInto(level, tx, ty int, dst *decoder.Image, opts ...DecodeOption) error
  • func (s *Slide) Format() Format
  • func (s *Slide) ICCProfile() []byte
  • func (s *Slide) ImageBestLevelForDownsample(image int, downsample float64) int
  • func (s *Slide) ImageDecodedTile(image, level, tx, ty int, opts ...DecodeOption) (*decoder.Image, error)
  • func (s *Slide) ImageDecodedTileInto(image, level, tx, ty int, dst *decoder.Image, opts ...DecodeOption) error
  • func (s *Slide) ImageRangeTiles(ctx context.Context, image, level int) iter.Seq2[TilePos, TileResult]
  • func (s *Slide) ImageRawTile(image, level, tx, ty int) ([]byte, error)
  • func (s *Slide) ImageRawTileInto(image, level, tx, ty int, dst []byte) (int, error)
  • func (s *Slide) ImageReadRegion(image, level, x, y, w, h int, opts ...DecodeOption) (*decoder.Image, error)
  • func (s *Slide) ImageReadRegionInto(image, level, x, y int, dst *decoder.Image, opts ...DecodeOption) error
  • func (s *Slide) ImageReadRegionScaled(image int, l0x, l0y, l0w, l0h, outW, outH int, opts ...DecodeOption) (*decoder.Image, error)
  • func (s *Slide) ImageReadRegionScaledInto(image int, l0x, l0y, l0w, l0h int, dst *decoder.Image, opts ...DecodeOption) error
  • func (s *Slide) ImageTileBodyInto(image, level, tx, ty int, dst []byte) (int, error)
  • func (s *Slide) ImageTileBodyMaxSize(image, level int) int
  • func (s *Slide) ImageTileMaxSize(image, level int) int
  • func (s *Slide) ImageTilePrefix(image, level int) []byte
  • func (s *Slide) ImageTileReader(image, level, tx, ty int) (io.ReadCloser, error)
  • func (s *Slide) ImageWarmLevel(image, level int) error
  • func (s *Slide) Images() []Image
  • func (s *Slide) Level(i int) (Level, error)
  • func (s *Slide) Levels() []Level
  • func (s *Slide) Metadata() Metadata
  • func (s *Slide) RangeTiles(ctx context.Context, level int) iter.Seq2[TilePos, TileResult]
  • func (s *Slide) RawTile(level, tx, ty int) ([]byte, error)
  • func (s *Slide) RawTileInto(level, tx, ty int, dst []byte) (int, error)
  • func (s *Slide) ReadRegion(level, x, y, w, h int, opts ...DecodeOption) (*decoder.Image, error)
  • func (s *Slide) ReadRegionInto(level, x, y int, dst *decoder.Image, opts ...DecodeOption) error
  • func (s *Slide) ReadRegionScaled(l0x, l0y, l0w, l0h, outW, outH int, opts ...DecodeOption) (*decoder.Image, error)
  • func (s *Slide) ReadRegionScaledInto(l0x, l0y, l0w, l0h int, dst *decoder.Image, opts ...DecodeOption) error
  • func (s *Slide) ScaledStrips(l0Rect image.Rectangle, outSize image.Point, stripHeight int, ...) *StripIterator
  • func (s *Slide) TileBodyInto(level, tx, ty int, dst []byte) (int, error)
  • func (s *Slide) TileBodyMaxSize(level int) int
  • func (s *Slide) TileMaxSize(level int) int
  • func (s *Slide) TilePrefix(level int) []byte
  • func (s *Slide) TileReader(level, tx, ty int) (io.ReadCloser, error)
  • func (s *Slide) UnwrapReader() any
  • func (s *Slide) WarmLevel(i int) error
• type StripIterator
  • func (it *StripIterator) Close() error
  • func (it *StripIterator) Next() (*decoder.Image, error)
  • func (it *StripIterator) Strips() int
• type StripOption
  • func WithStripContext(ctx context.Context) StripOption
  • func WithStripIDCTScale(scale int) StripOption
  • func WithStripKernel(k resample.Kernel) StripOption
  • func WithStripLookahead(strips int) StripOption
  • func WithStripWorkers(n int) StripOption
• type TileCoord
  • func (t TileCoord) String() string
• type TileError
  • func (e *TileError) Error() string
  • func (e *TileError) Unwrap() error
• type TilePos
• type TileResult

Constants

const (
	// PropertyCaseNumber is the clinical / specimen case identifier.
	PropertyCaseNumber = "case-number"
	// PropertyUserName is the scan operator / user name.
	PropertyUserName = "user-name"
	// PropertyScannedAreaMM2 is the physical scanned area in mm²
	// (string-formatted float; parse via strconv.ParseFloat).
	PropertyScannedAreaMM2 = "scanned-area-mm2"
	// PropertyScanDurationSec is the wall-clock scan duration in
	// seconds (string-formatted float; parse via strconv.ParseFloat).
	PropertyScanDurationSec = "scan-duration-seconds"
	// PropertyComments is free-text user comments (distinct from
	// ImageDescription, which is the structured per-format description).
	PropertyComments = "comments"
)

PropertyXxx are the canonical opentile-go cross-format keys for Metadata.Properties. Format readers use these constants to populate well-known cross-format fields that don't have typed struct positions.

Added in v0.17.

Variables

var (
	ErrUnsupportedFormat      = errors.New("opentile: unsupported format")
	ErrUnsupportedCompression = errors.New("opentile: unsupported compression")
	ErrTileOutOfBounds        = errors.New("opentile: tile position out of bounds")
	ErrCorruptTile            = errors.New("opentile: corrupt tile")
	ErrLevelOutOfRange        = errors.New("opentile: level index out of range")
	ErrImageIndexOutOfRange   = errors.New("opentile: image index out of range")
	ErrInvalidTIFF            = errors.New("opentile: invalid TIFF structure")

	// ErrTooManyIFDs is returned when a TIFF IFD chain exceeds the safety cap
	// (1024 IFDs) before terminating. Either the file is corrupt, presents a
	// cycle, or is malicious. Re-exports internal/tiff.ErrTooManyIFDs so
	// callers can errors.Is(err, opentile.ErrTooManyIFDs).
	ErrTooManyIFDs = tiff.ErrTooManyIFDs

	// Returned (wrapped in TileError) when internal/jpeg cannot parse a JPEG
	// bitstream or assemble a valid one from TIFF fragments.
	ErrBadJPEGBitstream = errors.New("opentile: invalid JPEG bitstream")

	// Returned when an operation requires an MCU-aligned region and the
	// computed or requested region is not. Primarily an internal invariant
	// guard; consumers encounter it only on malformed slides.
	ErrMCUAlignment = errors.New("opentile: operation requires MCU alignment")

	// Returned from NDPI one-frame levels and NDPI label on builds compiled
	// without cgo (CGO_ENABLED=0 or -tags nocgo).
	ErrCGORequired = errors.New("opentile: operation requires cgo build with libjpeg-turbo")

	// Reserved for future use; currently unfired because v0.2 defaults the
	// NDPI tile size to 512 rather than erroring. Predefined so exporting
	// it later is not a breaking change.
	ErrTileSizeRequired = errors.New("opentile: tile size not representable for this format")

	// ErrDimensionUnavailable is returned (wrapped in TileError) when a
	// caller asks for a non-zero Z, C, or T axis on a TileCoord but the
	// underlying Image's SizeZ/SizeC/SizeT is 1 (the format / slide
	// doesn't carry that dimension at all). Distinct from
	// ErrTileOutOfBounds: that error means "this axis exists but the
	// requested index is past its size"; this means "the axis itself
	// doesn't exist on this slide / format / milestone."
	//
	// Added in v0.7 alongside Level.TileAt and the multi-dim Image
	// dimension accessors.
	ErrDimensionUnavailable = errors.New("opentile: dimension not supported on this format/image")

	// ErrSparseTile is returned (wrapped in TileError) when a tile
	// position falls within the level's grid but the underlying file
	// has no compressed bytes at that cell — the format encodes
	// "absent / blank tile" as a sentinel offset rather than empty
	// content. Iris IFE uses NULL_TILE (0xFFFFFFFFFF in the 40-bit
	// offset field); other formats may add later. Consumers typically
	// translate this into an HTTP 404 or a fixed blank image. Distinct
	// from ErrTileOutOfBounds (the position itself is past the grid).
	//
	// Added in v0.8 alongside the Iris IFE format package.
	ErrSparseTile = errors.New("opentile: sparse tile (no compressed bytes at this position)")

	// ErrMmapUnavailable is returned by [OpenFile] when called with
	// [WithBacking](BackingMmap) (the default since v0.9) but the
	// underlying memory-map operation fails — typically because the
	// file is on a filesystem that doesn't support mmap (some FUSE
	// or network mounts) or the platform lacks `golang.org/x/exp/mmap`
	// support. Wraps the underlying error from `mmap.Open`.
	//
	// Callers that want automatic fallback to the os.File / pread
	// path can retry with `opts...` extended by
	// `WithBacking(BackingPread)` on this error.
	//
	// Added in v0.9 alongside the mmap-default OpenFile change.
	ErrMmapUnavailable = errors.New("opentile: memory-map unavailable for this file")

	// ErrCodecNotRegistered is returned by *Slide.DecodedTile and friends
	// when no decoder is registered for the level's Compression. The
	// wrapping error message names the compression and the suggested
	// blank-import that fixes it.
	//
	// Added in v0.24 alongside the DecodedTile family.
	ErrCodecNotRegistered = errors.New("opentile: codec not registered for this slide's tile compression")

	// ErrRegionEmpty is returned by *Slide.ReadRegion / ReadRegionScaled
	// when the requested rectangle has no in-bounds pixels.
	//
	// Added in v0.25 alongside the ReadRegion family.
	ErrRegionEmpty = errors.New("opentile: region has no in-bounds pixels")
)

var ErrBadJPEGSplice = errors.New("opentile: bad JPEG splice input")

ErrBadJPEGSplice is returned by SpliceJPEGTile when the body bytes don't conform to the expected SOS-bearing JPEG layout.

Functions

func CompressionToTIFFTag

func CompressionToTIFFTag(c Compression) uint16

CompressionToTIFFTag returns the TIFF Compression tag value that corresponds to c, or 0 if no standard mapping exists. Used internally by *Slide.DecodedTile to dispatch through the decoder package's GetByCompressionTag registry.

CompressionIRIS and CompressionPNG return 0 because neither has a TIFF-registered decoder; DecodedTile surfaces ErrCodecNotRegistered for these.

func SetOpenAnyHook

func SetOpenAnyHook(fn func(
	r io.ReaderAt,
	size int64,
	tileSize Size,
	hasTileSize bool,
	corruptTilePolicy CorruptTilePolicy,
	ndpiSynthLabel bool,
	backing Backing,
) (any, error))

SetOpenAnyHook registers the format dispatch function. Called once from internal/format's init() via a bridge file. Must be called before any Open/OpenFile call. Not safe for concurrent use during setup.

func SpliceJPEGTile

func SpliceJPEGTile(prefix, body []byte) ([]byte, error)

SpliceJPEGTile reconstitutes a complete JPEG from a level's TilePrefix bytes and one tile's TileBodyInto output. Inserts the prefix at the on-disk tile's SOS boundary (the same operation opentile-go does internally during Tile/TileInto).

Returns body verbatim (defensively copied) if prefix is empty / nil — degenerate case for levels without splice (e.g., non-JPEG compressions, NDPI stripped levels, IFE).

Returns ErrBadJPEGSplice if body is empty or doesn't contain an SOS marker (0xFF 0xDA per JPEG spec).

Algorithm (documented for non-Go consumers reimplementing client-side):

1. If prefix is empty: return body verbatim.
2. Find offset of the first 0xFF 0xDA byte sequence in body ("Start of Scan" marker).
3. Output = body[0:sosIdx] + prefix + body[sosIdx:]

Added in v0.13 alongside Level.TilePrefix and Level.TileBodyInto.

Types

type AssociatedImage

type AssociatedImage interface {
	Type() string
	Size() Size
	Compression() Compression
	Bytes() ([]byte, error)
}

AssociatedImage is a non-pyramidal slide-level image (label, overview, thumbnail).

Standard Type() values used across opentile-go's format readers. The choice of names follows DICOM PS3.3 / Supplement 145 (Whole Slide Microscopic Image IOD), where the Image Type attribute (0008,0008) value 3 enumerates: VOLUME / LABEL / OVERVIEW / THUMBNAIL. opentile-go uses the lowercase form, extended with format-specific kinds where the underlying file surfaces them:

"label"       — slide label / barcode
"overview"    — wide-field image of the slide. The DICOM-canonical
                term, also used by upstream Python opentile and by
                six of opentile-go's eight format readers. The
                seventh (Iris IFE) intentionally distinguishes
                "overview" from "macro" per the IFE spec.
"thumbnail"   — full-slide downsample (typically square, JPEG)
"map"         — NDPI / IFE: low-magnification map / overview-of-
                pyramid; semantically distinct from a wide-field
                slide image
"probability" — Ventana BIF / IFE: confidence / classification map
"macro"       — Iris IFE only. The IFE spec defines LABEL_MACRO
                as a kind distinct from LABEL_OVERVIEW. Other
                formats' wide-field slide images surface as
                "overview", not "macro".
"associated"  — generic-TIFF heuristic-fallback (v0.10+) when the
                classifier can't confidently match a kind above

Format readers use the string literals directly; the values above are stable and part of the public API contract from v0.15 onward.

type Backing

type Backing uint8

Backing identifies the I/O backend used to read tile bytes from a slide file. Selectable via WithBacking; defaults to BackingMmap since v0.9.

BackingMmap memory-maps the file read-only and reads tiles via userspace memcpy from the mapped region. No syscall per Tile() call once the kernel has paged in the relevant region. Recommended for high-RPS serving and warm-cache desktop use. Caveat: SIGBUS on file truncation; not suitable for storage that gets rewritten underneath open Tilers.

BackingPread keeps the v0.8 (and earlier) os.File-based path: pread(2) syscall per [Level.Tile] call. Use this on filesystems that don't support mmap (some FUSE / network mounts), or when you specifically need the os.File semantics around truncation.

const (
	// BackingMmap memory-maps the slide file. Default since v0.9.
	BackingMmap Backing = iota
	// BackingPread uses os.File + pread(2) per Tile().
	BackingPread
)

type Compression

type Compression uint8

Compression identifies the bitstream format of a tile as stored in a TIFF.

opentile-go returns tile bytes in the compression format of the source TIFF without decoding them. Consumers that need decoded pixels should pass the bytes to a codec appropriate for the reported compression.

The zero value is CompressionUnknown: a forgotten-to-initialize field surfaces loudly rather than masquerading as a known compression.

const (
	CompressionUnknown Compression = iota // zero value; unset or unrecognized
	CompressionNone
	CompressionJPEG
	CompressionJP2K
	CompressionLZW  // TIFF tag 259 value 5 (Aperio SVS label is commonly LZW)
	CompressionAVIF // tile bytes are an AVIF image; consumer decodes via libavif
	// CompressionIRIS is the Iris-proprietary tile codec used by IFE files
	// when written through Iris-Codec. opentile-go reports it but does not
	// decode the bytes; consumers either embed an Iris codec or 501 the
	// request. JPEG and AVIF tiles in IFE remain decodable by external
	// codecs.
	CompressionIRIS
	// CompressionDeflate identifies the Deflate (zlib) bitstream
	// commonly used by scientific imaging TIFFs and the
	// generic-TIFF catch-all reader (v0.10). TIFF tag 259 values
	// 8 (Deflate) and 32946 (Adobe Deflate) both map here; the
	// payload is identical zlib-wrapped DEFLATE either way.
	CompressionDeflate
	// CompressionWebP identifies a WebP-encoded tile (RIFF + WEBP +
	// VP8/VP8L/VP8X chunks). TIFF tag 259 value 50001 in libtiff
	// convention; same value is what the user's wsi-tools transcoder
	// emits. Tile bytes are a complete self-contained WebP file.
	// Consumer decodes via libwebp or golang.org/x/image/webp.
	//
	// Added in v0.14.
	CompressionWebP
	// CompressionJPEGXL identifies a JPEG XL codestream tile. TIFF
	// tag 259 value 50002 (wsi-tools convention; not formally
	// registered). Tile bytes are a bare JXL codestream beginning
	// with the 0xFF 0x0A marker. Consumer decodes via libjxl (cgo)
	// or stdlib image/jxl when available.
	//
	// Added in v0.14.
	CompressionJPEGXL
	// CompressionHTJ2K identifies an HTJ2K (High-Throughput JPEG
	// 2000, ISO/IEC 15444-15) codestream tile. TIFF tag 259 value
	// 60003 (wsi-tools convention). Distinct from CompressionJP2K
	// because HTJ2K uses a different entropy coder (FBCOT instead
	// of EBCOT) and a standard JP2K decoder will fail on HTJ2K
	// bytes. Consumer decodes via OpenJPEG 2.5+, OpenHTJ2K, or
	// Kakadu.
	//
	// Added in v0.14.
	CompressionHTJ2K
	// CompressionPNG identifies a PNG-encoded tile (`\x89PNG` magic).
	// DZI's Format attribute admits both jpeg and png. Tile bytes
	// are a complete self-contained PNG file. Consumer decodes via
	// `image/png` (stdlib).
	//
	// Added in v0.16.
	CompressionPNG
)

func (Compression) String

func (c Compression) String() string

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config is an opaque, read-only view of the configuration passed to a FormatFactory. Format packages import opentile.Config rather than the unexported config struct.

func NewTestConfig

func NewTestConfig(tileSize Size, policy CorruptTilePolicy) *Config

NewTestConfig constructs a Config for use in tests.

Deprecated: use opentile/opentiletest.NewConfig. This wrapper remains for one release to keep external callers compiling; it will be removed in v0.4.

func (*Config) Backing

func (c *Config) Backing() Backing

Backing reports the I/O backing the caller selected via WithBacking. Defaults to BackingMmap since v0.9 if no option was passed. Format packages typically don't need this — Open is path-agnostic — but it's exposed for diagnostic accessors.

func (*Config) CorruptTilePolicy

func (c *Config) CorruptTilePolicy() CorruptTilePolicy

CorruptTilePolicy returns the configured policy.

func (*Config) NDPISynthesizedLabel

func (c *Config) NDPISynthesizedLabel() bool

NDPISynthesizedLabel reports whether NDPI Tiler.Associated() should include a synthesized label cropped from the overview. Default true.

func (*Config) TileSize

func (c *Config) TileSize() (Size, bool)

TileSize returns the requested output tile size and whether the caller set one.

• (Size{}, false): caller did not pass WithTileSize. Format packages should use their format default (e.g. SVS reads the native tile size from the TIFF; NDPI uses 512).
• (Size{}, true): caller explicitly passed WithTileSize(0, 0). Format packages MUST reject this as malformed input. The zero Size is distinct from "unset" because the API contract is that an explicit option overrides the default.
• (non-zero, true): caller's requested tile size; format honors it (NDPI may snap to a stripe-multiple, SVS rejects when it doesn't match the native tile dimensions).

type CorruptTilePolicy

type CorruptTilePolicy uint8

CorruptTilePolicy controls how corrupt-edge tiles (currently: Aperio SVS) are reported. v0.1 supports only CorruptTileError.

const (
	CorruptTileError CorruptTilePolicy = iota // return ErrCorruptTile (default, v0.1)
	CorruptTileBlank                          // v0.3: return a typed blank tile
	CorruptTileFix                            // v1.0: reconstruct from parent level
)

type DecodeOption

type DecodeOption func(*decodeConfig)

DecodeOption configures a *Slide.DecodedTile / DecodedTileInto / ReadRegion / ReadRegionScaled call. See WithFormat, WithScale, WithResampleKernel.

func WithFormat

func WithFormat(f decoder.PixelFormat) DecodeOption

WithFormat sets the requested output pixel format. Defaults to PixelFormatRGB (3 bytes per pixel; alpha-free). PixelFormatRGBA is also universally supported.

func WithResampleKernel

func WithResampleKernel(k resample.Kernel) DecodeOption

WithResampleKernel chooses the resample kernel for ReadRegionScaled. Has no effect on ReadRegion (no resampling step).

resample.Lanczos  — best perceptual quality (default)
resample.Box      — fast integer-ratio downsampling, sharp
resample.Bilinear — fast, decent quality
resample.Nearest  — fastest, ugly under downsampling

func WithScale

func WithScale(s int) DecodeOption

WithScale sets the IDCT-time scale factor (JPEG decoders only). Valid values: 1, 2, 4, 8. Non-JPEG sources return ErrUnsupportedScale from the underlying decoder if Scale != 1.

type Format

type Format string

Format identifies the source file format.

const (
	FormatSVS  Format = "svs"
	FormatNDPI Format = "ndpi"
	// FormatPhilipsTIFF is the Philips IntelliSite Pathology Solution TIFF
	// reader. Renamed in v0.12 from FormatPhilips to FormatPhilipsTIFF to
	// align with v0.10's FormatGenericTIFF and v0.11's FormatLeicaSCN naming
	// convention; Philips has multiple WSI file formats (TIFF; iSyntax), so
	// the bare "philips" identifier was ambiguous. Reports as "philips-tiff".
	FormatPhilipsTIFF Format = "philips-tiff"
	// FormatOMETIFF is the OME-TIFF reader. Renamed in v0.12 to align
	// with v0.10/v0.11's FormatGenericTIFF / FormatLeicaSCN convention;
	// OME has multiple file formats (OME-TIFF, OME-Zarr, OME-NGFF), so
	// the bare "ome" identifier ambiguously claimed the family.
	FormatOMETIFF Format = "ome-tiff"
	FormatBIF     Format = "bif"
	FormatIFE     Format = "ife"
	// FormatGenericTIFF is the catch-all reader for tiled pyramidal TIFF
	// without vendor metadata (added in v0.10). Activates when no
	// vendor format factory claims the file. Reports as "generic-tiff"
	// to differentiate from possible future generic-non-TIFF readers.
	FormatGenericTIFF Format = "generic-tiff"
	// FormatLeicaSCN is the Leica SCN reader (added in v0.11). SCN is a
	// BigTIFF dialect produced by Leica SCN400 / SCN400F scanners;
	// scanner production stopped ~2015. Reports as "leica-scn" to
	// differentiate from other Leica-related formats (LIF, LMS) that
	// aren't SCN.
	FormatLeicaSCN Format = "leica-scn"
	// FormatSZI identifies a Smart Zoom Image file (ZIP-wrapped
	// Microsoft Deep Zoom pyramid + scan-properties.xml +
	// associated_images/, per the smartinmedia/SZI-Format spec).
	//
	// Added in v0.16.
	FormatSZI Format = "szi"
	// FormatCOGWSI identifies a Cloud Optimized GeoTIFF for WSI file —
	// a strict extension of GDAL Cloud Optimized GeoTIFF carrying
	// WSI-specific private tags + ghost-area marker. Spec at
	// docs/specs/2026-05-20-cog-wsi-format.md. Added in v0.19.
	FormatCOGWSI Format = "cog-wsi"
)

type Image

type Image struct {
	// Name identifies this image. For OME-TIFF, the <Image Name="...">
	// attribute. Empty for single-image formats.
	Name string

	// Index is the 0-based document-order index of this Image within
	// the parent Slide. Pass to *Slide.ImageRawTile(image, level, tx, ty).
	Index int

	// Levels is the pyramid for this image, finest-to-coarsest. Level 0
	// is the full-resolution base; subsequent indices are progressively
	// downsampled.
	Levels []Level
}

Image identifies one pyramid group within a slide. Single-image formats carry a single Image. OME-TIFF can carry multiple.

type Level

type Level struct {
	// Index is the 0-based index of this level within the parent
	// Image's Levels slice. Pass to *Slide.RawTile(level, tx, ty).
	Index int

	// PyramidIndex is the pyramid-group index for multi-image formats.
	// Single-image formats always have PyramidIndex = 0. OME-TIFF
	// multi-image files preserve the per-image series identifier here.
	PyramidIndex int

	// Size is the pixel dimensions of this level (Width × Height).
	Size Size

	// TileSize is the tile dimensions used by this level.
	TileSize Size

	// Grid is the tile grid dimensions: ceil(Size / TileSize) per axis.
	// Pre-computed for convenience.
	Grid Size

	// TileOverlap is the per-tile overlap (BIF / NDPI in overlapping
	// modes). Zero for non-overlapping tile formats.
	TileOverlap image.Point

	// Compression identifies the codec for tile bytes at this level.
	// Used by *Slide.DecodedTile to dispatch to the right decoder.
	Compression Compression

	// MPP is microns-per-pixel at this level (W and H; usually equal).
	// Zero value if the slide doesn't carry MPP metadata.
	MPP SizeMm

	// FocalPlane is the z-position in microns for multi-focal-plane
	// sources. Zero value for 2D slides.
	FocalPlane float64

	// Downsample is the resolution factor from L0. 1.0 at level 0,
	// 2.0 at half-resolution, 4.0 at quarter, etc. Computed at Open
	// time from the level's Size relative to the image's L0 Size.
	//
	// Used by *Slide.BestLevelForDownsample and *Slide.ReadRegionScaled
	// to translate L0 coords into level coords.
	//
	// Added in v0.25 alongside the ReadRegion family.
	Downsample float64
}

Level is value-type pyramid-level metadata. All fields are inspection-only (read at *Slide.Open time). Tile reads use *Slide.RawTile / *Slide.DecodedTile (takes level index).

type Metadata

type Metadata struct {
	Magnification       float64 // 0 if unknown
	ScannerManufacturer string
	ScannerModel        string
	ScannerSoftware     []string
	ScannerSerial       string
	// AcquisitionDateTime is the time the slide was scanned. Partial Date
	// or Time values that fail time.Parse yield the zero value
	// (time.Time{}); time.Time{}.IsZero() == true is the "unknown"
	// sentinel. Callers should always check IsZero rather than comparing
	// against a specific time — different scanner vendors emit dates in
	// different formats and our parsers are lenient but not exhaustive.
	AcquisitionDateTime time.Time

	// MicronsPerPixel is populated when MicronsPerPixelX and
	// MicronsPerPixelY are both set and equal (strict ==). When the
	// format reports asymmetric pixel size, MicronsPerPixel is zero
	// and consumers should consult the per-axis fields. Zero indicates
	// "unknown OR asymmetric"; check MicronsPerPixelX/Y to disambiguate.
	//
	// Added in v0.17.
	MicronsPerPixel float64

	// MicronsPerPixelX / MicronsPerPixelY are the per-axis pixel size
	// in microns. Zero indicates the format didn't report it.
	//
	// Added in v0.17.
	MicronsPerPixelX float64
	MicronsPerPixelY float64

	// ImageDescription is the structured per-format description (e.g.,
	// SVS ImageDescription TIFF tag, OME-XML <Image Description>
	// attribute). Empty when the format has no equivalent. For free-
	// text user comments, see Properties[PropertyComments].
	//
	// Added in v0.17.
	ImageDescription string

	// Properties is a flat key-value map for additional metadata
	// that doesn't fit the typed fields. Two key conventions:
	//
	//   - opentile-go-canonical keys (lowercase-with-hyphens):
	//     PropertyCaseNumber, PropertyUserName, PropertyScannedAreaMM2,
	//     PropertyScanDurationSec, PropertyComments. Populated by
	//     format readers when their format exposes the equivalent.
	//
	//   - vendor-namespaced keys (vendor.<key>): vendor-specific
	//     fields surfaced as-is. Format-prefixed: e.g., "szi.vendor.
	//     SerialNumber", "aperio.AppMag".
	//
	// Missing keys mean the format didn't expose that field. Numeric
	// values are string-formatted floats (parseable via
	// strconv.ParseFloat).
	//
	// Added in v0.17.
	Properties map[string]string

	// Writer identifies the software that wrote this file — the
	// file producer, distinct from ScannerManufacturer (scanner OEM)
	// and ScannerSoftware []string (broader software stack).
	//
	// Format-specific population:
	//   SVS Aperio canonical    "Aperio Image Library v11.2.1"
	//   SVS Grundium / other    "Grundium Ocus" (comma-suffix writer
	//                            from v0.18 detection)
	//   OME-TIFF                "OME Bio-Formats 6.0.0-rc1" (Creator
	//                            attribute; promoted from Properties)
	//   SZI                     "<SoftwareName> <SoftwareVersion>"
	//                            (e.g., "OcusScan 3.1.4")
	//   COG-WSI                 "wsitools/<WSIToolsVersion>" (file
	//                            producer; source scanner stays in
	//                            ScannerManufacturer per spec)
	//   Generic-TIFF (wsi-tools  "wsitools/<version>" from the
	//     fixtures avif/jxl/      wsi-tools ImageDescription parser
	//     htj2k/webp)
	//   NDPI / Philips / BIF /  format-specific Software field (often
	//     IFE / Leica SCN        equals ScannerSoftware[0])
	//
	// Empty when the format provides no writer indication. Consumers
	// checking presence compare against "" explicitly.
	//
	// Added in v0.20.
	Writer string
}

Metadata is the common subset of slide metadata surfaced across all formats. Format packages embed this struct to add format-specific fields exposed via type assertion on Tiler.Metadata().

func (*Metadata) SetMPPSymmetric

func (m *Metadata) SetMPPSymmetric()

SetMPPSymmetric populates MicronsPerPixel from MicronsPerPixelX and MicronsPerPixelY when they are equal (strict ==). When asymmetric, MicronsPerPixel is zeroed.

Format readers call this after setting the per-axis fields.

Added in v0.17.

func (*Metadata) SetProperty

func (m *Metadata) SetProperty(key, value string)

SetProperty is a nil-safe setter for Properties. Lazily initializes the map on first use.

Added in v0.17.

type Option

type Option func(*config)

Option mutates the opentile configuration before Open returns a Tiler.

func WithBacking

func WithBacking(b Backing) Option

WithBacking selects the I/O backend used by OpenFile. The default since v0.9 is BackingMmap; pass WithBacking(BackingPread) on the rare filesystem that doesn't support mmap or when you need os.File truncation semantics.

Has no effect on Open (which already takes a caller-provided io.ReaderAt); only the path-resolving OpenFile honors this.

When set to BackingMmap and the underlying mmap call fails (FUSE mount that doesn't support mapping, etc.), OpenFile returns ErrMmapUnavailable wrapping the underlying error rather than silently falling back. Callers that want auto-fallback should retry with WithBacking(BackingPread).

func WithCorruptTilePolicy

func WithCorruptTilePolicy(p CorruptTilePolicy) Option

WithCorruptTilePolicy sets the behavior for corrupt-edge tiles. v0.1 supports only CorruptTileError.

func WithNDPISynthesizedLabel

func WithNDPISynthesizedLabel(enable bool) Option

WithNDPISynthesizedLabel controls whether NDPI Tiler.Associated() includes a synthesized "label" image, which Go produces by cropping the left 30% of the overview page. Python opentile 0.20.0 does not expose NDPI labels; this is a Go-side extension. Default: true (matches v0.2 behavior).

func WithTileSize

func WithTileSize(w, h int) Option

WithTileSize requests output tile dimensions in pixels. If unset, the format default is used (SVS: native tile size from the TIFF). Required for formats that have no native rectangular tiles (NDPI, v0.2+).

type Point

type Point struct {
	X, Y int
}

Point is a 2D integer position measured in pixels or tile units.

func (Point) String

func (p Point) String() string

type Region

type Region struct {
	Origin Point
	Size   Size
}

Region is an axis-aligned rectangle in pixel or tile units.

func (Region) Contains

func (r Region) Contains(p Point) bool

Contains reports whether p lies inside r (inclusive of origin, exclusive of the far edge).

type Size

type Size struct {
	W, H int
}

Size is a 2D integer extent measured in pixels or tile units.

func (Size) Area

func (s Size) Area() int

func (Size) String

func (s Size) String() string

type SizeMm

type SizeMm struct {
	W, H float64
}

SizeMm is a 2D extent measured in millimeters. Used for pixel spacing and microns-per-pixel conversion (SizeMm scaled by 1000 equals micrometers).

func (SizeMm) IsZero

func (s SizeMm) IsZero() bool

type Slide

type Slide struct {
	// contains filtered or unexported fields
}

Slide is the canonical handle for an open whole-slide image. Constructed via OpenFile (path) or Open (io.ReaderAt). Replaces the pre-v0.23 Tiler interface as the public return type of Open and OpenFile.

Concurrency contract: all accessor methods (Format, Images, Levels, Level, Associated, Metadata, ICCProfile) are safe to call concurrently. Tile reads via RawTile / RawTileInto are safe concurrently. Close must not race with in-flight tile reads.

func Open

func Open(r io.ReaderAt, size int64, opts ...Option) (*Slide, error)

Open parses r as a WSI file and returns a *Slide for the matching format. size is the total file size in bytes.

Dispatch probes each registered format in registration order; the first whose match function returns nil wins. Returns an error if no format claims the input (requires a format package to be imported, e.g. _ "github.com/wsilabs/opentile-go/formats/all").

func OpenFile

func OpenFile(path string, opts ...Option) (*Slide, error)

OpenFile opens path for reading and delegates to Open. The returned *Slide owns the underlying file handle (or memory map); Close releases it.

Default backing since v0.9 is BackingMmap: the file is memory-mapped read-only and tile reads become userspace memcpys from the mapped region — no pread(2) syscall per [Level.Tile] call. The kernel page cache handles paging in tile-data regions on first access; warm-cache reads hit RAM at memory-bandwidth speed.

Pass WithBacking(BackingPread) to opt out and use the v0.8 (and earlier) os.File + pread path. Required for filesystems that don't support mmap (some FUSE / network mounts) or when the caller specifically needs os.File truncation semantics.

Failure modes:

• mmap unavailable for this file (filesystem doesn't support it, or some platform-specific failure): returns ErrMmapUnavailable wrapping the underlying error. Callers wanting automatic fallback should retry with WithBacking(BackingPread).
• file truncated underneath an open mmap-backed *Slide: subsequent Tile() calls into the truncated region raise SIGBUS in the calling thread. WSI files don't get truncated under normal use; if your storage allows it, use BackingPread.

func (*Slide) Associated

func (s *Slide) Associated() []AssociatedImage

Associated returns the auxiliary images (label, macro, thumbnail, overview, ...) embedded in this slide.

func (*Slide) BestLevelForDownsample

func (s *Slide) BestLevelForDownsample(downsample float64) int

BestLevelForDownsample returns the index of the largest pyramid level whose Downsample factor is ≤ the requested value. Matches openslide.best_level_for_downsample semantics.

Returns 0 (L0) if every level's downsample exceeds the requested value (the caller wants higher resolution than the slide carries).

Shortcut for ImageBestLevelForDownsample(0, downsample).

Added in v0.25 alongside the ReadRegion family.

func (*Slide) Close

func (s *Slide) Close() error

Close releases resources held by the slide.

func (*Slide) DecodedTile

func (s *Slide) DecodedTile(level, tx, ty int, opts ...DecodeOption) (*decoder.Image, error)

DecodedTile returns the decoded pixel data for the tile at (level, tx, ty) within image 0. The output pixel format defaults to PixelFormatRGB; override via WithFormat. JPEG sources support IDCT-time scaling via WithScale.

Requires that a decoder for the level's Compression is registered. Blank-import github.com/wsilabs/opentile-go/decoder/all or the specific codec subpackage (e.g., decoder/jpeg) to enable. Returns ErrCodecNotRegistered (wrapped with the compression name) if not.

As of v0.27, format readers implementing the unexported decodedTiler interface (currently NDPI striped levels) take a fast pixel-cache path that avoids per-tile JPEG re-encoding + decoder-handle churn. Other formats and non-striped NDPI levels keep the original RawTile + fresh- decoder path, which is preserved unchanged.

func (*Slide) DecodedTileInto

func (s *Slide) DecodedTileInto(level, tx, ty int, dst *decoder.Image, opts ...DecodeOption) error

DecodedTileInto decodes a tile into a caller-provided destination Image. dst.Width / dst.Height must match the tile's decoded dimensions; mismatched sizes return decoder.ErrDestinationSize from the underlying decoder. dst.Format may be RGB or RGBA (decoders convert as needed).

func (*Slide) Format

func (s *Slide) Format() Format

Format returns the canonical format identifier.

func (*Slide) ICCProfile

func (s *Slide) ICCProfile() []byte

ICCProfile returns the embedded color profile bytes, or nil if the slide has none.

func (*Slide) ImageBestLevelForDownsample

func (s *Slide) ImageBestLevelForDownsample(image int, downsample float64) int

ImageBestLevelForDownsample is the multi-image variant of BestLevelForDownsample.

func (*Slide) ImageDecodedTile

func (s *Slide) ImageDecodedTile(image, level, tx, ty int, opts ...DecodeOption) (*decoder.Image, error)

ImageDecodedTile is the multi-image variant of DecodedTile.

v0.27 fast-path dispatch: when s.r implements decodedTiler and the fast path succeeds, returns its output directly. ErrUnsupported from the reader signals "no fast path for this level" and falls through to the v0.26 RawTile + fresh-decoder path. Any other error propagates.

func (*Slide) ImageDecodedTileInto

func (s *Slide) ImageDecodedTileInto(image, level, tx, ty int, dst *decoder.Image, opts ...DecodeOption) error

ImageDecodedTileInto is the multi-image variant of DecodedTileInto.

v0.27 fast-path dispatch: when s.r implements decodedTiler and the fast path succeeds, copies its output into dst. Otherwise routes through the v0.26 path which decodes directly into dst.

func (*Slide) ImageRangeTiles

func (s *Slide) ImageRangeTiles(ctx context.Context, image, level int) iter.Seq2[TilePos, TileResult]

ImageRangeTiles is the multi-image variant of RangeTiles.

func (*Slide) ImageRawTile

func (s *Slide) ImageRawTile(image, level, tx, ty int) ([]byte, error)

ImageRawTile returns the compressed tile bytes at the given image, level, and tile coordinates. Required for multi-image formats (OME-TIFF); single-image formats accept only image=0.

func (*Slide) ImageRawTileInto

func (s *Slide) ImageRawTileInto(image, level, tx, ty int, dst []byte) (int, error)

ImageRawTileInto fills dst with the compressed tile bytes at the given image, level, and tile coordinates. Returns the byte count written.

func (*Slide) ImageReadRegion

func (s *Slide) ImageReadRegion(image, level, x, y, w, h int, opts ...DecodeOption) (*decoder.Image, error)

ImageReadRegion is the multi-image variant of ReadRegion.

func (*Slide) ImageReadRegionInto

func (s *Slide) ImageReadRegionInto(image, level, x, y int, dst *decoder.Image, opts ...DecodeOption) error

ImageReadRegionInto is the multi-image variant of ReadRegionInto.

func (*Slide) ImageReadRegionScaled

func (s *Slide) ImageReadRegionScaled(image int, l0x, l0y, l0w, l0h, outW, outH int, opts ...DecodeOption) (*decoder.Image, error)

ImageReadRegionScaled is the multi-image variant of ReadRegionScaled.

func (*Slide) ImageReadRegionScaledInto

func (s *Slide) ImageReadRegionScaledInto(image int, l0x, l0y, l0w, l0h int, dst *decoder.Image, opts ...DecodeOption) error

ImageReadRegionScaledInto is the multi-image variant.

func (*Slide) ImageTileBodyInto

func (s *Slide) ImageTileBodyInto(image, level, tx, ty int, dst []byte) (int, error)

ImageTileBodyInto is the multi-image variant of TileBodyInto.

func (*Slide) ImageTileBodyMaxSize

func (s *Slide) ImageTileBodyMaxSize(image, level int) int

ImageTileBodyMaxSize is the multi-image variant of TileBodyMaxSize.

func (*Slide) ImageTileMaxSize

func (s *Slide) ImageTileMaxSize(image, level int) int

ImageTileMaxSize is the multi-image variant of TileMaxSize.

func (*Slide) ImageTilePrefix

func (s *Slide) ImageTilePrefix(image, level int) []byte

ImageTilePrefix is the multi-image variant of TilePrefix.

func (*Slide) ImageTileReader

func (s *Slide) ImageTileReader(image, level, tx, ty int) (io.ReadCloser, error)

ImageTileReader is the multi-image variant of TileReader.

func (*Slide) ImageWarmLevel

func (s *Slide) ImageWarmLevel(image, level int) error

ImageWarmLevel pre-warms the page cache for the given image + level.

func (*Slide) Images

func (s *Slide) Images() []Image

Images returns the main pyramids carried by this file. Always returns at least one Image; multi-image OME-TIFF exposes multiple. Index 0 is the legacy Levels() / Level(i) shortcut target.

func (*Slide) Level

func (s *Slide) Level(i int) (Level, error)

Level is a shortcut for s.Images()[0].Levels[i].

func (*Slide) Levels

func (s *Slide) Levels() []Level

Levels is a shortcut for s.Images()[0].Levels.

func (*Slide) Metadata

func (s *Slide) Metadata() Metadata

Metadata returns the cross-format metadata view.

func (*Slide) RangeTiles

func (s *Slide) RangeTiles(ctx context.Context, level int) iter.Seq2[TilePos, TileResult]

RangeTiles returns a range-over-function iterator over all tiles in the given level within image 0.

func (*Slide) RawTile

func (s *Slide) RawTile(level, tx, ty int) ([]byte, error)

RawTile returns the compressed tile bytes at the given level and tile coordinates within image 0.

func (*Slide) RawTileInto

func (s *Slide) RawTileInto(level, tx, ty int, dst []byte) (int, error)

RawTileInto fills dst with the compressed tile bytes at the given level and tile coordinates within image 0. Returns the byte count written.

func (*Slide) ReadRegion

func (s *Slide) ReadRegion(level, x, y, w, h int, opts ...DecodeOption) (*decoder.Image, error)

ReadRegion returns the decoded pixel data for the rectangle (x, y)-(x+w, y+h) at the given level. ALL FOUR coords/dims are at the level's own resolution. Use ReadRegionScaled if you have L0 coords or want arbitrary output dimensions.

The rectangle may extend beyond the level's bounds; out-of-bounds pixels are white-filled (0xFF, 0xFF, 0xFF). Returns ErrRegionEmpty if the entire rectangle is outside the level.

Requires a registered decoder for the level's Compression — same constraint as DecodedTile.

Internally spans the relevant tiles and decodes each once. Adjacent ReadRegion calls do NOT share a decoded-tile cache; for high-throughput patterns use the v0.26 ScaledStrips iterator when it ships.

Shortcut for ImageReadRegion(0, level, x, y, w, h, opts...).

Added in v0.25.

func (*Slide) ReadRegionInto

func (s *Slide) ReadRegionInto(level, x, y int, dst *decoder.Image, opts ...DecodeOption) error

ReadRegionInto decodes a region into a caller-provided destination Image. (x, y) at the level's resolution; the region size is taken from dst.Width × dst.Height. dst.Format may be RGB or RGBA.

Shortcut for ImageReadRegionInto(0, level, x, y, dst, opts...).

func (*Slide) ReadRegionScaled

func (s *Slide) ReadRegionScaled(l0x, l0y, l0w, l0h, outW, outH int, opts ...DecodeOption) (*decoder.Image, error)

ReadRegionScaled reads an L0-coord rectangle and resamples it to (outW, outH). The library picks the best source pyramid level via BestLevelForDownsample, reads at that level, then resamples to the target.

All input coords (l0x, l0y, l0w, l0h) are at L0 (full-resolution) coordinates. Output dimensions (outW, outH) are the desired final pixel size — any value, regardless of level resolutions.

Use WithResampleKernel to choose the resample quality. Default: resample.Lanczos. Use WithFormat / WithScale as with DecodedTile.

Out-of-bounds: the L0 rectangle is auto-clipped against the slide dimensions before level selection. Out-of-bounds output pixels are white-filled.

Returns ErrRegionEmpty if the L0 rectangle has no in-bounds pixels.

Shortcut for ImageReadRegionScaled(0, l0x, l0y, l0w, l0h, outW, outH, opts...).

Added in v0.25.

func (*Slide) ReadRegionScaledInto

func (s *Slide) ReadRegionScaledInto(l0x, l0y, l0w, l0h int, dst *decoder.Image, opts ...DecodeOption) error

ReadRegionScaledInto fills caller-provided dst. dst.Width / dst.Height define the output dimensions.

func (*Slide) ScaledStrips

func (s *Slide) ScaledStrips(
	l0Rect image.Rectangle,
	outSize image.Point,
	stripHeight int,
	opts ...StripOption,
) *StripIterator

ScaledStrips returns an iterator over a slide's L0 rectangle, scaled to outSize, in horizontal strips of stripHeight rows. See the *StripIterator type for the iteration API.

Out-of-bounds l0Rect: auto-clipped to slide bounds; entirely out-of-bounds yields all-white strips.

Internally manages parallel decode workers + a per-iterator tile cache + lookahead pre-fetch. Caller must call Close on the returned iterator.

Shortcut for ImageScaledStrips(0, ...) — multi-image variant is deferred to a future release.

Added in v0.26.

func (*Slide) TileBodyInto

func (s *Slide) TileBodyInto(level, tx, ty int, dst []byte) (int, error)

TileBodyInto fills dst with the tile body bytes at the given level and tile coordinates within image 0.

func (*Slide) TileBodyMaxSize

func (s *Slide) TileBodyMaxSize(level int) int

TileBodyMaxSize returns the upper bound on tile-body (no prefix) bytes at the given level within image 0.

func (*Slide) TileMaxSize

func (s *Slide) TileMaxSize(level int) int

TileMaxSize returns the upper bound on tile byte size at the given level within image 0. Used for sizing caller-provided destination buffers passed to RawTileInto.

func (*Slide) TilePrefix

func (s *Slide) TilePrefix(level int) []byte

TilePrefix returns the JPEG-tables prefix bytes shared across all tiles at the given level within image 0. nil if the codec has no prefix.

func (*Slide) TileReader

func (s *Slide) TileReader(level, tx, ty int) (io.ReadCloser, error)

TileReader returns a streaming io.ReadCloser for the compressed tile at the given level and tile coordinates within image 0.

func (*Slide) UnwrapReader

func (s *Slide) UnwrapReader() any

UnwrapReader returns the underlying format-specific reader. Format packages use this to chain-walk through *Slide to their own concrete reader type (e.g., bif.MetadataOf(slide) walks the chain to find the BIF *Tiler).

func (*Slide) WarmLevel

func (s *Slide) WarmLevel(i int) error

WarmLevel pre-warms the page cache for level i within image 0. Hint-only.

type StripIterator

type StripIterator struct {
	// contains filtered or unexported fields
}

StripIterator yields horizontal strips of a slide scaled to a target output resolution. Not safe for concurrent use; one goroutine drives Next() / Close() per iterator.

func (*StripIterator) Close

func (it *StripIterator) Close() error

Close releases the iterator's workers + cache. Safe to call multiple times.

func (*StripIterator) Next

func (it *StripIterator) Next() (*decoder.Image, error)

Next returns the next decoded strip image. Returns io.EOF when all strips have been consumed, and io.ErrClosedPipe after Close.

func (*StripIterator) Strips

func (it *StripIterator) Strips() int

Strips returns the total number of strips this iterator will yield.

type StripOption

type StripOption func(*stripConfig)

StripOption configures a ScaledStrips iterator. See WithStripWorkers, WithStripLookahead, WithStripIDCTScale, WithStripKernel, WithStripContext.

func WithStripContext

func WithStripContext(ctx context.Context) StripOption

WithStripContext binds the iterator's worker pool to a cancellation context. Default: context.Background().

Cancelling ctx aborts in-flight Next() calls with ctx.Err(). Workers also respond to *StripIterator.Close().

func WithStripIDCTScale

func WithStripIDCTScale(scale int) StripOption

WithStripIDCTScale overrides the auto-selected IDCT-time scale factor for JPEG sources. Valid: 1, 2, 4, 8. Default 0 = auto- select based on output downsample.

Non-JPEG sources ignore this option silently.

func WithStripKernel

func WithStripKernel(k resample.Kernel) StripOption

WithStripKernel sets the resample kernel applied after the source-tile decode step (when IDCT alone doesn't reach the target output dims). Default: resample.Lanczos.

func WithStripLookahead

func WithStripLookahead(strips int) StripOption

WithStripLookahead sets how many strips ahead the iterator pre-fetches source tiles for. Default: 2. 0 disables lookahead entirely (workers idle between Next() calls). Higher values trade memory for steady-state throughput on slow consumers.

func WithStripWorkers

func WithStripWorkers(n int) StripOption

WithStripWorkers sets the number of parallel source-tile decode workers. Default: runtime.NumCPU(). Values < 1 are clamped to 1.

type TileCoord

type TileCoord struct {
	X, Y int
	Z    int
	C    int
	T    int
}

TileCoord identifies a tile by its position in the multi- dimensional WSI space. X and Y are the existing 2D grid position; Z, C, and T select among focal planes (Z), fluorescence / spectral channels (C), and time points (T) respectively.

Z, C, T default to zero — a TileCoord literal {X: x, Y: y} addresses the same tile that Level.Tile(x, y) returns. Zero is the "nominal" / "first" / "T=0" plane in every dimension.

Valid ranges per axis:

0 <= X < Level.Grid().W
0 <= Y < Level.Grid().H
0 <= Z < Image.SizeZ()
0 <= C < Image.SizeC()
0 <= T < Image.SizeT()

Out-of-range values yield *TileError wrapping ErrDimensionUnavailable (axis is unsupported on this Image — SizeZ/C/T == 1) or ErrTileOutOfBounds (axis exists but the index is past its declared size).

Added in v0.7 alongside Level.TileAt and Image.SizeZ/SizeC/SizeT.

func (TileCoord) String

func (t TileCoord) String() string

type TileError

type TileError struct {
	Level int
	X, Y  int
	Err   error
}

TileError wraps a per-tile failure with the (level, x, y) that produced it. Consumers use errors.As to extract the coordinates and errors.Is against the exported sentinels to branch on the underlying cause.

func (*TileError) Error

func (e *TileError) Error() string

func (*TileError) Unwrap

func (e *TileError) Unwrap() error

type TilePos

type TilePos struct{ X, Y int }

TilePos is a (column, row) pair returned by RangeTiles.

type TileResult

type TileResult struct {
	Bytes []byte
	Err   error
}

TileResult carries the yield from RangeTiles.