Crate wsi_dicom_annotations 

wsi-dicom-annotations

DICOM whole-slide workflow · API documentation

This checkout is version 0.2.1, including the shared metadata reader and headless CLI. The published 0.1.4 library remains available under its original MIT/Apache-2.0 licenses; see License for the new release’s licensing.

wsi-dicom-annotations provides UI-independent Rust models, readers, writers, and conversion boundaries for DICOM Whole Slide Microscopy derived objects:

• Microscopy Bulk Simple Annotations (ANN)
• Segmentation (SEG)
• Comprehensive 3D Structured Reports (SR)
• Parametric Maps (PM)
• explicitly profiled pathology and QuPath GeoJSON conversion

The default parametric-map feature includes profiled TIFF, NPY, Zarr, and tiled-raster PM conversion. Applications that only need ANN/SEG/SR and GeoJSON conversion can disable default features to avoid those raster dependencies.

Applications provide an existing DICOM VL Whole Slide Microscopy instance as the source context. The crate preserves Study and Frame of Reference identity while assigning new Series and SOP Instance identities to derived objects. For 2D ANN in the VOLUME pixel-origin interpretation, the writer preserves the exact referenced source SOP Class and Instance UIDs and copies a valid source Frame of Reference UID and Container Identifier when present. It omits either optional identity when the source omits it; these copied attributes aid viewer association and do not replace the normative 2D image reference.

Headless annotation CLI

This repository also owns wsi-annotation-probe, a standalone command-line package with no viewer or GUI dependencies:

cargo build -p wsi-annotation-probe --bin annotation_probe --locked
cargo test -p wsi-annotation-probe --locked

target/debug/annotation_probe supports inspect, roundtrip, convert-geojson, and convert-raster. It preserves the versioned JSON stdout reports and exit codes used by wsi-annotation-interop; diagnostics go to stderr. Newly converted objects identify the producer as Frames / Annotation Probe and use the CLI package version. Existing DICOM identities are retained by the inspection and roundtrip paths.

metadata::open_metadata_object is the shared bounded, pixel-free metadata reader for this library and the viewer. Its API documents admission limits and error types.

Checked editing and derived-object identity

Invariant-bearing ANN collections are edited atomically. Replace point or polygon geometry with AnnotationGroup::replace_points or AnnotationGroup::replace_polygons, and replace document groups with AnnotationDocument::replace_group or AnnotationDocument::replace_groups. An invalid replacement returns an error and leaves the original value intact.

New ANN, SEG, SR, and PM objects use a neutral library producer by default. Applications should identify themselves explicitly when publishing derived objects:

use wsi_dicom_annotations::{DerivedObjectProducer, Result};

let producer = DerivedObjectProducer::new(
    71,
    "Example Pathology",
    "Example Workstation",
    "WORKSTATION-1",
    "3.0",
)?
.with_series_description("Reviewed annotations")?;
// Apply the same value with `document.with_producer(producer)` to ANN, SEG,
// SR, or feature-gated PM documents before writing.

PathologyDicomDocuments::with_producers applies distinct caller-owned ANN, SEG, and SR series metadata to a companion-document set before publication.

SEG-to-ANN conversion is an explicit editing projection. Call vectorized_annotations(SegToAnnConversionPolicy::RejectLoss) to block nonrepresentable identity or applicability semantics. Use AllowLoss only when the caller will inspect and surface VectorizedAnnotations::diagnostics. The removed vectorized_annotation_groups API has no silent compatibility wrapper.

GeoJSON to DICOM

QuPath classification labels are never guessed as clinical terminology. A bounded mapping profile must explicitly connect every label, measurement, and qualitative value to its DICOM coded meaning.

use std::fs;
use wsi_dicom_annotations::{
    DicomAnnotationContext, PathologyAnnotationSet, PathologyCoordinateSpace,
};

let source = DicomAnnotationContext::from_source("level-0-wsi.dcm")?;
let geojson = fs::read("qupath.geojson")?;
let mapping = fs::read("pathology-mapping-v1.json")?;
let annotations = PathologyAnnotationSet::from_json(
    &geojson,
    &mapping,
    &source,
    &source,
    PathologyCoordinateSpace::Level0Pixels,
    false,
)?;
annotations.to_ann()?.write_ann("annotations.dcm")?;

Polygon holes and mask-style regions belong in SEG rather than ANN. Numeric measurements and coded evaluations can be retained in SR, including SR that references the exact SEG generated from the same profiled feature set.

