README.md

---
license: apache-2.0
library_name: rfdetr.cpp
tags:
  - object-detection
  - rfdetr
  - gguf
  - ggml
  - cpp-inference
  - image-segmentation
  - instance-segmentation
pipeline_tag: image-segmentation
base_model: roboflow/rfdetr
---

# RF-DETR Seg-Medium — GGUF for rfdetr.cpp

GGUF-format weights of [Roboflow RF-DETR Seg-Medium](https://github.com/roboflow/rf-detr) (segmentation variant) for use with [rfdetr.cpp](https://github.com/mudler/rf-detr.cpp), a C++/ggml implementation that matches the upstream PyTorch model on CPU.

This repo contains all four standard quantizations of this variant. **F16 is the recommended default** — near-identical accuracy to F32 (see the table below), 1.87× smaller than F32, and it takes ggml's F32×F16 matmul fast path.

## Available files

| File | Quant | Size (MB) | Recall @ IoU 0.5 | Recall @ IoU 0.95 | Mean mask IoU | Pixel agreement | Latency (median ms, T=8) |
|---|---|---:|---:|---:|---:|---:|---:|
| `rfdetr-seg-medium-f32.gguf` | F32 | 133.9 | 0.9841 | 0.9841 | 0.9975 | 0.9999 | — |
| `rfdetr-seg-medium-f16.gguf` ← **recommended** | F16 | 71.6 | 0.9841 | 0.9841 | 0.9975 | 0.9999 | — |
| `rfdetr-seg-medium-q8_0.gguf` | Q8_0 | 42.5 | 0.9841 | 0.9637 | 0.9938 | 0.9999 | — |
| `rfdetr-seg-medium-q4_K.gguf` | Q4_K | 33.6 | 0.9296 | 0.6420 | 0.9699 | 0.9993 | — |

All accuracy numbers are computed against the upstream PyTorch reference (`rfdetr 1.9.0`) on 7 COCO val2017 images at threshold 0.5.
No latency benchmark has been recorded for this variant yet, so the latency column is left empty. Run `scripts/quick_bench.sh` locally for timings on your own hardware.

## Architecture

- Backbone: DINOv2-small
- Input resolution: 432×432
- Patch size: 12
- Decoder layers: 5
- Object queries: 200
- Task: instance segmentation (boxes + per-query masks)
- Mask resolution: 108×108 per query (image_size / 4)

## Quantization notes

- **F32** — the full-precision conversion, 134 MB, and the closest match to the PyTorch reference (see the table above for measured agreement).
- **F16** — matmul-multiplicand weights only; LayerNorms, conv kernels, embeddings, biases, and layer-scale gammas stay F32. Accuracy tracks F32 closely on this model, and it takes ggml's F32×F16 matmul fast path.
- **Q8_0** — best size/accuracy tradeoff under F16; ~3.2× smaller than F32 with effectively identical detections.
- **Q4_K** — smallest practical quant. Rows with `ne[0] % 256 != 0` (the decoder's 128-dim MLP halves) silently fall back to Q8_0 per ggml's quantizer logic — net compression is still ~4.0× over F32. Use only when the size budget is tight; expect a measurable Recall@0.95 drop relative to F16/Q8_0 (see file table above).

## Usage

```bash
# 1. Clone + build rfdetr.cpp
git clone https://github.com/mudler/rf-detr.cpp
cd rf-detr.cpp
cmake -B build -DRFDETR_BUILD_CLI=ON && cmake --build build -j

# 2. Download a quant (F16 recommended)
hf download mudler/rfdetr-cpp-seg-medium rfdetr-seg-medium-f16.gguf --local-dir models/

# 3. Run segmentation (writes per-detection PNG masks to /tmp/seg_masks/)
build/bin/rfdetr-cli detect \
    --model models/rfdetr-seg-medium-f16.gguf \
    --input my_image.jpg \
    --threshold 0.5 --threads 8 \
    --masks /tmp/seg_masks \
    --output detections.json
```

## Accuracy methodology

All accuracy metrics are computed against the upstream PyTorch reference (`rfdetr 1.9.0`) on 7 COCO val2017 images at threshold 0.5. Each detection match uses greedy Hungarian-style assignment by IoU (≥ 0.5 lenient, ≥ 0.95 strict) with class equality required.

Mask metrics are pixel-wise IoU between binary masks at the **original** image resolution (not the network's working resolution), after sigmoid + bicubic upsample of the per-query mask logits. **Pixel agreement** is the fraction of pixels where the C++ and PyTorch binary masks match.

See [BENCHMARK.md](https://github.com/mudler/rf-detr.cpp/blob/main/BENCHMARK.md) and [`benchmarks/results/accuracy_sweep.json`](https://github.com/mudler/rf-detr.cpp/blob/main/benchmarks/results/accuracy_sweep.json) for the full sweep across the (variant × quant) cells.

## License

Apache-2.0 — matches the upstream [rfdetr](https://github.com/roboflow/rf-detr) license.