HHC

Head Hat Classification. HHC is a binary classifier for cropped head images. 48x48.

https://github.com/user-attachments/assets/d719d64e-8c5a-454c-9dc8-3c02b776a1a9

Classes

Default input size is 48x48.

Install

uv sync --all-extras
source .venv/bin/activate

Data sample

Demo

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_waitKey

For 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 cpu

For 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_mode

uv 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_mode

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

Train

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_amp

SIZE=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_amp

SIZE=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_amp

SIZE=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_amp

SIZE=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_amp

Export ONNX

Training 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 cpu

Use the hhc_best_*.pt checkpoint from the target run directory.

Arch

Ultra-lightweight classification model series

1. VSDLM: Visual-only speech detection driven by lip movements - MIT License
2. OCEC: Open closed eyes classification. Ultra-fast wink and blink estimation model - MIT License
3. PGC: Ultrafast pointing gesture classification - MIT License
4. SC: Ultrafast sitting classification - MIT License
5. PUC: Phone Usage Classifier is a three-class image classification pipeline for understanding how people
   interact with smartphones - MIT License
6. HSC: Happy smile classifier - MIT License
7. WHC: Waving Hand Classification - MIT License
8. UHD: Ultra-lightweight human detection - MIT License
9. MWC: Mask wearing classifier. - MIT License
10. SGC: Classification of wearing vs. not wearing sunglasses. 48x48. - MIT License
11. HHC: Head Hat Classification. HHC is a binary classifier for cropped head images. 48x48. - MIT License
12. BPC: Background Plain classification. 48x48. - MIT License
13. PPC: Binary classification to determine whether the subject is holding a smartphone. 48x48 RGB image. - MIT License

Citation

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