format

Documentation

Overview

Package format defines the internal Reader interface every opentile-go format implementation provides. The public opentile.Slide type wraps a Reader and delegates method calls. This interface is internal to opentile-go; external callers use *opentile.Slide.

Each format package (formats/svs, formats/ometiff, etc.) registers itself via Register in its init() function. opentile.OpenFile and opentile.Open dispatch through OpenAny, which probes each registered format in registration order.

Replaces the public Tiler interface as of opentile-go v0.23.

Index

• Variables
• func Register(name string, match Match, opener Opener)
• func RegisterFallback(name string, match Match, opener Opener)
• type Config
• type Match
• type Opener
• type Reader
  • func OpenAny(r io.ReaderAt, size int64, cfg *Config) (Reader, error)

Variables

var ErrUnknownFormat = errors.New("opentile: unknown format")

ErrUnknownFormat is returned by OpenAny when no registered format claims the input.

Functions

func Register

func Register(name string, match Match, opener Opener)

Register adds a format to the global registry. Called from each format package's init() function. Registration order matters: OpenAny dispatches in registration order; first Match wins.

func RegisterFallback

func RegisterFallback(name string, match Match, opener Opener)

RegisterFallback adds a format to the fallback registry. Fallback formats are only considered by OpenAny when no main-registry format matches. Use this for catch-all detectors (e.g. generic-tiff) that must not shadow more-specific formats regardless of import order.

Types

type Config

type Config struct {
	// TileSize is the requested output tile size (W, H in pixels) and
	// whether the caller explicitly set one. Mirrors opentile.Config.TileSize().
	TileSize    opentile.Size
	HasTileSize bool

	// CorruptTilePolicy controls how corrupt-edge tiles are reported.
	CorruptTilePolicy opentile.CorruptTilePolicy

	// NDPISynthesizedLabel controls whether NDPI Associated() includes a
	// synthesized label cropped from the overview. Default true.
	NDPISynthesizedLabel bool

	// Backing reports the I/O backend selected via WithBacking.
	Backing opentile.Backing
}

Config is passed from opentile.Open's option-config down into each format's Opener. Fields mirror the existing opentile.Config that FormatFactory.Open accepted; preserved verbatim for format packages.

type Match

type Match func(r io.ReaderAt, size int64) error

Match returns nil if the format applies to this input, or an error describing why it doesn't (the error is informational; only nil/non-nil determines dispatch).

type Opener

type Opener func(r io.ReaderAt, size int64, cfg *Config) (Reader, error)

Opener constructs a Reader from a parsed input. r is the raw bytes; cfg is the option-derived config. Returns a non-nil Reader on success.

type Reader

type Reader interface {
	Format() opentile.Format
	Images() []opentile.Image
	Level(image, level int) (opentile.Level, error)
	Associated() []opentile.AssociatedImage
	Metadata() opentile.Metadata
	ICCProfile() []byte
	WarmLevel(image, level int) error

	// Raw tile access.
	ImageRawTile(image, level, tx, ty int) ([]byte, error)
	ImageRawTileInto(image, level, tx, ty int, dst []byte) (int, error)

	// Splice-prefix optimization family.
	ImageTileMaxSize(image, level int) int
	ImageTilePrefix(image, level int) []byte
	ImageTileBodyMaxSize(image, level int) int
	ImageTileBodyInto(image, level, tx, ty int, dst []byte) (int, error)
	ImageTileReader(image, level, tx, ty int) (io.ReadCloser, error)

	// Range-over-function iterator.
	ImageRangeTiles(ctx context.Context, image, level int) iter.Seq2[opentile.TilePos, opentile.TileResult]

	Close() error
}

Reader is the contract every format implementation provides. The public *opentile.Slide type wraps a Reader and delegates all method calls. Internal to opentile-go.

In v0.24, Level and Image are value-type structs; tile reads happen at the Reader level with (image, level) addressing.

func OpenAny

func OpenAny(r io.ReaderAt, size int64, cfg *Config) (Reader, error)

OpenAny probes registered formats in registration order. The first whose Match returns nil wins; its Opener is invoked. Fallback formats are only considered when no main-registry format matches. Returns ErrUnknownFormat if no format matches.