# turoad/clrnet architecture

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

- Interactive diagram: https://gitdiagram.com/turoad/clrnet
- Repository: https://github.com/turoad/clrnet

## Overview

##### Project type and purpose
- CLRNet is a research‐oriented deep-learning framework (PyTorch) for lane detection (computer vision).
- It implements the “Cross Layer Refinement Network” for training, validating, and inferring lane lines on CULane, TuSimple, and LLAMAS datasets.

##### File structure
- Top level:
- main.py – entry point for training/validation/inference
- configs/ – model‐and‐dataset configuration scripts
- tools/ – auxiliary scripts (e.g., segmentation label generator)
- clrnet/ – core Python package
- setup.py, requirements.txt – packaging and dependencies
- clrnet/ subpackages:
- datasets/ – dataset classes, preprocessing, registry
- models/ – network backbones, necks, heads, losses, registry
- engine/ – training runner, optimizer & scheduler setup, registry
- ops/ – custom C++/CUDA operators (e.g., NMS)
- utils/ – configuration loader, logging, metrics, visualization, registry

##### README for architecture insights
- Input image → Backbone → Neck → Head → Refinement → Output lanes
- Training pipeline with losses, optimizer, scheduler
- Validation/inference with visualization

##### Main components
a. Data sources (external datasets)
– CULane, TuSimple, LLAMAS (mounted under `data/`)
b. Data pipeline
– `datasets/` classes & `process/transforms.py` → PyTorch DataLoader
c. Model pipeline
– Backbone (ResNet, DLA) → Neck (FPN, PAFPN) → CLR Head → Cross-layer refinement
d. Training engine
– Runner (engine/runner.py) orchestrates forward/backward, collects losses
– Optimizer & Scheduler (engine/optimizer.py & scheduler.py)
– Recorder & Logger (utils/recorder.py, utils/logger.py)
e. Custom operators
– NMS in `ops/csrc` for post-processing
f. Inference & visualization
– Runner’s validate/test mode → outputs → utils/visualization.py

##### Relationships and data flows
- CLI (`main.py`)
→ Load config (utils/config.py)
→ Instantiate Runner
→ Runner
- calls Dataset → DataLoader → batch of images
- feeds images to Model
- computes losses via Loss modules
- updates via Optimizer & Scheduler
- logs metrics & checkpoints
- on validate/test: runs model, calls NMS, then visualization
- Tools script (`tools/generate_seg_tusimple.py`)
→ consumes raw TuSimple JSON → generates segmentation labels

##### Architectural patterns and design principles
- Modular registry pattern (datasets, models, engines) for plug-and-play
- Separation of concerns: data, model, engine, utils, ops
- Config-driven design: all hyperparameters and paths in `configs/`
- Extensibility via custom ops and registries

