### Install 3ddfa_v2 Dependencies

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/README.md

Installs project dependencies and builds Cython extensions. Ensure you are in the 3DDFA_V2 directory.

```bash
cd 3DDFA_V2
pip install -r requirements.txt
sh ./build.sh  # Build Cython extensions
```

--------------------------------

### Run Specific Output Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Example of running the demo script on a still image and requesting a specific output type (e.g., '3d').

```python
python3 demo.py -f examples/inputs/emma.jpg -o 3d
```

--------------------------------

### Clone Repository

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Clone the 3DDFA_V2 repository to your local machine. This is the first step to get started with the project.

```shell
git clone https://github.com/cleardusk/3DDFA_V2.git
cd 3DDFA_V2
```

--------------------------------

### Pose Parameter Example Usage

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/types.md

An example demonstrating how to check if the head has turned more than 30 degrees sideways based on the yaw parameter.

```python
yaw, pitch, roll = pose
if abs(yaw) > 30:
    print("Head turned more than 30 degrees sideways")
```

--------------------------------

### Full Pipeline Example for 3D Face Reconstruction

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/visualization-utils.md

This snippet demonstrates the complete workflow for 3D face reconstruction using the 3ddfa_v2 library. It includes face detection, landmark localization, and generation of various visualizations like 3D models, head poses, and depth maps. Ensure you have the necessary weights and input image ('photo.jpg') available.

```python
import cv2
from FaceBoxes import FaceBoxes
from TDDFA import TDDFA
from utils.render import render
from utils.pose import viz_pose
from utils.depth import depth
from utils.functions import draw_landmarks

# Setup
detector = FaceBoxes()
tddfa = TDDFA(arch='MobileNet', checkpoint_fp='weights/mb1_120x120.pth')

# Load and process image
img = cv2.imread('photo.jpg')
boxes = detector(img)
param_lst, roi_box_lst = tddfa(img, boxes)

# Generate outputs
ver_lst = tddfa.recon_vers(param_lst, roi_box_lst, dense_flag=True)

# Visualize
img_3d = render(img, ver_lst, tddfa.tri, alpha=0.6, wfp='3d.jpg')
img_pose = viz_pose(img, param_lst, ver_lst, wfp='pose.jpg')
img_depth = depth(img, ver_lst, tddfa.tri, wfp='depth.jpg')
```

--------------------------------

### Create and Use MobileNet for 3DMM

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/models.md

Example of creating a MobileNet model for 3DMM parameter regression and performing a forward pass. Ensure `num_classes` is set to 62 for 3DMM parameters.

```python
from models import MobileNet
import torch

# Create model for 3DMM
model = MobileNet(
    widen_factor=1.0,
    num_classes=62,
    prelu=False,
    input_channel=3
)

# Forward pass
x = torch.randn(1, 3, 120, 120)
param = model(x)
print(param.shape)  # torch.Size([1, 62])
```

--------------------------------

### Typical Workflow for 3D Face Alignment

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/overview.md

This Python script demonstrates the typical workflow for 3D face alignment using the 3DDFA v2 library. It covers face detection, 3DMM parameter prediction, vertex reconstruction, and visualization. Ensure you have the necessary libraries and model weights installed.

```python
import cv2
from FaceBoxes import FaceBoxes
from TDDFA import TDDFA
from utils.render import render
from utils.pose import viz_pose

# Initialize
detector = FaceBoxes()
tddfa = TDDFA(arch='MobileNet', checkpoint_fp='weights/mb1_120x120.pth')

# Load image
img = cv2.imread('photo.jpg')

# Detect faces
boxes = detector(img)
if len(boxes) == 0:
    print("No faces detected")
    exit()

# Predict 3DMM parameters
param_lst, roi_box_lst = tddfa(img, boxes)

# Reconstruct 3D vertices
ver_lst = tddfa.recon_vers(param_lst, roi_box_lst, dense_flag=True)

# Visualize
img_3d = render(img, ver_lst, tddfa.tri, alpha=0.6, wfp='3d_mesh.jpg')
img_pose = viz_pose(img, param_lst, ver_lst, wfp='pose.jpg')

print(f"Processed {len(param_lst)} faces")
```

--------------------------------

### Run Webcam Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/README.md

Execute the smooth demo script for processing webcam input. Use the --onnx flag for ONNX runtime.

```bash
python demo_webcam_smooth.py --onnx
```

--------------------------------

### Run Video Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/README.md

Execute the demo script for processing a video file. Use the --onnx flag for ONNX runtime.

```bash
python demo_video.py -f video.avi --onnx
```

--------------------------------

### Specify Configuration File

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Run the demo script while specifying a custom configuration file for the model. This allows using different backbones or input sizes.

```python
python3 demo.py -c configs/mb05_120x120.yml
```

--------------------------------

### Load configuration and initialize models

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/demo.ipynb

Loads the configuration file and initializes FaceBoxes and TDDFA. Supports both standard and ONNX versions for potential speedup.

