<!-- examples/README-detr.md -->

# Reproduce the DETR examples

The small `detr_training.py` is offline random-weight mechanics. It is not the
original architecture, a pretrained detector, or a COCO evaluation. It uses a
stride-4 tiny CNN, width 32, one encoder and decoder layer, eight queries and
three foreground classes. It omits auxiliary decoder losses, dropout and
multi-process normalization. Exact Hungarian assignment, weighted CE, L1 and
GIoU retain the original operations.

```sh
python -m pip install -r requirements-detr.txt
python detr_training.py --smoke
```

Only torch is required for smoke. The other pinned packages serve the exporter.
The command performs one deterministic CPU AdamW update without any downloads.

## Genuine original ResNet50 detector

Download `detr_training.py`, `detr_export.py`, `detr-source-hashes.json`,
`requirements-detr.txt`, and `detr_native.zip` into one directory.
The ZIP contains unchanged official native sources and their Apache-2.0 license.

```sh
unzip detr_native.zip
curl -L https://dl.fbaipublicfiles.com/detr/detr-r50-e632da11.pth -o detr-r50-e632da11.pth
python detr_export.py --checkpoint detr-r50-e632da11.pth --output detr-demo
```

Checkpoint SHA256:
`e632da11ec76ae67bac2f8579fbed3724e08dead7d200ca13e019b197784eadc`.
Source revision: `29901c51d7fe8712168b8d0d64351170bc0f83e0` in
[facebookresearch/detr](https://github.com/facebookresearch/detr/tree/29901c51d7fe8712168b8d0d64351170bc0f83e0).
Every source file has an exact retrieval URL and SHA256 in
`detr_native/source-manifest.json` and the separate hash record.
`--source-dir` can point to this same authenticated bundle elsewhere.
No research-cache directory is needed. Source and checkpoint hashes are verified
before execution/loading. The complete DETR checkpoint is loaded strictly.

The compatibility adapter selects unchanged native class bodies with Python AST
so it can bypass imports of the SciPy training matcher and panoptic packages.
The native transformer and box operations are loaded directly. A minimal
`NestedTensor` container carries tensors and padding masks. The native
FrozenBatchNorm2d (epsilon 1e-5) and normalized PositionEmbeddingSine execute
unchanged. ResNet50 is instantiated with `weights=None`, avoiding any supervised
classifier download, then populated by the full detector checkpoint.

The exporter fetches and authenticates two pinned CC0 scikit-image photographs:
Chelsea the cat (Stefan van der Walt) and coffee (Rachel Michetti).
To run without network after obtaining these files, pass
`--photo-dir DIRECTORY` containing `source-cat.png` and `source-coffee.png`.
Their original URLs, license record, full hashes and authors are saved in JSON.

RGB images use Pillow bilinear resize: short side 800, long side capped at 1333,
with original DETR integer rounding, then ImageNet mean/std normalization.
Original geometry is retained without cropping. Bottom/right padding uses zeros
in normalized space and a True padding mask; the one-image exports need none.
All 100 normalized cxcywh boxes, logits, foreground scores/category IDs and
original-image pixel xyxy boxes are saved, together with the exact normalized
input and mask in NPZ. COCO category IDs include gaps, with no-object at index 91.
The native postprocessor chooses the best foreground class from a softmax that
includes no-object. NMS is never applied. Numeric boxes are never clipped.
Only overlay rectangles are clipped to image boundaries, with score > 0.7 used
for display. The selected query inspector does not change that fixed overlay.

Outputs include original and resized images, overlays, arrays, and a complete
JSON record with producer/source/checkpoint/input/artifact hashes, versions,
command, strict-load receipt and native postprocessing parity. The two photos
are inference examples, not ground-truth detection accuracy evaluation.

Native source ZIP SHA256:
`caecdefb171d53cc039b1a65af7d3b02dc84bdd7bd54ccea9f96ad710eca92f8`.
