# cornerstonejs/cornerstone3d architecture

> Architecture diagram of the GitHub repository cornerstonejs/cornerstone3d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cornerstonejs/cornerstone3d
- Repository: https://github.com/cornerstonejs/cornerstone3d

## Overview

##### Overall architectural layers and modules
- Core Imaging Engine – At the heart is the “packages/core” module, which contains the rendering engine, viewport management, image/volume loading utilities, caching, and common utilities. This component is responsible for the foundation of image/volume display and manipulations.
- Adapters and Data Loading – For handling image input, several specialized packages exist. For instance, “packages/dicomImageLoader” is dedicated to DICOM image retrieval and processing, “packages/nifti-volume-loader” for NIfTI files, and “packages/ai” (possibly to support integrating AI segmentation) add specialized functionality.
- Annotation, Segmentation, and Tools – The “packages/tools”, “packages/polymorphic-segmentation”, “packages/labelmap-interpolation”, and other related packages handle drawing annotations, segmenting regions of interest, and converting between different representations. These modules build on the core to provide radiology-specific interfaces.
- AddOns and External Integrations – The “addOns” folder and various “externals” (like the referenced DICOM microscopy-viewer) indicate additional optional extensions or integrations.
- Supporting Utilities and Examples – Several directories (like “utils”, “tests”, and “packages/docs”) round out the project by providing helper functions, test harnesses, and extensive documentation with live examples.

##### Lay out the relationships and interactions between components
- Data Flow: Start with the image input layer (from PACS or local file systems) that is ingested by specialized image loaders (DICOM, NIfTI, etc.). Images are then passed to the core rendering engine which manages viewports, caching, and event dispatching.
- Tools and overlays: Separate packages (tools, segmentation modules, annotation libraries) enhance the core imaging experience by allowing users to annotate images, compute measurements, and perform advanced operations (like progressive image loading or segmentation).

##### Architectural patterns and design principles
- Extensibility: The design enables easy swapping or extending of image loaders and tools. Show extension points (or “interfaces”) between the core and the add-ons.
- Event-driven and Worker-based Processing: Highlight how user actions (annotations, slice changes) generate events that propagate through an event dispatcher to update viewports, or offload processing to web workers.

##### Technologies and frameworks
- JavaScript/TypeScript (the codebase uses TypeScript for types and modern JS modules)
- WebGL for rendering image and volume data
- WebAssembly (used for fast decompression/processing)
- Dependencies to external libraries such as those provided by OHIF or other community-driven tools

##### Additional details
- Design patterns like “Observer/Event Dispatch” as part of user interfaces and how updates propagate.
- For testing and examples, you may add a section outlining how integration tests or example applications are structured to validate the overall architecture.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Input & Preprocessing Layer
    subgraph "Data Input & Preprocessing"
        AD("Adapters"):::dataInput
        DIL("DICOM Image Loader"):::dataInput
        NVL("NIfTI Volume Loader"):::dataInput
    end

    %% Core Rendering Engine Layer
    subgraph "Core Rendering Engine"
        CORE("Core Imaging Engine"):::coreEngine
    end

    %% Annotation & Segmentation Tools Layer
    subgraph "Annotation & Segmentation Tools"
        AT("Annotation Tools"):::tools
        PS("Polymorphic Segmentation"):::tools
        LI("Labelmap Interpolation"):::tools
        AI("AI Segmentation"):::tools
    end

    %% Extensions & External Integrations Layer
    subgraph "Extensions & External Integrations"
        ADD("AddOns"):::external
    end

    %% Supporting Documentation & Examples Layer
    subgraph "Supporting Documentation & Examples"
        DOC("Documentation"):::docs
        ER("Example Runner"):::docs
    end

    %% Connections: Data loaders feed into Core Engine
    AD -->|"feeds"| CORE
    DIL -->|"feeds"| CORE
    NVL -->|"feeds"| CORE

    %% Connections: Core Engine provides to Tools and External Integrations
    CORE -->|"updates"| AT
    CORE -->|"updates"| PS
    CORE -->|"updates"| LI
    CORE -->|"updates"| AI
    CORE -->|"extension call"| ADD

    %% Optional: Documentation linked from Tools
    AT -->|"documentedBy"| DOC
    PS -->|"documentedBy"| DOC
    LI -->|"documentedBy"| DOC
    AI -->|"documentedBy"| DOC

    %% Class Definitions for colors
    classDef dataInput fill:#cce5ff,stroke:#000,stroke-width:2px;
    classDef coreEngine fill:#ffebcc,stroke:#000,stroke-width:2px;
    classDef tools fill:#d4edda,stroke:#000,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#000,stroke-width:2px;
    classDef docs fill:#f8d7da,stroke:#000,stroke-width:2px;

    %% Click Events
    click CORE "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/core"
    click DIL "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/dicomImageLoader"
    click NVL "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/nifti-volume-loader"
    click AD "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/adapters"
    click AT "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/tools"
    click PS "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/polymorphic-segmentation"
    click LI "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/labelmap-interpolation"
    click AI "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/ai"
    click ADD "https://github.com/cornerstonejs/cornerstone3d/tree/main/addOns"
    click DOC "https://github.com/cornerstonejs/cornerstone3d/tree/main/packages/docs"
    click ER "https://github.com/cornerstonejs/cornerstone3d/tree/main/utils/ExampleRunner"
```