```python
# load config
cfg = yaml.load(open('configs/mb1_120x120.yml'), Loader=yaml.SafeLoader)

# Init FaceBoxes and TDDFA, recommend using onnx flag
onnx_flag = True  # or True to use ONNX to speed up
if onnx_flag:
    import os
    os.environ['KMP_DUPLICATE_LIB_OK'] = 'True'
    os.environ['OMP_NUM_THREADS'] = '4'
    
    from FaceBoxes.FaceBoxes_ONNX import FaceBoxes_ONNX
    from TDDFA_ONNX import TDDFA_ONNX
    
    face_boxes = FaceBoxes_ONNX()
    tddfa = TDDFA_ONNX(**cfg)
else:
    tddfa = TDDFA(gpu_mode=False, **cfg)
    face_boxes = FaceBoxes()
```

--------------------------------

### Run Webcam Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Process live video feed from the webcam using a smooth approach. ONNX runtime is enabled.

```python
python3 demo_webcam_smooth.py --onnx
```

--------------------------------

### Get File Suffix

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/utility-functions.md

Extracts the file extension from a given filename. Handles cases with multiple dots in the filename, returning only the last extension.

```python
get_suffix('image.jpg')  # Returns '.jpg'
get_suffix('model.tar.gz')  # Returns '.gz'
```

--------------------------------

### BFM Keypoints Data Type

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/types.md

Stores the indices of semantic keypoints within the BFM model. These indices refer to vertices, for example, the first vertex can be a keypoint.

```python
keypoints: np.ndarray  # Shape: (num_keypoints,), dtype: int64
# Indices of semantic keypoints (e.g., 68 landmarks)
# keypoints[0] = 0  # First vertex is a keypoint
```

--------------------------------

### Initialize TDDFA and Detect Faces

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/TDDFA.md

Demonstrates initializing the FaceBoxes detector and TDDFA model, then loading an image and detecting faces. Ensure the correct model checkpoint path is provided.

```python
import cv2
from TDDFA import TDDFA
from FaceBoxes import FaceBoxes

# Initialize
face_boxes = FaceBoxes()
tddfa = TDDFA(arch='MobileNet', checkpoint_fp='weights/mb1_120x120.pth')

# Load image
img = cv2.imread('face.jpg')

# Detect faces and predict 3DMM parameters
boxes = face_boxes(img)
param_lst, roi_box_lst = tddfa(img, boxes)
```

--------------------------------

### Visualization and Serialization Utilities

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Demonstrates how to use utility functions for rendering 3D face models, visualizing poses, and exporting to PLY format. Requires importing specific functions from the utils module.

```python
from utils.render import render
from utils.pose import viz_pose
from utils.serialization import ser_to_ply

render(img, ver_lst, tddfa.tri, wfp='3d.jpg')
viz_pose(img, param_lst, ver_lst, wfp='pose.jpg')
ser_to_ply(ver_lst, tddfa.tri, img.shape[0], 'mesh.ply')
```

--------------------------------

### ONNX Inference for Face Detection and Alignment

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Utilizes ONNX versions of FaceBoxes and TDDFA for faster inference. The API is consistent with the PyTorch version. Ensure ONNX runtime is installed and model checkpoints are present.

```python
from FaceBoxes.FaceBoxes_ONNX import FaceBoxes_ONNX
from TDDFA_ONNX import TDDFA_ONNX

detector = FaceBoxes_ONNX()
tddfa = TDDFA_ONNX(checkpoint_fp='weights/mb1_120x120.pth')

# Same API, 4-5× faster
boxes = detector(img)
param_lst, roi_box_lst = tddfa(img, boxes)
```

--------------------------------

### Run Demo Script with Overrides

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/configuration.md

Command-line arguments for running the demo script, allowing overrides for configuration files, input images, processing mode, output options, ONNX runtime, and display flags.

```bash
python demo.py \
  -c configs/mb1_120x120.yml \
        # Config file
  -f examples/inputs/image.jpg \
        # Input image
  -m cpu \
        # 'cpu' or 'gpu'
  -o 3d \
        # Output option
  --onnx                              # Use ONNX runtime
  --show_flag true                    # Display result
```

--------------------------------

### Run Smooth Video Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Run a demo on video with smooth transitions by looking ahead a specified number of frames (`n_next`). Uses ONNX runtime.

```python
python3 demo_video_smooth.py -f examples/inputs/videos/214.avi --onnx
```

--------------------------------

### Run Face Detection Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/FaceBoxes/readme.md

Executes the face detection demo using the FaceBoxes script.

```shell
python3 FaceBoxes.py
```

--------------------------------

### Initialize BFMModel

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/BFMModel.md

Instantiate the BFMModel by providing the path to the BFM pickle file and optionally specifying the dimensions for shape and expression components. This loads the mean shape, shape basis, expression basis, and triangle connectivity.

```python
from bfm import BFMModel

# Load BFM model
bfm = BFMModel(
    bfm_fp='configs/bfm_noneck_v3.pkl',
    shape_dim=40,
    exp_dim=10
)

print(f'Base shape vertices: {bfm.u.shape}')  # (209530,) — 69843 vertices × 3
print(f'Shape basis: {bfm.w_shp.shape}')      # (209530, 40)
print(f'Triangles: {bfm.tri.shape}')          # (number_faces, 3)
```

--------------------------------

### Loading Configuration from YAML

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/types.md

