# bhklab/med-imagetools architecture

> Architecture diagram of the GitHub repository bhklab/med-imagetools, 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/bhklab/med-imagetools
- Repository: https://github.com/bhklab/med-imagetools

## Overview

- CLI/Entry Point:
– Represent the command-line interface (“imgtools”) located under src/imgtools/cli with its __main__ module.
– This is where users initiate the autopipeline using flags (e.g., --dry_run, --continue_processing, --nnunet).

- Autopipeline Module:
– The core “pipeline” function (src/imgtools/pipeline.py) coordinates the overall processing workflow.
– It takes the user inputs and triggers the subsequent processing modules.

- DICOM Processing Modules:
– Highlight the dedicated DICOM module (src/imgtools/dicom) that includes reading, querying, sorting, and metadata extraction functionalities.
– Include the “modality_utils” sub-module that contains modality-specific processing routines (e.g., rtplan, rtstruct, seg_utils, etc.).
– The “dicom_find.py”, “dicom_reader.py”, and “read_tags.py” files are key for ingesting and parsing the raw DICOM data.

- Graph and Query System:
– Indicate that one of the design goals is to “crawl” the dataset and form a network that links various DICOMs based on interdependencies.
– Although not explicitly a separate module, this graph creation (or network formation) can be illustrated as part of the autopipeline workflow.

- Core Types and ROI Handling:

- IO Layer (Writers and Loaders):
– The input/output handling modules, found under src/imgtools/io, manage the reading and writing of processed data.
– Include the various writers such as the nifti_writer, numpy_writer, and hdf5_writer that convert processed images to deep learning–compatible formats.

- Logging and Exception Handling:
– The logging components (src/imgtools/loggers) and the exceptions module help with process tracking and error management.

- Utility and Pattern Parsing:
– The “pattern_parser” and “utils” modules include helper functions for data sanitization, filename processing, and timing/logging utilities.

- Configuration/Deployment:
– With Dockerfile, pixi.toml, and various config files (myppy.ini, pytest.ini, etc.), these may be shown as supporting elements that facilitate development, testing, and production deployments.

##### Relationships and Interactions
- From the autopipeline, branch out to the DICOM processing module, which further interacts with modality utilities and core types (building the graph of interdependencies).
- A side line for logging and error handling that intersects with all primary components to indicate cross-cutting concerns.
- Optionally, show that configuration elements (e.g., Dockerfile, config files) underlie all modules by supporting environment setup and deployment.

##### Architectural Patterns and Design Principles
- The use of a pipeline architecture is central: raw DICOM data becomes a graph-based model of modalities, then is processed and transformed into output formats suitable for ML.
- That the design supports reproducibility (with flags like random_state and dry_run) and extensibility (via clear module boundaries with coretypes, pattern parsing, and modality-specific utilities).

