# anhtuanhsgs/colorrl architecture

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

- Interactive diagram: https://gitdiagram.com/anhtuanhsgs/colorrl
- Repository: https://github.com/anhtuanhsgs/colorrl

## Overview

##### Project Type and Purpose
- This is ColorRL, a research‐grade machine‐learning project implementing a reinforcement‐learning approach (“Reinforced Coloring”) for end‐to‐end instance segmentation of 2D and 3D biomedical imagery (e.g., CVPPP plant leaves, CREMI neuron data, zebrafish volumes).
- The README and notebooks show pipelines for data preparation, RL environment setup, training an agent (policy network), model checkpointing, deployment for inference, and post‐hoc evaluation.

##### File‐Structure Analysis
- Top‐level directories:
- Data/ – raw and preprocessed data folders (CVPPP, CREMI), plus scripts (ExtractData.py) to convert and organize images/labels.
- Utils/ – Python utilities and Jupyter notebooks for data augmentation (img_aug_func.py), synthetic data generation (SynData.ipynb), metrics, logging (Logger.py), and other helper functions.
- models/ – definitions of neural architectures (UNet, AttUNet variants, DeepLabV3, GCN‐UNet, Conv‐GRU/LSTM modules, etc.) and the main policy model API.
- evaluation/ – Jupyter notebooks and helper scripts for computing segmentation metrics and visualizing results on different datasets.
- run_scrips/ – collection of bash scripts orchestrating training and deployment across datasets (cvppp_train.sh, 256_cremi_train.sh, 3d_zebrafish_train.sh, etc.).
- Entrypoint scripts at root: main.py (configures environment, data paths, hyperparameters), train.py (starts RL training loop), deploy.py (loads a checkpoint and runs inference), load.py (dataset loading), test.py/test_models.py (unit/functional tests), shared_optim.py, rewards.py, player_util.py.
- logs/ – hierarchical subdirectories capturing prior training runs, organized by dataset, date, and model variant, containing scripts, environment snapshots, logs, and saved checkpoints.

