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 , 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.