README.md

metadata

title: GNM Head — Interactive 3D Face Model
emoji: 🧬
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.20.0
app_file: app.py
short_description: Reactive 3D demo of Google's GNM parametric head model
python_version: '3.12'
startup_duration_timeout: 30m
license: apache-2.0

GNM Head — Interactive 3D Face Model

A reactive Gradio demo of GNM (Generative aNthropometric Model), Google's state-of-the-art parametric 3D statistical model of the human head. This Space replicates the official interactive slider demo from gnm/shape/demos/gnm_head_demo.ipynb: move any slider and the 3D head mesh regenerates live.

Controls

Control labels are named to match exactly what each one changes in the model:

• Identity — first 10 components of the linear identity basis, i.e. overall head shape.
• Expression — selected blendshape components per region, named as in the upstream gnm_head_demo.ipynb: left eye, right eye, mouth (the lower_face_region_* components the notebook exposes as its mouth group), tongue, and pupil dilation. The Expression tab also has a keyword-expression control (mirroring the reference semantic sampling demo): pick a named expression (happy, surprise, wink, smile, ...) — or several to blend — set the strength, and hit Apply to drive the expression sliders toward that expression via GNM's semantic CVAE sampler. It only sets the slider values, so you can keep tweaking each slider by hand afterwards.
• Pose — neck and head rotations (pitch / yaw / roll, in degrees), plus gaze (eyeball pitch / yaw with a cross-eye vergence control).
• Translation — global position of the whole head (X left/right, Y up/down, Z forward/back).

The 3D view opens front-facing and keeps your current camera position and orientation as you move the sliders. The viewer is a small custom Three.js component with a persistent scene: each slider change only streams the new vertex positions, which are written straight into the existing geometry buffer, so the mesh morphs in place — it is never reloaded/remounted, so there is no camera reset and no flicker.

The model is pure NumPy (a few matrix multiplies, ~40 ms per evaluation), so the Space runs on cpu-basic with no GPU required.

Direct manipulation

You can also grab the 3D head directly instead of only moving sliders — hover any region to see what it does (the head is colour-coded by control region):

• Eye — drag ↕ to open / close that eye, ↔ to glance (aim the eyes).
• Mouth — drag the centre / chin down to open the jaw; drag a lip corner outward to smile / stretch.
• Tongue — drag down to stick it out.
• Skull / forehead — drag to turn & nod the head; gaze aims when you grab an eyeball.
• Ear — drag in / out (drives Head shape 8); Cheek — drag to stretch the face (drives Head shape 7).
• Alt + drag free-sculpts the surface under the cursor with a soft falloff brush (nose, brow, jawline). These are geometric offsets on top of the model — a ↺ Reset shaping button clears them.
• Shift + drag repositions the head, right-drag (or drag empty space) orbits the camera, scroll zooms.

Each region drives the very same slider(s) — hovering one glows the matching control and its tab — so the sliders and the head stay in sync. Every gesture runs through the same reactive pipeline as the sliders; slider-driving drags are throttled and run off the queue so the mesh tracks the cursor in real time.

Credits

Model and reference demo: google/GNM, Apache 2.0. This Space vendors the upstream gnm.shape NumPy backend and its model data (gnm_head.npz).