# yueliao/cdn architecture

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

- Interactive diagram: https://gitdiagram.com/yueliao/cdn
- Repository: https://github.com/yueliao/cdn

## Overview

##### Project Type and Purpose
- This is a research-oriented deep learning codebase for Human-Object Interaction (HOI) detection.
- It implements a hybrid “two-stage + one-stage” detection network (CDN), built on top of DETR, PPDM and QPIC ideas, for HICO-DET and V-COCO benchmarks.

##### File Structure
- Top-level scripts:
- main.py: entry point for training/evaluation
- engine.py: training & evaluation loops, distributed setup
- convert_parameters.py: prepares DETR pretrained weights
- convert_vcoco_annotations.py & generate_vcoco_official.py: data conversion & metric generation
- Directories:
- datasets/: data loaders & transforms for HICO and V-COCO
- models/: building blocks — backbone, position encoding, matcher, CDN HOI heads
- paper_images/: contains the published framework illustration
- Config & metadata:
- requirements.txt, README.md, LICENSE

##### Key Insights from README
- The framework image outlines data prep → model (backbone + two decoders) → loss/matcher → output.
- Supports multi-GPU training via torch.distributed.launch.
- Two-step training: base model → dynamic re-weighting fine-tune.
- Evaluation includes both built-in scripts and an external V-COCO eval module.