Demonstrates how to load a configuration dictionary from a YAML file using the PyYAML library and initialize a TDDFA model with the loaded configuration.

```python
import yaml

cfg = yaml.load(open('configs/mb1_120x120.yml'), Loader=yaml.SafeLoader)
tddfa = TDDFA(**cfg)
```

--------------------------------

### Run Demo on Still Image

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Execute the main demo script on a still image. The `--onnx` flag enables ONNX runtime for potentially faster inference. Use the `-o` flag to specify the desired output type.

```python
python3 demo.py -f examples/inputs/emma.jpg --onnx # -o [2d_sparse, 2d_dense, 3d, depth, pncc, pose, uv_tex, ply, obj]
```

--------------------------------

### List Available Model Architectures

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/conversion-utils.md

Shows how to import and list available model architectures from the 'models' package. This is useful for verifying compatibility when encountering 'Incompatible Architecture' errors.

```python
from models import *
# Available: MobileNet, MobileNet_V3, ResNet
```

--------------------------------

### Build CPU Version of NMS (Alternative)

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/FaceBoxes/readme.md

An alternative script to build the CPU version of NMS.

```shell
sh ./build_cpu_nms.sh
```

--------------------------------

### Initialize and Use FaceBoxes with TDDFA

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/FaceBoxes.md

Demonstrates how to initialize FaceBoxes and TDDFA detectors and use them to detect faces and obtain bounding boxes for further processing.

```python
from FaceBoxes import FaceBoxes
from TDDFA import TDDFA
import cv2

detector = FaceBoxes()
tddfa = TDDFA(arch='MobileNet', checkpoint_fp='weights/mb1_120x120.pth')

img = cv2.imread('photo.jpg')
boxes = detector(img)  # Get bounding boxes

# Bounding boxes directly compatible with TDDFA
if len(boxes) > 0:
    param_lst, roi_box_lst = tddfa(img, boxes)
```

--------------------------------

### Run Smooth Video Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/README.md

Execute the smooth demo script for processing a video file. Use the --onnx flag for ONNX runtime.

```bash
python demo_video_smooth.py -f video.avi --onnx
```

--------------------------------

### Basic CMake Configuration

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/Sim3DR/tests/CMakeLists.txt

Sets the minimum CMake version, defines the target name, and initializes the project. Includes directories and compiler flags for C++11.

```cmake
cmake_minimum_required(VERSION 2.8)

set(TARGET test)
project(${TARGET})

#find_package( OpenCV REQUIRED )
#include_directories( ${OpenCV_INCLUDE_DIRS} )

#set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fPIC -O3")
include_directories(../lib)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC -std=c++11")
add_executable(${TARGET} test.cpp ../lib/rasterize_kernel.cpp io.cpp)
target_include_directories(${TARGET} PRIVATE ${PROJECT_SOURCE_DIR})
```

--------------------------------

### Build Render Library

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Compile the render.c file into a shared library (.so) for use in asset building. Ensure you are in the correct directory before running.

```shell
cd utils/asset
gcc -shared -Wall -O3 render.c -o render.so -fPIC
cd ../..
```

--------------------------------

### Build Project Script

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Execute the build script to compile project assets. This is a convenient way to build all necessary components.

```shell
sh ./build.sh
```

--------------------------------

### Load and Run ONNX Model with ONNX Runtime

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/conversion-utils.md

Demonstrates how to load a converted ONNX model using ONNX Runtime and perform inference. Ensure the ONNX model path is correct and the input data is prepared in the expected format.

```python
import onnxruntime as rt

# Create session
session = rt.InferenceSession('weights/mb1_120x120.onnx', None)

# Prepare input
import numpy as np
x = np.random.randn(1, 3, 120, 120).astype(np.float32)

# Run inference
inputs = {'input': x}
output = session.run(None, inputs)[0]
print(output.shape)  # (1, 62)
```

--------------------------------

### Select MobileNet_V3 Architecture

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/configuration.md

Use this snippet to configure the model to use the MobileNet_V3 architecture and specify the checkpoint file. Ensure the checkpoint is compatible with the chosen architecture.

```python
# Use MobileNet_V3
cfg['arch'] = 'MobileNet_V3'
cfg['checkpoint_fp'] = 'weights/mv3_120x120.pth'  # If available

tddfa = TDDFA(**cfg)
```

--------------------------------

### Run Single Image Demo

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/README.md

Execute the demo script for processing a single image. Use the --onnx flag for ONNX runtime.

```bash
python demo.py -f image.jpg -o 3d --onnx
```

--------------------------------

### Initialize Face Detector

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/overview.md

Instantiate the FaceBoxes detector. The detector takes an image and returns bounding boxes.

```python
from FaceBoxes import FaceBoxes
detector = FaceBoxes()
boxes = detector(img)  # Returns (N, 5) array [x1, y1, x2, y2, conf]
```

--------------------------------

### mkdir

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/io-and-data.md

Creates a directory at the specified path. It supports recursive creation of parent directories and does not raise an error if the directory already exists.

```APIDOC
## Function: mkdir

### Description
Create directory if it doesn't exist (recursive, no error if exists).

### Parameters
#### Path Parameters
- **d** (str) - Required - Directory path

### Request Example
```python
from utils.io import mkdir

