🔦 lucid-yolo¶
lucid-yolo is an independent, from-scratch PyTorch Lightning implementation of the real-time detection, instance segmentation, and oriented detection methods described in the YOLO26 paper (arXiv:2606.03748), plus a keypoint task composed onto the same trunk whose loss and evaluation protocol are taken from RLE (arXiv:2107.11291) rather than from that paper. "YOLO" refers to the family of real-time detectors originated by Redmon et al. (2016). This project is not affiliated with, endorsed by, or derived from Ultralytics or its codebase. No Ultralytics source code, configurations, or model weights were consulted or used. See docs/PROVENANCE.md.
🧭 What this is¶
A paper describes three real-time vision models, and a second paper the keypoint loss a fourth task is built on. This repository implements all four from those descriptions — the equations, the tables, the figures — and from the primary literature the paper cites, and from nothing else. The reference implementation was never opened, and neither was any mirror, package copy, or documentation site generated from it. That constraint is the point of the exercise rather than an obstacle to it: an implementation that shares no lineage with the original is the only kind that can independently test whether the published claims follow from the published method.
Three habits keep that claim auditable rather than asserted.
- Every design decision cites a public source. Each commit carries a
Provenance:trailer naming an entry in the provenance log, and that log is a strict allowlist — the three papers, their cited primary literature, and neutral dataset or tooling documentation. - Every gap in the papers is a recorded assumption. Where the papers underdetermine the implementation, the choice, its public basis, and the test that would validate it are written into the assumption register before the code lands. The accepted tier runs exercised a subset of them, and the record says which of those a passing run actually isolated and which merely rode along — the reproduction report's Assumption outcomes, consolidated section is where that accounting lives and is kept current, rather than a figure restated here.
- Guessing is escalated, not performed. An implementer who cannot answer a question from an allowed source stops and writes an escalation entry instead of resolving the ambiguity by looking at someone else's code.
What is claimed is a faithful reproduction of the method, not of the paper's exact numbers (decision record, D2). Each of the four models has been trained once, on a single device, at the smallest of five scales, on a deliberately short schedule — a smoke tier, in this project's vocabulary, sized to prove the mechanism works rather than to compete with a published leaderboard. No run has ever spanned more than one accelerator, so no distributed strategy is exercised or tuned for anywhere in this repository. No trained weights are published (decision record, D14); the source, the frozen golden metrics, and the report below are the release artifacts.
🧠 The four tasks¶
Each task is the previous one plus a head, not a new model: all four share one backbone, one neck, one DFL-free dual detection head, one NMS-free deploy path, and one optimizer (reproduction report, One trunk, three heads — written when there were three, and the argument is unchanged by the fourth).
| Task | What it adds to the trunk | Data | Size at n scale |
Card |
|---|---|---|---|---|
| Detection | the trunk itself — dual head, direct ltrb boxes, no distribution bins |
COCO 2017, 640 px | 2.4 M params, 5.4 GFLOPs | detection |
| Instance segmentation | prototype–coefficient masks and a training-only auxiliary semantic branch | COCO 2017, 640 px | 2.72 M params, 9.00 GFLOPs | segmentation |
| Oriented detection | per-branch angle stems, a rotated IoU term, a retargeted L1 | DOTA-v1.0 tiles, 1024 px | 2.56 M params, 14.68 GFLOPs | oriented |
| Keypoints | a K-generic point stem, and a normalizing-flow residual likelihood (RLE) as its loss |
COCO 2017 person_keypoints, 640 px |
2.38 M params, 5.51 GFLOPs | keypoints |
The fourth task is keypoints, not pose. K is a constructor argument the way the class count is; nothing in the head, the loss or the decode path knows what a point means. Human pose is the instantiation the keypoint tier trained on (K = 17, COCO's person schema) — no checkpoint ships (D14), so that names the run, not an artifact you can download — and it is the one the OKS metric's sigma table is defined for. The wiring gate runs a 7-point synthetic symbol schema instead.
That genericity stops at the count, and it is worth being exact about where. K buys a head, a loss and a decode path that do not care what a point means; it does not buy an OKS protocol for an arbitrary schema. Scoring one needs a per-point sigma vector and the left/right pairs a mirror must swap, and neither follows from K: R12 publishes one sigma table (17 human values, derived from annotator variance), this project adds a single uniform fallback for schemas that have no annotator to measure (A67), and the flip pairs are read off the annotation file's own keypoint names — a COCO file that names its points supplies them, a YOLO root never does. A new schema is a modelling decision, not a constructor argument.
Parameter and FLOP counts are from the What was reproduced subsection of each release section of the reproduction report. Three of the four tasks are gated against the paper's own published tables — detection against R1 Table 7 within ±2% params, segmentation against Table S9 within ±3%, oriented detection against Table S11 within ±3.5% at 1024 px on DOTA's 15 classes, and all three within ±5% FLOPs. The oriented tolerance is the widest because the angle-stem width is inferred rather than published (A20 stays open), and the gate is explicit that it admits a rule rather than claiming Table S11 parity; a frozen golden runs beside it as a drift lock. Keypoints have the golden and no published-table gate at all: the source paper (R14) states a loss and an evaluation protocol, never an architecture, so there is no size table in the literature to hold that head to. The golden catches an architecture change; it corroborates nothing.
📊 What was reproduced, in numbers¶
Every figure below is quoted from REPRODUCTION_REPORT.md, with the section it comes from named beside it. All four runs are n scale, roughly 50 epochs, seed 0, single seed throughout.
| Result | Value | Source section |
|---|---|---|
| Detection, COCO val2017, EMA weights, NMS path | 25.30 mAP50-95 (38.12 mAP50) | 0.1.0 — Detection → Det-smoke acceptance |
| Detection, same weights, NMS-free end-to-end path | 23.84 mAP50-95 | 0.1.0 — Detection → Det-smoke acceptance |
| Cost of dropping NMS, detection | 1.11 AP on raw weights, 1.46 on EMA | 0.1.0 — Detection → Det-smoke acceptance |
| Segmentation, COCO val2017, EMA weights, NMS path | 19.01 segm mAP50-95, 26.12 box mAP50-95 | 0.2.0 — Instance segmentation → The Seg-smoke run |
| Mask accuracy as a fraction of box accuracy | 0.728 (NMS), 0.732 (E2E), against a 0.65 acceptance floor | 0.2.0 — Instance segmentation → Seg-smoke acceptance |
| Cost of dropping NMS, segmentation | 1.27 box AP, 0.81 segm AP | 0.2.0 — Instance segmentation → The Seg-smoke run |
| Oriented detection, DOTA-v1.0 val, EMA weights, per tile | 0.2914 rotated mAP50-95, 0.5242 rotated mAP50 | 0.3.0 — Oriented detection → The OBB-smoke run |
| Cost of dropping NMS, oriented detection | not measured | Consolidated note → One trunk, three heads |
| Keypoints, COCO val2017, EMA weights, NMS-free end-to-end path | 0.2738 OKS AP, 0.5030 box mAP50-95 | 0.5.0 — Keypoint detection → The Pose-smoke run |
| RLE's learned flow against its own flow-free control | 0.2738 vs 0.2527 OKS AP — same direction as the source paper's 70.5-vs-67.4 | 0.5.0 — Keypoint detection → Acceptance |
Four readings the report insists on, and this page repeats rather than smooths over.
The oriented numbers are per tile and are comparable to nothing published. DOTA images are cut into overlapping 1024 px crops and scored crop by crop; detections are not merged back onto whole images, so no tile ever pays the duplicate cost a whole-image protocol charges. The report states this as a property of the measurement rather than a caveat about its precision, and makes no comparison to the paper's oriented tables anywhere (0.3.0 — Oriented detection → The OBB-smoke run).
The NMS-free deficit is wider than the paper's. The paper reports 0.6–0.8 AP between its NMS-free and NMS paths; this reproduction measures 1.11 AP on raw weights. Right sign, right order of magnitude, wider — recorded as a reproducible claim of its own rather than explained away (0.1.0 — Detection → Det-smoke acceptance).
Three earlier detection runs failed before the one above passed, at 3.96, 6.28 and 4.00 mAP50-95, and the report treats the failures as the more instructive half: two semantic defects — a loss term computed in the wrong coordinate frame, and an augmentation random stream that every worker replayed identically — that crashed nothing, failed no test, and cost roughly 35 GPU-hours (0.1.0 — Detection → What went wrong first, and why it matters).
These are smoke tiers. Roughly 50 epochs at the smallest scale against the paper's from-scratch 500- and 600-epoch schedules, no Objects365 pretraining, no evolutionary hyperparameter search, one seed (Consolidated note → Deviations).
🗂️ Reading the rest of this site¶
The documents fall into three registers, and which one you want depends on what you came for.
| If you want to | Read | It answers |
|---|---|---|
| run a model yourself | Launching a training run | the launch command for each of the four tiers, and what to override |
| get the data first | Provisioning the datasets | where COCO 2017 and DOTA-v1.0 come from, what has to be on disk, how each layout is read |
| know what was measured | Reproduction report | one section per release: what was reproduced, what was assumed, what diverged |
| judge one model before using it | Model cards | intended and out-of-scope use, limitations, licensing, per task family |
| check the clean-room claim | Provenance log | the source allowlist and the audit trail behind every commit trailer |
| find where the papers ran out | Assumption register | every gap, the choice made, its public basis, and how it was validated |
| understand why the project is shaped this way | Decision record | architecture and policy decisions, including four ADRs |
| see what is done and what is next | Work-package roadmap | the numbered work queue with live status |
| learn what execution actually cost | Research log | fidelity measurements, rejected modeling approaches, and negative results, per work package |
| learn what the repo tooling cost | Engineering log | CI, packaging, licensing, and doc-tooling findings, split out of the research log by claim |
| see where work stopped for the principal | Escalation log | the anti-guessing rule and every entry raised under it |
| contribute a change | Contributor guide | the clean-room rule, DCO sign-off, provenance trailers, and what the gate does and does not decide |
The roadmap and the two logs are deliberately split: the roadmap says what a work package does, the logs say what executing it taught. Between the two logs the split is by claim, not by work package -- a fidelity finding in one, a tooling finding in the other, and a WP whose finding is genuinely both gets one entry in each, cross-linked. A row that restates any of them is duplicating a record with an owner.
🚀 Running it yourself¶
Datasets are never committed and never downloaded by the test suite. Provisioning the datasets covers acquiring them; launching a training run carries the exact command for each tier, and the minutes-long overfit gate worth running before a launch that costs hours.
Four commands ship with the package — lucid-yolo for training and validation, lucid-data for dataset download, checking and tiling, lucid-eval for acceptance scoring, and lucid-predict for single-image prediction — so a remote run needs no checkout. Contributors and agents working on the repository itself start at AGENTS.md in the repository root, which is the execution contract the roadmap is run under.
make gate green is a structural verdict, not a quality one. The merge gate is entirely offline: linters, types, the unit suite over synthetic fixtures (A26/D12b), and the frozen release goldens. The learned-quality floors — the per-task overfit gates quoted in the model cards — live under goldens/gpu/, which the default golden check deliberately never discovers; they run in make gate-gpu, whose CI schedule stays a skipped job until the GPU_RUNNER_LABEL repository variable names a self-hosted accelerator runner. A green gate says nothing was structurally disturbed. It does not say the models are good, and 0.8.0 exists because a defect that cost the keypoint tier most of its overfit floor passed every offline golden.