##### Main Components
a. Data Preparation & Conversion
- External data sources (HICO-DET, V-COCO)
- Conversion scripts (convert_vcoco_annotations.py, convert_parameters.py)
- Local data store (data/hico_20160224_det, data/v-coco)
b. Data Pipeline
- datasets/*.py: Dataset classes + transforms
- DataLoader → batching
c. Model
- Backbone (ResNet50)
- Encoding
- Query-based DETR decoder for object proposals
- Two HOI decoders:
- hopd (two-stage)
- interaction (one-stage)
- Matcher (Hungarian algorithm)
d. Training Engine
- engine.py: forward, compute losses, backward, optimizer step
- Distributed training orchestration
e. Evaluation & Output
- Built-in eval via main.py with --eval
- Official V-COCO eval (generate_vcoco_official.py + vsrl_eval.py)
- Outputs: logs/, checkpoint files, .pickle results

##### Relationships & Data Flow
- From local data → Dataset loader → model input.
- Within model: image → backbone → feature maps → queries → HOI decoders → predictions.
- Predictions → matcher → loss → engine → optimized weights → checkpoints.
- Checkpoints → evaluation scripts → metrics.

##### Architectural Patterns & Design Principles
- Modular separation: dataset code vs. model vs. engine vs. utilities.
- Dependency injection: passing configs/paths via CLI arguments.
- Reuse of external libraries: DETR, PPDM, PyTorch Distributed.
- Two-stage pipeline (proposal + interaction) combined with one-stage pipeline (end-to-end queries).

##### Technologies & Frameworks
- Python 3 (with Python 2 requirement only for V-COCO conversion)
- PyTorch + torchvision
- Torch distributed for multi-GPU
- External repos: DETR, PPDM, QPIC

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Preparation & Conversion Layer
    subgraph "Data Preparation & Conversion" 
        direction TB
        EXTSRC_HICO["HICO-DET & V-COCO Data"]:::ext
        CONV_VCOCO["convert_vcoco_annotations.py"]:::data
        CONV_DETR["convert_parameters.py"]:::data
        GEN_VCOCO["generate_vcoco_official.py"]:::data
        LOCAL_DATA["Local Data Store\n(data/hico_20160224_det, data/v-coco)"]:::data
    end

    %% Data Pipeline Layer
    subgraph "Data Loading & Transforms"
        direction TB
        HICO_DS["HICO Dataset & Transforms"]:::data
        VCOCO_DS["V-COCO Dataset & Transforms"]:::data
        TRANSFORMS["Shared Transforms"]:::data
        DATALOADER["DataLoader & Batching"]:::data
        HICO_EVAL_UTIL["HICO Evaluation Utils"]:::data
        VCOCO_EVAL_UTIL["V-COCO Evaluation Utils"]:::data
    end

    %% Model Components Layer
    subgraph "Model Components"
        direction TB
        BACKBONE["Backbone (ResNet50)"]:::model
        POSENC["Position Encoding"]:::model
        DETR_DECODER["DETR Query Decoder"]:::model
        HOI_HEADS["CDN Hybrid HOI Detector"]:::model
        INTERACT_DECODER["HOI Detection Heads & Interaction Decoder"]:::model
        MATCHER["Hungarian Matcher"]:::model
    end

    %% Training Engine Layer
    subgraph "Training Engine" 
        direction TB
        ENGINE["engine.py\n(Training & Eval Loops,\nDistributed Setup)"]:::train
        MAIN["main.py\n(CLI Interface)"]:::train
    end

    %% Evaluation & Metrics Layer
    subgraph "Evaluation & Output"
        direction TB
        BUILT_IN_EVAL["Built-in Eval (--eval)"]:::eval
        VCOCO_OFF_EVAL["Official V-COCO Eval\n(generate_vcoco_official)"]:::eval
        OUTPUTS["Outputs:\nlogs/, checkpoints, .pickle"]:::eval
    end

    %% Data Conversion Flow
    EXTSRC_HICO -->|"raw data"| CONV_VCOCO
    EXTSRC_HICO -->|"raw data"| CONV_DETR
    CONV_VCOCO --> LOCAL_DATA
    CONV_DETR --> LOCAL_DATA
    GEN_VCOCO -.-> LOCAL_DATA

    %% Data Pipeline Flow
    LOCAL_DATA --> HICO_DS
    LOCAL_DATA --> VCOCO_DS
    HICO_DS --> TRANSFORMS
    VCOCO_DS --> TRANSFORMS
    TRANSFORMS --> DATALOADER

    %% Model Flow
    DATALOADER --> BACKBONE
    BACKBONE --> POSENC
    POSENC --> DETR_DECODER
    DETR_DECODER --> HOI_HEADS
    HOI_HEADS --> INTERACT_DECODER
    INTERACT_DECODER --> MATCHER

    %% Training Flow
    MATCHER -->|"losses"| ENGINE
    ENGINE -->|"optimizer step"| BACKBONE
    ENGINE --> MAIN

    %% Evaluation Flow
    MAIN -->|"--eval"| BUILT_IN_EVAL
    BUILT_IN_EVAL --> OUTPUTS
    BUILT_IN_EVAL --> VCOCO_OFF_EVAL
    VCOCO_OFF_EVAL --> OUTPUTS

    %% Click Events
    click CONV_VCOCO "https://github.com/yueliao/cdn/blob/main/convert_vcoco_annotations.py"
    click CONV_DETR "https://github.com/yueliao/cdn/blob/main/convert_parameters.py"
    click GEN_VCOCO "https://github.com/yueliao/cdn/blob/main/generate_vcoco_official.py"
    click HICO_DS "https://github.com/yueliao/cdn/blob/main/datasets/hico.py"
    click VCOCO_DS "https://github.com/yueliao/cdn/blob/main/datasets/vcoco.py"
    click TRANSFORMS "https://github.com/yueliao/cdn/blob/main/datasets/transforms.py"
    click HICO_EVAL_UTIL "https://github.com/yueliao/cdn/blob/main/datasets/hico_eval.py"
    click VCOCO_EVAL_UTIL "https://github.com/yueliao/cdn/blob/main/datasets/vcoco_eval.py"
    click BACKBONE "https://github.com/yueliao/cdn/blob/main/models/backbone.py"
    click POSENC "https://github.com/yueliao/cdn/blob/main/models/position_encoding.py"
    click HOI_HEADS "https://github.com/yueliao/cdn/blob/main/models/cdn.py"
    click INTERACT_DECODER "https://github.com/yueliao/cdn/blob/main/models/hoi.py"
    click MATCHER "https://github.com/yueliao/cdn/blob/main/models/matcher.py"
    click ENGINE "https://github.com/yueliao/cdn/blob/main/engine.py"
    click MAIN "https://github.com/yueliao/cdn/blob/main/main.py"
    click BOXOPS "https://github.com/yueliao/cdn/blob/main/util/box_ops.py"
    click MISC "https://github.com/yueliao/cdn/blob/main/util/misc.py"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef model fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef train fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef eval fill:#E1BEE7,stroke:#8E24AA,color:#4A148C
    classDef ext fill:#ECEFF1,stroke:#607D8B,color:#263238
```
