3ddfa

# 3DDFA Repo Skill Use this repo skill when a task involves 3DDFA / 3D Dense Face Alignment: face alignment in full pose range, 68-point landmark prediction, dense 3D face vertices, pose boxes, PLY/OBJ export, depth/PNCC/PAF outputs, MobileNet-V1 checkpoints, 3DDFA training/evaluation, or the optional C++ OpenCV DNN port. This skill is an operating guide for a 3DDFA checkout or adapted codebase. It is self-contained: use the references and bundled scripts here for routing, command construction, diagnostics, and troubleshooting instead of reopening the original repository documentation. ## First Checks 1. Read [references/repo-provenance.md](references/repo-provenance.md) before deciding whether this skill matches a checkout. 2. Read [references/install-and-compatibility.md](references/install-and-compatibility.md) before installing dependencies or choosing CPU/CUDA/dlib/Cython paths. 3. Run [scripts/check_3ddfa_environment.py](scripts/check_3ddfa_environment.py) against the target checkout for a safe import/resource diagnostic. 4. If the task names a concrete workflow, route to the matching sub-skill below. Minimal diagnostic from this skill root: ```bash python scripts/check_3ddfa_environment.py --repo-root /path/to/3DDFA ``` The diagnostic checks resources and imports; it does not run native inference, training, downloads, CMake builds, or benchmarks. ## Route Map | User task or signal | Read | |---|---| | Run still-image inference, no-dlib bbox inference, inspect `main.py` flags, diagnose dlib/Cython startup, verify MobileNet forward shape, understand output filenames | [sub-skills/python-inference/SKILL.md](sub-skills/python-inference/SKILL.md) | | Decode 62-D parameters, ROI boxes, sparse/dense vertices, PLY/OBJ/`.mat`, pose matrices, depth/PNCC/PAF, Cython renderer, BFM/3DMM data artifacts, video-frame rendering | [sub-skills/geometry-rendering/SKILL.md](sub-skills/geometry-rendering/SKILL.md) | | Adapt training commands, choose WPDC/VDC/PDC, validate filelists/param files/data roots, resume checkpoints, interpret AFLW/AFLW2000 metrics | [sub-skills/training-evaluation/SKILL.md](sub-skills/training-evaluation/SKILL.md) | | Export MobileNet checkpoint to ONNX, place C++ weights, build/run OpenCV DNN demo, debug CMake/OpenCV/Yolo/ONNX issues | [sub-skills/cpp-onnx-port/SKILL.md](sub-skills/cpp-onnx-port/SKILL.md) | | Cross-cutting install/import/runtime failure | [references/troubleshooting.md](references/troubleshooting.md) | ## Operating Boundaries - Prefer CPU-safe diagnostics first. CUDA training/evaluation and GPU inference are optional capability paths and must be verified separately. - The unmodified Python image CLI imports `dlib` and render utilities before argument parsing. Even bbox-only workflows can fail at startup if Python `dlib` or the Cython render extension is missing. - Depth and PNCC require the compiled Cython mesh core; PLY/OBJ/landmarks can be planned separately, but the native CLI import path may still require the extension unless wrapped or patched. - Full training, benchmark extraction, and the C++ demo depend on external datasets, optional weights, system packages, or GPUs. Treat these as explicit prerequisites, not default verification steps. - Do not use this skill for 3DDFA_V2 unless the user explicitly asks to port concepts; this skill is based on the legacy 3DDFA repository snapshot in the provenance reference. ## Bundled Scripts - [scripts/check_3ddfa_environment.py](scripts/check_3ddfa_environment.py) — shared checkout/resource/import diagnostic. - [sub-skills/python-inference/scripts/inspect_3ddfa_inference.py](sub-skills/python-inference/scripts/inspect_3ddfa_inference.py) — image/video inference-specific diagnostic and command planner. - [sub-skills/python-inference/scripts/smoke_mobilenet_forward.py](sub-skills/python-inference/scripts/smoke_mobilenet_forward.py) — safe MobileNet architecture forward smoke. - [sub-skills/geometry-rendering/scripts/smoke_geometry.py](sub-skills/geometry-rendering/scripts/smoke_geometry.py) — safe 3DMM reconstruction shape smoke. - [sub-skills/training-evaluation/scripts/validate_training_args.py](sub-skills/training-evaluation/scripts/validate_training_args.py) — training command/data-layout checker that does not launch training. - [sub-skills/cpp-onnx-port/scripts/export_mobilenet_to_onnx.py](sub-skills/cpp-onnx-port/scripts/export_mobilenet_to_onnx.py) — explicit ONNX export helper for the optional C++ port. ## Verification Expectations Safe verification usually includes: - package/import/resource diagnostics; - MobileNet CPU forward shape `(1, 62)`; - geometry reconstruction shapes `(3, 68)` and dense `(3, 53215)`; - script `--help` checks for bundled helpers; - explicit skip notes for dlib predictor, Cython build, CUDA, external datasets, and OpenCV C++ demo when unavailable. Do not claim native end-to-end inference, GPU training/evaluation, full benchmarks, or C++ runtime success unless those exact paths were run in the target environment.