Face Anything — Gradio demo

4D face reconstruction and tracking from any image sequence — upload up to 40 images or a video (its first 40 frames are used) — in a single feed-forward pass. The model jointly predicts depth and canonical facial coordinates, from which the demo derives:

• Canonical 2D video — per-frame canonical facial-coordinate map
• Depth 2D video — per-frame depth map (JET)
• Normals 2D video — per-frame surface normals (from depth)
• 3D point cloud with colorful tracks — viewable/orbitable in the 3D viewer (rendered as a .glb on a white background), with a frame slider to scrub the sequence and a downloadable .zip containing both the track-colored point clouds (tracks/) and the plain colored point clouds (points/)
• (bonus) a 2D point-track overlay video

Reconstruction always uses the model's predicted camera poses (a multi-view consistent world frame).

Two inference modes (the repo's --process-mode):

• Joint (all-at-once) — all frames processed together → more 3D-consistent.
• One-by-one — each frame processed independently → more surface detail and lower memory (pairs well with a higher processing resolution).

Exposed hyperparameters (defaults match the published run_inference.py): processing resolution, background removal (Robust Video Matting), depth-confidence cut, number/blur/threshold of point tracks, output FPS, and a frame cap.

Deploying this Space

The Gradio code (app.py) and the model source (src/faceanything, src/depth_anything_3) are included here. To make the Space runnable you still need the checkpoint (~15 GB), which is not committed.

Checkpoint storage

Don't commit 15 GB into the Space repo. Put the checkpoint in a Hugging Face model repo and expose it to the Space with a mounted volume (HF's current mechanism for persisting data — the old fixed persistent-storage disk has been superseded by volumes / storage buckets).

Recommended — mount the model repo as a read-only volume. The checkpoint then appears as a plain local file; no download code, nothing to re-fetch on cold start, and zero ZeroGPU seconds spent moving it.

# one-time: upload the checkpoint into your model repo
hf upload UmutKocasari/FaceAnything /path/to/checkpoint.pt checkpoint.pt --repo-type=model

# mount that model repo into the Space at /models (read-only) — restarts the Space
hf spaces volumes set UmutKocasari/FaceAnything \
    -v hf://models/UmutKocasari/FaceAnything:/models

Then set one Space variable (Settings → Variables and secrets):

FACEANYTHING_CHECKPOINT = /models/checkpoint.pt

Add the HF_TOKEN secret too if the model repo is private. Verify the mount with hf spaces volumes ls UmutKocasari/FaceAnything. (Models/datasets are always read-only mounts; only storage buckets can be mounted read-write.)

Keep FACEANYTHING_CHECKPOINT_REPO set as well. On a long-running container the mount has returned zero-filled bytes for the checkpoint, which made every run fail with invalid load key, '\x00'. The app now checks the file before loading (zip header and end record) and retries. If the mount still serves bad data, it downloads a local copy from FACEANYTHING_CHECKPOINT_REPO once, on the CPU node, and uses that copy until the container restarts.

Alternative — download at startup. Skip the volume and set FACEANYTHING_CHECKPOINT_REPO = UmutKocasari/FaceAnything; the app calls hf_hub_download on the CPU node at startup. It re-downloads on each cold start unless you back the HF cache with a read-write Storage Bucket volume and point HF_HOME at it:

hf buckets create UmutKocasari/faceanything-cache
hf spaces volumes set UmutKocasari/FaceAnything \
    -v hf://buckets/UmutKocasari/faceanything-cache:/data
# then set Space variable:  HF_HOME = /data/.huggingface

Last resort: commit the weights via Git LFS at checkpoints/checkpoint.pt (bloats the Space repo and slows every clone).

Hardware

This needs a CUDA GPU. On ZeroGPU, @spaces.GPU is used automatically; raise FACEANYTHING_GPU_DURATION (seconds, default 180) if long clips time out. On a dedicated GPU Space, spaces degrades to a no-op.

The DA3 backbone config/architecture is pulled from the public model depth-anything/DA3-GIANT-1.1 on first run (its weights are then overwritten by the checkpoint); it lands in the same HF_HOME cache.

Environment variables

Running locally

export FACEANYTHING_ROOT=/path/to/FaceAnything        # source checkout (has src/, checkpoints/)
pip install -r requirements.txt
python app.py

Project page: https://kocasariumut.github.io/FaceAnything/ · Code: https://github.com/kocasariumut/FaceAnything