| # 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 |
| 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: |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| 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. |
|
|