mkdir('results/output/nested')  # Creates all intermediate directories
```
```

--------------------------------

### Create Directory Recursively

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/io-and-data.md

Creates a directory, including any necessary parent directories, without raising an error if the directory already exists. Use this to ensure output paths are available.

```python
from utils.io import mkdir

mkdir('results/output/nested')  # Creates all intermediate directories
```

--------------------------------

### Run Demo on Video

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Process a video file using the demo script. The `--onnx` flag is used for ONNX runtime.

```python
python3 demo_video.py -f examples/inputs/videos/214.avi --onnx
```

--------------------------------

### Initialize BFM Model Access

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/overview.md

Instantiate the BFMModel for accessing the 3D Morphable Model. Requires a configuration file and dimensions for shape and expression.

```python
from bfm import BFMModel
bfm = BFMModel('configs/bfm_noneck_v3.pkl', shape_dim=40, exp_dim=10)
# Access: bfm.u (mean shape), bfm.w_shp, bfm.w_exp, bfm.tri
```

--------------------------------

### Parameter Decomposition and Transformation

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/utility-functions.md

Shows how to parse parameters and reconstruct 3D points, then transform them to image space. Requires a BFM model and specific utility functions.

```python
from utils.tddfa_util import _parse_param, similar_transform

R, offset, alpha_shp, alpha_exp = _parse_param(param)

# Reconstruct vertices
pts3d = R @ (bfm.u + bfm.w_shp @ alpha_shp + bfm.w_exp @ alpha_exp).reshape(3, -1, order='F') + offset

# Transform to image space
pts_image = similar_transform(pts3d, roi_box, size=120)
```

--------------------------------

### Serialization Patterns

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/io-and-data.md

Demonstrates patterns for serializing face data to PLY files, either as single files per face or a single concatenated file for multiple faces. Also shows command-line output naming conventions.

```python
# Single face -> suffix with index
ser_to_ply(ver_lst, tri, height, 'face.ply')
# Creates: face_1.ply, face_2.ply, ...

# Multiple faces -> single file
ser_to_ply(ver_lst, tri, height, 'faces.ply')
# Creates: faces.ply (concatenated)
```

```bash
# Named results with visualization type
demo.py -f input.jpg -o 3d
# Creates: results/input_3d.jpg
```

--------------------------------

### Initialize TDDFA_ONNX and Perform Face Alignment

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/TDDFA_ONNX.md

Demonstrates how to initialize the TDDFA_ONNX class with a specified checkpoint and ONNX model file, and then use it to predict 3DMM parameters and ROI boxes from an input image.

```python
import cv2
from FaceBoxes.FaceBoxes_ONNX import FaceBoxes_ONNX
from TDDFA_ONNX import TDDFA_ONNX

# Initialize ONNX version
face_boxes = FaceBoxes_ONNX()
tddfa = TDDFA_ONNX(
    checkpoint_fp='weights/mb1_120x120.pth',
    onnx_fp='weights/mb1_120x120.onnx'
)

# Same usage as TDDFA
img = cv2.imread('face.jpg')
boxes = face_boxes(img)
param_lst, roi_box_lst = tddfa(img, boxes)
```

--------------------------------

### Image and Landmark Utilities

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Provides functions for image cropping, ROI parsing, landmark drawing, and hypotenuse calculation.

```python
from utils.functions import (
    crop_img,
    parse_roi_box_from_bbox,
    parse_roi_box_from_landmark,
    calc_hypotenuse,
    get_suffix,
    draw_landmarks,
    cv_draw_landmark,
    plot_image
)

roi_box = parse_roi_box_from_bbox(bbox)
cropped = crop_img(img, roi_box)
marked = cv_draw_landmark(img, landmarks)
```

--------------------------------

### BFMModel Constructor

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/BFMModel.md

Initializes the BFMModel by loading the Basel Face Model from a specified file path and configuring the dimensions for shape and expression components.

```APIDOC
## Constructor: BFMModel

### Description
Loads and provides access to the Basel Face Model, including shape basis, expression basis, and face topology.

### Signature
```python
def __init__(self, bfm_fp: str, shape_dim: int = 40, exp_dim: int = 10)
```

### Parameters
#### Parameters
- **bfm_fp** (str) - Required - Path to BFM pickle file (e.g., 'configs/bfm_noneck_v3.pkl')
- **shape_dim** (int) - Optional - Default: 40 - Number of shape PCA components to use (max 100 in BFM)
- **exp_dim** (int) - Optional - Default: 10 - Number of expression PCA components (max 29 in BFM)

### Example
```python
from bfm import BFMModel

# Load BFM model
bfm = BFMModel(
    bfm_fp='configs/bfm_noneck_v3.pkl',
    shape_dim=40,
    exp_dim=10
)

print(f'Base shape vertices: {bfm.u.shape}')  # (209530,) — 69843 vertices × 3
print(f'Shape basis: {bfm.w_shp.shape}')      # (209530, 40)
print(f'Triangles: {bfm.tri.shape}')          # (number_faces, 3)
```
```

--------------------------------

### Data Input/Output Utilities

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Offers functions for loading and dumping data in various formats like pickle and numpy, and managing directories.

