# sejong-rcv/insanet architecture

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

- Interactive diagram: https://gitdiagram.com/sejong-rcv/insanet
- Repository: https://github.com/sejong-rcv/insanet

## Overview

##### Project type and purpose
- This is a specialized machine‐learning research codebase (not a web app or microservice). It implements INSANet, a PyTorch model for multispectral pedestrian detection, with utilities for data download/prep, training, inference, evaluation, and visualization.

##### File structure
- Top-level folders:
- data: download scripts & raw dataset layout
- docker: Dockerfile + Makefile + Python requirements
- evaluation: COCO conversions, benchmark scripts, state-of-art results
- pretrained: scripts to fetch pretrained weights
- src: core implementation (config, datasets, model, train_eval.py, inference.py), plus subfolders:
– script: shell wrappers for train/infer
– utils: helper code (transforms, evaluation scripts)
– imageSets & annotations: dataset index files and JSON
– results: stored detection outputs
- fig: architecture & paper figures
- environment*.yaml: Conda environment specs

##### README for additional insights
- Describes the high-level model architecture (INtra/INter spectral attention)
- Describes Docker vs. Conda setup
- Presents demo, train & inference procedures, evaluation protocols

##### Main components and interactions
a. Data Layer
- External dataset sources (KAIST, LLVIP)
- data/download_*.sh/.py → populates data/kaist-rgbt
- data loader (src/datasets.py + src/imageSets + JSON annotations)
b. Environment & Deployment
- Docker container (docker/Dockerfile, Makefile)
- Conda env (environment.yaml, environment_cu113.yaml)
c. Core Model & Training
- Model definition (src/model.py, src/insa.py)
- Configuration (src/config.py)
- Training script (src/train_eval.py + src/script/train_eval.sh)
- Intra-/Inter-Spectral Attention blocks—key architectural pattern
d. Inference
- Inference entrypoint (src/inference.py + src/script/inference.sh)
- Loads pretrained weights (pretrained/download_pretrained.py)
e. Evaluation & Visualization
- COCO conversion & evaluation (src/utils/coco*.py, evaluation/coco*.py)
- Scene-specific evaluation (src/utils/evaluation_scene*)
- Benchmark plotting (evaluation/evaluation_script.py)
- Visualization tool (vis.py)
f. Outputs & Artifacts
- Trained models (checkpoints)
- Detection results (src/results)
- Figures (fig/, evaluation/*.jpg)

Interactions:
Data Layer → DataLoader → Model → Training/Inﬁnference → Results → Evaluation → Figures

##### Architectural patterns & design principles
- Pipeline pattern: clearly separated stages (data download → preprocessing → training → inference → evaluation)
- Modular organization: config, dataset, model, utils, scripts
- Containerized reproducibility: Docker + Conda
- Attention-based fusion: INSANet blocks in model graph

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    ExternalDatasets("External KAIST & LLVIP"):::external
    ExternalDatasets --> DownloadKAIST
    ExternalDatasets --> DownloadLLVIP

    %% Data Download & Storage
    DownloadKAIST["download_kaist.sh"]:::data
    DownloadLLVIP["download_llvip.py"]:::data
    DownloadKAIST --> DataStorage
    DownloadLLVIP --> DataStorage

    DataStorage[(data/)]:::data
    DataStorage --> DataLoader
    DataStorage --> ImageSets
    DataStorage --> Annotations

    %% Data Loader & Config
    DataLoader["src/datasets.py"]:::compute
    ImageSets[(src/imageSets/)]:::data
    Annotations[(kaist_annotations_test20.json)]:::data
    DataLoader --> Config

    Config["src/config.py"]:::compute

    %% Model Definition
    ModelDef["src/model.py\n(INSANet)"]:::compute
    Insablock["src/insa.py\n(Attention Blocks)"]:::compute
    Config --> ModelDef
    Config --> Insablock

    %% Training Pipeline
    TrainingScript["src/train_eval.py"]:::scripts
    TrainWrapper([train_eval.sh]):::scripts
    DataLoader --> TrainingScript
    ModelDef --> TrainingScript
    Insablock --> TrainingScript
    TrainingScript --> TrainWrapper
    TrainingScript --> Results

    %% Inference Pipeline
    Pretrained["pretrained/download_pretrained.py"]:::scripts
    InferenceScript["src/inference.py"]:::scripts
    InferWrapper([inference.sh]):::scripts
    DataLoader --> InferenceScript
    ModelDef --> InferenceScript
    Pretrained --> InferenceScript
    InferenceScript --> InferWrapper
    InferenceScript --> Results

    %% Evaluation & Visualization
    Results[(src/results/)]:::output
    Results --> EvaluationUtils
    Results --> Visualization

    EvaluationUtils("src/utils coco & scene modules"):::scripts
    EvaluationUtils --> EvaluationProj

    EvaluationProj("evaluation coco & benchmarks"):::scripts
    EvaluationProj --> Figures

    Visualization["src/vis.py"]:::scripts

    Figures[(fig/)]:::output

    %% Environment & Reproducibility
    subgraph "Environment & Container"
        Dockerfile["docker/Dockerfile"]:::env
        Makefile["docker/Makefile"]:::env
        Requirements["docker/requirements.txt"]:::env
        EnvStd["environment.yaml"]:::env
        EnvCuda["environment_cu113.yaml"]:::env
    end

    %% Click Events
    click DownloadKAIST "https://github.com/sejong-rcv/insanet/blob/main/data/download_kaist.sh"
    click DownloadLLVIP "https://github.com/sejong-rcv/insanet/blob/main/data/download_llvip.py"
    click DataStorage "https://github.com/sejong-rcv/insanet/tree/main/data/"
    click DataLoader "https://github.com/sejong-rcv/insanet/blob/main/src/datasets.py"
    click ImageSets "https://github.com/sejong-rcv/insanet/tree/main/src/imageSets/"
    click Annotations "https://github.com/sejong-rcv/insanet/blob/main/src/kaist_annotations_test20.json"
    click Config "https://github.com/sejong-rcv/insanet/blob/main/src/config.py"
    click ModelDef "https://github.com/sejong-rcv/insanet/blob/main/src/model.py"
    click Insablock "https://github.com/sejong-rcv/insanet/blob/main/src/insa.py"
    click TrainingScript "https://github.com/sejong-rcv/insanet/blob/main/src/train_eval.py"
    click TrainWrapper "https://github.com/sejong-rcv/insanet/blob/main/src/script/train_eval.sh"
    click Pretrained "https://github.com/sejong-rcv/insanet/blob/main/pretrained/download_pretrained.py"
    click InferenceScript "https://github.com/sejong-rcv/insanet/blob/main/src/inference.py"
    click InferWrapper "https://github.com/sejong-rcv/insanet/blob/main/src/script/inference.sh"
    click Results "https://github.com/sejong-rcv/insanet/tree/main/src/results/"
    click EvaluationUtils "https://github.com/sejong-rcv/insanet/blob/main/src/utils/coco.py"
    click EvaluationUtils "https://github.com/sejong-rcv/insanet/blob/main/src/utils/cocoeval.py"
    click EvaluationUtils "https://github.com/sejong-rcv/insanet/blob/main/src/utils/evaluation_scene.py"
    click EvaluationUtils "https://github.com/sejong-rcv/insanet/blob/main/src/utils/evaluation_script.py"
    click EvaluationProj "https://github.com/sejong-rcv/insanet/blob/main/evaluation/coco.py"
    click EvaluationProj "https://github.com/sejong-rcv/insanet/blob/main/evaluation/cocoeval.py"
    click EvaluationProj "https://github.com/sejong-rcv/insanet/blob/main/evaluation/evaluation_script.py"
    click EvaluationProj "https://github.com/sejong-rcv/insanet/blob/main/evaluation/state_of_arts/INSANet_result.txt"
    click Visualization "https://github.com/sejong-rcv/insanet/blob/main/src/vis.py"
    click Figures "https://github.com/sejong-rcv/insanet/tree/main/fig/"
    click Dockerfile "https://github.com/sejong-rcv/insanet/tree/main/docker/Dockerfile"
    click Makefile "https://github.com/sejong-rcv/insanet/tree/main/docker/Makefile"
    click Requirements "https://github.com/sejong-rcv/insanet/blob/main/docker/requirements.txt"
    click EnvStd "https://github.com/sejong-rcv/insanet/blob/main/environment.yaml"
    click EnvCuda "https://github.com/sejong-rcv/insanet/blob/main/environment_cu113.yaml"

    %% Styles
    classDef data fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef compute fill:#B8E4B8,stroke:#333,stroke-width:1px
    classDef scripts fill:#F7E79D,stroke:#333,stroke-width:1px
    classDef env fill:#DCC6E0,stroke:#333,stroke-width:1px
    classDef output fill:#F5CBA7,stroke:#333,stroke-width:1px
    classDef external fill:#D5DBDB,stroke:#333,stroke-width:1px
```
