# vijayscodehub/ml_pedestrian_detection_and_tracking architecture

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

- Interactive diagram: https://gitdiagram.com/vijayscodehub/ml_pedestrian_detection_and_tracking
- Repository: https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking

## Overview

This is a KITTI camera–LiDAR pedestrian perception research pipeline. Its principal workflow loads a frame and calibration, detects and tracks pedestrians in RGB, projects LiDAR points into camera coordinates, associates robust depth and 3D position with each box, then renders results and writes tracking/fusion artifacts for evaluation. A separate early-fusion branch rasterizes LiDAR depth images and prepares YOLO datasets; the README also documents detector training and comparison of RGB and depth inputs. Edges reflect the shown runners and explicit README capabilities; unsampled training internals are not inferred.

Main entry points: [`scripts/run_tracking_sequence.py`](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_tracking_sequence.py) (Sequence Runner), [`scripts/run_pipeline.py`](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_pipeline.py) (Object Pipeline Runner), [`src/pedestrian_pipeline/kitti.py`](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/kitti.py) (KITTI Frame Loading), [`scripts/generate_depth_images.py`](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/generate_depth_images.py) (Depth Image Generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["KITTI Data & Geometry"]
  node_kitti["KITTI Frame Loading<br/>[kitti.py]"]
  node_calib["Camera Calibration<br/>[calibration.py]"]
end

subgraph group_perception["Detection &amp; Fusion"]
  node_runner["Object Pipeline Runner<br/>[run_pipeline.py]"]
  node_tracking_runner["Sequence Runner"]
  node_detector["YOLO ByteTrack<br/>[detector.py]"]
  node_fusion["LiDAR Box Association<br/>[fusion.py]"]
end

subgraph group_artifacts["Outputs &amp; Evaluation"]
  node_visual["Frame Annotation<br/>[visualization.py]"]
  node_rendered["Annotated Frames"]
  node_trackdata["Tracking Predictions<br/>[evaluation.py]"]
  node_fuseddata["Fused Detection Records"]
  node_trackeval["Tracking Metrics<br/>[evaluation.py]"]
  node_distanceeval["LiDAR Distance Metrics<br/>[evaluation.py]"]
end

subgraph group_learning["Depth &amp; Dataset Preparation"]
  node_depthgen["Depth Image Generation"]
  node_depth["Depth Rasterization<br/>[depth.py]"]
  node_datasetprep["YOLO Dataset Preparation<br/>[training.py]"]
  node_modeltraining["YOLO Detector Training<br/>[training.py]"]
  node_depthimages["Camera-Aligned Depth Images"]
  node_yolodata["YOLO Dataset"]
end

node_user(("Researcher"))
node_ultralytics["Ultralytics YOLO"]

node_user -->|"runs frames"| node_runner
node_runner -->|"loads frames"| node_kitti
node_kitti -->|"loads calibration"| node_calib
node_runner -->|"tracks image"| node_detector
node_runner -->|"projects LiDAR"| node_calib
node_runner -->|"associates points"| node_fusion
node_runner -->|"renders detections"| node_visual
node_runner -->|"writes frames"| node_rendered
node_user -->|"runs sequence"| node_tracking_runner
node_tracking_runner -->|"loads sequence"| node_kitti
node_tracking_runner -->|"tracks image"| node_detector
node_tracking_runner -->|"projects LiDAR"| node_calib
node_tracking_runner -->|"associates points"| node_fusion
node_tracking_runner -->|"renders detections"| node_visual
node_tracking_runner -->|"writes frames"| node_rendered
node_tracking_runner -->|"writes predictions"| node_trackdata
node_tracking_runner -->|"writes associations"| node_fuseddata
node_user -->|"evaluates tracks"| node_trackeval
node_user -->|"evaluates distance"| node_distanceeval
node_trackdata -->|"scores tracks"| node_trackeval
node_fuseddata -->|"scores positions"| node_distanceeval
node_user -->|"generates depth"| node_depthgen
node_depthgen -->|"loads point clouds"| node_kitti
node_depthgen -->|"rasterizes points"| node_depth
node_depthgen -->|"writes images"| node_depthimages
node_user -->|"prepares dataset"| node_datasetprep
node_datasetprep -->|"reads sequences"| node_kitti
node_datasetprep -->|"builds depth inputs"| node_depth
node_datasetprep -->|"writes splits"| node_yolodata
node_user -.->|"trains detector"| node_modeltraining
node_modeltraining -.->|"uses YOLO"| node_ultralytics
node_depthimages -.->|"depth input"| node_modeltraining
node_yolodata -.->|"training data"| node_modeltraining

click node_kitti "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/kitti.py"
click node_calib "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/calibration.py"
click node_runner "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_pipeline.py"
click node_tracking_runner "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_tracking_sequence.py"
click node_detector "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/detector.py"
click node_fusion "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/fusion.py"
click node_visual "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/visualization.py"
click node_rendered "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/tree/main/outputs"
click node_trackdata "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/evaluation.py"
click node_fuseddata "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_tracking_sequence.py"
click node_trackeval "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/evaluation.py"
click node_distanceeval "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/evaluation.py"
click node_depthgen "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/generate_depth_images.py"
click node_depth "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/depth.py"
click node_datasetprep "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/training.py"
click node_modeltraining "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/training.py"
click node_depthimages "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/tree/main/outputs"
click node_yolodata "https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/tree/main/outputs"

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_kitti,node_calib toneBlue
class node_runner,node_tracking_runner,node_detector,node_fusion toneAmber
class node_visual,node_rendered,node_trackdata,node_fuseddata,node_trackeval,node_distanceeval toneMint
class node_depthgen,node_depth,node_datasetprep,node_modeltraining,node_depthimages,node_yolodata toneRose
class node_user,node_ultralytics toneIndigo
```

## Components

### KITTI Data & Geometry

- [KITTI Frame Loading](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/kitti.py): `src/pedestrian_pipeline/kitti.py`
- [Camera Calibration](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/calibration.py): `src/pedestrian_pipeline/calibration.py`

### Detection & Fusion

- [Object Pipeline Runner](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_pipeline.py): `scripts/run_pipeline.py`
- [Sequence Runner](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_tracking_sequence.py): `scripts/run_tracking_sequence.py`
- [YOLO ByteTrack](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/detector.py): `src/pedestrian_pipeline/detector.py`
- [LiDAR Box Association](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/fusion.py): `src/pedestrian_pipeline/fusion.py`

### Outputs & Evaluation

- [Frame Annotation](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/visualization.py): `src/pedestrian_pipeline/visualization.py`
- [Annotated Frames](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/tree/main/outputs): `outputs`
- [Tracking Predictions](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/evaluation.py): `src/pedestrian_pipeline/evaluation.py`
- [Fused Detection Records](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/run_tracking_sequence.py): `scripts/run_tracking_sequence.py`
- [Tracking Metrics](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/evaluation.py): `src/pedestrian_pipeline/evaluation.py`
- [LiDAR Distance Metrics](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/evaluation.py): `src/pedestrian_pipeline/evaluation.py`

### Depth & Dataset Preparation

- [Depth Image Generation](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/scripts/generate_depth_images.py): `scripts/generate_depth_images.py`
- [Depth Rasterization](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/depth.py): `src/pedestrian_pipeline/depth.py`
- [YOLO Dataset Preparation](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/training.py): `src/pedestrian_pipeline/training.py`
- [YOLO Detector Training](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/blob/main/src/pedestrian_pipeline/training.py): `src/pedestrian_pipeline/training.py`
- [Camera-Aligned Depth Images](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/tree/main/outputs): `outputs`
- [YOLO Dataset](https://github.com/vijayscodehub/ml_pedestrian_detection_and_tracking/tree/main/outputs): `outputs`

### Other components

- **Researcher**
- **Ultralytics YOLO**

## Connections

- Researcher → Object Pipeline Runner: runs frames (evidence: `scripts/run_pipeline.py`)
- Object Pipeline Runner → KITTI Frame Loading: loads frames (evidence: `scripts/run_pipeline.py`)
- KITTI Frame Loading → Camera Calibration: loads calibration (evidence: `src/pedestrian_pipeline/kitti.py`)
- Object Pipeline Runner → YOLO ByteTrack: tracks image (evidence: `scripts/run_pipeline.py`)
- Object Pipeline Runner → Camera Calibration: projects LiDAR (evidence: `scripts/run_pipeline.py`)
- Object Pipeline Runner → LiDAR Box Association: associates points (evidence: `scripts/run_pipeline.py`)
- Object Pipeline Runner → Frame Annotation: renders detections (evidence: `scripts/run_pipeline.py`)
- Object Pipeline Runner → Annotated Frames: writes frames (evidence: `scripts/run_pipeline.py`)
- Researcher → Sequence Runner: runs sequence (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → KITTI Frame Loading: loads sequence (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → YOLO ByteTrack: tracks image (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → Camera Calibration: projects LiDAR (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → LiDAR Box Association: associates points (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → Frame Annotation: renders detections (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → Annotated Frames: writes frames (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → Tracking Predictions: writes predictions (evidence: `scripts/run_tracking_sequence.py`)
- Sequence Runner → Fused Detection Records: writes associations (evidence: `scripts/run_tracking_sequence.py`)
- Researcher → Tracking Metrics: evaluates tracks
- Researcher → LiDAR Distance Metrics: evaluates distance
- Tracking Predictions → Tracking Metrics: scores tracks (evidence: `scripts/evaluate_tracking.py`)
- Fused Detection Records → LiDAR Distance Metrics: scores positions (evidence: `scripts/run_tracking_sequence.py`)
- Researcher → Depth Image Generation: generates depth (evidence: `scripts/generate_depth_images.py`)
- Depth Image Generation → KITTI Frame Loading: loads point clouds (evidence: `scripts/generate_depth_images.py`)
- Depth Image Generation → Depth Rasterization: rasterizes points (evidence: `scripts/generate_depth_images.py`)
- Depth Image Generation → Camera-Aligned Depth Images: writes images (evidence: `scripts/generate_depth_images.py`)
- Researcher → YOLO Dataset Preparation: prepares dataset
- YOLO Dataset Preparation → KITTI Frame Loading: reads sequences (evidence: `src/pedestrian_pipeline/training.py`)
- YOLO Dataset Preparation → Depth Rasterization: builds depth inputs (evidence: `src/pedestrian_pipeline/training.py`)
- YOLO Dataset Preparation → YOLO Dataset: writes splits (evidence: `src/pedestrian_pipeline/training.py`)
- Researcher → YOLO Detector Training: trains detector (evidence: `README.md`)
- YOLO Detector Training → Ultralytics YOLO: uses YOLO (evidence: `README.md`)
- Camera-Aligned Depth Images → YOLO Detector Training: depth input (evidence: `README.md`)
- YOLO Dataset → YOLO Detector Training: training data (evidence: `README.md`)