Semantic objects and WSI

v0.4.1 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. RT Dose and Parametric Map volumes can also be drawn as colorwash overlays on the images they cover. 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 normalizes pixels for viewing, and raw frames carry the decoded samples. Neither rewrites pixel values with a Real World Value Mapping, dose scaling, or segmentation meaning. Declared mappings are reported separately, and the viewer uses them for the pixel readout, for window/level in real-world units, and for colorwash overlays. None of these establishes 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 display color;
• per-frame segment and source-image mappings;
• resolved DICOM references; and
• warnings about how the object is displayed.

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. Each segment is painted in its Recommended Display CIELab Value converted to sRGB, else its Recommended Display Grayscale Value, else a fixed palette color. 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.

A FRACTIONAL SEG that declares a Maximum Fractional Value above 1 but stores only 0 and 1 across the entire object is drawn as a binary mask, and the context shows a warning. The declared attributes are reported unchanged, a binary-valued frame within a genuinely fractional object does not trigger this, and genuine fractional opacity and ordinary pixel previews are unchanged.

Eligibility means the declared mapping can be displayed by the viewer. It does not validate clinical segmentation correctness. 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. Separate Real World Value Mapping instances that a Parametric Map references are also summarized.

The default viewport still shows the stored-pixel preview. On that preview, window/level works in the map’s unit with a legend, and the pixel readout reports the mapped value. Mappings are reported, not inferred, and do not assert quantitative or clinical validity.

RT Dose context

RT Dose context can summarize dose units, dose type, summation type, Dose Grid Scaling, grid dimensions, spacing, frame offsets, patient geometry, resolved references, and whether a colorwash overlay is eligible. Its stored-pixel preview uses Dose Grid Scaling for the readout and window/level in Gy or the declared Dose Units.

The viewer does not establish prescription correctness, treatment-planning correctness, or clinical acceptability.

Colorwash overlays

RT Dose and Parametric Map volumes decorate the images they cover rather than replacing them. A volume is a stack of parallel planes: an RT Dose grid from its position, orientation, pixel spacing, and Grid Frame Offset Vector, or a Parametric Map from per-frame positions that share orientation, spacing, and in-plane origin.

A displayed image in the same Frame of Reference, in any orientation, is resampled trilinearly through patient coordinates, and each sample is converted through the volume’s preferred mapping (Dose Grid Scaling for RT Dose). Colors follow a viridis legend on one scale for every slice: the RT Dose legend spans zero to the grid’s maximum dose with zero dose transparent, and the Parametric Map legend spans the minimum to maximum mapped value. Pixels outside the volume or without a mapped value are transparent.

The Overlay bar offers the eligible volumes that cover a frame of the active image, turns one on, and sets its opacity. A color bar shows the unit. A slice that the volume does not reach shows a note instead of a layer. The colorwash is drawn on its own layer, so window/level, cine, ROIs, and viewport transforms keep working. Show dose on source image or Show map on source image in the volume’s Semantic Context opens a covered image with the overlay on.

A volume is ineligible when its frames cannot be decoded, a dose grid has no positive dose, a Parametric Map lacks a usable mapping on every frame in one unit, or the displayed image lies in another Frame of Reference or lacks geometry. Eligibility means the declared geometry and mapping can be displayed; it is not dose verification or clinical validation.

Presentation state annotations

Grayscale and Color Softcopy Presentation States decorate the images they reference with graphic and text annotations. dcmview draws the objects positioned in image pixel units: points, polylines, interpolated curves, circles, ellipses, and text with a bounding box or an anchor point.

An annotation item applies to the images of its own Referenced Image Sequence. An item without one applies to every image listed in the state’s Referenced Series Sequence. A reference without frame numbers covers every frame of the image. Images are matched by SOP Instance UID among the files in the scan.

The Annotations bar offers the states that annotate the active image, one at a time and off until chosen, and steps through the shown state’s annotation items. Shapes are drawn in image coordinates, so viewport transforms apply to them; text and point marks stay upright. The presentation state’s Semantic Context lists its layers, annotation items, and annotated local frames.

Only the annotations are applied. The state’s window, shutter, LUTs, displayed area, and spatial transformation are not, so the image keeps the viewer’s own presentation. Objects in DISPLAY units need the displayed area to be placed and are counted instead of drawn. Only the standard’s referencing conventions are followed. Drawing an annotation does not validate the finding it marks.

In a masked session (--mask), a state’s text objects are not drawn, because they are free text placed on the image. Semantic Context counts them as hidden, masks the content creator’s name, and shifts the creation date. Graphics are still drawn.

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 images, grouped as label, overview, thumbnail, volume, and other roles, which open in the viewer; and
• bounded warnings or truncation state.

In a masked session (--mask), slide label and overview images are not shown, because they photograph the slide label with its identifiers. They stay in the file list as unsupported, with tags available under the masking rules.

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 lists refresh as discovery progresses.

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.