##### Final Guidance
- Remind the engineer that detail is key—each module from src/imgtools (CLI, coretypes, dicom, io, loggers, pattern_parser, etc.) should be represented as its own component.
- Integrate relationships and dependencies as identified from both the file structure and README; for example, illustrate how the raw datasets flow through a series of processing steps to result in a ML-ready dataloader.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI("imgtools CLI (__main__)"):::cli
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        PIPELINE("Autopipeline"):::pipeline

        subgraph "DICOM Processing"
            DICOM_FIND("DICOM Find"):::processing
            DICOM_READER("DICOM Reader"):::processing
            DICOM_READ("DICOM Read Tags"):::processing
            DICOM_META("DICOM Metadata"):::processing
            MODALITY("Modality Utils"):::processing
            DICOM_SORT("DICOM Sorting"):::processing
        end

        CORE_TYPES("Core Types & ROI"):::processing
        UTILS("Utilities"):::utility
        PATTERN("Pattern Parser"):::utility
    end

    %% IO and Logging
    subgraph "IO & Logging"
        IO_WRITERS("IO Writers"):::io
        IO_LOADERS("IO Loaders"):::io
        LOGGER("Loggers"):::logging
        EXC("Exceptions"):::logging
    end

    %% Configuration / Deployment
    subgraph "Configuration/Deployment"
        DOCKER("Dockerfile"):::config
        PIXI("pixi.toml"):::config
        CONFIG_FILES("Config Files"):::config
    end

    %% Relationships
    CLI -->|"start"| PIPELINE

    PIPELINE -->|"triggers"| DICOM_FIND
    PIPELINE -->|"triggers"| DICOM_READER
    PIPELINE -->|"triggers"| DICOM_READ
    PIPELINE -->|"triggers"| DICOM_META
    PIPELINE -->|"invokes"| MODALITY
    PIPELINE -->|"sorts"| DICOM_SORT
    PIPELINE --> CORE_TYPES
    PIPELINE --> UTILS
    PIPELINE --> PATTERN

    DICOM_FIND --> CORE_TYPES
    DICOM_META --> CORE_TYPES
    DICOM_SORT --> CORE_TYPES
    MODALITY --> CORE_TYPES

    PIPELINE -->|"savesOutput"| IO_WRITERS
    PIPELINE --> IO_LOADERS

    CORE_TYPES --> LOGGER
    UTILS --> LOGGER
    PATTERN --> LOGGER
    IO_WRITERS --> LOGGER
    IO_LOADERS --> LOGGER

    CONFIG_FILES --> PIPELINE
    CONFIG_FILES --> IO_WRITERS
    CONFIG_FILES --> LOGGER
    CONFIG_FILES --> CORE_TYPES
    CONFIG_FILES --> UTILS
    CONFIG_FILES --> PATTERN

    LOGGER --> EXC

    %% Click Events
    click CLI "https://github.com/bhklab/med-imagetools/blob/development/src/imgtools/cli/__main__.py"
    click PIPELINE "https://github.com/bhklab/med-imagetools/blob/development/src/imgtools/pipeline.py"
    click DICOM_FIND "https://github.com/bhklab/med-imagetools/blob/development/src/imgtools/dicom/dicom_find.py"
    click DICOM_READER "https://github.com/bhklab/med-imagetools/blob/development/src/imgtools/dicom/dicom_reader.py"
    click DICOM_READ "https://github.com/bhklab/med-imagetools/blob/development/src/imgtools/dicom/read_tags.py"
    click DICOM_META "https://github.com/bhklab/med-imagetools/blob/development/src/imgtools/dicom/dicom_metadata.py"
    click MODALITY "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/dicom/modality_utils/"
    click DICOM_SORT "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/dicom/sort/"
    click CORE_TYPES "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/coretypes/"
    click IO_WRITERS "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/io/writers/"
    click IO_LOADERS "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/io/loaders/"
    click LOGGER "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/loggers/"
    click EXC "https://github.com/bhklab/med-imagetools/blob/development/src/imgtools/exceptions.py"
    click UTILS "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/utils/"
    click PATTERN "https://github.com/bhklab/med-imagetools/tree/development/src/imgtools/pattern_parser/"
    click DOCKER "https://github.com/bhklab/med-imagetools/tree/development/Dockerfile"
    click PIXI "https://github.com/bhklab/med-imagetools/blob/development/pixi.toml"
    click CONFIG_FILES "https://github.com/bhklab/med-imagetools/tree/development/config/"

    %% Styles
    classDef cli fill:#ffe6e6,stroke:#b30000,stroke-width:2px;
    classDef pipeline fill:#e6f7ff,stroke:#005c99,stroke-width:2px;
    classDef processing fill:#e6ffe6,stroke:#008000,stroke-width:2px;
    classDef io fill:#fff2cc,stroke:#cc9900,stroke-width:2px;
    classDef logging fill:#ffe6cc,stroke:#ff6600,stroke-width:2px;
    classDef utility fill:#e6e6ff,stroke:#4d4dff,stroke-width:2px;
    classDef config fill:#f9e6ff,stroke:#9900cc,stroke-width:2px;
```
