Imported from YN2TB/bdd100k-object-detection (
AGENTS.md). Install upstream withnpx skills add YN2TB/bdd100k-object-detection. Copyright stays with the author.
Repository Guidelines
Project Structure & Module Organization
This Python midterm compares two hand-written CNN object detectors with a YOLO11s baseline on all publicly labelled BDD100K images.
src/bddcv/: class definitions, label readers, custom CNN detectors, and COCO evaluation.scripts/: data preparation, label verification, training/resume, prediction, and evaluation entry points.configs/bdd_source.yaml: dataset location and class names.data/: tracked census and train/validation manifests; generated images and annotations are ignored.runs/: ignored checkpoints, logs, predictions, and plots.docs/experiments.mdanddocs/HANDOFF_3060.md: historical experiment details and RT-DETR training handoff instructions.
Setup & Development Commands
Run commands from the repository root. Set path in configs/bdd_source.yaml to
your local data/source_full directory; preserve the split paths and class names.
python -m pip install ultralytics pycocotools -c constraints.txt --extra-index-url https://download.pytorch.org/whl/cu128
Use constraints.txt for dependency installs that can pull PyTorch to preserve the pinned CUDA build. No separate build step is configured.
- Data pipeline, in order:
python scripts/prepare_data.py, thenpython scripts/build_labels.py. - Label check:
python scripts/verify_labels.pycross-checks train/val/test labels and produces a visual montage. - CNN smoke run:
python scripts/train_cnn.py --model simple-cnn --epochs 1 --limit-train 2 --limit-val 2 --workers 0. - CNN training:
python scripts/train_cnn.py --model simple-cnn --epochs 30 --batch 16or replace the model withcomplex-cnn. - Supervised YOLO training:
python scripts/train_with_resume.py ultra --model yolo11s.pt --name yolo11s --epochs 30 --batch 16. - Score test predictions:
python scripts/evaluate.py runs/predictions_full/yolo11s.json --title YOLO11s.
Coding Style & Experiment Contracts
Use four-space indentation, snake_case functions/variables, uppercase constants, type hints, and concise docstrings. No formatter or linter is configured.
Import class order from bddcv.constants; never duplicate or reorder it. YOLO class i maps to COCO category i + 1. Resolve image IDs by filename. Stream raw labels with stream_records(). Report metrics through bddcv.evaluation with at most 100 detections per image. The two custom CNNs share 640x360 inputs and one grid head; record YOLO's native preprocessing difference.
Testing Guidelines
Run python -m unittest discover -s tests -v for artifact routing and migration regression checks. No coverage threshold is configured. For data changes, run label verification and inspect the montage. For trainer changes, run a short smoke experiment in a separate output directory. Record commands and outcomes.
Commit & Pull Request Guidelines
History contains one descriptive initial commit; no formal message convention is established. Use concise, action-oriented subjects. PRs should explain the change, experiment impact, and validation performed, linking issues when relevant. Preserve tracked subset manifests; exclude datasets, weights, and run artifacts.
Shared Agent Workflow
- This file is the shared project instruction source.
CLAUDE.mdimports it for Claude Code. - Before continuing unfinished work, read
.agent/HANDOFF.md,.agent/TODO.md, and.agent/DECISIONS.md. - Use
.agent/PLANS.mdto locate only the relevant plan in.agent/plans/active/. - Before handing work off, update the handoff with changes, verification, uncertainties, and the next concrete step. Keep TODO limited to outstanding work.
- Record durable decisions in
.agent/DECISIONS.md; move completed plans to.agent/plans/archive/and update the index. - Keep state tool-neutral: use repository-relative paths and commands, without credentials or machine-local settings.
Subagent Routing
- Use
$bddcv-orchestrationwhen classifying work or considering delegation. - Handle work directly when it is both easy and short; do not propose a subagent for casual tasks.
- Before delegating difficult or long work, tell the user the classification, reason, recommended roles and models, execution order, and material actions, then wait for confirmation.
- Use
bddcv-explorerfor read-heavy mapping,bddcv-workerfor scoped implementation,bddcv-validatorfor acceptance evidence, andbddcv-reviewerfor independent review. - Keep the primary conversation focused by sending compact task packets and receiving concise evidence summaries.
Additional Experiment Contracts
- Current experiment membership is fixed by the three
data/source_full/*_images.txtmanifests: 55,904 train, 15,973 validation, and 7,986 test images, generated withseed=0from all 79,863 public labelled records. Do not filter attributes. - Domain shift, target-data budgets, and recovery curves belong to a separate project; do not expand this repository into that work.
- Read
docs/experiments.mdbefore changing training, checkpointing, data conversion, or evaluation. It preserves historical context, not current run status. - Use
canonical_category()for legacy category aliases anddetection_boxes()to exclude annotations without boxes. - Preserve atomic checkpoint writes and complete resume state, including optimizer, scaler, epoch, iteration counter, and best score. Preserve resume compatibility checks and append-only result logging.
- Preserve the reliable-class metric policy for sparse validation classes. Disclose optimizer, schedule, and augmentation differences in comparisons.
docs/HANDOFF_3060.mdand the six-model files are historical. The current report contains onlysimple-cnn,complex-cnn, andyolo11s.
