# woxihuanjiangguo/bevnext architecture

> Architecture diagram of the GitHub repository woxihuanjiangguo/bevnext, 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/woxihuanjiangguo/bevnext
- Repository: https://github.com/woxihuanjiangguo/bevnext

## Overview

##### Project type and purpose
- BEVNeXt is a deep‐learning research framework for 3D object detection using Bird’s‐Eye‐View (BEV) representations.
- It is built on top of mmdetection3d and BEVDet, providing modular components for data handling, model definition, training, inference, and deployment.
- It’s neither a web service nor a classic full-stack app, but rather a machine‐learning library + CLI toolchain + model zoo.

##### File structure
- config/… : hundreds of Python config files grouped by model family (bevnext, bevdet, centerpoint, etc.), base defaults, datasets, schedules.
- mmdet3d/… : the core Python package with submodules
- apis: train/inference/test entry-points
- core: anchor generators, bbox coders, voxel utilities, hook system, evaluation
- datasets: dataset wrappers, pipelines, loading/augmentation
- models: backbones, necks, heads, detectors, losses, fusion layers, ops
- ops: custom CUDA/CPU kernels (bev_pool, spconv, dgcnn)
- utils: environment setup, logger, config compatibility
- tools/: command-line scripts for data conversion, training (dist_train.sh), testing (dist_test.sh), benchmarking, model conversion, deployment (TorchServe handler)
- demo/: example scripts for point-cloud demos
- docker/: Dockerfiles for building containers and serving models
- docs/: Sphinx documentation in English/Chinese
- tests/: unit tests covering datasets, pipelines, models, runtime, utils

##### README for additional insights
- Describes installation, dataset preparation, multi-stage training & inference workflows
- Highlights dependency on Anaconda, PyTorch, mmcv, mmdetection3d
- Points to config files in configs/bevnext/ for stage1 and stage2

##### Main components & their interactions
a. Data Layer
- Raw datasets (nuScenes, KITTI, Waymo…)
- tools/create_data_bevdet.py → preprocess → generate PKL files
- mmdet3d.datasets + pipelines: loading, augmentation, voxelization
b. Configuration Manager
- Python config files (configs/_base_, configs/bevnext/…)
- Registry & builder pattern (mmdet3d/models/builder.py, mmdet3d/datasets/builder.py)
c. Model Components
- Backbones (ResNet, PointNet2, DGCNN, Voxel encoders)
- Necks (FPN, scatter, view_transformer)
- Heads (dense heads, ROI heads, segmentation heads)
- Fusion modules (temporal fusion for BEV)
- Loss functions & post-processing (NMS, decode)
d. Training & Validation
- mmdet3d.apis.train → builds dataset, model, optimizer, hooks
- Hook system for EMA, sync-BN, checkpointing
- Distributed training scripts (tools/dist_train.sh)
e. Inference & Evaluation
- mmdet3d.apis.inference / test → load checkpoint → forward → postprocess → metrics
- tools/dist_test.sh, tools/deployment/mmdet3d2torchserve.py
f. Deployment
- Docker containers (docker/, docker/serve/)
- TorchServe handler (tools/deployment/mmdet3d_handler.py)

