3ddfa-v2

# 3DDFA_V2 Use this skill for the 3DDFA_V2 face-alignment repo. The public workflow is a small pipeline: build the native pieces, then run still-image, video/tracking, or ONNX/benchmark commands. ## Start here 1. If anything fails to build or import, open `references/troubleshooting.md`. 2. If you need model files or config choices, open `references/model-assets.md`. 3. If you need class/function details, open `references/api-reference.md`. 4. Run the setup route first whenever `render.so`, `cpu_nms`, or `Sim3DR_Cython` is missing. The repository is source-first, not a packaged wheel. Use the bundled helpers in this skill tree instead of calling the original repo scripts directly. ## Routes ### `setup-and-assets` Use when the user asks to install or verify the runtime, build compiled pieces, check checkpoint/config assets, or fix import/build failures. Read `sub-skills/setup-and-assets/SKILL.md`, `references/model-assets.md`, and `references/troubleshooting.md`. Use the bundled helpers: - `scripts/build_native_extensions.py` - `scripts/check_assets.py` - `scripts/check_core_imports.py` ### `still-image-demo` Use for single-image inference, 2D landmark overlays, 3D renderings, depth, PNCC, UV texture, pose boxes, PLY, or OBJ exports. Read `sub-skills/still-image-demo/SKILL.md` and `sub-skills/still-image-demo/references/workflows.md`. Use `sub-skills/still-image-demo/scripts/run-still-image.py` for a headless-friendly wrapper. ### `video-and-tracking` Use for MP4/AVI processing, tracking, smoothing, or frame-window control. Read `sub-skills/video-and-tracking/SKILL.md` and `sub-skills/video-and-tracking/references/workflows.md`. Use `sub-skills/video-and-tracking/scripts/run-video.py` and `sub-skills/video-and-tracking/scripts/run-video-smooth.py`. ### `onnx-and-benchmarking` Use for ONNX acceleration, CPU latency, thread tuning, or microbenchmarks. Read `sub-skills/onnx-and-benchmarking/SKILL.md` and `sub-skills/onnx-and-benchmarking/references/workflows.md`. Use `sub-skills/onnx-and-benchmarking/scripts/run-latency.py` and `sub-skills/onnx-and-benchmarking/scripts/run-speed-cpu.py`. ## Common runtime facts - Default config: `configs/mb1_120x120.yml`. - Alternate configs: `configs/mb05_120x120.yml` and `configs/resnet_120x120.yml`. - Provide an input image or video path for demos; local smoke fixtures may be used when the checkout includes them. - Generated outputs live under `examples/results/`. - `demo.py` supports `2d_sparse`, `2d_dense`, `3d`, `depth`, `pncc`, `uv_tex`, `pose`, `ply`, and `obj`. - `demo_video.py` and `demo_video_smooth.py` support `2d_sparse` and `3d`; webcam mode is manual-only and is documented, but not bundled as a runnable helper. - `--onnx` switches the demo pipeline to the CPU-friendly ONNX path. - `uv_tex` needs SciPy and the BFM UV/config assets. - The repo still references deprecated NumPy aliases such as `np.long`, so the bundled runtime helpers restore a compatibility layer before importing the pipeline. ## Headless use The bundled helpers default to headless plotting behavior so they work in non-GUI environments. If you need interactive windows, override that behavior explicitly. ## What not to route here - Experimental Gradio notebook/demo code. - Generic face detection tasks that do not involve the 3DDFA_V2 alignment pipeline. - Training or dataset creation tasks; this repo is inference-oriented.