The tool addresses incomplete labels in multi-class YOLO datasets. A single multi-class detector is not used as the only source of truth because a missing label can become a weak learning signal. Instead, specialist single-class detectors provide independent evidence for each class.
- Optionally run the model-free audit for schema errors, corrupt images and exact cross-split leakage.
- Validate the dataset structure,
data.yaml, selected classes and model paths. - Build a path index for
train,valandtestonce. - Copy the original label tree to
labels_autofill_v1only in apply mode. - Load one class model and one class label cache.
- Infer the split in batches with
stream=True. - Move the small prediction representation to CPU and compare against same-class GT boxes.
- Discard matched predictions, duplicate candidates and low-confidence predictions.
- Stream candidates to CSV and keep bounded image samples for review.
- Append AUTO labels only to the output copy after the current batch is processed.
- Flush audit files and atomically advance
state.jsonafter the batch commit. - Release results, model, label cache and CUDA cache before the next class.
- Generate
report.htmlfrom the summary, CSV audit trail and bounded sample images. - Optionally build an exhaustive GT/AUTO review bundle from the candidate evidence.
- Apply only explicit human decisions to a new dataset after duplicate and source-GT drift checks.
Each recovery run also writes manifest.json at startup. It captures the immutable run signature, arguments, image/model inventory, package versions, CUDA details and GPU properties. A completed run adds result totals and per-class statistics. If the process crashes, the manifest remains in running state and state.json identifies the last committed batch.
The specialist models make the source of a candidate explicit. A helmet prediction is compared only with existing helmet labels; it is not considered covered merely because a person box overlaps it. This is useful for combined scenes where multiple classes occupy the same region.
The implementation keeps two IoU thresholds separate:
iou_existing: prediction versus original same-class GT. Default0.50.iou_candidate_duplicate: candidate versus candidate after model NMS. Default0.95.
The first asks whether an object was already annotated. The second asks whether two predictions are almost the same box. Reusing one threshold for both questions can erase nearby real objects.
Dry-run and apply share the same candidate generation logic. Apply adds two side effects: a copied label tree with AUTO additions and, optionally, a materialized YOLO dataset. This makes dry-run the recommended audit gate before training.
The checkpoint cursor advances only after CSV rows and labels are committed. Writes are idempotent: candidate identity prevents duplicate CSV records and normalized label lines are checked before appending. If a process stops between a data write and checkpoint update, --resume safely retries the same batch.
The state signature covers dataset metadata, teacher files, classes, splits, thresholds and matching parameters. A resume attempt with different inputs is rejected instead of silently mixing experiments.
Threshold calibration turns the recovery pipeline into an iterative data-quality system rather than a one-off inference script.
flowchart LR
A["Teacher scan"] --> B["AUTO / REVIEW candidates"]
B --> C["Stratified human audit"]
C --> D["Per-class precision-recall curves"]
D --> E["Precision-constrained AUTO policy"]
D --> F["Recall-constrained REVIEW policy"]
E --> G["Versioned threshold overrides"]
F --> G
G --> A
The calibration sample is evidence for the routing policy, not a replacement for an independent model test set. A policy should be recalibrated when the Teacher model, target camera domain, operating conditions or annotation rules change.
The 0.9 review workflow separates evidence generation from label-writing authority. review-build is read-only and classifies every candidate using same-class and cross-class geometry. review-ui records explicit human decisions. review-apply is the only stage allowed to create a reviewed dataset, and it never targets the source tree.
Same-target ambiguity cannot be accepted as a second box: it requires an explicit replacement decision tied to the reviewed GT line and coordinates. If that GT changes between review and apply, the replacement is rejected. Val/test decisions remain held by default so dataset remediation cannot silently move the evaluation goalposts.
The optional prioritize stage consumes candidate CSV evidence after scanning. It groups boxes by image, resolves each image inside the dataset boundary and ranks a fixed review budget using confidence entropy, dynamically decayed class rarity and minimum perceptual distance to the already selected set.
This queue is intentionally biased toward informative cases. It belongs on the remediation path, not the model-metric path: precision and recall estimates still require an independent random or stratified-random audit sample.