##### Architectural patterns & design principles
- Modular plugin registry (models, datasets, pipelines)
- Separation of concerns: data-I/O, model definition, training loop, deployment
- Config-driven instantiation: no hard-coded hyperparams
- Extendability: add new backbones/heads by registering in builder

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Preprocessing
    subgraph "Data & Preprocessing"
        direction TB
        RawData["Raw Sensor Files"]:::data
        CreateData["create_data_bevdet.py"]:::data
        DataConv["data_converter/"]:::data
        DatasetsPkg["mmdet3d.datasets"]:::core
        RawData --> CreateData --> DataConv --> DatasetsPkg
    end
    click CreateData "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/create_data_bevdet.py"
    click DataConv "https://github.com/woxihuanjiangguo/bevnext/tree/master/tools/data_converter/"
    click DatasetsPkg "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/datasets/"

    %% Configuration Manager
    subgraph "Configuration Manager"
        direction TB
        BaseCfg["configs/_base_/"]:::config
        BevnextCfg["configs/bevnext/"]:::config
        Compat["compat_cfg.py"]:::config
        SetupEnv["setup_env.py"]:::config
        BaseCfg --> BevnextCfg
        BevnextCfg --> Compat
        BevnextCfg --> SetupEnv
    end
    click BaseCfg "https://github.com/woxihuanjiangguo/bevnext/tree/master/configs/_base_/"
    click BevnextCfg "https://github.com/woxihuanjiangguo/bevnext/tree/master/configs/bevnext/"
    click Compat "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/utils/compat_cfg.py"
    click SetupEnv "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/utils/setup_env.py"

    %% Registry & Builder
    subgraph "Model Registry & Builder"
        direction TB
        ModelBuilder["models/builder.py"]:::core
        DataBuilder["datasets/builder.py"]:::core
        BevnextCfg --> ModelBuilder
        BevnextCfg --> DataBuilder
    end
    click ModelBuilder "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/models/builder.py"
    click DataBuilder "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/datasets/builder.py"

    %% Core Library
    subgraph "Core Library"
        direction TB

        subgraph "Model Submodules"
            direction TB
            Backbones["backbones/"]:::core
            Necks["necks/"]:::core
            Heads["dense_heads/ & roi_heads/ & decode_heads/"]:::core
            Fusion["fusion_layers/"]:::core
            Losses["losses/"]:::core
            VoxelEnc["voxel_encoders/"]:::core
            MiddleEnc["middle_encoders/"]:::core
            subgraph Detectors
                direction TB
                Bevdet["bevdet.py"]:::core
                BevnextDet["bevnext.py"]:::core
                Centerpt["centerpoint.py"]:::core
            end
        end

        subgraph "Training & Validation"
            direction TB
            TrainAPI["apis/train.py"]:::core
            Hooks["core/hook/"]:::core
            Logger["core/utils/logger.py"]:::core
            DistTrain["dist_train.sh"]:::cli
        end

        subgraph "Inference & Evaluation"
            direction TB
            InferAPI["apis/inference.py"]:::core
            TestAPI["apis/test.py"]:::core
            EvalCore["core/evaluation/"]:::core
            PostProc["core/post_processing/box3d_nms.py"]:::core
            DistTest["dist_test.sh"]:::cli
        end

    end
    click Backbones "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/models/backbones/"
    click Necks "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/models/necks/"
    click Heads "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/models/dense_heads/"
    click Fusion "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/models/fusion_layers/"
    click Losses "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/models/losses/"
    click VoxelEnc "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/models/voxel_encoders/"
    click MiddleEnc "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/models/middle_encoders/"
    click Bevdet "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/models/detectors/bevdet.py"
    click BevnextDet "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/models/detectors/bevnext.py"
    click Centerpt "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/models/detectors/centerpoint.py"
    click TrainAPI "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/apis/train.py"
    click Hooks "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/core/hook/"
    click Logger "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/core/utils/logger.py"
    click DistTrain "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/dist_train.sh"
    click InferAPI "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/apis/inference.py"
    click TestAPI "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/apis/test.py"
    click EvalCore "https://github.com/woxihuanjiangguo/bevnext/tree/master/mmdet3d/core/evaluation/"
    click PostProc "https://github.com/woxihuanjiangguo/bevnext/blob/master/mmdet3d/core/post_processing/box3d_nms.py"
    click DistTest "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/dist_test.sh"

    %% CLI & Utility Scripts
    subgraph "CLI & Utility Scripts"
        direction TB
        TrainScript["tools/train.py"]:::cli
        TestScript["tools/test.py"]:::cli
        PrintCfg["tools/misc/print_config.py"]:::cli
        Visualize["tools/misc/visualize_results.py"]:::cli
        DevScripts[".dev_scripts/"]:::cli
    end
    click TrainScript "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/train.py"
    click TestScript "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/test.py"
    click PrintCfg "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/misc/print_config.py"
    click Visualize "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/misc/visualize_results.py"
    click DevScripts "https://github.com/woxihuanjiangguo/bevnext/tree/master/.dev_scripts/"

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        direction TB
        DockerMain["docker/"]:::deploy
        DockerServe["docker/serve/"]:::deploy
        Handler["mmdet3d_handler.py"]:::deploy
        Model2TS["mmdet3d2torchserve.py"]:::deploy
    end
    click DockerMain "https://github.com/woxihuanjiangguo/bevnext/tree/master/docker/"
    click DockerServe "https://github.com/woxihuanjiangguo/bevnext/tree/master/docker/serve/"
    click Handler "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/deployment/mmdet3d_handler.py"
    click Model2TS "https://github.com/woxihuanjiangguo/bevnext/blob/master/tools/deployment/mmdet3d2torchserve.py"

    %% Connections
    DatasetsPkg --> TrainAPI
    ModelBuilder --> TrainAPI
    DataBuilder --> DatasetsPkg
    TrainAPI --> DistTrain
    TrainAPI --> Checkpoint
    Checkpoint["Checkpoint"]:::core
    Checkpoint --> InferAPI
    InferAPI --> DistTest
    InferAPI --> EvalCore
    Checkpoint --> Handler
    Handler --> DockerServe
    DockerServe --> Serving["Serving Endpoint"]:::deploy

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch"]:::ext
        MMCV["mmcv"]:::ext
        CUDA["CUDA"]:::ext
    end
    PyTorch --> TrainAPI
    MMCV --> TrainAPI
    CUDA --> Backbones

    %% Styles
    classDef data fill:#D0E8FF,stroke:#004A9F,color:#004A9F
    classDef core fill:#DFF7D9,stroke:#2D8A00,color:#2D8A00
    classDef cli fill:#FFE4B3,stroke:#CC7000,color:#CC7000
    classDef config fill:#F2F2F2,stroke:#999999,color:#333333
    classDef deploy fill:#E8D4F2,stroke:#6F287E,color:#6F287E
    classDef ext fill:#F0F0F0,stroke:#666666,color:#666666
```
