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
- If anything fails to build or import, open
references/troubleshooting.md. - If you need model files or config choices, open
references/model-assets.md. - If you need class/function details, open
references/api-reference.md. - Run the setup route first whenever
render.so,cpu_nms, orSim3DR_Cythonis 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.pyscripts/check_assets.pyscripts/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.ymlandconfigs/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.pysupports2d_sparse,2d_dense,3d,depth,pncc,uv_tex,pose,ply, andobj.demo_video.pyanddemo_video_smooth.pysupport2d_sparseand3d; webcam mode is manual-only and is documented, but not bundled as a runnable helper.--onnxswitches the demo pipeline to the CPU-friendly ONNX path.uv_texneeds 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.


