# mehdih7/rf-detr architecture

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

- Interactive diagram: https://gitdiagram.com/mehdih7/rf-detr
- Repository: https://github.com/mehdih7/rf-detr

## Overview

##### Overall Project Breakdown
- Project as a deep learning training framework for object detection using RF-DETR.
- Recognize that the system includes separate entry points for training (train.py, train_RF-DETR.py), evaluation (evaluate_model.py), and result analysis (analyze_results.py).
- Understand that external configuration (config.json) and utility modules (under utils/) support the training, logging, distributed processing, and file management functions.

##### Main Components
a. Configuration & Setup:
- Config.json file as the starting point for setting training, model, loss, data, and distributed parameters.
- Configuration loading utilities from utils/config.py.
b. Training Engine:
- That this entry point routes to the trainers modules:
- trainers/single_gpu.py (for non-distributed training)
- trainers/distributed.py (for distributed training)
- Decision logic (possibly involving utilities in utils/distributed.py) which determines whether to use single GPU or distributed training.
c. Utility & Support Modules:
- Various utility modules (in the utils/ folder) for analysis (utils/analysis.py), directory management (utils/directories.py), logging (utils/logging.py), and training parameter management (utils/training.py).
- How these modules support both the training and evaluation processes.
d. Evaluation Pipeline:
- Automatic (or optionally overridden) class name detection and the generation of evaluation plots.
e. Analysis and Reporting:
- Analyze_results.py as a separate module that takes the output run directory (with its detailed structure containing configuration, training history, predictions, plots, etc.) and produces detailed performance graphs (loss curves, accuracy, confusion matrices, etc.).

##### Data Flow and Interactions
- Utilities (esp. config, logging, directories, distributed) to both the training and evaluation modules to underline their reusable nature.
- That:
- Once training is complete, output directories are populated with checkpoints, training history, and analysis plots.
- The evaluation script consumes these outputs for test inference and metric generation.
- The analysis script further processes the output data to create comprehensive visual reports.
- That support scripts (like convert_to_coco.py and dataset-download.py) facilitate data transformation and acquisition used during training and evaluation.

##### Architectural Patterns & Technologies
- Modular design of the project: clear separation between training, evaluation, analysis, and utility functionality.
- That the architecture supports both centralized and distributed approaches (using a form of abstraction for training methods).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Setup
    subgraph "Configuration & Setup"
        configFile["config.json"]:::config
        configLoader["Configuration Loader\n(utils/config.py)"]:::config
        configFile -->|"loads"| configLoader
    end

    %% Training Engine
    subgraph "Training Engine"
        trainPy["train.py"]:::entry
        trainRF["train_RF-DETR.py"]:::entry
        distLogic["Distributed Logic\n(utils/distributed.py)"]:::logic
        singleGPU["Single GPU Trainer\n(trainers/single_gpu.py)"]:::trainer
        distributed["Distributed Trainer\n(trainers/distributed.py)"]:::trainer

        trainPy -->|"uses"| distLogic
        trainRF -->|"uses"| distLogic
        distLogic --"single"--> singleGPU
        distLogic --"distributed"--> distributed
    end

    %% Utility & Support Modules
    subgraph "Utility & Support Modules"
        utilAnalysis["Analysis Utilities\n(utils/analysis.py)"]:::util
        utilDirectories["Directory Management\n(utils/directories.py)"]:::util
        utilLogging["Logging Utilities\n(utils/logging.py)"]:::util
        utilTraining["Training Parameter Management\n(utils/training.py)"]:::util
    end

    %% Output & Reporting
    subgraph "Output & Reporting"
        trainingOutput["Training Output\n(checkpoints, logs, plots)"]:::output
        evaluation["Evaluation Module\n(evaluate_model.py)"]:::eval
        analysis["Analysis Module\n(analyze_results.py)"]:::analysis

        singleGPU --> trainingOutput
        distributed --> trainingOutput
        trainingOutput --> evaluation
        evaluation --> analysis
    end

    %% Data Tools
    subgraph "Data Tools"
        dataConversion["Data Conversion\n(convert_to_coco.py)"]:::data
        dataDownload["Data Downloading\n(dataset-download.py)"]:::data
    end

    %% External Services
    external["External Services\n(Comet ML & DL Libraries)"]:::external

    %% Connections among groups
    configLoader --> trainPy
    configLoader --> trainRF

    utilLogging --> trainPy
    utilLogging --> trainRF
    utilTraining --> trainPy
    utilTraining --> trainRF
    utilDirectories --> trainingOutput
    utilAnalysis --> evaluation

    external --> trainPy
    external --> trainRF

    %% Click Events
    click configFile "https://github.com/mehdih7/rf-detr/blob/main/config.json"
    click configLoader "https://github.com/mehdih7/rf-detr/blob/main/utils/config.py"
    click trainPy "https://github.com/mehdih7/rf-detr/blob/main/train.py"
    click trainRF "https://github.com/mehdih7/rf-detr/blob/main/train_RF-DETR.py"
    click distLogic "https://github.com/mehdih7/rf-detr/blob/main/utils/distributed.py"
    click singleGPU "https://github.com/mehdih7/rf-detr/blob/main/trainers/single_gpu.py"
    click distributed "https://github.com/mehdih7/rf-detr/blob/main/trainers/distributed.py"
    click utilAnalysis "https://github.com/mehdih7/rf-detr/blob/main/utils/analysis.py"
    click utilDirectories "https://github.com/mehdih7/rf-detr/blob/main/utils/directories.py"
    click utilLogging "https://github.com/mehdih7/rf-detr/blob/main/utils/logging.py"
    click utilTraining "https://github.com/mehdih7/rf-detr/blob/main/utils/training.py"
    click evaluation "https://github.com/mehdih7/rf-detr/blob/main/evaluate_model.py"
    click analysis "https://github.com/mehdih7/rf-detr/blob/main/analyze_results.py"
    click dataConversion "https://github.com/mehdih7/rf-detr/blob/main/convert_to_coco.py"
    click dataDownload "https://github.com/mehdih7/rf-detr/blob/main/dataset-download.py"

    %% Styling
    classDef config fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef entry fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef logic fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef trainer fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef util fill:#f5c6cb,stroke:#333,stroke-width:2px;
    classDef output fill:#ffe5b4,stroke:#333,stroke-width:2px;
    classDef eval fill:#b3e5fc,stroke:#333,stroke-width:2px;
    classDef analysis fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef data fill:#d1e7dd,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
