Skip to main content

Metadata Module

@cornerstonejs/metadata is the canonical metadata layer for current Cornerstone3D. It centralizes metadata ingestion, typed provider resolution, and shared cache behavior so applications do not need to duplicate source-specific metadata conversion logic.

Current package role​

  • Owns metadata provider registration and typed provider orchestration.
  • Normalizes source metadata into common module outputs used by core/tools.
  • Provides metadata cache coordination across source and derived metadata types.
  • Exposes utilities for tag mapping, normalized object handling, and metadata organization flows.

Import path guidance​

  • Recommended: import metadata APIs from @cornerstonejs/metadata.
  • Legacy compatibility: @cornerstonejs/core still re-exports metadata APIs via core/src/metaData.ts, but this path is deprecated.

Provider model​

The module supports two complementary provider patterns:

  • General provider chain (addProvider): priority-ordered providers, highest priority first.
  • Typed provider chain (addTypedProvider): per-type provider composition with a typed provider bridge in the general chain.

This allows applications to keep legacy provider integrations while adopting typed providers incrementally.

Add-path ingestion and NATURALIZED​

Current metadata changes add explicit ingestion handlers through the add path:

  • metaData.addMetaData(type, query, options) routes to typed typeAdd providers.
  • NATURALIZED is the canonical base metadata state for DICOM source data.
  • Callers can provide source payloads (for example DICOMweb JSON or Part10 data) and let the metadata layer naturalize and cache them consistently.

Cache and imageId model (current behavior)​

  • Shared typed caches support read-through and in-flight de-duplication.
  • Source metadata (especially NATURALIZED) should be keyed by canonical base imageId.
  • Derived frame-specific modules resolve on frame imageIds.
  • Frame/base normalization and frame-image expansion are handled by metadata providers (including FRAME_IMAGE_IDS) rather than scattered call-site logic.

Initialization and provider registration​

registerDefaultProviders() wires the default typed provider stack and related helpers. If the provider chain is reset or re-initialized by application startup flow, required providers must be re-registered after init.

This is especially important during migration from older code paths where provider registration happened once and relied on persistent global state.

Display sets​

The metadata layer also organizes a series' instances into display sets — the unit a viewport renders — via framework-agnostic split rules, exposed as the data-shaped IDisplaySet. Because this is a large topic (the split pipeline, driving a viewport, caching, the split-rule model, and the data model), it has its own page:

  • Display sets — splitImageIdsBySplitRules → createDisplaySetFromGroup → driving a viewport via setDisplaySets / caching via registerDisplaySetMetadata, the split-rule model (with the DWI worked example), and the IDisplaySet attributes + module-augmentation pattern.

Package boundaries​

  • @cornerstonejs/metadata: metadata ingestion, provider chains, normalized module resolution, metadata-specific cache orchestration.
  • @cornerstonejs/core: rendering/runtime primitives and rendering-focused caches and loaders.
  • @cornerstonejs/dicom-image-loader: retrieve/decode pipeline and source data handoff into metadata.
  • adapters: conversion between parsed metadata and tool/segmentation representations.