```python
from utils.io import (
    _load,
    _dump,
    mkdir,
    _get_suffix,
    _load_tensor,
    _load_gpu,
    _numpy_to_tensor,
    _tensor_to_numpy,
    _numpy_to_cuda,
    _cuda_to_tensor,
    _cuda_to_numpy
)

data = _load('file.pkl')
_dump('output.npy', array)
```

--------------------------------

### Enable OpenMP on macOS with KMP_DUPLICATE_LIB_OK

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/configuration.md

Set the KMP_DUPLICATE_LIB_OK environment variable to 'True' on macOS to ensure proper OpenMP operation. This is often required to avoid issues with duplicate libraries.

```python
import os
os.environ['KMP_DUPLICATE_LIB_OK'] = 'True'
```

--------------------------------

### Image Processing Pipeline

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/utility-functions.md

Demonstrates a common image processing pipeline involving cropping and resizing. Requires OpenCV and specific utility functions.

```python
from utils.functions import crop_img, parse_roi_box_from_bbox
import cv2

img = cv2.imread('face.jpg')
bbox = [100, 50, 300, 200, 0.95]

roi_box = parse_roi_box_from_bbox(bbox)
cropped = crop_img(img, roi_box)
resized = cv2.resize(cropped, (120, 120))
```

--------------------------------

### Model and Parameter Utilities

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Includes functions for loading models, parsing parameters, and performing similarity transformations.

```python
from utils.tddfa_util import (
    load_model,
    _parse_param,
    similar_transform,
    str2bool,
    ToTensorGjz,
    NormalizeGjz,
    _to_ctype
)

R, offset, alpha_shp, alpha_exp = _parse_param(param)
pts_image = similar_transform(pts3d, roi_box, size=120)
model = load_model(model, checkpoint_fp)
```

--------------------------------

### Basic Pipeline with PyTorch

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Performs face detection and 3D alignment using PyTorch models. Requires importing FaceBoxes and TDDFA. Ensure model checkpoints are available.

```python
import cv2
from FaceBoxes import FaceBoxes
from TDDFA import TDDFA

detector = FaceBoxes()
tddfa = TDDFA(arch='MobileNet', checkpoint_fp='weights/mb1_120x120.pth')

img = cv2.imread('photo.jpg')
boxes = detector(img)
param_lst, roi_box_lst = tddfa(img, boxes)
ver_lst = tddfa.recon_vers(param_lst, roi_box_lst, dense_flag=True)
```

--------------------------------

### Build CPU Version of NMS

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/FaceBoxes/readme.md

Builds the CPU version of NMS using the provided build script. Navigate to the 'utils' directory before running.

```shell
cd utils
python3 build.py build_ext --inplace
```

--------------------------------

### Render Image with Utilities

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Renders an image using either the Python or faster C++ backend. Requires 'img', 'ver_lst', 'tri', and optional 'alpha' for transparency.

```python
from utils.render import render
# or for faster C++ backend:
from utils.render_ctypes import render

render(img, ver_lst, tri, alpha=0.6, wfp='3d.jpg')
```

--------------------------------

### Check BFM Version and Parameter Dimension

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/io-and-data.md

Loads BFM and parameter configuration files to check their format and dimension compatibility. Assumes `_load` function is available.

```python
bfm = _load('configs/bfm_noneck_v3.pkl')
if bfm['u'].shape[0] == 209530:
    print("Valid BFM format")

param_stats = _load('configs/param_mean_std_62d_120x120.pkl')
if param_stats['mean'].shape[0] == 62:
    print("Standard 62-dim format")
```

--------------------------------

### CPU Inference with TDDFA

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/configuration.md

Initializes the TDDFA model for CPU inference by loading configuration from a YAML file. GPU mode defaults to False.

```python
from TDDFA import TDDFA
import yaml

cfg = yaml.load(open('configs/mb1_120x120.yml'), Loader=yaml.SafeLoader)
tddfa = TDDFA(**cfg)  # gpu_mode defaults to False
```

--------------------------------

### ONNX Conversion Process

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/conversion-utils.md

This code block illustrates the internal steps for converting a PyTorch model to ONNX. It covers model creation, checkpoint loading, dummy input generation, and the ONNX export process.

```python
# 1. Create PyTorch model
model = getattr(models, arch)(
    num_classes=num_params,
    widen_factor=widen_factor,
    size=size,
    mode=mode
)

# 2. Load checkpoint
model = load_model(model, checkpoint_fp)
model.eval()

# 3. Create dummy input
batch_size = 1
dummy_input = torch.randn(batch_size, 3, size, size)

# 4. Export to ONNX
wfp = checkpoint_fp.replace('.pth', '.onnx')
torch.onnx.export(
    model,
    (dummy_input, ),
    wfp,
    input_names=['input'],
    output_names=['output'],
    do_constant_folding=True
)
```

--------------------------------

### Initialize BFMModel for Morphable Model Operations

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Instantiate the BFMModel class to load and access the 3D Morphable Model data. Configure paths to BFM data and specify dimensionality for shape and expression.

