中文 | English

Face Emotion Detection (YOLOv8)

A lightweight face emotion detection project built on Ultralytics YOLOv8. This repository includes training and inference scripts, along with a simple environment check to help you get started fast.

Note on data and weights: To keep the repo small, datasets and intermediate model checkpoints are not tracked by git (ignored via .gitignore). Datasets are NOT shipped in Releases. Please download datasets yourself using the links/scripts referenced in the YAML files under ./datasets/*.yaml. Some Releases may provide trained model weights to help you run inference quickly; otherwise, specify your own weights.

Requirements

• Python 3.8+
• Windows/Linux/macOS (GPU optional)
• Install dependencies:

pip install -r .\requirements.txt

PyTorch install notes:

• If your Python is 3.8, the requirements file pins a compatible torch 2.2.x trio automatically.
• If your Python is 3.9+, you'll get torch 2.5.x by default using the official PyTorch wheel index.
• CPU-only: add the CPU index to the command:

pip install -r .\requirements.txt --index-url https://download.pytorch.org/whl/cpu

• CUDA GPUs (Windows/Linux): the default requirements already include the CUDA 12.1 extra index, so pip will resolve cu121 wheels automatically. Ensure your NVIDIA driver supports CUDA 12.x. If you prefer CPU, use the CPU command above.

• (Optional) Verify your environment:

python .\test_environment.py

Quick Start

1) Inference (three modes)

Weights lookup order by default:

• ./emotion_detection/train_v1/weights/best.pt
• ./best.pt

You can also specify a custom path with --model path/to/weights.pt.

1. Images directory

• Put test images into ./input (output will go to ./output)

python .\detect.py

2. Video file

python .\detect.py --video .\path\to\video.mp4 --show --save-out .\output\detected_video.mp4

3. Webcam

python .\detect.py --camera --cam-id 0 --show --save-out .\output\camera_out.mp4

For more runtime options (confidence, device, image size, etc.), see DETECT_USAGE.md.

2) Training

If you need to train:

• Download the dataset yourself. Open datasets/emotion_dataset.yaml (or your dataset YAML) and follow the download field or linked script/URL to fetch the data. Place the dataset under ./datasets matching the YAML structure (train/val/test with images/labels).
• Optionally, download trained weights from Releases (if available) to resume training or for warm starts.

Run training with presets:

# Default preset
python .\train.py

# Quick preset (fewer epochs, smaller batch, may use subset)
python .\train.py --config-preset quick

# High-quality preset (longer training)
python .\train.py --config-preset high-quality

Training artifacts are saved under runs/detect/<experiment>/weights/ (e.g., best.pt, last.pt). For detailed configuration (batch size, epochs, device, optimizer, etc.), see CONFIG_USAGE.md.

Dataset too large? Use subset training to fit your resources:

# Use 25% of the dataset (first N files)
python .\train.py --use-subset --subset-ratio 0.25 --subset-method first

# Use 30% with stratified sampling
python .\train.py --use-subset --subset-ratio 0.3 --subset-method stratified

# Quick preset already uses a subset by default
python .\train.py --config-preset quick

More Configuration

• Detector runtime options: DETECT_USAGE.md
• Training configuration and presets: CONFIG_USAGE.md

Utilities

Cache cleaner (datasets *.npy)

Clean .npy cache files under ./datasets/train and ./datasets/val.

PowerShell examples:

# Preview (no deletion)
python .\ccache.py

# Actually delete (skip confirmation)
python .\ccache.py --no-dry-run -y

# Delete files older than 7 days
python .\ccache.py --older-than 7 --no-dry-run

# Include/Exclude patterns
python .\ccache.py --include *.cache.npy *.idx.npy
python .\ccache.py --exclude *keep*.npy --no-dry-run

# Verbose output
python .\ccache.py -v

Releases and Assets

• Datasets are NOT included in Releases. Download datasets via the download references in ./datasets/*.yaml.
• Some Releases may provide trained model weights; if available, you can start inference faster.
• If you clone this repository, you must:
  • Provide trained weights at one of the expected locations or via --model for inference.
  • Download and place the dataset under ./datasets (per YAML) if you plan to train.

Troubleshooting

• Run the environment check:

python .\test_environment.py

• If no weights are found, specify them explicitly:

python .\detect.py --model .\emotion_detection\train_v1\weights\best.pt

Need more help? See the detailed guides: CONFIG_USAGE.md and DETECT_USAGE.md.

Common issues table

Symptom	Likely cause	How to fix
ImportError: cv2/torch/ultralytics	Missing packages	pip install -r .\requirements.txt
No weights found error	Trained weights not present	Download the Release bundle or pass --model path\to\weights.pt
Dataset YAML/path errors during training	Dataset not placed under ./datasets or wrong structure	Follow datasets/emotion_dataset.yaml; ensure images/labels split exists
CUDA out of memory	Batch/img size too large for GPU memory	Reduce --batch or --imgsz; try --device cpu; consider half precision
OpenCV cannot open camera	Wrong camera id or permission	Try --cam-id 0/1; close other apps; check drivers
Video writer failed	Codec/permission/path issues	Ensure output folder exists; try different output path/filename
PyTorch/CUDA mismatch	Torch installed without matching CUDA	Reinstall torch for your CUDA, or use CPU device

PyTorch install errors (no matching distribution found)

Typical causes and fixes:

• Python too old/new for the pinned torch: use Python 3.8–3.12. For 3.8, we auto-pin torch==2.2.*; for 3.9+ torch>=2.5.1.
• Platform-specific wheel index missing: our requirements add the official PyTorch index for CUDA 12.1. For CPU-only install, use the CPU index command shown above.
• Corporate mirror/proxy stripping extra-index: re-run with the explicit index-url flag or set PIP_EXTRA_INDEX_URL accordingly.

FAQ

What are the default training settings and expected performance?

• Dataset: current packaged dataset is a quarter of the original, with about 27,000 training items. Release no longer includes datasets; please download datasets yourself using the download field or links in datasets/emotion_dataset.yaml and place them under ./datasets per the YAML structure.
• Reference machine: Ryzen 7 7735H + RTX 4060 Laptop + 32 GB RAM.
• Caching: default uses disk caching; using in-RAM caching (or disabling cache) may cause OOM on 32 GB RAM. If you hit OOM, consider shrinking the dataset further or using the quick preset.
• Runtime: Using 25% of the original dataset, 40 epochs take about ~5 hours on the reference machine.

Tips to adapt to your machine:

• Use presets to start: --config-preset quick for limited resources, high-quality for longer training.
• Reduce batch size and/or image size if you see OOM.
• Consider using dataset subsets; see CONFIG_USAGE.md for options and details.
• GPU users: ensure proper NVIDIA drivers and a matching PyTorch CUDA build.