Head Hat Classification. HHC is a binary classifier for cropped head images. 48x48.
output_.mp4
| class_id | label |
|---|---|
| 0 | no_wearing_hat |
| 1 | wearing_hat |
Default input size is 48x48.
| Variant | Size | F1 | CPU inference latency |
ONNX |
|---|---|---|---|---|
| P | 115 KB | 0.9150 | 0.23 ms | Download |
| N | 176 KB | 0.9314 | 0.41 ms | Download |
| T | 280 KB | 0.9463 | 0.52 ms | Download |
| S | 495 KB | 0.9702 | 0.64 ms | Download |
| L | 6.4 MB | 0.9650 | 1.03 ms | Download |
uv sync --all-extras
source .venv/bin/activate| 1 | 2 | 3 | 4 | 5 | 6 |
|---|---|---|---|---|---|
The demo script needs a YOLO whole-body detector ONNX/TFLite model and an HHC hat classifier ONNX model.
Place the detector model in the repository root, or pass its path with --model.
Use the ONNX file exported by training for --hhc_model.
uv run python demo_hhc.py \
--model yolomit_t_wholebody28_1x3x480x640.onnx \
--hhc_model hhc_is_l_48x48.onnx \
--images_dir path/to/images \
--execution_provider cpu \
--disable_waitKeyFor a video file:
uv run python demo_hhc.py \
--model yolomit_t_wholebody28_1x3x480x640.onnx \
--hhc_model hhc_is_l_48x48.onnx \
--video path/to/video.mp4 \
--execution_provider cpuFor a camera:
uv run python demo_hhc.py \
--model yolomit_t_wholebody28_1x3x480x640.onnx \
--hhc_model hhc_is_l_48x48.onnx \
--video 0 \
--execution_provider cpu \
--disable_generation_identification_mode \
--disable_gender_identification_mode \
--disable_left_and_right_hand_identification_mode \
--disable_headpose_identification_modeuv run python demo_hhc.py \
--model yolomit_t_wholebody28_1x3x480x640.onnx \
--hhc_model hhc_is_l_48x48.onnx \
--video 0 \
--execution_provider cuda \
--disable_generation_identification_mode \
--disable_gender_identification_mode \
--disable_left_and_right_hand_identification_mode \
--disable_headpose_identification_modeProcessed still images are saved under output/.
Video input is also recorded to output.mp4 by default; add --disable_video_writer to skip recording.
Use --execution_provider cuda or --execution_provider tensorrt when the required ONNXRuntime GPU/TensorRT environment is available.
SIZE=48x48
VAR=p
uv run python -m hhc train \
--data_root data/dataset.parquet \
--seed 42 \
--output_dir runs/hhc_is_${VAR}_${SIZE} \
--epochs 100 \
--batch_size 256 \
--train_resampling balanced \
--image_size ${SIZE} \
--base_channels 32 \
--num_blocks 1 \
--arch_variant inverted_se \
--head_variant avgmax_mlp \
--device auto \
--use_ampSIZE=48x48
VAR=n
uv run python -m hhc train \
--data_root data/dataset.parquet \
--seed 42 \
--output_dir runs/hhc_is_${VAR}_${SIZE} \
--epochs 100 \
--batch_size 256 \
--train_resampling balanced \
--image_size ${SIZE} \
--base_channels 32 \
--num_blocks 2 \
--arch_variant inverted_se \
--head_variant avgmax_mlp \
--device auto \
--use_ampSIZE=48x48
VAR=t
uv run python -m hhc train \
--data_root data/dataset.parquet \
--seed 42 \
--output_dir runs/hhc_is_${VAR}_${SIZE} \
--epochs 100 \
--batch_size 256 \
--train_resampling balanced \
--image_size ${SIZE} \
--base_channels 32 \
--num_blocks 3 \
--arch_variant inverted_se \
--head_variant avgmax_mlp \
--device auto \
--use_ampSIZE=48x48
VAR=s
uv run python -m hhc train \
--data_root data/dataset.parquet \
--seed 42 \
--output_dir runs/hhc_is_${VAR}_${SIZE} \
--epochs 100 \
--batch_size 256 \
--train_resampling balanced \
--image_size ${SIZE} \
--base_channels 32 \
--num_blocks 4 \
--arch_variant inverted_se \
--head_variant avgmax_mlp \
--device auto \
--use_ampSIZE=48x48
VAR=l
uv run python -m hhc train \
--data_root data/dataset.parquet \
--seed 42 \
--output_dir runs/hhc_is_${VAR}_${SIZE} \
--epochs 100 \
--batch_size 256 \
--train_resampling balanced \
--image_size ${SIZE} \
--base_channels 32 \
--num_blocks 8 \
--arch_variant inverted_se \
--head_variant avgmax_mlp \
--device auto \
--use_ampTraining exports the best checkpoint to ONNX automatically. To export a checkpoint manually, run:
uv run python -m hhc exportonnx \
--checkpoint runs/hhc_is_l_48x48/hhc_best_epoch0067_f1_0.9430.pt \
--output hhc_is_l_48x48.onnx \
--opset 17 \
--device cpuUse the hhc_best_*.pt checkpoint from the target run directory.
- VSDLM: Visual-only speech detection driven by lip movements - MIT License
- OCEC: Open closed eyes classification. Ultra-fast wink and blink estimation model - MIT License
- PGC: Ultrafast pointing gesture classification - MIT License
- SC: Ultrafast sitting classification - MIT License
- PUC: Phone Usage Classifier is a three-class image classification pipeline for understanding how people interact with smartphones - MIT License
- HSC: Happy smile classifier - MIT License
- WHC: Waving Hand Classification - MIT License
- UHD: Ultra-lightweight human detection - MIT License
- MWC: Mask wearing classifier. - MIT License
- SGC: Classification of wearing vs. not wearing sunglasses. 48x48. - MIT License
- HHC: Head Hat Classification. HHC is a binary classifier for cropped head images. 48x48. - MIT License
- BPC: Background Plain classification. 48x48. - MIT License
- PPC: Binary classification to determine whether the subject is holding a smartphone. 48x48 RGB image. - MIT License
If you find this project useful, please consider citing:
@software{hyodo2026hhc,
author = {Katsuya Hyodo},
title = {PINTO0309/HHC},
month = {06},
year = {2026},
publisher = {Zenodo},
doi = {10.5281/zenodo.20931298},
url = {https://github.com/PINTO0309/hhc},
abstract = {Head Hat Classification. HHC is a binary classifier for cropped head images. 48x48.},
}