```python
from bfm import BFMModel

bfm = BFMModel(
    bfm_fp='configs/bfm_noneck_v3.pkl',
    shape_dim=40,
    exp_dim=10
)

# Attributes
bfm.u           # Mean shape (209530,)
bfm.w_shp       # Shape basis (209530, 40)
bfm.w_exp       # Expression basis (209530, 10)
bfm.tri         # Face triangles
bfm.keypoints   # Landmark indices
bfm.u_base      # Sparse shape
bfm.w_shp_base  # Sparse shape basis
bfm.w_exp_base  # Sparse expression basis
```

--------------------------------

### Load Parameter Statistics

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/io-and-data.md

Load parameter statistics (mean and standard deviation) from a .pkl file using `_load`. These are used for denormalizing parameters.

```python
from utils.io import _load

stats = _load('configs/param_mean_std_62d_120x120.pkl')

# Contents
param_mean = stats['mean']    # Shape: (62,), dtype: float32
param_std = stats['std']      # Shape: (62,), dtype: float32

# Usage in denormalization
param_denorm = param_norm * param_std + param_mean
```

--------------------------------

### Load Large BFM Model

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/io-and-data.md

Demonstrates loading a large BFM model using `_load` and accessing its components. Includes memory estimation and suggestions for memory reduction.

```python
import numpy as np
from utils.io import _load

# Load large BFM (340MB)
bfm = _load('configs/bfm_noneck_v3.pkl')

# Use selective components only
u = bfm['u']           # 209K values
w_shp = bfm['w_shp']   # 209K × 40
w_exp = bfm['w_exp']   # 209K × 29

# Memory estimate: ~500MB after loading

# To reduce memory, load only sparse basis
# Or use a smaller BFM variant if available
```

--------------------------------

### Initialize MobileNet Model

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Instantiates the MobileNet model for image processing. Specify parameters like widen_factor, num_classes, prelu, and input_channel.

```python
from models import MobileNet, MobileNet_V3, ResNet

# Create model
model = MobileNet(
    widen_factor=1.0,
    num_classes=62,
    prelu=False,
    input_channel=3
)
```

--------------------------------

### Build Cython Modules

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/readme.md

Build the cython versions of NMS, Sim3DR, and the faster mesh render. These are necessary for optimal performance.

```shell
cd FaceBoxes
sh ./build_cpu_nms.sh
cd ..

cd Sim3DR
sh ./build_sim3dr.sh
cd ..
```

--------------------------------

### Use Different Architecture (ResNet)

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/overview.md

Configure the TDDFA model to use the ResNet architecture and specify the checkpoint file.

```python
cfg['arch'] = 'ResNet'
cfg['checkpoint_fp'] = 'weights/resnet_120x120.pth'  # Must exist
tddfa = TDDFA(**cfg)
```

--------------------------------

### Export BFMModel_ONNX to ONNX

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/conversion-utils.md

This process demonstrates how to export a PyTorch BFMModel_ONNX to the ONNX format. It involves creating the model, setting it to evaluation mode, defining dummy inputs, and using torch.onnx.export.

```python
# 1. Create PyTorch model
bfm_decoder = BFMModel_ONNX(bfm_fp, shape_dim, exp_dim)
bfm_decoder.eval()

# 2. Create dummy inputs
R = torch.randn(3, 3)
offset = torch.randn(3, 1)
alpha_shp = torch.randn(shape_dim, 1)
alpha_exp = torch.randn(exp_dim, 1)

# 3. Export to ONNX
torch.onnx.export(
    bfm_decoder,
    (R, offset, alpha_shp, alpha_exp),
    bfm_onnx_fp,
    input_names=['R', 'offset', 'alpha_shp', 'alpha_exp'],
    output_names=['output'],
    dynamic_axes={
        'alpha_shp': [0],
        'alpha_exp': [0]
    },
    do_constant_folding=True
)
```

--------------------------------

### Initialize TDDFA Model

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/models.md

Instantiates the TDDFA model, automatically loading architecture and weights from the specified configuration. This is the primary way to set up TDDFA for use.

```python
from TDDFA import TDDFA

# Automatically loads architecture and weights from config
tddfa = TDDFA(
    arch='MobileNet',
    checkpoint_fp='weights/mb1_120x120.pth',
    num_params=62,
    widen_factor=1,
    size=120
)
```

--------------------------------

### Load Numpy or Pickle File

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/utility-functions.md

Use this function to load data from either a .npy or .pkl file. Ensure the file path is correct.

```python
def _load(fp: str) -> Any:
    pass
```

--------------------------------

### Import necessary libraries

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/demo.ipynb

Imports required libraries for face detection, 3D face reconstruction, and visualization. Ensure FaceBoxes and TDDFA are built successfully before running.

```python
# before import, make sure FaceBoxes and Sim3DR are built successfully, e.g., 
# sh build.sh

import cv2
import yaml

from FaceBoxes import FaceBoxes
from TDDFA import TDDFA
from utils.functions import draw_landmarks
from utils.render import render
from utils.depth import depth

import matplotlib.pyplot as plt
```

--------------------------------

### Initialize FaceBoxes Detector

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Instantiate the FaceBoxes class for face detection. The detector returns bounding boxes for detected faces.

