decoder

Documentation

Overview

Package decoder defines the public Decoder interface and registry for opentile-go's pluggable codec layer. Codec-specific subpackages (decoder/jpeg, decoder/jpeg2000, decoder/lzw, etc.) register themselves into this package's registry at init() time.

Most consumers wanting "all codecs available" should blank-import the decoder/all subpackage:

import _ "github.com/wsilabs/opentile-go/decoder/all"

Smaller-footprint consumers can blank-import only the codec subpackages they need.

The decoder layer backs Slide.DecodedTile / ReadRegion / ScaledStrips. It is also usable standalone for third-party Go pathology code that wants decoded tile bytes from opentile-go-readable WSI files.

Design spec: docs/superpowers/specs/2026-05-23-opentile-go-v22-decoder-resample-lift-design.md.

Index

• Variables
• func Register(f Factory)
• func Registered() []string
• type DecodeOptions
• type Decoder
• type Factory
  • func Get(name string) (Factory, bool)
  • func GetByCompressionTag(tag uint16) (Factory, bool)
• type Image
  • func NewImage(w, h int) *Image
  • func NewImageFormat(w, h int, fmt PixelFormat) *Image
• type PixelFormat

Variables

var (
	// ErrCodecUnavailable is returned by the stub Decoder of a codec
	// subpackage that was excluded from this build (via -tags
	// no<codec> or -tags nocgo). The wrapping error message names the
	// codec and the build tag to remove.
	ErrCodecUnavailable = errors.New("decoder: codec not available in this build")

	// ErrUnsupportedScale is returned by Decode when DecodeOptions.Scale
	// is not a value the decoder supports. JPEG decoders accept 1, 2,
	// 4, 8; other decoders accept only 1.
	ErrUnsupportedScale = errors.New("decoder: scale factor not supported by this codec")

	// ErrUnsupportedFormat is returned by Decode when DecodeOptions.Format
	// is not producible by the decoder.
	ErrUnsupportedFormat = errors.New("decoder: pixel format not supported by this codec")

	// ErrDestinationSize is returned by Decode when DecodeOptions.Dst
	// is non-nil but its dimensions don't match the decoded size.
	ErrDestinationSize = errors.New("decoder: dst Image dimensions don't match decoded size")

	// ErrCorruptInput is returned by Decode when the compressed bytes
	// can't be parsed.
	ErrCorruptInput = errors.New("decoder: corrupt input data")
)

Sentinel errors used by Decode implementations. Wrap with fmt.Errorf("...: %w", ErrXxx) for codec-specific context; callers detect via errors.Is.

Functions

func Register

func Register(f Factory)

Register adds a factory to the global decoder registry. Called from each codec subpackage's init(). Last-in-wins on name or tag collision (intentional — lets consumers shadow a default decoder with a custom impl).

func Registered

func Registered() []string

Registered returns the canonical names of every registered decoder. Order is unspecified.

Types

type DecodeOptions

type DecodeOptions struct {
	// Scale is the in-codec downscale factor. Valid values: 1, 2, 4, 8;
	// other values return ErrUnsupportedScale. The zero value (0) is
	// treated as 1 (no scaling). Decode produces ceil(srcDim/Scale).
	// Supported by: jpeg (libjpeg IDCT fast-scale), jpeg2000 and htj2k
	// (DWT resolution-level decode, 1/2^log2(Scale), box-finishing any
	// residual when the codestream has too few levels). Other decoders
	// return ErrUnsupportedScale if Scale != 1.
	Scale int

	// Format is the requested output pixel format. Decoders return
	// ErrUnsupportedFormat if they can't produce the requested format.
	// Today: PixelFormatRGB and PixelFormatRGBA are universal.
	Format PixelFormat

	// Dst is an optional caller-supplied destination Image. If nil, the
	// decoder allocates. If non-nil and its dimensions match the
	// decoded size, the decoder writes into Dst.Pix and returns Dst.
	// Mismatched dimensions return ErrDestinationSize.
	Dst *Image
}

DecodeOptions configures a single Decode call. The zero value is valid (Scale=1, Format=PixelFormatRGB, Dst=nil → allocate fresh RGB).

type Decoder

type Decoder interface {
	// Decode the compressed bytes per opts. If opts.Dst is non-nil and
	// matches the decoded dimensions, writes into Dst and returns it;
	// otherwise allocates a fresh Image.
	Decode(compressed []byte, opts DecodeOptions) (*Image, error)

	// Close releases the decoder's internal state. Safe to call
	// multiple times. After Close, further Decode calls return an
	// error.
	Close() error
}

Decoder turns compressed tile bytes into a decoded Image. Decoders are NOT safe for concurrent use; callers running concurrent decodes on the same slide should construct one Decoder per goroutine via Factory.New().

type Factory

type Factory interface {
	// Name is the canonical codec identifier (e.g., "jpeg",
	// "jpeg2000", "lzw"). Lowercase.
	Name() string

	// TIFFCompressionTags lists the TIFF Compression tag values this
	// factory's decoder handles. Multiple tags allowed (e.g., JPEG
	// 2000 is both 33003 (Aperio) and 34712 (libtiff)). Empty for
	// non-TIFF-associated codecs.
	TIFFCompressionTags() []uint16

	// New returns a fresh Decoder instance. Each call returns a new
	// instance with its own state. Decoders are NOT safe for
	// concurrent use across goroutines.
	New() Decoder
}

Factory constructs decoders for a specific codec. Codec subpackages register a Factory in their init() function.

func Get

func Get(name string) (Factory, bool)

Get returns the factory registered for the given codec name, or (nil, false) if none is registered.

func GetByCompressionTag

func GetByCompressionTag(tag uint16) (Factory, bool)

GetByCompressionTag returns the factory registered for the given TIFF Compression tag value, or (nil, false) if none is registered.

type Image

type Image struct {
	Width, Height int
	Stride        int // bytes per row; may over-allocate for SIMD alignment
	Format        PixelFormat
	Pix           []byte // len(Pix) == Stride * Height
}

Image is a decoded raster bitmap.

func NewImage

func NewImage(w, h int) *Image

NewImage returns a freshly-allocated Image with PixelFormatRGB and Stride = w * 3. The Pix slice is zero-filled.

func NewImageFormat

func NewImageFormat(w, h int, fmt PixelFormat) *Image

NewImageFormat returns a freshly-allocated Image with the requested format. Stride is set to the format's bytes-per-pixel times w.

type PixelFormat

type PixelFormat int

PixelFormat selects the in-memory pixel layout of a decoded Image.

const (
	// PixelFormatRGB is 3 bytes per pixel, no alpha channel.
	// The default — WSI imagery is opaque so alpha is wasted memory.
	PixelFormatRGB PixelFormat = iota

	// PixelFormatRGBA is 4 bytes per pixel with alpha = 0xFF.
	// Use when interop with Go stdlib image.NRGBA matters.
	PixelFormatRGBA
)