File size: 6,648 Bytes
9b92c75 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 | 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.
|