Landmarks and the Topology Lock

"The detector's only job is to point at the eyes in the photo. The moment it also decides what the eyes mean, you've lost the answer key."

478 Points, 468 Kept

MediaPipe's FaceLandmarker looks at a photo and returns 478 points: a 468-point mesh blanketing the face, plus 10 iris points for gaze. Loomis keeps the 468 mesh and drops the iris — the construction needs the face's structure, not where the eyes are pointing. Those 468 points are the entire bridge from raw pixels to geometry: they are the 2-D half of every correspondence the camera solve consumed two lessons ago.

The Topology Lock

Here is the invariant that makes those points usable. The 468 mesh landmarks match the canonical head model index for index: landmark 33 in the photo is the same anatomical spot as point 33 on canonical_face_model.obj. That one-to-one alignment — the topology lock — is what lets solvePnP pair a pixel with a known 3-D point. It is also fragile in the quietest possible way: change the indexing on either side without changing the other and every correspondence still looks valid while pointing at the wrong anatomy. No crash, no error — just a fit that is subtly, permanently wrong. The two sides must move together or not at all.

Read the Live Docs, Not Your Memory

A concrete trap lives right here. MediaPipe's older mp.solutions.face_mesh API — the one most training-data code imports — was removed upstream. The current library (0.10.x) exposes landmark detection through the tasks API instead. Code you or a model 'remember' writing will import a module that no longer exists and fail on the first line. This is the standing rule for every fast-moving dependency: the installed version is almost certainly newer than any training cutoff, so you read the live documentation and let the real API — not your recollection of it — write the import.

Detection Is Noisy; Geometry Is Not

Landmarks jitter frame to frame, drift on extreme angles, and go unreliable under occlusion. That is completely fine, because they are a proposal, not a verdict. The geometry that consumes them is exact and reproducible, and when the proposal is bad the reprojection error rises to say so. The whole architecture rests on keeping the noisy, learned part (find the points) rigidly separated from the exact, deterministic part (turn the points into a construction) — which is exactly the boundary the next two lessons make into law.

Code

Tasks-API detection, and the topology-lock assertion·python

# MediaPipe 0.10.x TASKS API. The legacy mp.solutions.face_mesh was REMOVED
# upstream -- training-data code that imports it will not run. Read live docs.
from mediapipe.tasks.python import vision

landmarker = vision.FaceLandmarker.create_from_options(options)
result = landmarker.detect(mp_image)
pts = result.face_landmarks[0]           # 478 points: 468 mesh + 10 iris

mesh = pts[:468]                         # keep the mesh, drop the 10 iris points

# TOPOLOGY LOCK: mesh[i] corresponds to CANONICAL_HEAD[i], index-for-index.
# This IS the 2D-to-3D correspondence solvePnP consumed two lessons back.
assert len(mesh) == len(CANONICAL_HEAD)  # 468 == 468, or every fit is a silent lie

Exercise

Find a place in your own code where two arrays or lists are matched by position — names and scores, ids and rows, inputs and labels. Ask: what silently breaks if one side is reordered, filtered, or re-indexed without the other? Add an assertion that would catch the mismatch loudly. That's the topology lock, applied to your own correspondences.

Hint

Position-matched collections are everywhere and they fail quietly, because a mismatch produces valid-looking-but-wrong results rather than a crash. The defense is the same one Loomis uses: assert the lengths (and ideally the identities) line up, and keep the index map in one authoritative place so the two sides can't drift independently.