Semantic objects and WSI

v0.2.12 keeps decoded pixels distinct from domain interpretation. SEG, Parametric Map, and RT Dose objects render a stored-pixel preview first and expose declared semantic metadata in a separate opt-in context. WSI context positions the selected tile without pretending to reconstruct a whole slide.

Stored-pixel preview is the default

The semantic-context response declares default_mode: "pixel_preview" and states that the preview preserves stored values. This avoids silently applying an inferred meaning that the source object or geometry does not support.

Display windowing can normalize pixels for viewing; the raw endpoint remains the decoded sample transport. Neither path by itself applies Real World Value Mapping, dose scaling, segmentation meaning, or clinical interpretation.

Segmentation context

For SEG objects, the context can report:

• segmentation and fractional type;
• declared segment number, label, description, coded category/type, algorithm, and recommended display values;
• per-frame segment and source-image mappings; and
• resolved DICOM references.

For the selected SEG frame, explicit per-frame derivation references take precedence. If the SEG instead declares source instances at the top level, the viewer can resolve classic single-frame source series by compatible Frame of Reference, Image Position (Patient), Image Orientation (Patient), and Pixel Spacing. Source and SEG matrices do not need identical dimensions.

An overlay becomes eligible only when exactly one local source frame and a compatible patient-coordinate transform are validated. Missing, ambiguous, non-coplanar, non-overlapping, or otherwise incompatible geometry produces an explicit unavailable reason.

When eligible, the viewer decodes the binary or fractional mask and nearest-neighbor resamples it through patient coordinates into a transparent, source-sized PNG. Pixel Preview remains the default. Selecting Semantic Context composes the source display frame and mask while keeping the active logical frame attached to the SEG object.

Eligibility means the declared mapping can be displayed by the viewer. It does not validate clinical segmentation correctness. Recommended Display CIELab values are not yet interpreted. ROI editing, interactive window/level, and cine are disabled while the composed view is active because those controls require separate source-image state contracts.

Parametric Map context

Parametric Map context exposes the stored numeric range and declared Real World Value Mapping items, including label, units, slope/intercept or LUT data, and mapped stored-value bounds when present.

Mappings are reported, not inferred. The default viewport still shows the stored-pixel preview, and Real World Value Mapping context does not assert quantitative or clinical validity.

RT Dose context

RT Dose context can summarize dose units, dose type, summation type, Dose Grid Scaling, frame offsets, grid geometry, resolved references, and whether overlay geometry is eligible.

The viewer does not establish prescription correctness, treatment-planning correctness, or clinical acceptability. Ambiguous or incompatible geometry disables overlay eligibility.

Whole Slide Microscopy context

For a selected WSI frame, the viewer can report:

• Total Pixel Matrix dimensions and origin;
• the tile rectangle within that matrix;
• pyramid and derived level information;
• optical-path and focal-plane identity;
• slide coordinate and pixel spacing context;
• locally resolved companion objects; and
• bounded warnings or truncation state.

The minimap uses this metadata to show where the selected tile lies. It does not fetch neighboring tiles, stitch a mosaic, support slide-wide panning, or reconstruct the Total Pixel Matrix.

References describe identity, not rendering

Typed DICOM references preserve declared one-based frame numbers and resolve local matches to validated zero-based viewer frames. An empty local match means the declaration was understood but its target is not in the current scan.

Reference resolution supports navigation and semantic context; it does not by itself apply presentation states, registration transforms, structured-report meaning, or other object-family semantics.