DOCSEARCHbyAlgolia
Submit Docs

Cornerstone3D Documentation

website·Indexed 33 days ago

https://www.cornerstonejs.org/

A high-performance JavaScript library for medical imaging designed for building web-based medical applications. The documentation covers core concepts including Rendering, Tools, Tool Group Manager, and Synchronizers, as well as installation guides for Cornerstone3D, Cornerstone3DTools, and StreamingImageVolumeLoader. It includes migration paths from legacy Cornerstone to version 1.0, API specifications for tools like Crosshairs, and tutorials for implementing annotation and manipulation tools.

Tokens
67.1K
Snippets
282
Records
429
Agent score
70%

What's inside Cornerstone3D

  1. Overview of Cornerstone3D

    Cornerstone3D is a high-performance JavaScript library specifically designed for building web-based medical imaging applications. It provides a comprehensive set of tools for rendering, manipulating, and analyzing medical images, with native support for various formats, including DICOM.

  2. Manage viewport data using Display Sets

    In the 'Next' architecture, prefer using display set IDs and bindings over legacy methods like setStack(), setVolumes(), or addImages(). This allows for explicit roles (e.g., 'source' or 'overlay') and better management of multiple data layers.
    // Set multiple display sets with roles
await viewport.setDisplaySets(
  {
    displaySetId: ctDataId,
    options: {
      orientation: Enums.OrientationAxis.SAGITTAL,
      role: 'source',
    },
  },
  {
    displaySetId: ptDataId,
    options: {
      orientation: Enums.OrientationAxis.SAGITTAL,
      role: 'overlay',
    },
  }
);

// Add an overlay image via metadata provider and display set
utilities.genericViewportDisplaySetMetadataProvider.add(overlayDataId, {
  kind: 'planar',
  imageIds: [imageId],
  initialImageIdIndex: 0,
});

await viewport.addDisplaySet(overlayDataId, {
  role: 'overlay',
});

  3. Retrieve VolumeId from a Viewport

    In previous versions, the actor UID was often used as the volume ID. In the updated architecture, the actor UID is always a unique identifier (uuidv4()), and the volume ID is stored as the referencedId. To retrieve the volume ID from a viewport, use the viewport.getVolumeId() method instead of accessing the actor's UID.
    // Before
const defaultActor = viewport.getDefaultActor();
const volumeId = defaultActor.uid;
const volume = cache.getVolume(volumeId);

// After
const volume = cache.getVolume(viewport.getVolumeId());

  4. Construct a StreamingImageVolume without scalarData

    In the new architecture, scalarData is no longer passed during the construction of StreamingImageVolume. Instead, provide the dataType and numberOfComponents to let the VoxelManager handle data internally.
    const streamingImageVolume = new StreamingImageVolume({
  volumeId,
  metadata,
  dimensions,
  spacing,
  origin,
  direction,
  imageIds,
  dataType,
  numberOfComponents,
});

  5. Understand architectural changes in Cornerstone3D state management

    Cornerstone3D shifts from element-based state to an ID-based lookup system. Core API methods now use renderingEngineId, viewportId, and volumeId as lookup keys to retrieve imaging data. Additionally, interaction state snapshots now return camera properties and coordinates in world space relative to the viewport's frame of reference.

  6. Resolve Rollup external library warnings

    If Rollup complains about missing libraries like @icr/polyseg-wasm, itk-wasm, or @itk-wasm/morphological-contour-interpolation (which are excluded from the bundle to reduce size), mark them as external in the Vite worker configuration.
    worker: {
    format: "es",
    rollupOptions: {
      external: ["@icr/polyseg-wasm"],
    },
  },

  7. Cornerstone3D Monorepo Package Overview

    The Cornerstone3D monorepo is divided into the following functional packages:

    • @cornerstonejs/core: Core library for rendering images/volumes and caching.
    • @cornerstonejs/tools: Library for manipulation, annotation, and segmentation tools.
    • @cornerstonejs/dicom-image-loader: Loader for wadors and wadouri DICOM P10 instances over HTTP.
    • @cornerstonejs/nifti-volume-loader: Loader for NIfTI files.
    • @cornerstonejs/docs: Documentation, guides, and API references.

  8. Migrate from Stack/Volume Viewports to PlanarNext

    In the Generic Viewport architecture, 2D viewing is unified under Enums.ViewportType.PLANAR_NEXT. The render path is automatically inferred from the dataset shape and configuration rather than being hardcoded into the viewport class.
    // New way to enable a planar viewport
renderingEngine.enableElement({
  viewportId,
  type: Enums.ViewportType.PLANAR_NEXT,
  element,
});

const viewport = renderingEngine.getViewport(viewportId) as PlanarViewport;

  9. Calculate voxel statistics in oblique views

    To avoid common errors in oblique view statistics (such as sampling gaps at 45° angles, display-dependent results from canvas sampling, or 'one-voxel thick' sheets), Cornerstone3D uses iterateVoxelsInShape. This iterator works directly in index space, ensuring that every voxel within the shape and thickness is visited exactly once, regardless of zoom, pan, or camera orientation.

  10. Manage Segmentations and Segmentation Representations

    Cornerstone3DTools decouples Segmentation (the underlying data) from Segmentation Representation (the presentational aspect). This allows a single Segmentation to have multiple representations, such as a 3D Labelmap and a Contour.
    import { segmentation } from '@cornerstonejs/tools';

// Access segmentation state (all segmentations and toolGroup specific representations)
segmentation.state.XYZ;

// Manage active segmentation
segmentation.activeSegmentation.XYZ;

// Manage segment index manipulations
segmentations.segmentIndex.XYZ;

  11. Manage annotations using the Annotation Manager

    The Annotation Manager is a singleton used to store, retrieve, and persist annotations. The default implementation, FrameOfReferenceSpecificAnnotationManager, organizes annotations by FrameOfReferenceUID. This ensures that VolumeViewports sharing the same Frame of Reference share the same annotations, whereas StackViewports (which operate on a per-imageId basis) do not. Custom managers can be created by implementing the IAnnotationManager interface.

  12. Understand ImageId and Image Loader Plugins

    An ImageId is a URL that uniquely identifies a single image. Cornerstone3D uses the URL scheme of the ImageId to determine which registered Image Loader plugin should be used to fetch the data. This allows the library to display images from multiple protocols (e.g., WADO-URI, WADO-RS, or proprietary GUIDs) simultaneously. The specific format of the URL is defined by the Image Loader plugin, not by the core library.