116 lines
5.2 KiB
Markdown
116 lines
5.2 KiB
Markdown
# anime-facesaver
|
|
|
|
Scene-gated still extractor for building anime training datasets from
|
|
video. Fork of `facesaver`, created Oct 2026.
|
|
|
|
## Why this fork exists
|
|
|
|
The original facesaver ran stock COCO `yolov11l.pt` and accepted
|
|
class 0 — **`person`** — as a "proxy for face" (their comment, not ours).
|
|
COCO has no face class, so every frame containing a large enough person
|
|
passed: full-body shots, headless crops, a hand at 75% confidence. That
|
|
is why the old Gabriel Dropout output contained stills of shoes.
|
|
|
|
anime-facesaver uses a dedicated anime-face detector instead:
|
|
[`yolov8x6_animeface`](https://huggingface.co/Fuyucchi/yolov8_animeface)
|
|
— yolov8x6 fine-tuned at 1280px on 10k manually annotated anime images
|
|
(P=0.957 R=0.924 mAP50=0.955 on its test set). It detects faces. Only
|
|
faces. The scene-change gate from the original is preserved: at most one
|
|
still is saved per detected scene, which keeps near-duplicates out of
|
|
the dataset.
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
uv venv --python 3.12 .venv # or: python3.12 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt # add --index-url for your CUDA ver
|
|
python anime_facesaver.py --download-model ... # fetches weights once
|
|
```
|
|
|
|
Weights land in `models/yolov8x6_animeface.pt` (~195 MB, AGPL-3.0).
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python anime_facesaver.py \
|
|
-I /home/alex/Documents/image-training-datasets/gabriel-dropout-show \
|
|
-O /home/alex/Documents/image-training-datasets/gabriel-dropout-v2 \
|
|
--gpu 1 \
|
|
--preview-dir /home/alex/Documents/image-training-datasets/gabriel-dropout-v2-preview
|
|
```
|
|
|
|
### GPU pinning (important on the shared .80 box)
|
|
|
|
`--gpu` sets `CUDA_VISIBLE_DEVICES` **before** torch initializes, so no
|
|
context leaks onto the wrong card:
|
|
|
|
| flag | effect |
|
|
|-----------|-----------------------------------------------|
|
|
| `--gpu 1` | pin to physical GPU 1 (recommended on .80) |
|
|
| `--gpu 0` | pin to GPU 0 — OOMs while Strata holds it |
|
|
| `--gpu cpu` | force CPU |
|
|
| `--gpu auto` | let torch pick |
|
|
|
|
### Key options
|
|
|
|
| flag | default | meaning |
|
|
|------|---------|---------|
|
|
| `--conf` | 0.3 | detector confidence (model's own recommendation; it is high-precision) |
|
|
| `--min-width` / `--min-height` | 100 | minimum face box size in px |
|
|
| `--min-face-fraction` | 0.005 | face box area as fraction of frame — kills distant background extras; `0` disables |
|
|
| `--max-face-fraction` | 0.30 | face box area upper cap — kills detector meltdowns on full-frame ED/OP effects (feather storms etc.); `0` disables |
|
|
| `--min-aspect` / `--max-aspect` | 0.45 / 1.6 | face box W/H ratio window — effect blobs rarely keep face proportions |
|
|
| `--edge-margin` | 0 | require faces this far inside frame edges; `0` accepts edge-touching faces (original hard-rejected them) |
|
|
| `--scene-threshold` | 30.0 | PySceneDetect ContentDetector threshold (same as original) |
|
|
| `--imgsz` | 1280 | inference size; model was trained at 1280, `640` is faster at some recall cost |
|
|
| `--all-files` | off | also scan OP/ED files. Off by default: music videos are full of stylized graphics (feather storms, transformation emblems) that false-positive as face-shaped; episodes carry the real character close-ups |
|
|
| `--preview-dir` | off | also write annotated copies (green boxes) of every saved frame for eyeball QC |
|
|
|
|
## Notes
|
|
|
|
- Runs every frame of every scene until a face qualifies, then waits
|
|
for the next scene start. That is the original behavior and it is why
|
|
dense scenes don't flood the output.
|
|
- The detector ships as `yolov8x6` — big and a little slow (it was
|
|
trained to be precise, not cheap). On a 3090 at 1280px expect roughly
|
|
8-12 fps; an hour of 24fps anime is ~15 min of inference per GPU.
|
|
- **License**: the model weights are AGPL-3.0 (Fuyucchi); ultralytics is
|
|
AGPL-3.0 too. Fine for personal/research dataset building; if this
|
|
ever ships in a product, revisit.
|
|
|
|
## QC: auditing an existing collection
|
|
|
|
`audit_stills.py` runs the same detector over a directory of stills and
|
|
reports how many contain no face at all — e.g. measuring the damage the
|
|
old person-proxy pipeline did:
|
|
|
|
```bash
|
|
python audit_stills.py -I ~/Documents/image-training-datasets/gabriel-dropout \
|
|
--gpu 1 --write-report old_run_report.csv
|
|
```
|
|
|
|
## Verified run (Gabriel Dropout, Oct 18 2026)
|
|
|
|
12 episodes + 2 specials, OP/ED skipped: **3,526 stills** vs 887 from
|
|
the old person-proxy run (~4x yield — chibi reaction faces no longer
|
|
missed). QC: full box-size distribution audited (p5=0.7%, median 6.6%,
|
|
max 29.9%); 5 largest and 5 smallest saves inspected with annotated
|
|
copies — all real faces; zero faceless images found. The 5 largest sit
|
|
against the 30% area cap and are legitimate extreme close-ups (crying
|
|
faces count).
|
|
|
|
## Verification workflow
|
|
|
|
Always run with `--preview-dir` and eyeball the `_ann.png` files: every
|
|
saved frame should show a green box on a real face. Pay attention to
|
|
saves clustered *against* a gate (e.g. many boxes at ~max area) — that
|
|
pattern means the gate is doing work and deserves a look. For a
|
|
known-dirty legacy collection, `audit_stills.py` quantifies the damage.
|
|
|
|
Recipe:
|
|
```bash
|
|
python anime_facesaver.py -I <show_dir> -O <out> --gpu <n> \
|
|
--preview-dir <out>-preview
|
|
```
|