# peterande/d-fine architecture

> Architecture diagram of the GitHub repository peterande/d-fine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peterande/d-fine
- Repository: https://github.com/peterande/d-fine

## Overview

D-FINE is a real-time object-detection system centered on fine-grained distribution refinement and localization self-distillation. Its principal workflow configures a detector, loads and transforms labeled images, trains and validates the model, then produces postprocessed detections for inference or export. The graph includes documented capabilities whose implementations are not fully sampled; their connections are omitted or marked unverified rather than inferred. Source excerpts show parts of data loading, the decoder, and training, while the README supplies the high-level product and capability context.

Main entry points: [`src/solver/det_engine.py`](https://github.com/peterande/d-fine/blob/master/src/solver/det_engine.py) (Detection engine), [`tools/inference`](https://github.com/peterande/d-fine/tree/master/tools/inference) (Inference tools), [`src/zoo/dfine/dfine_decoder.py`](https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/dfine_decoder.py) (D-FINE decoder), [`train.py`](https://github.com/peterande/d-fine/blob/master/train.py) (Training entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_yaml_config["YAML config<br/>[yaml_config.py]"]
  node_workspace["Component registry<br/>[workspace.py]"]
end

subgraph group_data["Data pipeline"]
  node_dataset["Detection datasets<br/>[coco_dataset.py]"]
  node_transforms["Image transforms"]
  node_loader["Batch loader<br/>[dataloader.py]"]
end

subgraph group_detector["Detection model"]
  node_backbone["Feature backbone<br/>[hgnetv2.py]"]
  node_encoder["Hybrid encoder<br/>[hybrid_encoder.py]"]
  node_decoder["D-FINE decoder<br/>[dfine_decoder.py]"]
  node_denoising["Denoising queries<br/>[denoising.py]"]
  node_criterion["Detection losses<br/>[dfine_criterion.py]"]
  node_postprocessor["Detection postprocess<br/>[postprocessor.py]"]
end

subgraph group_training["Training and evaluation"]
  node_train_entry["Training entry<br/>[train.py]"]
  node_engine["Detection engine<br/>[det_engine.py]"]
  node_solver["Training solver<br/>[det_solver.py]"]
  node_validator["Model validation<br/>[validator.py]"]
  node_optim["Optimization tools<br/>[optim.py]"]
  node_ema["EMA weights<br/>[ema.py]"]
end

subgraph group_deployment["Inference and deployment"]
  node_export["Model export<br/>[export_onnx.py]"]
  node_inference["Inference tools"]
end

node_user(("Researcher"))
node_runtime(("External runtime"))

node_user -->|"starts training"| node_train_entry
node_train_entry -->|"loads config"| node_yaml_config
node_train_entry -->|"starts solver"| node_solver
node_yaml_config -.->|"builds components"| node_workspace
node_loader -->|"reads samples"| node_dataset
node_dataset -.->|"applies transforms"| node_transforms
node_solver -.->|"runs epochs"| node_engine
node_engine -->|"iterates batches"| node_loader
node_engine -->|"validates model"| node_validator
node_engine -.->|"updates weights"| node_optim
node_engine -.->|"updates average"| node_ema
node_engine -.->|"computes losses"| node_criterion
node_engine -.->|"runs detector"| node_backbone
node_backbone -.->|"provides features"| node_encoder
node_encoder -.->|"passes features"| node_decoder
node_decoder -->|"uses queries"| node_denoising
node_decoder -.->|"provides predictions"| node_criterion
node_user -.->|"requests export"| node_export
node_export -.->|"exports model"| node_inference
node_user -.->|"runs inference"| node_inference
node_inference -.->|"formats detections"| node_postprocessor
node_inference -.->|"targets runtime"| node_runtime

click node_train_entry "https://github.com/peterande/d-fine/blob/master/train.py"
click node_yaml_config "https://github.com/peterande/d-fine/blob/master/src/core/yaml_config.py"
click node_workspace "https://github.com/peterande/d-fine/blob/master/src/core/workspace.py"
click node_dataset "https://github.com/peterande/d-fine/blob/master/src/data/dataset/coco_dataset.py"
click node_transforms "https://github.com/peterande/d-fine/tree/master/src/data/transforms"
click node_loader "https://github.com/peterande/d-fine/blob/master/src/data/dataloader.py"
click node_backbone "https://github.com/peterande/d-fine/blob/master/src/nn/backbone/hgnetv2.py"
click node_encoder "https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/hybrid_encoder.py"
click node_decoder "https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/dfine_decoder.py"
click node_denoising "https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/denoising.py"
click node_criterion "https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/dfine_criterion.py"
click node_postprocessor "https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/postprocessor.py"
click node_engine "https://github.com/peterande/d-fine/blob/master/src/solver/det_engine.py"
click node_solver "https://github.com/peterande/d-fine/blob/master/src/solver/det_solver.py"
click node_validator "https://github.com/peterande/d-fine/blob/master/src/solver/validator.py"
click node_optim "https://github.com/peterande/d-fine/blob/master/src/optim/optim.py"
click node_ema "https://github.com/peterande/d-fine/blob/master/src/optim/ema.py"
click node_export "https://github.com/peterande/d-fine/blob/master/tools/deployment/export_onnx.py"
click node_inference "https://github.com/peterande/d-fine/tree/master/tools/inference"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_yaml_config,node_workspace toneBlue
class node_dataset,node_transforms,node_loader toneAmber
class node_backbone,node_encoder,node_decoder,node_denoising,node_criterion,node_postprocessor toneMint
class node_train_entry,node_engine,node_solver,node_validator,node_optim,node_ema toneRose
class node_export,node_inference,node_user,node_runtime toneIndigo
```

## Components

### Configuration

- [YAML config](https://github.com/peterande/d-fine/blob/master/src/core/yaml_config.py): `src/core/yaml_config.py`
- [Component registry](https://github.com/peterande/d-fine/blob/master/src/core/workspace.py): `src/core/workspace.py`

### Data pipeline

- [Detection datasets](https://github.com/peterande/d-fine/blob/master/src/data/dataset/coco_dataset.py): `src/data/dataset/coco_dataset.py`
- [Image transforms](https://github.com/peterande/d-fine/tree/master/src/data/transforms): `src/data/transforms`
- [Batch loader](https://github.com/peterande/d-fine/blob/master/src/data/dataloader.py): `src/data/dataloader.py`

### Detection model

- [Feature backbone](https://github.com/peterande/d-fine/blob/master/src/nn/backbone/hgnetv2.py): `src/nn/backbone/hgnetv2.py`
- [Hybrid encoder](https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/hybrid_encoder.py): `src/zoo/dfine/hybrid_encoder.py`
- [D-FINE decoder](https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/dfine_decoder.py): `src/zoo/dfine/dfine_decoder.py`
- [Denoising queries](https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/denoising.py): `src/zoo/dfine/denoising.py`
- [Detection losses](https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/dfine_criterion.py): `src/zoo/dfine/dfine_criterion.py`
- [Detection postprocess](https://github.com/peterande/d-fine/blob/master/src/zoo/dfine/postprocessor.py): `src/zoo/dfine/postprocessor.py`

### Training and evaluation

- [Training entry](https://github.com/peterande/d-fine/blob/master/train.py): `train.py`
- [Detection engine](https://github.com/peterande/d-fine/blob/master/src/solver/det_engine.py): `src/solver/det_engine.py`
- [Training solver](https://github.com/peterande/d-fine/blob/master/src/solver/det_solver.py): `src/solver/det_solver.py`
- [Model validation](https://github.com/peterande/d-fine/blob/master/src/solver/validator.py): `src/solver/validator.py`
- [Optimization tools](https://github.com/peterande/d-fine/blob/master/src/optim/optim.py): `src/optim/optim.py`
- [EMA weights](https://github.com/peterande/d-fine/blob/master/src/optim/ema.py): `src/optim/ema.py`

### Inference and deployment

- [Model export](https://github.com/peterande/d-fine/blob/master/tools/deployment/export_onnx.py): `tools/deployment/export_onnx.py`
- [Inference tools](https://github.com/peterande/d-fine/tree/master/tools/inference): `tools/inference`

### Other components

- **Researcher**
- **External runtime**

## Connections

- Researcher → Training entry: starts training
- Training entry → YAML config: loads config (evidence: `train.py`)
- Training entry → Training solver: starts solver (evidence: `train.py`)
- YAML config → Component registry: builds components
- Batch loader → Detection datasets: reads samples (evidence: `src/data/dataloader.py`)
- Detection datasets → Image transforms: applies transforms
- Training solver → Detection engine: runs epochs
- Detection engine → Batch loader: iterates batches (evidence: `src/solver/det_engine.py`)
- Detection engine → Model validation: validates model (evidence: `src/solver/det_engine.py`)
- Detection engine → Optimization tools: updates weights
- Detection engine → EMA weights: updates average
- Detection engine → Detection losses: computes losses
- Detection engine → Feature backbone: runs detector
- Feature backbone → Hybrid encoder: provides features
- Hybrid encoder → D-FINE decoder: passes features
- D-FINE decoder → Denoising queries: uses queries (evidence: `src/zoo/dfine/dfine_decoder.py`)
- D-FINE decoder → Detection losses: provides predictions
- Researcher → Model export: requests export
- Model export → Inference tools: exports model
- Researcher → Inference tools: runs inference
- Inference tools → Detection postprocess: formats detections
- Inference tools → External runtime: targets runtime