- Notation for file‐based configuration (configs/*.py) feeding into Runner

- Visualizes the end-to-end training/inference flow
- Highlights the modular architecture and registry patterns
- Illustrates how core components interact with data, configs, and custom ops
- Is tailored to the CLRNet project’s structure and cross-layer refinement objective

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data
    subgraph "External Datasets" 
        direction TB
        CULane["CULane Dataset"]:::gray
        TuSimple["TuSimple Dataset"]:::gray
        LLAMAS["LLAMAS Dataset"]:::gray
    end

    %% Configuration
    Configs["configs/*.py"]:::gray
    click Configs "https://github.com/turoad/clrnet/tree/main/configs/clrnet/"

    %% CLI Entry
    CLI["main.py"]:::orange
    click CLI "https://github.com/turoad/clrnet/blob/main/main.py"

    %% Data & Preprocessing
    subgraph "Data & Preprocessing" 
        direction TB
        DatasetRegistry["Dataset Registry"]:::blue
        click DatasetRegistry "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/registry.py"
        BaseDataset["base_dataset.py"]:::blue
        click BaseDataset "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/base_dataset.py"
        CULaneDS["culane.py"]:::blue
        click CULaneDS "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/culane.py"
        TuSimpleDS["tusimple.py"]:::blue
        click TuSimpleDS "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/tusimple.py"
        LLAMASDS["llamas.py"]:::blue
        click LLAMASDS "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/llamas.py"
        Process["process.py"]:::blue
        click Process "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/process/process.py"
        Transforms["transforms.py"]:::blue
        click Transforms "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/process/transforms.py"
        GenerateLane["generate_lane_line.py"]:::blue
        click GenerateLane "https://github.com/turoad/clrnet/blob/main/clrnet/datasets/process/generate_lane_line.py"
        DataLoader["PyTorch DataLoader"]:::blue
    end

    %% Model Components
    subgraph "Model Components" 
        direction TB
        ModelRegistry["Model Registry"]:::green
        click ModelRegistry "https://github.com/turoad/clrnet/blob/main/clrnet/models/registry.py"
        Backbone["Backbone (ResNet, DLA)"]:::green
        ResNet["resnet.py"]:::green
        click ResNet "https://github.com/turoad/clrnet/blob/main/clrnet/models/backbones/resnet.py"
        DLA["dla34.py"]:::green
        click DLA "https://github.com/turoad/clrnet/blob/main/clrnet/models/backbones/dla34.py"
        Neck["Neck (FPN, PAFPN)"]:::green
        FPN["fpn.py"]:::green
        click FPN "https://github.com/turoad/clrnet/blob/main/clrnet/models/necks/fpn.py"
        PAFPN["pafpn.py"]:::green
        click PAFPN "https://github.com/turoad/clrnet/blob/main/clrnet/models/necks/pafpn.py"
        CLRHead["CLR Head"]:::green
        click CLRHead "https://github.com/turoad/clrnet/blob/main/clrnet/models/heads/clr_head.py"
        DetectorNet["Detector Net"]:::green
        click DetectorNet "https://github.com/turoad/clrnet/blob/main/clrnet/models/nets/detector.py"
        Losses["Loss Functions"]:::green
        Accuracy["accuracy.py"]:::green
        click Accuracy "https://github.com/turoad/clrnet/blob/main/clrnet/models/losses/accuracy.py"
        Focal["focal_loss.py"]:::green
        click Focal "https://github.com/turoad/clrnet/blob/main/clrnet/models/losses/focal_loss.py"
        LineIoU["lineiou_loss.py"]:::green
        click LineIoU "https://github.com/turoad/clrnet/blob/main/clrnet/models/losses/lineiou_loss.py"
    end

    %% Training Engine & Utils
    subgraph "Training Engine & Utilities"
        direction TB
        Runner["Runner"]:::orange
        click Runner "https://github.com/turoad/clrnet/blob/main/clrnet/engine/runner.py"
        Optimizer["Optimizer Setup"]:::orange
        click Optimizer "https://github.com/turoad/clrnet/blob/main/clrnet/engine/optimizer.py"
        Scheduler["Scheduler Setup"]:::orange
        click Scheduler "https://github.com/turoad/clrnet/blob/main/clrnet/engine/scheduler.py"
        EngineRegistry["Engine Registry"]:::orange
        click EngineRegistry "https://github.com/turoad/clrnet/blob/main/clrnet/engine/registry.py"
        Logger["Logger"]:::orange
        click Logger "https://github.com/turoad/clrnet/blob/main/clrnet/utils/logger.py"
        Recorder["Recorder"]:::orange
        click Recorder "https://github.com/turoad/clrnet/blob/main/clrnet/utils/recorder.py"
        ConfigLoader["Config Loader"]:::orange
        click ConfigLoader "https://github.com/turoad/clrnet/blob/main/clrnet/utils/config.py"
        Visualization["Visualization"]:::orange
        click Visualization "https://github.com/turoad/clrnet/blob/main/clrnet/utils/visualization.py"
        CULaneMetric["culane_metric.py"]:::orange
        click CULaneMetric "https://github.com/turoad/clrnet/blob/main/clrnet/utils/culane_metric.py"
        TuSimpleMetric["tusimple_metric.py"]:::orange
        click TuSimpleMetric "https://github.com/turoad/clrnet/blob/main/clrnet/utils/tusimple_metric.py"
        LLAMASMetric["llamas_metric.py"]:::orange
        click LLAMASMetric "https://github.com/turoad/clrnet/blob/main/clrnet/utils/llamas_metric.py"
        LLAMASUtils["llamas_utils.py"]:::orange
        click LLAMASUtils "https://github.com/turoad/clrnet/blob/main/clrnet/utils/llamas_utils.py"
    end

    %% Custom Operators
    subgraph "Custom C++/CUDA Ops" 
        direction TB
        NMSCPP["nms.cpp"]:::red
        click NMSCPP "https://github.com/turoad/clrnet/blob/main/clrnet/ops/csrc/nms.cpp"
        NMSKernel["nms_kernel.cu"]:::red
        click NMSKernel "https://github.com/turoad/clrnet/blob/main/clrnet/ops/csrc/nms_kernel.cu"
        NMSPy["nms.py"]:::red
        click NMSPy "https://github.com/turoad/clrnet/blob/main/clrnet/ops/nms.py"
    end

    %% Tools
    Tools["generate_seg_tusimple.py"]:::gray
    click Tools "https://github.com/turoad/clrnet/blob/main/tools/generate_seg_tusimple.py"

    %% Core Flow
    CLI -->|"load config"| ConfigLoader
    CLI -->|"init runner"| Runner
    ConfigLoader --> Configs
    CULane --> DatasetRegistry
    TuSimple --> DatasetRegistry
    LLAMAS --> DatasetRegistry
    DatasetRegistry --> BaseDataset
    BaseDataset --> CULaneDS & TuSimpleDS & LLAMASDS
    CULaneDS & TuSimpleDS & LLAMASDS --> Process
    Process --> Transforms
    Transforms --> GenerateLane
    GenerateLane --> DataLoader
    DataLoader -->|batch of images| Backbone
    Backbone --> Neck
    Neck --> CLRHead
    CLRHead --> DetectorNet
    DetectorNet --> Losses
    Losses --> Runner
    Runner --> Optimizer
    Runner --> Scheduler
    Runner --> Logger
    Runner --> Recorder
    Runner -->|validate/test| NMSPy
    NMSPy --> Visualization

    Tools --> GenerateLane

    %% Styles
    classDef blue fill:#E3F2FD,stroke:#90CAF9,stroke-width:1px;
    classDef green fill:#E8F5E9,stroke:#66BB6A,stroke-width:1px;
    classDef orange fill:#FFF3E0,stroke:#FFA726,stroke-width:1px;
    classDef red fill:#FFEBEE,stroke:#EF5350,stroke-width:1px;
    classDef gray fill:#ECEFF1,stroke:#B0BEC5,stroke-width:1px;
```
