bifxml

Documentation

Overview

Package bifxml parses the XMP metadata embedded in Ventana BIF TIFF IFDs.

BIF files carry two XMP payloads:

• IFD 0 XMP: an <iScan> element with scanner settings and AOI geometry.
• IFD 2 XMP: an <EncodeInfo> element with tile grid layout, tile joints, serpentine frame ordering, and AOI origin coordinates.

Parsing is lenient: missing attributes produce zero/default values rather than errors. Unknown attributes are collected in IScan.RawAttributes for caller use (e.g. metadata mirroring).

The two public entry points are ParseIScan and ParseEncodeInfo.

Index

• type AOI
• type AoiInfo
• type AoiOrigin
• type EncodeInfo
  • func ParseEncodeInfo(xmp []byte) (*EncodeInfo, error)
• type Frame
• type IScan
  • func ParseIScan(xmp []byte) (*IScan, error)
• type ImageInfo
• type TileJoint

Types

type AOI

type AOI struct {
	Index         int
	Left, Top     int
	Right, Bottom int
}

AOI is one scanned region from an <AOI<N>> child of <iScan>.

type AoiInfo

type AoiInfo struct {
	XImageSize, YImageSize int // tile width/height in pixels
	NumRows, NumCols       int
	PosX, PosY             int
}

AoiInfo carries the tile-grid dimensions from <AoiInfo> inside <SlideInfo>.

type AoiOrigin

type AoiOrigin struct {
	Index            int
	OriginX, OriginY int
}

AoiOrigin is the pixel origin for one AOI region, from <AoiOrigin><AOI<N>>.

type EncodeInfo

type EncodeInfo struct {
	Ver int // Must be >= 2 per spec; ParseEncodeInfo returns an error if < 2.

	AoiInfo AoiInfo // from <SlideInfo><AoiInfo>

	ImageInfos []ImageInfo // one per <SlideStitchInfo><ImageInfo>
	AoiOrigins []AoiOrigin // one per <AoiOrigin><AOI<N>>
}

EncodeInfo holds the tile-encoding block from IFD 2 XMP.

func ParseEncodeInfo

func ParseEncodeInfo(xmp []byte) (*EncodeInfo, error)

ParseEncodeInfo parses the XMP byte slice from IFD 2 and returns an EncodeInfo.

The document root must be <EncodeInfo Ver="N">. Returns an error if Ver < 2 per the BIF spec requirement. Parsing otherwise proceeds leniently.

Actual nesting in BIF fixtures (confirmed against Ventana-1 and OS-1):

SlideStitchInfo
  ImageInfo  → TileJointInfo children
  FrameInfo  → Frame children  (sibling of ImageInfo, not a child)

The parser associates each FrameInfo's frames with the last ImageInfo that shares the same AOIIndex. When FrameInfo carries no AOIIndex (or there is only one ImageInfo), frames are appended to the first/only ImageInfo. Frames are stored in the flat []Frame slice on ImageInfo for ergonomic access.

type Frame

type Frame struct {
	Col, Row int
	Z        int
}

Frame is one <Frame> element inside a <FrameInfo> child of <ImageInfo>. Col and Row are extracted from the XY="C,R" attribute.

type IScan

type IScan struct {
	ScannerModel  string  // empty if missing
	Magnification float64 // 0 if missing
	ScanRes       float64 // microns per pixel; 0 if missing

	ScanWhitePoint        uint8 // 0..255 when present; consult ScanWhitePointPresent to detect absence
	ScanWhitePointPresent bool  // false when the attribute is absent entirely

	ZLayers      int     // default 1; 1 = single nominal focus plane (not volumetric)
	ZSpacing     float64 // microns per Z-plane step (per <iScan>/@Z-spacing); 0 when absent
	BuildVersion string
	BuildDate    string
	UnitNumber   string
	UserName     string

	AOIs []AOI // one per <AOI0>, <AOI1>, ... child element

	// RawAttributes contains every iScan XML attribute that does not map to a
	// typed field above, keyed by the exact attribute name as it appears in the
	// XML. Callers can use this to mirror all metadata without hard-coding every
	// attribute name.
	RawAttributes map[string]string
}

IScan holds the scanner settings block from IFD 0 XMP. It appears either as <Metadata><iScan ...> or as a bare <iScan ...> root.

func ParseIScan

func ParseIScan(xmp []byte) (*IScan, error)

ParseIScan parses the XMP byte slice from IFD 0 and returns an IScan.

The parser tolerates two layouts:

• <Metadata><iScan ...> (Ventana-1 / spec-compliant BIF)
• bare <iScan ...> as the document root (OS-1 / legacy BIF)

Missing or empty attributes produce zero values. The ScanWhitePoint field's value must be interpreted with ScanWhitePointPresent: when Present is false, the attribute was absent (caller's responsibility to apply a default). Unknown attributes are collected in RawAttributes.

type ImageInfo

type ImageInfo struct {
	AOIScanned       bool
	AOIIndex         int
	NumRows, NumCols int
	Width, Height    int
	PosX, PosY       int

	Joints []TileJoint
	Frames []Frame
}

ImageInfo carries per-AOI stitch information from <ImageInfo> inside <SlideStitchInfo>. TileJoints contains every <TileJointInfo> child; Frames contains every <Frame> from the nested <FrameInfo> child.

type TileJoint

type TileJoint struct {
	FlagJoined         bool
	Direction          string // pass-through; "LEFT"|"RIGHT"|"UP"|"DOWN" or any value
	Tile1, Tile2       int
	OverlapX, OverlapY int
}

TileJoint is one <TileJointInfo> entry inside an <ImageInfo>. Direction is stored verbatim from the XML; all four compass values (LEFT, RIGHT, UP, DOWN) are valid per the BIF whitepaper. Openslide rejects LEFT and DOWN — we do not.