Scope

This crate owns DICOM interchange, terminology primitives, annotation schemes, tracking identity, and profiled external-data conversion. It deliberately does not contain a viewer, renderer, editing history, workspace persistence, PACS or DICOMweb transport, clinical workflow claims, or collaborative review state.

Applications consume this library for import and export. The separate wsi-annotation-interop project remains an independent file-level conformance harness and does not share the production implementation.

Dependency security note

Local Zarr support currently resolves lru 0.16.4 through zarrs 0.23.14. RUSTSEC-2026-0253 requires a key with a panicking Drop implementation and unwind recovery; this dependency path uses only StoreKey(String) and ChunkIndices(Vec<u64>), whose drops cannot panic. The repository records this reachability decision explicitly. Remove the exception when a compatible zarrs release permits lru >= 0.18.2.

License

Starting with version 0.2.0, this project is available under the GNU Affero General Public License version 3 only (AGPL-3.0-only), or under a separate commercial license from Frames. Commercial use is permitted under the AGPL without purchasing a commercial license when its terms are followed.

Published releases through 0.1.4 retain their original MIT/Apache-2.0 licenses. Existing permissive grants and separately licensed material are preserved; see LICENSE. The separate wsi-annotation-interop test harness retains its existing permissive licensing.

Modules

metadata

Bounded, pixel-free DICOM metadata loading shared by derived-object readers and viewers.

Structs

AlgorithmIdentification

AnnotationClass

AnnotationClassConceptKey

AnnotationDocument

AnnotationGroup

AnnotationMeasurement

AnnotationScheme

BinaryMaskRun

BinarySegmentationFrame

DerivedObjectProducer

Caller-owned identity and series metadata for a newly derived DICOM object.

DicomAnnotationContext

DicomBundlePublication

DicomCode

DicomPublicationError

DicomSinglePublication

FractionalMaskRun

FractionalSegmentationFrame

InteroperabilityDiagnostic

LinearMeasurementSpec

MeasurementReportSemantics

ParametricMapDocument

ParametricMapInstance

ParametricMapPartPlan

ParametricMapPlan

ParametricMapPreview

PathologyAnnotationSet

PathologyDicomDocuments

A target-consistent set of pathology-derived DICOM documents.

PathologyPreview

PathologyPreviewFeature

PathologyPreviewPolygon

Point2

Point3

RasterProfile

SegmentationDocument

SegmentationSegment

SidecarMetadata

SpatialCoordinates

StructuredReportDocument

StructuredReportMeasurement

StructuredReportMeasurementGroup

StructuredReportQualitativeEvaluation

TrackingIdentity

VectorizedAnnotations

Editable ANN groups projected from a SEG, together with typed loss diagnostics.

Enums

AnnotationClassGeometry

AnnotationGeometry

AnnotationGraphicType

AnnotationObjectKind

CoordinateGraphic

DiagnosticDisposition

DiagnosticSeverity

DicomCodeValueKind

Error

Error returned by annotation import, conversion, and DICOM persistence.

GenerationType

PathologyCoordinateSpace

PathologyDicomTarget

PathologyDocumentWriteError

PathologyGeometryKind

PathologyPreviewGeometry

RasterChannelSelection

RasterInputFormat

SegToAnnConversionPolicy

Controls whether SEG-to-ANN projection may discard nonrepresentable semantics.

SegmentationKind

SidecarKind

StructuredReportReferenceKind

Functions

annotation_class_concept_key

Builds the stable semantic identity used to match imported concepts to a controlled annotation class.

annotation_object_kind

dicom_cielab_to_srgb

discover_sidecars

Discover local DICOM annotation sidecars without reading ANN coordinate arrays or SEG functional groups and Pixel Data.

format_dicom_decimal

Formats a finite number as a DICOM Decimal String of at most 16 bytes.

polygon_boundaries_intersect

Reports whether any edges from two implicitly closed polygons intersect.

polygon_contains_point

Reports whether point is inside polygon using an even-odd ray cast.

polygon_self_intersects

Reports whether non-adjacent edges of an implicitly closed polygon intersect.

polygon_signed_area

Returns the signed area of an implicitly closed polygon.

srgb_to_dicom_cielab

validate_polygon

Validates a finite, non-self-intersecting, implicitly closed polygon ring.

validate_unique_object_keys

Validates one JSON value while rejecting duplicate object keys at any depth.

Type Aliases

Result

Result type used by annotation operations.