docs/USAGE.md

Image3D Student v0.1.0 — Windows, Linux and macOS

This is the first public prototype release. The bundled checkpoint learned only synthetic ellipsoids. It is useful for testing installation, loading, training and PLY export; it is not a general image-to-3D model. Original project code, documentation and synthetic demonstration artifacts are Apache-2.0.

Install Python 3.13 (or use 3.11/3.12). Start in a new directory. Windows uses PowerShell. CPU is supported by the code on all three platforms; actual execution was verified on macOS CPU and Metal only. This version does not implement a CUDA student device. Do not pass --device cuda.

Windows

1. Create an environment and install the Hub downloader.

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install huggingface_hub

2. Download the immutable first release and install its source package.

.\.venv\Scripts\hf.exe download Lucasgitguy-co/image3d-student --revision v0.1.0 --local-dir image3d-student
.\.venv\Scripts\python.exe -m pip install -e "./image3d-student[test]"
.\.venv\Scripts\python.exe -m image3d_student.cli doctor

3. Generate a test PLY using the bundled synthetic-only checkpoint.

.\.venv\Scripts\python.exe -m image3d_student.cli generate --checkpoint image3d-student/examples/synthetic-smoke/synthetic-only.pt --image image3d-student/examples/synthetic-smoke/dataset/images/fixture-007.png --out results/synthetic-demo.ply --device cpu
.\.venv\Scripts\python.exe -m image3d_student.cli preview --ply results/synthetic-demo.ply --out results/turntable.png

4. Test training from scratch on procedural fixtures.

.\.venv\Scripts\python.exe -m image3d_student.cli demo-data --out data/demo --count 12 --grid 8
.\.venv\Scripts\python.exe -m image3d_student.cli train --manifest data/demo/manifest.jsonl --out runs/demo --device cpu --width 64 --steps 100 --lr 0.001 --eval-every 25 --allow-synthetic
.\.venv\Scripts\python.exe -m pytest image3d-student/tests -q

Linux

1. Create an environment and install the Hub downloader.

python3.13 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install huggingface_hub

2. Download the immutable first release and install its source package.

.venv/bin/hf download Lucasgitguy-co/image3d-student --revision v0.1.0 --local-dir image3d-student
.venv/bin/python -m pip install -e "./image3d-student[test]"
.venv/bin/python -m image3d_student.cli doctor

3. Generate a test PLY using the bundled synthetic-only checkpoint.

.venv/bin/python -m image3d_student.cli generate --checkpoint image3d-student/examples/synthetic-smoke/synthetic-only.pt --image image3d-student/examples/synthetic-smoke/dataset/images/fixture-007.png --out results/synthetic-demo.ply --device cpu
.venv/bin/python -m image3d_student.cli preview --ply results/synthetic-demo.ply --out results/turntable.png

4. Test training from scratch on procedural fixtures.

.venv/bin/python -m image3d_student.cli demo-data --out data/demo --count 12 --grid 8
.venv/bin/python -m image3d_student.cli train --manifest data/demo/manifest.jsonl --out runs/demo --device cpu --width 64 --steps 100 --lr 0.001 --eval-every 25 --allow-synthetic
.venv/bin/python -m pytest image3d-student/tests -q

macOS

1. Create an environment and install the Hub downloader.

python3.13 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install huggingface_hub

2. Download the immutable first release and install its source package.

.venv/bin/hf download Lucasgitguy-co/image3d-student --revision v0.1.0 --local-dir image3d-student
.venv/bin/python -m pip install -e "./image3d-student[test]"
.venv/bin/python -m image3d_student.cli doctor

3. Generate a test PLY using the bundled synthetic-only checkpoint.

.venv/bin/python -m image3d_student.cli generate --checkpoint image3d-student/examples/synthetic-smoke/synthetic-only.pt --image image3d-student/examples/synthetic-smoke/dataset/images/fixture-007.png --out results/synthetic-demo.ply --device mps
.venv/bin/python -m image3d_student.cli preview --ply results/synthetic-demo.ply --out results/turntable.png

4. Test training from scratch on procedural fixtures.

.venv/bin/python -m image3d_student.cli demo-data --out data/demo --count 12 --grid 8
.venv/bin/python -m image3d_student.cli train --manifest data/demo/manifest.jsonl --out runs/demo --device mps --width 64 --steps 100 --lr 0.001 --eval-every 25 --allow-synthetic
.venv/bin/python -m pytest image3d-student/tests -q

On Intel Macs, or when Metal is unavailable, replace --device mps with --device cpu.

Train on real teacher outputs

Use the project workflow to cache the exact teacher input image and Idol PLY, optionally adding explicitly aligned InstantMesh/Hi3D meshes. Use a new run/output directory for each experiment. These models are not downloaded or run by the student training command.

Only the experimental Idol runner exists in this release. Full pretrained Idol inference remains unverified; InstantMesh/Hi3D are import-only integrations. The Mac adapter is not a validated Windows/Linux teacher runner. All upstream model/encoder licenses and access terms remain separate from this prototype's Apache license.

Version and outputs

v0.1.0 pins this first release. Downloading main instead may fetch later changes. The .ply file is a Gaussian-splat artifact, not a triangle mesh. last.pt is the latest training checkpoint; best.pt exists only when held-out validation is enabled. Outputs refuse overwriting: choose a new filename/directory when rerunning.

No 1-bit quantization is implemented. The default untrained architecture has 465,041 parameters; the bundled smaller smoke-test checkpoint has 306,321 parameters. See verification for the exact test conditions.