# jimmycai91/dlt architecture

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

- Interactive diagram: https://gitdiagram.com/jimmycai91/dlt
- Repository: https://github.com/jimmycai91/dlt

## Overview

##### Project type and purpose
- This is an open-source lesion-tracking benchmark and toolkit.
- Primary tasks:
- Convert raw DeepLesion PNGs to NIfTI volumes (DL_save_nifti.py)
- Provide lesion pair annotations (JSON files in data/)
- Run evaluation code (evaluation.py) on predictions.

##### File structure
- Top-level scripts:
- DL_save_nifti.py – conversion from PNG to .nii.gz
- evaluation.py – scoring/prediction evaluation
- Data directory:
- train.json, valid.json, test.json – lesion_pair_annotation records
- DLTMix.json – combined annotation set
- Config/build:
- No heavy build system; it’s invoked via simple CLI scripts.

##### README for insights
- Describes dataset format and fields in lesion_pair_annotation
- Points to external DeepLesion source (NIH) as upstream data
- No existing service or web UI—purely batch scripts & data.

##### Main components
a. External DeepLesion Data Source
– Raw PNG slices (external repository)
b. Data Conversion Module
– DL_save_nifti.py
– Input: DeepLesion PNGs → Output: NIfTI subvolumes
c. Annotation Store
– JSON files under data/ (train/valid/test)
d. Deep Lesion Tracker (DLT) Model
– *Not included in this repo*, but implied: training & inference code
e. Evaluation Module
– evaluation.py reads model outputs + JSON → quantitative metrics

##### Relationships & data flows
- Annotation JSONs reference those NIfTI files (bidirectional link)
- evaluation.py consumes predicted outputs + ground truth JSON → evaluation metrics

##### Architectural patterns & design principles
- Pipeline pattern: clear, linear transform steps (convert → annotate → infer → evaluate)
- Separation of concerns:
- Conversion (data ingestion)
- Annotation (data labelling)
- Model (algorithmic core)
- Evaluation (metrics)
- Extensibility point: swapping in a new tracker model or evaluation metric is easy by following JSON I/O spec.

##### Technologies & formats
- Python scripts (DL_save_nifti.py, evaluation.py)
- NIfTI (.nii.gz) volumes
- JSON annotation schema
- CLI invocation (bash commands)

- Labels on every component (e.g., “DL_save_nifti.py”)

[External DeepLesion PNG Repository]
|
| (.png slices)
v
[DL_save_nifti.py] ––> [NIfTI Volume Store]
|
| (references)
v
[Annotation Store (train/valid/test JSON)]
|
| (consumed by)
v
[DLT Model (Training/Inference)]
|
| (predictions JSON)
v
[evaluation.py] ––> [Evaluation Metrics Output]

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External resources
    External(("External DeepLesion PNG Source")):::external

    %% Conversion process
    Conversion["DL_save_nifti.py"]:::process

    %% NIfTI store
    NIfTIStore[(NIfTI Volume Store)]:::dataStore

    %% Annotation store subgraph
    subgraph "Annotation Store"
        direction TB
        train["train.json"]:::dataStore
        valid["valid.json"]:::dataStore
        test["test.json"]:::dataStore
        DLTMix["DLTMix.json"]:::dataStore
    end

    %% Model component
    DLTModel["DLT Model (Training/Inference)"]:::process

    %% Evaluation process
    Evaluation["evaluation.py"]:::process

    %% Metrics output
    Metrics[(Evaluation Metrics Output)]:::dataStore

    %% Data flows
    External -->|".png slices"| Conversion
    Conversion -->|".nii.gz volumes"| NIfTIStore
    NIfTIStore -->|".nii.gz references"| train
    NIfTIStore -->|".nii.gz references"| valid
    NIfTIStore -->|".nii.gz references"| test
    NIfTIStore -->|".nii.gz references"| DLTMix
    train -->|"NIfTI + JSON"| DLTModel
    valid -->|"NIfTI + JSON"| DLTModel
    test -->|"NIfTI + JSON"| DLTModel
    DLTMix -->|"NIfTI + JSON"| DLTModel
    DLTModel -->|"predictions JSON"| Evaluation
    train -->|"ground truth JSON"| Evaluation
    valid -->|"ground truth JSON"| Evaluation
    test -->|"ground truth JSON"| Evaluation
    DLTMix -->|"ground truth JSON"| Evaluation
    Evaluation -->|"metrics"| Metrics

    %% Click events
    click Conversion "https://github.com/jimmycai91/dlt/blob/main/DL_save_nifti.py"
    click Evaluation "https://github.com/jimmycai91/dlt/blob/main/evaluation.py"
    click train "https://github.com/jimmycai91/dlt/blob/main/data/train.json"
    click valid "https://github.com/jimmycai91/dlt/blob/main/data/valid.json"
    click test "https://github.com/jimmycai91/dlt/blob/main/data/test.json"
    click DLTMix "https://github.com/jimmycai91/dlt/blob/main/data/DLTMix.json"

    %% Styles
    classDef dataStore fill:#ADD8E6,stroke:#000;
    classDef process fill:#98FB98,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
```
