# pyushkevich/itksnap architecture

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

- Interactive diagram: https://gitdiagram.com/pyushkevich/itksnap
- Repository: https://github.com/pyushkevich/itksnap

## Overview

##### Project Type and Purpose
- ITK-SNAP is a standalone, cross-platform desktop application for semi-automated 3D medical image segmentation.
- It is written in C++ and uses CMake as its build system. It relies on Qt for the GUI, ITK for image-processing pipelines, VTK/OpenGL for rendering, and various third-party libraries (JSONcpp, REST client, etc.) for support functionality.

##### High-Level File Structure Analysis
- Top-level directories:
- CMake, Utilities – build scripts, packaging, Dockerfiles, OS-specific installers
- Common – low-level helpers, exception, IPC, JSON, GPU settings, history, registry
- Logic – core image‐processing pipelines, segmentation, meshing, preprocessing, slicing, I/O (REST, CSV), workspace API
- GUI – Qt Model/View, Components, Windows dialogs, coupling code, resources, main entry point
- Renderer – VTK/OpenGL rendering abstractions for slices, 3D views, overlays, annotation, widgets
- ProgramData – runtime data: help pages, tutorials, sample images, presets
- Submodules – embedded third-party libraries (c3d, greedy, digestible)
- Testing – unit and GUI tests, test data

##### Insights from README
- ITK-SNAP is open source and intended for research labs.
- Users interact via a rich Qt GUI for image loading, annotation, and segmentation.
- No web or distributed microservices; it is monolithic with optional REST calls for workspace integration (Logic/WorkspaceAPI/RESTClient).

##### Main Architectural Components
a. GUI Layer (Qt)
- Modules:
- GUI/Model – Qt data models (MVC pattern)
- GUI/Qt/Components – custom Qt widgets & panels
- GUI/Qt/Coupling – binding between models and Qt widgets
- GUI/Windows – dialogs, wizards, main windows
- Entry point: GUI/main.cxx
- Responsibilities: user interaction, command dispatch, model updates, menu/toolbars, dialogs.

b. Logic Layer (Core Processing)
- Subsystems:
- Framework – application lifecycle, global state, undo/redo, layer associations
- ImageWrapper – abstraction over ITK image types, CPU‐GPU filters
- Preprocessing, LevelSet, Mesh, Slicing, RLEImage – specialized pipelines
- WorkspaceAPI – optional REST calls (upload/download projects)
- MetaDataAccess, PresetManager, Registry I/O
- Responsibilities: load and transform image data, run segmentation algorithms, maintain application state.

c. Rendering Layer
- Subsystems:
- AbstractVTKRenderer, SceneRenderer – generic rendering interfaces
- Slice & 3D view renderers, annotation renderers, overlays
- Orientation widget, GL→PNG exporter

d. Common Utilities
- Provides cross-cutting functionality: command-line parsing, IPC handlers, JSON parsing, event management, affine transforms, exception handling, threading helpers.

e. Data & Submodules
- ProgramData – read-only assets loaded at runtime (help HTML, preset curves, sample images).
- Submodules – compiled in or linked at build time.

f. Build and Packaging
- CMake scripts (CMakeLists.txt, CMake/DeployQt5.cmake) orchestrate build.
- Utilities manage platform installers (Docker, Linux shell scripts, Mac bundles, InnoSetup for Windows).

##### Relationships and Interactions
- GUI Layer ↔ Logic Layer:
- GUI models subscribe to Logic framework global state and image data.
- User actions in GUI trigger Logic processes (e.g., segmentation, mesh export).
- Logic Layer ↔ Rendering Layer:
- Logic produces data (slices, meshes, overlays) that Rendering consumes.
- Rendering notifies Logic of user interactions (e.g., ROI selection).
- GUI Layer ↔ Rendering Layer:
- QtVTK integration: Rendering widgets embedded in Qt windows.
- Coupling code links Qt events to rendering updates.
- Logic Layer ↔ Common Utilities:
- Use JSON, IPC, registry I/O, threading from Common.
- Build/Packaging operate externally but produce the deliverable that includes all layers.

