Initial model release

.gitattributes

@@ -33,3 +33,18 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+TechnicalReport.pdf filter=lfs diff=lfs merge=lfs -text
+figures/CrowdHuman_Dataset.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/head_high/05_273275,c0ae0000aec25c12.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/head_low/02_283647,120b7000e2e46855.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/head_low/03_283554,3a7ad00020c75baa.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/head_low/10_273278,76802000732a3dff.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/head_medium/02_273278,14081f000db0bb9ab.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/head_medium/10_273278,3ffee00000e633e6.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/person_high/01_283647,2944000f069ba24.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/person_high/04_273275,12f36e000ed03b48f.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/person_low/01_282555,bc73f000c20d1945.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/person_low/10_283647,b71200031068c38.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/person_medium/01_282555,a8d86000f6480c8d.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/person_medium/02_283554,1079d00027611494.png filter=lfs diff=lfs merge=lfs -text
+figures/qualitative_five_model_panels/person_medium/07_273278,16c7a0000490fb17.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+outputs/
+converted/

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,171 @@
+---
+license: apache-2.0
+language:
+  - en
+library_name: pytorch
+pipeline_tag: object-detection
+datasets:
+  - sshao0516/CrowdHuman
+tags:
+  - crowdhuman
+  - object-detection
+  - person-detection
+  - head-detection
+  - rtdetrv4
+  - rf-detr
+---
+
+# Improving RT-DETRv4 Person and Head Detection on CrowdHuman with C-RADIOv4 Distillation
+
+## Abstract
+
+Real-time person and head detection in dense crowds remains fundamentally difficult, as detectors must localize partially visible bodies under severe inter-person occlusion while preserving the fine-grained semantics needed to separate tiny heads in heavily cluttered scenes. Recent real-time detection transformers such as RT-DETRv4 address feature degradation in lightweight detectors by distilling knowledge from vision foundation models (VFMs), yet the impact of teacher choice on detection performance is underexplored. In this paper, we benchmark RT-DETRv4-S against YOLO26-S, YOLOv8-S, and RF-DETR-S on CrowdHuman visible-person and head detection, and investigate whether replacing the default DINOv3-Base teacher with C-RADIOv4-SO400M can further improve detection quality. Rather than scaling the DINOv3 teacher from the default Base model to a much larger DINOv3-7B variant, we study an alternative design in which the student is supervised by C-RADIOv4, an agglomerative vision backbone that already distills knowledge from DINOv3-7B together with complementary teachers such as SAM3 and SigLIP2. RT-DETRv4-S already surpasses all three baselines under both teachers. With C-RADIOv4, it achieves the best mAP on both visible-person (0.8410) and head detection (0.7881), improving over DINOv3 by +0.91 pp and +1.71 pp, respectively, and outperforming the Ultralytics YOLO26-S baseline by +2.47 pp and +2.91 pp.
+
+For detailed methodology, training protocol,evaluation protocol, please refer to [Technical Report](TechnicalReport.pdf).
+
+## Evaluation and Results
+
+This release focuses on compact visible-person and head detection on CrowdHuman. The study uses CrowdHuman visible-body and head annotations, trains on the training split, and evaluates on the validation split. RT-DETRv4-S is compared against YOLO26-S, YOLOv8-S, and RF-DETR-S, and the teacher study isolates the effect of replacing the default DINOv3-Base teacher with C-RADIOv4-SO400M while keeping the RT-DETRv4-S detector fixed.
+
+Across the evaluated compact models, RT-DETRv4-S with C-RADIOv4-SO400M is the strongest configuration on both visible-person and head detection. The teacher swap improves visible-person mAP from `0.8319` to `0.8410` and head mAP from `0.7710` to `0.7881`. Because RT-DETRv4 uses distillation only during training, the DINOv3-Base and C-RADIOv4 variants share the same inference architecture and deployment cost.
+
+**Table 1.** Visible-person detection results on CrowdHuman validation. Best result in **bold**, second-best <u>underlined</u>.
+
+| Model | mAP |
+|---|---:|
+| RT-DETRv4-S (C-RADIOv4-SO400M) | **0.8410** |
+| RT-DETRv4-S (DINOv3 Base) | <u>0.8319</u> |
+| YOLOv8-S | 0.8263 |
+| YOLO26-S | 0.8163 |
+| RF-DETR-S | 0.8006 |
+
+**Table 2.** Head detection results on CrowdHuman validation (ignore-region mode 1). Best in **bold**, second-best <u>underlined</u>.
+
+| Model | mAP |
+|---|---:|
+| RT-DETRv4-S (C-RADIOv4-SO400M) | **0.7881** |
+| RT-DETRv4-S (DINOv3 Base) | <u>0.7710</u> |
+| YOLO26-S | 0.7590 |
+| YOLOv8-S | 0.7336 |
+| RF-DETR-S | 0.6990 |
+
+**Table 3.** Visible-person mAP of default COCO-pretrained checkpoints evaluated on CrowdHuman validation. Best in **bold**, second-best <u>underlined</u>.
+
+| Model | mAP |
+|---|---:|
+| RF-DETR-S | **0.6956** |
+| YOLOv8-S | <u>0.6935</u> |
+| RT-DETRv4-S | 0.6846 |
+| YOLO26-S | 0.6715 |
+
+**Table 4.** TensorRT latency on NVIDIA T4 together with reported model complexity.
+
+| Model | Resolution | TensorRT Latency on T4 (ms) | Params (M) | GFLOPs |
+|---|---:|---:|---:|---:|
+| RT-DETRv4-S [12] | 640 | 3.66 | 10 | 25 |
+| YOLO26-S [16] | 640 | **2.5** | **9.5** | **20.7** |
+| YOLOv8-S [8, 15] | 640 | 6.97 | 11 | 29 |
+| RF-DETR-S [13, 14] | 512 | 3.50 | 32.1 | 59.8 |
+
+## Qualitative Analysis
+
+ Qualitative comparisons use `2 x 3` panels with the original image first and the five detectors ordered by descending mAP for the corresponding task. Visualizations use confidence threshold `0.40`, and true-positive versus false-positive assignments are determined by greedy one-to-one matching at IoU `0.50`. Dashed blue boxes denote ground truth, green boxes denote true positives, and red boxes denote false positives.
+
+[![Visible-person low-density example](figures/qualitative_five_model_panels/person_low/01_282555,bc73f000c20d1945.png)](figures/qualitative_five_model_panels/person_low/01_282555,bc73f000c20d1945.png)
+
+[![Visible-person medium-density example](figures/qualitative_five_model_panels/person_medium/07_273278,16c7a0000490fb17.png)](figures/qualitative_five_model_panels/person_medium/07_273278,16c7a0000490fb17.png)
+
+[![Visible-person high-density example](figures/qualitative_five_model_panels/person_high/01_283647,2944000f069ba24.png)](figures/qualitative_five_model_panels/person_high/01_283647,2944000f069ba24.png)
+
+[![Head low-density example](figures/qualitative_five_model_panels/head_low/03_283554,3a7ad00020c75baa.png)](figures/qualitative_five_model_panels/head_low/03_283554,3a7ad00020c75baa.png)
+
+[![Head medium-density example](figures/qualitative_five_model_panels/head_medium/10_273278,3ffee00000e633e6.png)](figures/qualitative_five_model_panels/head_medium/10_273278,3ffee00000e633e6.png)
+
+[![Head high-density example](figures/qualitative_five_model_panels/head_high/05_273275,c0ae0000aec25c12.png)](figures/qualitative_five_model_panels/head_high/05_273275,c0ae0000aec25c12.png)
+
+## Model Inference
+
+All model weights are available in this repository:
+
+- `ckpts/rt-detrv4s-cradiov4-so400m/best_stg2.safetensors`
+- `ckpts/rt-detrv4s-dinov3b/best_stg2.safetensors`
+- `ckpts/rf-detrs/checkpoint_best_total.safetensors`
+
+Use the official repositories for inference:
+
+1. [RT-DETRv4](https://github.com/RT-DETRs/RT-DETRv4) for the two RT-DETRv4-S checkpoints.
+2. [RF-DETR](https://github.com/roboflow/rf-detr) for the RF-DETR-S checkpoint.
+
+### Dependencies
+
+The inference wrapper requires the following Python packages:
+
+```bash
+pip install torch safetensors pillow numpy supervision
+```
+
+For RT-DETRv4, also install the dependencies from the [RT-DETRv4 repository](https://github.com/RT-DETRs/RT-DETRv4).
+For RF-DETR, also install the dependencies from the [RF-DETR repository](https://github.com/roboflow/rf-detr) (or `pip install rfdetr`).
+
+### Usage
+
+Use `scripts/inference.py` to run inference. It handles checkpoint conversion automatically and runs inference through the official repository code. For RT-DETRv4 it also generates a minimal 2-class inference config automatically, so users do not need to hand-write one. The C-RADIOv4 teacher is not needed at inference time; only the trained student weights are used.
+
+The RT-DETRv4 wrapper saves the converted checkpoint, the generated inference YAML, and the official `torch_results.jpg` / `torch_results.mp4` output. The RF-DETR wrapper saves the converted checkpoint, an annotated image, and a JSON file with predictions.
+
+Example RT-DETRv4 inference (C-RADIOv4 teacher):
+
+```bash
+python scripts/inference.py rtdetrv4 \
+  --repo /path/to/RT-DETRv4 \
+  --checkpoint ckpts/rt-detrv4s-cradiov4-so400m/best_stg2.safetensors \
+  --input /path/to/image.jpg \
+  --device cuda \
+  --output-dir outputs/rtdetrv4_cradio
+```
+
+Example RT-DETRv4 inference (DINOv3-Base teacher):
+
+```bash
+python scripts/inference.py rtdetrv4 \
+  --repo /path/to/RT-DETRv4 \
+  --checkpoint ckpts/rt-detrv4s-dinov3b/best_stg2.safetensors \
+  --input /path/to/image.jpg \
+  --device cuda \
+  --output-dir outputs/rtdetrv4_dinov3b
+```
+
+Example RF-DETR inference:
+
+```bash
+python scripts/inference.py rfdetr \
+  --repo /path/to/rf-detr \
+  --checkpoint ckpts/rf-detrs/checkpoint_best_total.safetensors \
+  --input /path/to/image.jpg \
+  --device cuda \
+  --output-dir outputs/rfdetr
+```
+
+### Standalone Checkpoint Conversion
+
+This release also includes `scripts/convert_release_checkpoint.py` for users who only want checkpoint conversion without running inference.
+
+```bash
+# Convert RT-DETRv4 checkpoint
+python scripts/convert_release_checkpoint.py \
+  --framework rtdetrv4 \
+  --input ckpts/rt-detrv4s-cradiov4-so400m/best_stg2.safetensors \
+  --output converted/best_stg2.pth
+
+# Convert RF-DETR checkpoint
+python scripts/convert_release_checkpoint.py \
+  --framework rfdetr \
+  --input ckpts/rf-detrs/checkpoint_best_total.safetensors \
+  --output converted/checkpoint_best_total.pth
+```
+
+## Summary
+
+This release packages the main checkpoints from the accompanying CrowdHuman study and highlights teacher selection as a key design choice for VFM-distilled detectors. With the RT-DETRv4-S student fixed, replacing DINOv3-Base with C-RADIOv4 improves visible-person mAP by `+0.91` points and head mAP by `+1.71` points, indicating that the gains come from a stronger transferred representation rather than from increased student capacity.
+
+Among the compact models evaluated, the C-RADIOv4-distilled RT-DETRv4-S checkpoint is the strongest overall, reaching `0.8410` visible-person mAP and `0.7881` head mAP on CrowdHuman validation. Because the teacher is used only during training, these gains do not add inference-time cost, making the C-RADIOv4-based RT-DETRv4-S checkpoint the most practical release in this comparison.

TechnicalReport.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:409448d09566f8c839dbd1d8f051fce590ead2de9e71bb64573ab9fea39e35a3
+size 22841660

ckpts/rf-detrs/checkpoint_best_total.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:16092352a61d4bd0fe77be94db28db5fc19e9201540d6f39f3513f037fb03db1
+size 127238024

ckpts/rt-detrv4s-cradiov4-so400m/best_stg2.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8a0cc9acdf6adccf39511ac626335c1deb0003278e74b12295d70cdb6a44c869
+size 42417812

ckpts/rt-detrv4s-dinov3b/best_stg2.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c553edb5546f0f21201c2d3272b081b92e1cf3fbee062246fbfc3a3db6497ffb
+size 42023052

scripts/convert_release_checkpoint.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Convert HF release safetensors checkpoints into official repo checkpoint layouts."""
+
+from __future__ import annotations
+
+import argparse
+from argparse import Namespace
+from pathlib import Path
+
+import torch
+from safetensors.torch import load_file
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Convert a safetensors release checkpoint into the PyTorch checkpoint "
+            "layout expected by the official RT-DETRv4 or RF-DETR repositories."
+        )
+    )
+    parser.add_argument(
+        "--framework",
+        choices=("rtdetrv4", "rfdetr"),
+        required=True,
+        help="Target official repository format.",
+    )
+    parser.add_argument(
+        "--input",
+        type=Path,
+        required=True,
+        help="Input .safetensors checkpoint path.",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        required=True,
+        help="Output .pth checkpoint path.",
+    )
+    parser.add_argument(
+        "--class-names",
+        nargs="+",
+        default=["person", "head"],
+        help="Class names to store in RF-DETR checkpoint metadata.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    state_dict = load_file(str(args.input))
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+
+    if args.framework == "rtdetrv4":
+        payload = {"model": state_dict}
+    else:
+        payload = {
+            "model": state_dict,
+            "args": Namespace(class_names=args.class_names),
+        }
+
+    torch.save(payload, args.output)
+
+    print(f"Converted {args.input} -> {args.output}")
+    print(f"Framework: {args.framework}")
+    print(f"Tensors: {len(state_dict)}")
+    if args.framework == "rfdetr":
+        print(f"Class names: {args.class_names}")
+
+
+if __name__ == "__main__":
+    main()

scripts/inference.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Run release checkpoints through the official RT-DETRv4 or RF-DETR repositories."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from argparse import Namespace
+from pathlib import Path
+
+import torch
+from safetensors.torch import load_file
+
+
+IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png", ".bmp", ".webp"}
+VIDEO_SUFFIXES = {".mp4", ".avi", ".mov", ".mkv"}
+DEFAULT_CLASS_NAMES = ["person", "head"]
+
+
+def convert_checkpoint(
+    framework: str,
+    checkpoint_path: Path,
+    output_dir: Path,
+    class_names: list[str] | None = None,
+) -> Path:
+    checkpoint_path = checkpoint_path.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if checkpoint_path.suffix == ".pth":
+        return checkpoint_path
+
+    if checkpoint_path.suffix != ".safetensors":
+        raise ValueError(f"Unsupported checkpoint format: {checkpoint_path}")
+
+    state_dict = load_file(str(checkpoint_path))
+    output_path = output_dir / f"{checkpoint_path.stem}.pth"
+
+    if framework == "rtdetrv4":
+        payload = {"model": state_dict}
+    else:
+        payload = {
+            "model": state_dict,
+            "args": Namespace(class_names=class_names or DEFAULT_CLASS_NAMES),
+        }
+
+    torch.save(payload, output_path)
+    return output_path
+
+
+def infer_teacher_dim(checkpoint_path: Path, explicit: int | None) -> int:
+    if explicit is not None:
+        return explicit
+
+    checkpoint_path = checkpoint_path.resolve()
+    state_dict = None
+    if checkpoint_path.suffix == ".safetensors":
+        state_dict = load_file(str(checkpoint_path))
+    elif checkpoint_path.suffix == ".pth":
+        payload = torch.load(checkpoint_path, map_location="cpu", weights_only=False)
+        state_dict = payload["model"] if isinstance(payload, dict) and "model" in payload else payload
+
+    if isinstance(state_dict, dict) and "encoder.feature_projector.0.weight" in state_dict:
+        return int(state_dict["encoder.feature_projector.0.weight"].shape[0])
+
+    name = checkpoint_path.as_posix().lower()
+    if "cradio" in name or "cradiov4" in name or "c-radio" in name:
+        return 1152
+    return 768
+
+
+def write_rtdetrv4_config(repo_path: Path, output_dir: Path, teacher_dim: int) -> Path:
+    config_path = output_dir / "rtdetrv4_person_head_inference.yml"
+    base_config = (repo_path / "configs" / "rtv4" / "rtv4_hgnetv2_s_coco.yml").resolve()
+    config_text = (
+        "__include__: [\n"
+        f"  '{base_config}'\n"
+        "]\n\n"
+        "num_classes: 2\n"
+        "remap_mscoco_category: False\n\n"
+        "HGNetv2:\n"
+        "  pretrained: False\n\n"
+        "HybridEncoder:\n"
+        f"  distill_teacher_dim: {teacher_dim}\n"
+    )
+    config_path.write_text(config_text)
+    return config_path
+
+
+def run_rtdetrv4(args: argparse.Namespace) -> None:
+    repo_path = args.repo.resolve()
+    input_path = args.input.resolve()
+    output_dir = args.output_dir.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    converted_ckpt = convert_checkpoint("rtdetrv4", args.checkpoint, output_dir / "artifacts")
+    teacher_dim = infer_teacher_dim(args.checkpoint, args.teacher_dim)
+    config_path = write_rtdetrv4_config(repo_path, output_dir, teacher_dim)
+
+    command = [
+        sys.executable,
+        str((repo_path / "tools" / "inference" / "torch_inf.py").resolve()),
+        "-c",
+        str(config_path),
+        "-r",
+        str(converted_ckpt),
+        "-i",
+        str(input_path),
+        "-d",
+        args.device,
+    ]
+
+    subprocess.run(command, cwd=output_dir, check=True)
+
+    result_name = "torch_results.jpg"
+    if input_path.suffix.lower() in VIDEO_SUFFIXES:
+        result_name = "torch_results.mp4"
+
+    print(
+        json.dumps(
+            {
+                "framework": "rtdetrv4",
+                "converted_checkpoint": str(converted_ckpt),
+                "generated_config": str(config_path),
+                "result": str(output_dir / result_name),
+                "teacher_dim": teacher_dim,
+            },
+            indent=2,
+        )
+    )
+
+
+def build_label_lookup(class_names) -> dict[int, str]:
+    """Build an int -> str lookup from whatever format class_names is in."""
+    if isinstance(class_names, dict):
+        return {int(k): v for k, v in class_names.items()}
+    if isinstance(class_names, (list, tuple)):
+        return {i: name for i, name in enumerate(class_names)}
+    return {}
+
+
+def resolve_class_name(label_lookup: dict[int, str], raw_class_id: int) -> str:
+    if raw_class_id in label_lookup:
+        return label_lookup[raw_class_id]
+    if raw_class_id + 1 in label_lookup:
+        return label_lookup[raw_class_id + 1]
+    return str(raw_class_id)
+
+
+def run_rfdetr(args: argparse.Namespace) -> None:
+    import numpy as np
+    import supervision as sv
+    from PIL import Image
+
+    repo_path = args.repo.resolve()
+    output_dir = args.output_dir.resolve()
+    input_path = args.input.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if input_path.suffix.lower() not in IMAGE_SUFFIXES:
+        raise ValueError("RF-DETR wrapper currently supports image inference only.")
+
+    sys.path.insert(0, str(repo_path))
+    sys.path.insert(0, str(repo_path / "src"))
+
+    from rfdetr import RFDETRSmall
+
+    converted_ckpt = convert_checkpoint(
+        "rfdetr",
+        args.checkpoint,
+        output_dir / "artifacts",
+        class_names=args.class_names,
+    )
+
+    model = RFDETRSmall(
+        pretrain_weights=str(converted_ckpt),
+        device=args.device,
+    )
+
+    image = Image.open(input_path).convert("RGB")
+    detections = model.predict(image, threshold=args.threshold)
+
+    label_lookup = build_label_lookup(getattr(model, "class_names", args.class_names))
+    labels = []
+    for class_id, confidence in zip(detections.class_id.tolist(), detections.confidence.tolist()):
+        class_name = resolve_class_name(label_lookup, int(class_id))
+        labels.append(f"{class_name} {confidence:.2f}")
+
+    image_np = np.array(image)
+    annotated = sv.BoxAnnotator().annotate(scene=image_np, detections=detections)
+    annotated = sv.LabelAnnotator().annotate(scene=annotated, detections=detections, labels=labels)
+
+    output_image = output_dir / f"{input_path.stem}_rfdetr.jpg"
+    output_json = output_dir / f"{input_path.stem}_rfdetr.json"
+
+    Image.fromarray(annotated).save(output_image)
+
+    predictions = []
+    for box, confidence, class_id in zip(
+        detections.xyxy.tolist(),
+        detections.confidence.tolist(),
+        detections.class_id.tolist(),
+    ):
+        raw_id = int(class_id)
+        predictions.append(
+            {
+                "bbox_xyxy": [round(float(v), 4) for v in box],
+                "confidence": round(float(confidence), 6),
+                "class_id": raw_id,
+                "class_name": resolve_class_name(label_lookup, raw_id),
+            }
+        )
+
+    output_json.write_text(json.dumps(predictions, indent=2))
+
+    print(
+        json.dumps(
+            {
+                "framework": "rfdetr",
+                "converted_checkpoint": str(converted_ckpt),
+                "result_image": str(output_image),
+                "result_json": str(output_json),
+            },
+            indent=2,
+        )
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run this release through the official RT-DETRv4 or RF-DETR repositories."
+    )
+    subparsers = parser.add_subparsers(dest="framework", required=True)
+
+    rtdetr_parser = subparsers.add_parser("rtdetrv4", help="Run official RT-DETRv4 inference.")
+    rtdetr_parser.add_argument("--repo", type=Path, required=True, help="Path to the official RT-DETRv4 repository.")
+    rtdetr_parser.add_argument("--checkpoint", type=Path, required=True, help="Release checkpoint (.safetensors or .pth).")
+    rtdetr_parser.add_argument("--input", type=Path, required=True, help="Input image or video path.")
+    rtdetr_parser.add_argument("--device", default="cpu", help="Inference device passed to official script.")
+    rtdetr_parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path("outputs/rtdetrv4"),
+        help="Directory where converted weights, temp config, and outputs are written.",
+    )
+    rtdetr_parser.add_argument(
+        "--teacher-dim",
+        type=int,
+        choices=(768, 1152),
+        default=None,
+        help="Override the RT-DETRv4 distillation projection dimension if auto-detection is wrong.",
+    )
+    rtdetr_parser.set_defaults(func=run_rtdetrv4)
+
+    rfdetr_parser = subparsers.add_parser("rfdetr", help="Run official RF-DETR inference.")
+    rfdetr_parser.add_argument("--repo", type=Path, required=True, help="Path to the official RF-DETR repository.")
+    rfdetr_parser.add_argument("--checkpoint", type=Path, required=True, help="Release checkpoint (.safetensors or .pth).")
+    rfdetr_parser.add_argument("--input", type=Path, required=True, help="Input image path.")
+    rfdetr_parser.add_argument("--device", default="cpu", help="Device passed to RF-DETR.")
+    rfdetr_parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path("outputs/rfdetr"),
+        help="Directory where converted weights and outputs are written.",
+    )
+    rfdetr_parser.add_argument("--threshold", type=float, default=0.4, help="Detection threshold.")
+    rfdetr_parser.add_argument(
+        "--class-names",
+        nargs="+",
+        default=DEFAULT_CLASS_NAMES,
+        help="Class names stored in converted RF-DETR checkpoints.",
+    )
+    rfdetr_parser.set_defaults(func=run_rfdetr)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()