```python
from FaceBoxes import FaceBoxes

detector = FaceBoxes(timer_flag=False)

# Method
boxes = detector(img)  # Returns (N, 5) array

# Utility function
from FaceBoxes.FaceBoxes import viz_bbox
viz_bbox(img, boxes, wfp='output.jpg')
```

--------------------------------

### Compact Model for Mobile Inference

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/configuration.md

Initializes a compact TDDFA_ONNX model suitable for mobile devices, using a specific configuration file.

```python
from TDDFA_ONNX import TDDFA_ONNX
import yaml

cfg = yaml.load(open('configs/mb05_120x120.yml'), Loader=yaml.SafeLoader)
tddfa = TDDFA_ONNX(**cfg)  # 0.5x width, 0.5ms inference
```

--------------------------------

### Build Sim3DR Extension

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/Sim3DR/readme.md

Builds the Cython extension modules for Sim3DR in-place.

```shell
python3 setup.py build_ext --inplace
```

--------------------------------

### Main Classes and Models Import

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/exports.md

Imports essential classes for TDDFA, ONNX versions, FaceBoxes, and BFM models, along with neural network model architectures.

```python
# Main classes
from TDDFA import TDDFA
from TDDFA_ONNX import TDDFA_ONNX
from FaceBoxes import FaceBoxes
from FaceBoxes.FaceBoxes_ONNX import FaceBoxes_ONNX
from bfm import BFMModel

# Models
from models import MobileNet, MobileNet_V3, ResNet

# Visualization
from utils.pose import calc_pose, viz_pose, matrix2angle, P2sRt
from utils.render import render
from utils.render_ctypes import render
from utils.depth import depth
from utils.pncc import pncc
from utils.uv import uv_tex

# Serialization
from utils.serialization import ser_to_ply, ser_to_obj

# Utilities
from utils.functions import (
    crop_img, parse_roi_box_from_bbox, parse_roi_box_from_landmark,
    draw_landmarks, cv_draw_landmark
)
from utils.tddfa_util import _parse_param, similar_transform, load_model
from utils.io import _load, _dump

# Conversion
from utils.onnx import convert_to_onnx
from bfm.bfm_onnx import convert_bfm_to_onnx
from FaceBoxes.onnx import convert_to_onnx as convert_faceboxes_to_onnx
```

--------------------------------

### Face Detection Implementation Details

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/FaceBoxes.md

Internal implementation details for face detection, including preprocessing, normalization, forward pass, decoding, and Non-Maximum Suppression (NMS).

```python
# Preprocessing
img = np.float32(img_)
if scale_flag:
    # Auto-scale to fit within 720×1080
    scale = HEIGHT / h if h > HEIGHT else 1
    if w * scale > WIDTH:
        scale *= WIDTH / (w * scale)
    img = cv2.resize(img, (w*scale, h*scale))

# Normalization and conversion
scale_bbox = torch.Tensor([W, H, W, H])
img -= (104, 117, 123)
img = torch.from_numpy(img.transpose(2,0,1)).unsqueeze(0)

# Forward pass
loc, conf = self.net(img)

# Decode and NMS
priors = PriorBox(image_size=(im_height, im_width))
boxes = decode(loc, priors.data, cfg['variance'])
boxes = nms(boxes, conf, nms_threshold)

# Unscale to original resolution if needed
boxes = boxes / scale
```

--------------------------------

### Visualize Face Reconstruction Outputs

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/README.md

Renders the 3D mesh, visualizes head pose, and generates a depth map from the reconstructed face vertices. Requires optional Matplotlib for visualization.

```python
from utils.render import render
from utils.pose import viz_pose
from utils.depth import depth

render(img, ver_lst, tddfa.tri, alpha=0.6, wfp='3d.jpg')
viz_pose(img, param_lst, ver_lst, wfp='pose.jpg')
depth(img, ver_lst, tddfa.tri, wfp='depth.jpg')
```

--------------------------------

### Initialize ONNX 3D Face Alignment

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/overview.md

Instantiate the TDDFA_ONNX class for 3D face alignment using ONNX. Requires specifying the checkpoint path.

```python
from TDDFA_ONNX import TDDFA_ONNX
tddfa = TDDFA_ONNX(checkpoint_fp='weights/mb1_120x120.pth')
param_lst, roi_box_lst = tddfa(img, boxes)
ver_lst = tddfa.recon_vers(param_lst, roi_box_lst, dense_flag=True)
```

--------------------------------

### Load and display input image

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/demo.ipynb

Loads an image from the specified file path using OpenCV and displays it using Matplotlib.

```python
# given an image path
img_fp = 'examples/inputs/emma.jpg'
img = cv2.imread(img_fp)
plt.imshow(img[..., ::-1])
```

--------------------------------

### _load

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/io-and-data.md

Loads data from a file, automatically detecting whether it's a numpy (.npy) or pickle (.pkl) file. It returns a numpy array for .npy files and a Python object for .pkl files.

```APIDOC
## Function: _load

### Description
Load numpy or pickle file with automatic format detection.

### Parameters
#### Path Parameters
- **fp** (str) - Required - File path (.npy or .pkl extension)

### Returns
Loaded data:
- `.npy` files return numpy array
- `.pkl` files return Python object (dict, array, etc.)

### Request Example
```python
from utils.io import _load