a. Main Components
- Data Ingestion & Preprocessing: Data/ExtractData.py, load.py, Utils/img_aug_func.py, Utils/utils.py
- Policy Network (Agent): models/main.py + models/*.py define CNN‐based actor networks (UNet, AttUNet variants, etc.), sometimes with temporal modules (Conv‐GRU/LSTM)
- Training Loop: train.py orchestrates episodes, interacts with environment, updates policy via shared_optim.py (optimizer and learning‐rate schedule), logs to TensorBoard (Logger.py) and disk (logs/)
- Deployment / Inference: deploy.py loads a saved checkpoint (via --load flag configured in run_scrips/*.sh), wraps the environment for inference, saves predicted instance masks to deploy/
- Evaluation: evaluation/utils.py and evaluation/metrics.py, plus Jupyter notebooks in evaluation/ compute IoU, boundary‐F1, etc., and generate figures.

b. Relationships & Data Flow
1. Bash script (run_scrips/*.sh) → launches main.py/train.py/deploy.py with command‐line args
2. main.py or train.py calls load.py to list Data/A & Data/B images and applies augmentations via Utils/img_aug_func.py
3. environment.py exposes step() and reset() to the agent; retrieves images and labels from Data/ via load.py
4. train.py loops: reset env → for t in horizon: policy_network(state) → action → env.step(action) → reward → store transition → after each batch, call shared_optim optimizer to update policy parameters
5. Checkpoints saved under trained_models/ (implied by README) and logs written to logs/ and TensorBoard via Logger.py
6. deploy.py loads checkpoint, runs episodes on test images, outputs predicted masks to deploy/
7. evaluation notebooks read deploy/ results and use evaluation/metrics.py to compute performance.

c. Architectural Patterns & Design Principles
- Modular directory layout separating data, model definitions, utilities, scripts, and evaluation
- Gym‐style RL environment abstraction promoting plug‐and‐play of different model architectures
- Separation of concerns: policy networks in models/, optimization logic in shared_optim.py, reward logic in rewards.py, data I/O in load.py, experimentation orchestration via shell scripts.
- Logging & reproducibility: logs/ structure that mirrors run_scrips parameters, checkpoint versioning, environment snapshots.

d. Key Technologies & Frameworks
- PyTorch 1.x for neural network models and training
- OpenAI Gym pattern (custom env in environment.py)
- NumPy and SciPy for data handling
- TIFF, PNG I/O via PIL or tifffile (implied)
- Bash for experiment orchestration
- Jupyter notebooks for exploratory evaluation
- TensorBoard for training visualization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Experiment Orchestration
    subgraph "Experiment Orchestration" 
        ORC_RUN["Bash Scripts"]:::scripts
        ENTRY["main.py"]:::scripts
    end
    ORC_RUN -->|launches| ENTRY
    ORC_RUN -->|launches| TRAIN_LOOP
    ORC_RUN -->|launches| DEPLOY_MOD

    click ORC_RUN "https://github.com/anhtuanhsgs/colorrl/blob/master/run_scrips/*.sh"
    click ENTRY "https://github.com/anhtuanhsgs/colorrl/blob/master/main.py"

    %% Data Preprocessing
    subgraph "Data Ingestion & Preprocessing" 
        RAW["Raw Images & Labels (TIFF/PNG)"]:::data
        EXTRACT["ExtractData.py"]:::data
        LOAD["load.py"]:::data
        AUG["img_aug_func.py"]:::data
        UTILS["utils.py"]:::data
    end
    RAW --> EXTRACT
    EXTRACT --> LOAD
    LOAD --> AUG
    AUG --> UTILS

    click EXTRACT "https://github.com/anhtuanhsgs/colorrl/blob/master/Data/CVPPP_Challenge/ExtractData.py"
    click LOAD "https://github.com/anhtuanhsgs/colorrl/blob/master/load.py"
    click AUG "https://github.com/anhtuanhsgs/colorrl/blob/master/Utils/img_aug_func.py"
    click UTILS "https://github.com/anhtuanhsgs/colorrl/blob/master/Utils/utils.py"

    %% Environment
    subgraph "RL Environment" 
        ENV["environment.py"]:::train
        REW["rewards.py"]:::train
    end
    UTILS --> ENV
    ENV --> REW
    click ENV "https://github.com/anhtuanhsgs/colorrl/blob/master/environment.py"
    click REW "https://github.com/anhtuanhsgs/colorrl/blob/master/rewards.py"

    %% Policy Network
    subgraph "Policy Network (Agent)" 
        MODELS_MAIN["models/main.py"]:::train
        UNET["UNet.py"]:::train
        ATTUNET["att_unet.py"]:::train
        ASPP["aspp_att_unet.py"]:::train
        DEEPLAB["deeplabv3.py"]:::train
        GCN["gcn_att_unet.py"]:::train
        GRU["conv_gru.py"]:::train
        LSTM["conv_lstm.py"]:::train
        BASIC["basic_modules.py"]:::train
        MODELS_ALL["models.py"]:::train
    end
    ENV --> MODELS_MAIN
    click MODELS_MAIN "https://github.com/anhtuanhsgs/colorrl/blob/master/models/main.py"
    click UNET "https://github.com/anhtuanhsgs/colorrl/blob/master/models/UNet.py"
    click ATTUNET "https://github.com/anhtuanhsgs/colorrl/blob/master/models/att_unet.py"
    click ASPP "https://github.com/anhtuanhsgs/colorrl/blob/master/models/aspp_att_unet.py"
    click DEEPLAB "https://github.com/anhtuanhsgs/colorrl/blob/master/models/deeplabv3.py"
    click GCN "https://github.com/anhtuanhsgs/colorrl/blob/master/models/gcn_att_unet.py"
    click GRU "https://github.com/anhtuanhsgs/colorrl/blob/master/models/conv_gru.py"
    click LSTM "https://github.com/anhtuanhsgs/colorrl/blob/master/models/conv_lstm.py"
    click BASIC "https://github.com/anhtuanhsgs/colorrl/blob/master/models/basic_modules.py"
    click MODELS_ALL "https://github.com/anhtuanhsgs/colorrl/blob/master/models/models.py"

    %% Training Loop & Optimization
    subgraph "Training Loop & Optimization" 
        TRAIN_LOOP["train.py"]:::train
        OPT["shared_optim.py"]:::train
        LOGGER["Logger.py"]:::train
        CHECKPOINT["Checkpoint Store"]:::train
    end
    TRAIN_LOOP --> ENV
    TRAIN_LOOP --> MODELS_MAIN
    TRAIN_LOOP --> LOGGER
    TRAIN_LOOP --> OPT
    OPT --> MODELS_MAIN
    MODELS_MAIN --> CHECKPOINT
    click TRAIN_LOOP "https://github.com/anhtuanhsgs/colorrl/blob/master/train.py"
    click OPT "https://github.com/anhtuanhsgs/colorrl/blob/master/shared_optim.py"
    click LOGGER "https://github.com/anhtuanhsgs/colorrl/blob/master/Utils/Logger.py"

    %% Deployment / Inference
    subgraph "Deployment / Inference" 
        DEPLOY_MOD["deploy.py"]:::deploy
        DEPLOY_SCRIPTS["Deploy Scripts"]:::deploy
        DEPLOY_OUT["deploy/ (Predicted Masks)"]:::deploy
    end
    DEPLOY_MOD --> MODELS_MAIN
    DEPLOY_MOD --> ENV
    DEPLOY_MOD --> DEPLOY_OUT
    click DEPLOY_MOD "https://github.com/anhtuanhsgs/colorrl/blob/master/deploy.py"
    click DEPLOY_SCRIPTS "https://github.com/anhtuanhsgs/colorrl/blob/master/run_scrips/256_cremi_deploy.sh"
    click DEPLOY_SCRIPTS "https://github.com/anhtuanhsgs/colorrl/blob/master/run_scrips/448_cremi_deploy.sh"
    click DEPLOY_SCRIPTS "https://github.com/anhtuanhsgs/colorrl/blob/master/run_scrips/cvppp_deploy.sh"

    %% Evaluation
    subgraph "Evaluation Module" 
        EVAL_UTIL["evaluation/utils.py"]:::eval
        EVAL_METR["evaluation/metrics.py"]:::eval
        EVAL_NB["Notebooks"]:::eval
    end
    EVAL_UTIL --> EVAL_METR
    EVAL_METR --> EVAL_NB
    DEPLOY_OUT --> EVAL_UTIL
    click EVAL_UTIL "https://github.com/anhtuanhsgs/colorrl/blob/master/evaluation/utils.py"
    click EVAL_METR "https://github.com/anhtuanhsgs/colorrl/blob/master/evaluation/metrics.py"
    click EVAL_NB "https://github.com/anhtuanhsgs/colorrl/blob/master/evaluation/*.ipynb"

    %% Testing & Validation
    subgraph "Testing & Validation" 
        TEST1["test.py"]:::scripts
        TEST2["test_models.py"]:::scripts
    end
    click TEST1 "https://github.com/anhtuanhsgs/colorrl/blob/master/test.py"
    click TEST2 "https://github.com/anhtuanhsgs/colorrl/blob/master/test_models.py"

    %% Player Utilities
    PLAYER_UTIL["player_util.py"]:::scripts
    click PLAYER_UTIL "https://github.com/anhtuanhsgs/colorrl/blob/master/player_util.py"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef train fill:#D0FFD6,stroke:#028A0F,color:#028A0F;
    classDef deploy fill:#FFE4B3,stroke:#E28A00,color:#E28A00;
    classDef eval fill:#F2D4FF,stroke:#A000E2,color:#A000E2;
    classDef scripts fill:#F0F0F0,stroke:#888888,color:#333333;
```