##### Architectural Patterns and Principles
- Model-View-Controller (MVC) / Model-View (Qt): clear separation of data (Logic) and presentation (GUI).
- Layered architecture: Common utilities at bottom, Logic above it, Rendering and GUI on top.
- Plugin-like modularity: individual image processing pipelines under Logic/Common, Logic/Preprocessing, Logic/LevelSet, Logic/Mesh, etc.
- Dependency Injection via Qt coupling classes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% ProgramData & Submodules Layer
    subgraph "ProgramData & Submodules"
        PD(("ProgramData<br>Help HTML, Tutorials,<br>Sample Images, Presets")):::external
        SM(("Submodules<br>Third-Party Libraries")):::external
    end

    %% GUI Layer
    subgraph "GUI Layer" 
        Entry["GUI/main.cxx<br>(Entry Point)"]:::gui
        Models["GUI/Model<br>(Qt Data Models)"]:::gui
        QtComp["GUI/Qt/Components<br>(Custom Widgets)"]:::gui
        QtCoupling["GUI/Qt/Coupling<br>(Model-View Binding)"]:::gui
        QtView["GUI/Qt/View<br>(Views)"]:::gui
        Windows["GUI/Qt/Windows<br>(Dialogs & Wizards)"]:::gui
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        Renderer["VTK/OpenGL Renderers"]:::render
    end

    %% Logic Layer
    subgraph "Logic Layer"
        Framework["Logic/Framework<br>(App Lifecycle, State)"]:::logic
        ImageWrapper["Logic/ImageWrapper<br>(ITK Abstraction, Filters)"]:::logic
        Preprocessing["Logic/Preprocessing<br>(Pipelines)"]:::logic
        LevelSet["Logic/LevelSet<br>(Segmentation)"]:::logic
        Mesh["Logic/Mesh<br>(Mesh Generation & Export)"]:::logic
        Slicing["Logic/Slicing<br>(Slicing Pipelines)"]:::logic
        RLEImage["Logic/RLEImage<br>(RLE Support)"]:::logic
        WSAPI["Logic/WorkspaceAPI<br>(REST/CSV)"]:::logic
        LogicCommon["Logic/Common<br>(Metadata, Presets, Registry)"]:::logic
    end

    %% Common Utilities Layer
    subgraph "Common Utilities"
        Common["Common/<br>Core Helpers, IPC, JSON, Threading"]:::common
    end

    %% Data Flows
    Entry -->|"dispatch commands"| Framework
    Windows -->|"user actions"| Framework
    QtCoupling -->|"bind updates"| Framework
    Framework -->|"state updates"| Models
    Preprocessing -->|"processed data"| Renderer
    LevelSet -->|"segmentation data"| Renderer
    Mesh -->|"mesh data"| Renderer
    Slicing -->|"slice data"| Renderer
    Renderer -->|"render events"| QtComp

    Common -->|"services"| Framework
    Common -->|"utilities"| WSAPI

    PD --- Entry
    SM --- Framework

    %% Click Events
    click Entry "https://github.com/pyushkevich/itksnap/blob/master/GUI/main.cxx"
    click Models "https://github.com/pyushkevich/itksnap/tree/master/GUI/Model/"
    click QtComp "https://github.com/pyushkevich/itksnap/tree/master/GUI/Qt/Components/"
    click QtCoupling "https://github.com/pyushkevich/itksnap/tree/master/GUI/Qt/Coupling/"
    click QtView "https://github.com/pyushkevich/itksnap/tree/master/GUI/Qt/View/"
    click Windows "https://github.com/pyushkevich/itksnap/tree/master/GUI/Qt/Windows/"
    click Renderer "https://github.com/pyushkevich/itksnap/tree/master/GUI/Renderer/"
    click Common "https://github.com/pyushkevich/itksnap/tree/master/Common/"
    click Framework "https://github.com/pyushkevich/itksnap/tree/master/Logic/Framework/"
    click ImageWrapper "https://github.com/pyushkevich/itksnap/tree/master/Logic/ImageWrapper/"
    click Preprocessing "https://github.com/pyushkevich/itksnap/tree/master/Logic/Preprocessing/"
    click LevelSet "https://github.com/pyushkevich/itksnap/tree/master/Logic/LevelSet/"
    click Mesh "https://github.com/pyushkevich/itksnap/tree/master/Logic/Mesh/"
    click Slicing "https://github.com/pyushkevich/itksnap/tree/master/Logic/Slicing/"
    click RLEImage "https://github.com/pyushkevich/itksnap/tree/master/Logic/RLEImage/"
    click WSAPI "https://github.com/pyushkevich/itksnap/tree/master/Logic/WorkspaceAPI/"
    click LogicCommon "https://github.com/pyushkevich/itksnap/tree/master/Logic/Common/"
    click PD "https://github.com/pyushkevich/itksnap/tree/master/ProgramData/"
    click SM "https://github.com/pyushkevich/itksnap/tree/master/Submodules/"

    %% Styling
    classDef gui fill:#D0E8FF,stroke:#004C99,color:#004C99;
    classDef logic fill:#E2F7D4,stroke:#3C763D,color:#3C763D;
    classDef render fill:#FFE5B4,stroke:#CC8400,color:#CC8400;
    classDef common fill:#EEEEEE,stroke:#AAAAAA,color:#555555;
    classDef external fill:#FFF6BF,stroke:#CCA700,color:#CCA700;
```