# Load numpy array
arr = _load('data/coefficients.npy')
print(arr.shape)

# Load pickle (BFM model)
bfm = _load('configs/bfm_noneck_v3.pkl')
print(bfm.keys())

# Load pickle (parameters)
param_stats = _load('configs/param_mean_std_62d_120x120.pkl')
print(param_stats['mean'].shape)
```
```

--------------------------------

### Load YAML Configuration for TDDFA

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/configuration.md

Loads configuration from a YAML file and initializes the TDDFA model. Ensure the config file path is correct.

```python
import yaml
from TDDFA import TDDFA

# Load from config file
cfg = yaml.load(open('configs/mb1_120x120.yml'), Loader=yaml.SafeLoader)

# Initialize with config
tddfa = TDDFA(**cfg)
```

--------------------------------

### Reconstruct 3D Face Vertices (Dense)

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/TDDFA_ONNX.md

Illustrates the ONNX-based dense reconstruction of 3D face vertices using the BFM ONNX session.

```python
inp_dct = {
    'R': R, 'offset': offset, 
    'alpha_shp': alpha_shp, 'alpha_exp': alpha_exp
}
pts3d = self.bfm_session.run(None, inp_dct)[0]
```

--------------------------------

### Initialize FaceBoxes_ONNX Detector

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/FaceBoxes_ONNX.md

Instantiate the FaceBoxes_ONNX detector. The constructor automatically checks for and converts the PyTorch model to ONNX format if the ONNX model file does not exist. It initializes the ONNX Runtime inference session using CPU providers by default.

```python
from FaceBoxes.FaceBoxes_ONNX import FaceBoxes_ONNX
import cv2

# Auto-converts .pth to .onnx if needed
detector = FaceBoxes_ONNX()

img = cv2.imread('image.jpg')
boxes = detector(img)
print(f'Found {len(boxes)} faces')
```

--------------------------------

### 3DDFA_V2 Project File Structure

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/overview.md

Overview of the directory and file organization within the 3DDFA_V2 project.

```tree
3DDFA_V2/
├── TDDFA.py                    # Main PyTorch class
├── TDDFA_ONNX.py               # ONNX variant
├── FaceBoxes/
│   ├── FaceBoxes.py            # PyTorch detector
│   ├── FaceBoxes_ONNX.py       # ONNX detector
│   ├── models/
│   │   └── faceboxes.py        # Network architecture
│   └── utils/
├── bfm/
│   ├── bfm.py                  # BFM model
│   └── bfm_onnx.py             # ONNX BFM
├── models/
│   ├── mobilenet_v1.py         # MobileNet architecture
│   ├── mobilenet_v3.py         # MobileNet v3
│   └── resnet.py               # ResNet
├── utils/
│   ├── functions.py            # Image processing
│   ├── tddfa_util.py           # Parameter utilities
│   ├── pose.py                 # Pose estimation
│   ├── render.py               # Mesh rendering
│   ├── depth.py                # Depth visualization
│   ├── pncc.py                 # PNCC rendering
│   ├── uv.py                   # UV texture mapping
│   ├── serialization.py        # PLY/OBJ export
│   ├── onnx.py                 # ONNX conversion
│   └── io.py                   # File I/O
├── configs/
│   ├── mb1_120x120.yml         # Config file
│   ├── bfm_noneck_v3.pkl       # BFM data
│   └── ...                     # Other data files
├── weights/
│   ├── mb1_120x120.pth         # Model weights
│   └── ...
└── examples/
    └── inputs/
```

--------------------------------

### Export 3D Face Model to PLY and OBJ

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/serialization-utils.md

This script demonstrates the full pipeline for detecting a face, reconstructing its 3D model, and exporting it to both PLY and OBJ formats using the provided utility functions. Ensure you have the necessary libraries and pre-trained models.

```python
import cv2
from FaceBoxes import FaceBoxes
from TDDFA import TDDFA
from utils.serialization import ser_to_ply, ser_to_obj

# Setup
detector = FaceBoxes()
tddfa = TDDFA(arch='MobileNet', checkpoint_fp='weights/mb1_120x120.pth')

# Process
img = cv2.imread('photo.jpg')
boxes = detector(img)
param_lst, roi_box_lst = tddfa(img, boxes)
ver_lst = tddfa.recon_vers(param_lst, roi_box_lst, dense_flag=True)

# Export
ser_to_ply(ver_lst, tddfa.tri, img.shape[0], 'output.ply')
ser_to_obj(img, ver_lst, tddfa.tri, img.shape[0], 'output.obj')
```

--------------------------------

### Initialize FaceBoxes Detector

Source: https://github.com/cleardusk/3ddfa_v2/blob/master/_autodocs/api-reference/FaceBoxes.md

Initializes the FaceBoxes detector. Set timer_flag to True to print timing information for forward pass and post-processing.

```python
from FaceBoxes import FaceBoxes
import cv2

# Initialize detector
face_detector = FaceBoxes(timer_flag=True)

# Load image
img = cv2.imread('image.jpg')

# Detect faces
boxes = face_detector(img)
print(f'Detected {len(boxes)} faces')
```