src/objectmodel_v1.egg-info/PKG-INFO

Metadata-Version: 2.4
Name: objectmodel-v1
Version: 0.1.0
Summary: ObjectModel-v1: compact end-to-end object detection research
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: Pillow>=10.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: scipy>=1.11
Requires-Dist: torch>=2.4
Provides-Extra: coco
Requires-Dist: pycocotools>=2.0.7; extra == "coco"
Provides-Extra: export
Requires-Dist: onnx>=1.16; extra == "export"
Requires-Dist: onnxscript>=0.1; extra == "export"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# ObjectModel-v1

ObjectModel-v1 is a clean-room, compact, end-to-end object detector from Bench Labs. It is a
research implementation, not a benchmark claim. The model tests
whether global semantic reasoning can be compressed into a small fixed latent memory while
precise geometry is recovered by query-conditioned sampling from full-resolution pyramid
features.

The model is NMS-free. It predicts a fixed set of objects and is trained with Hungarian
bipartite matching.

## Status

- Architecture, COCO data path, losses, training, evaluation, profiling, and ONNX export are implemented.
- Synthetic forward/loss/backward and data tests are included.
- No COCO training has been run in this repository yet.
- No accuracy, speed, or "state of the art" claim is made before controlled benchmarks.

## Architecture

```text
image
  -> compact convolutional backbone (strides 8/16/32)
  -> top-down pyramid fusion
  -> pooled multi-scale tokens
  -> fixed latent memory (global semantics)
  -> learned object queries
       -> query self-attention
       -> cross-attention to latent memory
       -> local sampling around the current query box
       -> iterative class and box prediction
  -> object set (no anchors, no NMS)
```

The local sampling radius scales with each query's current width and height. Early decoder
layers can search broadly; later layers focus naturally as boxes are refined. During training,
an optional dense auxiliary head adds one-to-many spatial supervision. It is discarded for
inference and must be evaluated as an ablation, not assumed to help.

## Installation

Use Python 3.11 or another PyTorch-supported Python version:

```bash
python3.11 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e '.[coco,export,dev]'
```

For a specific CUDA build, install the matching PyTorch wheel first using the command from
<https://pytorch.org/get-started/locally/>, then install ObjectModel-v1.

## Data

The default configuration expects COCO 2017:

```text
/path/to/coco/
  annotations/instances_train2017.json
  annotations/instances_val2017.json
  train2017/*.jpg
  val2017/*.jpg
```

Category IDs are mapped to contiguous training labels and converted back during evaluation.
Images without target objects are supported.

## Commands

Profile the model before allocating training compute:

```bash
objectmodel-profile --config configs/objectmodel_v1.yaml --device cuda
```

Overfit a small dataset first. A full single-GPU command is:

```bash
objectmodel-train \
  --config configs/objectmodel_v1.yaml \
  --data-root /path/to/coco \
  --output outputs/objectmodel_v1
```

Distributed training:

```bash
torchrun --standalone --nproc_per_node=8 -m objectmodel_v1.train \
  --config configs/objectmodel_v1.yaml \
  --data-root /path/to/coco \
  --output outputs/objectmodel_v1
```

Resume and override configuration values:

```bash
objectmodel-train \
  --config outputs/objectmodel_v1/config.yaml \
  --data-root /path/to/coco \
  --output outputs/objectmodel_v1 \
  --resume outputs/objectmodel_v1/last.pt \
  --set train.batch_size=8
```

Evaluate the EMA checkpoint with canonical `pycocotools` metrics:

```bash
objectmodel-eval \
  --config outputs/objectmodel_v1/config.yaml \
  --checkpoint outputs/objectmodel_v1/best.pt \
  --data-root /path/to/coco
```

Export raw logits and normalized `cxcywh` boxes to ONNX:

```bash
objectmodel-export \
  --config outputs/objectmodel_v1/config.yaml \
  --checkpoint outputs/objectmodel_v1/best.pt \
  --output outputs/objectmodel_v1/objectmodel-v1.onnx
```

## Minimum Validation Protocol

Before describing ObjectModel-v1 as competitive, run all models on the same COCO train2017 and
val2017 data, image resolution, augmentation budget, training epochs, and hardware. Report:

- COCO AP, AP50, AP75, APS, APM, and APL.
- Parameters, FLOPs/MACs, FP32/FP16/INT8 artifact sizes.
- End-to-end batch-1 median and p95 latency, including preprocessing and decoding.
- Peak training and inference memory, GPU-hours, epochs, and images seen.
- Three seeds for the principal result, with mean and standard deviation.
- Results both from random initialization and with the same permitted pretraining.

Required ablations:

| Experiment | Question |
|---|---|
| latent memory vs flattened feature attention | Does compression preserve useful global context? |
| local sampler disabled | Does high-resolution geometric evidence improve localization? |
| fixed vs box-scaled offsets | Does coarse-to-fine sampling matter? |
| dense auxiliary head disabled | Does added supervision improve convergence? |
| 1/2/3 latent layers | Where is the accuracy/latency optimum? |
| 32/64/96 latents | How aggressively can global context be compressed? |
| 3/4/6 decoder layers | What is the anytime speed/accuracy curve? |

Suggested external baselines are RT-DETR-R18, D-FINE-N/S, LW-DETR-T/S, and YOLOX-S. Use
their official implementations and report their license and measurement setup separately.

## Research Basis

ObjectModel-v1 builds on published, independently attributable ideas:

- DETR: set prediction and Hungarian matching.
- Conditional and Deformable DETR: spatially conditioned/local sparse attention.
- RT-DETR: efficient separation of multi-scale encoding and query decoding.
- D-FINE: evidence that fine-grained iterative localization is valuable.
- DEIM: evidence that one-to-one matching benefits from denser training supervision.
- LW-DETR: evidence that compact transformer detectors can compete with real-time CNNs.

ObjectModel-v1's specific hypothesis is the combination of a **fixed compressed global memory** and
**box-scaled local pyramid sampling**. Publication novelty requires a broader prior-art search
and empirical ablations; this repository does not claim that the combination is patent-new.

## License

Apache License 2.0. Dataset images, annotations, pretrained weights, and external baselines
retain their own licenses and are not included.