Hugging Face's logo

Lucasgitguy-co
/
forma3d-tiny

Image-to-3D
PyTorch
gaussian-splatting
research-prototype
mesh-proxy-supervision
Model card Files
xet
 Community
forma3d-tiny / COMMANDS.md
Lucasgitguy-co's picture
Lucasgitguy-co
Publish evaluated Forma3D-Tiny v0.2
e80b8d8 verified
preview code
|
Raw History Blame Contribute Delete
5.65 kB

Mac commands

Run these in macOS Terminal, from the extracted forma3d folder. Requires Apple Silicon and Python 3.11 (the setup script lets uv manage Python). If uv is not installed, run brew install uv first. Do not paste Hugging Face tokens into chat.

bash setup-mac.sh
source "$HOME/Library/Application Support/Forma3D/venv/bin/activate"
hf auth login
hf auth whoami

# Pin the original checkpoint so the run is reproducible.
hf download Lucasgitguy-co/image3d-student \
  examples/synthetic-smoke/synthetic-only.pt \
  --revision 1738cdfaf1bb940bf576a96d11b742ce014b9139 \
  --local-dir base

# 96 mesh assets, four canonical rendered views per object.
# Dataset files and original meshes stay on your machine.
python scripts/prepare_hf.py \
  --out data/forma3d-v1 --cache data/downloads \
  --scenario 64 --objaverse 32 --objaverse-shards 8 --resume \
  --grid 16 --views 4 --max-file-mb 16 --max-download-mb 2048

# The base checkpoint width is 64. All learned weights are loaded.
# Use a NEW --out directory for every run.
caffeinate -i image3d train \
  --manifest data/forma3d-v1/manifest.jsonl \
  --init-from base/examples/synthetic-smoke/synthetic-only.pt \
  --out runs/forma3d-v1 --device mps \
  --width 64 --steps 5000 --batch-size 2 --lr 0.0001 \
  --eval-every 100 --validation-fraction 0.2 --seed 42

# Independent held-out evaluation, release packaging, then publication.
python scripts/release.py \
  --run runs/forma3d-v1 --data data/forma3d-v1 \
  --base base/examples/synthetic-smoke/synthetic-only.pt \
  --release release/forma3d-v1 --device mps \
  --repo Lucasgitguy-co/forma3d-tiny --publish

The last command requires a Hugging Face token with permission to create and write model repositories. It creates a private repository, uploads the complete evaluated release, and makes it public only after a successful upload. It refuses to overwrite an existing repository. If an upload fails, a private partial repository can remain; inspect it before retrying. No raw source datasets or authentication files are uploaded.

For a fresh run, the same sequence is available as one command:

caffeinate -i bash train-mac.sh --publish

This reuses the runtime in ~/Library/Application Support/Forma3D/venv, creating it only if missing. It uses that interpreter explicitly and verifies/reuses the local base checkpoint. With the dataset already prepared, training needs no Hugging Face connection. Publication still requires service availability and your saved HF login. Use bash setup-mac.sh explicitly when installing updated package source. Dataset preparation now verifies and resumes completed objects, including the old 64-Scenario/28-Objaverse shortage. It saves progress after each object and searches eight Objaverse metadata shards. Completely black rendered objects are replaced; exact image/target duplicates remain in the same object group. Excluded existing files are preserved but omitted from the manifests. If preparation stops, rerun the same command. Training and release directories still must be fresh; after training has started, follow the individual commands from the failed stage. The wrapper does not resume optimizer state. Downloaded meshes remain cached in data/downloads.

Publication requires completed optimizer steps, lower validation and independent test loss than the starting checkpoint, higher test occupancy IoU, test IoU at least 0.05, and nonempty qualitative predictions. These are baseline research checks, not proof of production quality. A failed gate writes runs/forma3d-v1/evaluation.json and does not publish. Inspect the generated PNG comparisons in runs/forma3d-v1/inspection.

To inspect first without publishing, omit --publish. When subsequently publishing, use a fresh --release directory. The evaluation is repeated against the actual weights.

To test inference after training:

image3d generate --checkpoint runs/forma3d-v1/best.pt \
  --image your-centered-cutout.png --out results/object.ply --device mps
image3d preview --ply results/object.ply --out results/preview.png

Replace your-centered-cutout.png with a real file. Output is Gaussian PLY, not GLB or a triangle mesh. Real photos are outside the tested proxy-render distribution.

For a larger experiment, increase object counts, shard count and download budget in a fresh dataset directory after checking free disk space. Source metadata is pinned, selection is deterministic, and all views/known shared inputs stay grouped. The starter run is not a claim that 96 objects or 5,000 steps are enough for strong generalization. Training time depends on the Mac and is not yet benchmarked for the full recipe. Ctrl-C saves last.pt; --init-from runs/forma3d-v1/last.pt starts a fresh optimizer in a new output directory and is not exact resume.

If Terminal cannot use Metal, --device mps fails explicitly. --device cpu is available for small tests and Intel Macs but is much slower. Keep the selected device consistent in training and evaluation commands.

Local runtime repair — 2026-11-03

The previous .venv under Documents contained offloaded (dataless) files, causing Python read timeouts. The runtime now lives under Library/Application Support and uses a regular package installation rather than an editable .pth link. The old .venv, source data, and checkpoints are preserved.

A Hugging Face 503 can prevent browsing or publishing without affecting local training. Wait and retry the evaluation/publish step when the service is available; do not rerun completed training. Use a new --release directory when restaging.