No description
  • CSS 29%
  • JavaScript 22.5%
  • Python 20.3%
  • HTML 18.7%
  • Shell 5.4%
  • Other 4.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
yuuhikaze cdb57649f7 feat: robust head SDF, masked TSDF mesher and face-fitted contact pads
- tsdf_mesh.py: masked TSDF via Open3D VoxelBlockGrid (legacy volume returned
  empty meshes), cameras built without loading images
- measure.py: scale from length + circumference, face measures as a check,
  saves the head<->world transform
- mask_fit.py: visual-hull + normal signed distance, mirrored outside the face
  core, skin 3 mm / beanie 0 mm clearance, fixed-region snug term, exact slide
- add_pads.py: brow, glabella and cheekbone pads at exactly the clearance,
  fused into the body STL with manifold3d; pipeline stage 'pads'
- render_fit.py: discrete clearance bands

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q7bU4KvubkzyRQ1Vns53v9
2026-10-28 02:41:18 -05:00
.tern docs: describe the generic method and drop setup-specific notes 2026-10-28 00:08:29 -05:00
config feat: robust head SDF, masked TSDF mesher and face-fitted contact pads 2026-10-28 02:41:18 -05:00
container feat: add phone-video head scan and Tengu mask fitting pipeline 2026-10-28 00:04:28 -05:00
docs fix: correct work-root paths, frontal-only landmarks, eye-midpoint alignment 2026-10-28 00:31:28 -05:00
docs-html fix: correct work-root paths, frontal-only landmarks, eye-midpoint alignment 2026-10-28 00:31:28 -05:00
print/presets feat: add phone-video head scan and Tengu mask fitting pipeline 2026-10-28 00:04:28 -05:00
scripts feat: robust head SDF, masked TSDF mesher and face-fitted contact pads 2026-10-28 02:41:18 -05:00
.gitignore fix: track tern template data by anchoring ignore patterns to the root 2026-10-28 00:04:33 -05:00
flake.lock feat: add phone-video head scan and Tengu mask fitting pipeline 2026-10-28 00:04:28 -05:00
flake.nix feat: add phone-video head scan and Tengu mask fitting pipeline 2026-10-28 00:04:28 -05:00
README.md docs: describe the generic method and drop setup-specific notes 2026-10-28 00:08:29 -05:00

mask-fit

The pipeline turns a phone video of a head turning around into a millimetre-accurate 3D model. It then resizes a 3D-printable prop mask so that it sits on that face with a chosen gap. Its outputs are the head model, pictures showing the fit, and print jobs grouped by filament colour.

It works like this:

  1. The phone stays still while the person turns slowly in place under even light.
  2. A segmentation model cuts the head out of every video frame.
  3. Photogrammetry works out where the camera was for each frame.
  4. A surface-reconstruction model builds the head's shape from all the frames together.
  5. A few tape measurements give the model its real-world size, and the thickness of any cap or beanie is estimated and subtracted.
  6. The mask model is resized and positioned so that, at its closest point, it sits a set distance from the skin.

Documentation

The documentation index links every guide:

  • Capture — how to record the video and take the tape measurements
  • Pipeline — what happens to the video, step by step
  • Stack — the tools and AI models used, and why each one was chosen
  • Fitting — real-world scale, beanie compensation and how the mask is sized
  • Printing — colour batches and sending the jobs to the printer
  • Development — running the pipeline, the GPU machine and building these docs

Repository layout

scripts/          Pipeline stages (Python + shell) and the run/remote wrappers
container/        Containerfile for the GPU image (PyTorch + CUDA + OpenGL libraries)
config/head.json  Tape measurements of the bare head and the wanted face clearance
print/presets/    OrcaSlicer presets (printer, process, filament)
docs/             Documentation source (Markdown); docs/img holds images
docs-html/        Compiled HTML (generated by tern)
data/             Inputs, git-ignored: videos/, mask/ (the mask model), models/ (face detector)
work/, gcode/     Generated outputs, git-ignored

Quick start

These commands run the whole pipeline on the GPU machine, copy the results back, and slice the print jobs:

scripts/remote.sh image env      # once: build the container and the Python environment
scripts/remote.sh                # frames → masks → camera poses → surface → QC → scale → fit
scripts/remote.sh --pull
nix develop path:.#slice --command scripts/slice.sh

Documentation build

The documentation (this README and docs/) compiles to docs-html/ with:

nix develop path:. --command tern

Licensing

Mask models are usually purchased designs under their own license. They live in the git-ignored data/mask/ folder and are never committed or redistributed.