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

# DINO detector mechanics

Run `python3 examples/dino_detr.py` from the repository root with Python 3.9+.
The default generator filename is `dino_detr.py`. It prints deterministic JSON
to stdout, writes no files and needs only the standard library.
Run `node --test test/dinoDetr*.test.mjs` for mathematical and Python parity checks.

This reference demonstrates mixed top-K anchor selection with independent learned
content, positive/negative corner perturbations, directional denoising masks,
logit-space box refinement and a two-layer scalar gradient graph. Regions
`queries`, `denoising`, `mask`, `refinement`, `gradients` are extracted by the
repository synchronizer. Its parser uses `# region: name` / `# endregion: name`.
Root integration owns generated `src/data/dinoDetrCode.mjs` and public downloads.

The source is an authored illustration, not copied training code and not a
checkpoint-backed detector. Fixed perturbations are examples of the official
corner-noise parameterization. They do not implement random label corruption,
variable-sized batches, padding or dynamic DN group allocation. Negatives receive
background classification supervision, not a box reconstruction target.
The mask returns **allowed** booleans, the inverse of PyTorch's blocked mask.
Rows read columns. Matching queries cannot read denoising queries; the reverse
is allowed, and denoising groups cannot read each other.

The scalar graph instantiates the dependency structure of paper Eq. 2 with an
authored tanh offset head and half squared error. It holds the stopped reference
fixed during finite differences. It is neither a full autodiff engine nor an
empirical gradient trace from DINO training. Only the additional adjacent-loss
path is isolated; decoder hidden-state gradient paths are omitted. These numbers
cannot establish AP, convergence, robustness or runtime.

Primary references: [DINO v4 §§3.3–3.5, Eq. 2](https://arxiv.org/html/2203.03605v4),
[official CDN preparation](https://github.com/IDEA-Research/DINO/blob/main/models/dino/dn_components.py),
[transformer](https://github.com/IDEA-Research/DINO/blob/main/models/dino/deformable_transformer.py)
and [prediction heads](https://github.com/IDEA-Research/DINO/blob/main/models/dino/dino.py).
DINO detector is ICLR 2023, preprint 2022, distinct from self-supervised DINO.
No inference, training, checkpoint download or timing experiment is performed.
