README.md

---
license: agpl-3.0
pipeline_tag: object-detection
tags:
- yolo
- finger
- detection
---

# CountHallu — RealHand Counting Model

Finger detector from **[Counting Hallucinations in Diffusion Models](https://arxiv.org/abs/2510.13080)**
(arXiv:2510.13080). A YOLO-based detector is used to count fingers in generated/real hand images, enabling the evaluation to flag hands with an incorrect number of fingers as counting hallucinations.

## Architecture & checkpoint

- An **Ultralytics YOLO-v13** object detector, ships a single `model.pt`.
- One class, **`0 = finger`**; a correct hand has exactly **5** detected fingers.
- Inference settings used in the paper: `imgsz=640, conf=0.25, iou=0.1`.

> **Two-stage pipeline.** RealHand scoring first passes each image through the
> quality classifier
> [`CountHallu-quality_cls_model-RealHand`](https://huggingface.co/ShyFoo/CountHallu-quality_cls_model-RealHand),
> which filters out non-countable (visually failed) images; only clean images reach
> this finger detector. You need both models to calculate the counting hallucination rates in the RealHand dataset.

## Usage

See the [CountHallu repository](<https://github.com/ShyFoo/CountHallu-Diff>) for the full evaluation protocol.

```python
from ultralytics import YOLO
from huggingface_hub import hf_hub_download

ckpt = hf_hub_download("ShyFoo/CountHallu-counting_model-RealHand", "model.pt")
model = YOLO(ckpt, task="detect")
results = model.predict(source="hand.png", imgsz=640, conf=0.25, iou=0.1)
num_fingers = len(results[0].boxes)
```

Or let the evaluation protocol fetch it for you:

```python
from counthallu.utils import load_counting_model
model, model_type, ref_counts, target_classes = load_counting_model(
    "realhand", use_hub_model=True,
    repo_id="ShyFoo/CountHallu-counting_model-RealHand"
)
```

## License

This detector is trained with **Ultralytics YOLO-v13** on the [CountHallu-RealHand dataset](https://huggingface.co/datasets/ShyFoo/CountHallu-dataset-RealHand), which is **AGPL-3.0**.

## Citation

```bibtex
@article{fu2025counting,
  title={Counting Hallucinations in Diffusion Models},
  author={Fu, Shuai and Zhou, Jian and Chen, Qi and Jing, Huang and Nguyen, Huy Anh and Liu, Xiaohan and Zeng, Zhixiong and Ma, Lin and Zhang, Quanshi and Wu, Qi},
  journal={arXiv preprint arXiv:2510.13080},
  year={2025}
}
```