devin-lai/Hi3Dv1.0-mlx

Hi3D v1.0 for Apple silicon

Turn a reference image and a coarse mesh into detailed 3D geometry — locally with MLX.

Quick start · GitHub source · Choose a model · Collection · Benchmarks · Meshes & galleries · 简体中文

Public inference code. Ready-to-use weights. Selective downloads. This community MLX port of Hi3D v1.0 includes FP16, INT8, INT4 and experimental W8A8 variants. The main repository is lightweight: model weights and the optional results dataset live in linked repositories. Checkpoint conversion tooling remains private. Source development, bug reports and contributions are welcome on GitHub.

Refine locally	Pick your footprint	Inspect the evidence
512³, 1024³ and 1536³ sparse extraction grids	Download one precision and only the required transformers	87 historical runs, 68 unique meshes, three example objects

The model refines geometry, using both an image and an existing coarse mesh. It does not generate textures or create the initial coarse mesh. Colorful renders below show surface normals. Validated on the M5 family; see hardware notes.

See the geometry

Download one recorded output: Dragon GLB · 17.2 MiB · Bust GLB · 17.2 MiB · Locomotive GLB · 17.2 MiB.

Two views of the same recorded mesh

These images are rendered from saved benchmark outputs. No generated promotional imagery is presented as model output. Original inputs and derived assets retain their documented third-party terms.

Quick start

Use Apple silicon, native arm64 Python 3.12 and macOS with Metal support. The recorded stack is macOS 27.0.1 and MLX 0.32.4. Install uv, then:

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install huggingface-hub==0.36.2
hf download devin-lai/Hi3Dv1.0-mlx --revision v1.0.0 --local-dir hi3d-mlx
uv pip install ./hi3d-mlx

hi3d-mlx refine \
  --image hi3d-mlx/examples/dragon.png \
  --coarse-mesh hi3d-mlx/examples/dragon_coarse.glb \
  --preset fp16 --resolution 512 --output dragon-refined.glb

The first run fetches the shared VAE/configs, the 512 transformer only, and two pinned image encoders. Later runs reuse the cache. The output includes a GLB mesh and a JSON timing/memory record. Replace the two example inputs with your own image and coarse mesh to refine another object.

For smaller weights, use --preset int8. For higher resolution, use --resolution 1024 or 1536; the high-resolution transformer downloads when needed. Python API, offline use and troubleshooting →

Choose your model

Repository	512³ download¹	1024³ / 1536³ download¹	Best fit
FP16	3.77 GiB	7.20 GiB	Start here. Reference MLX configuration.
INT8	2.28 GiB	4.22 GiB	Smaller storage and good observed reference agreement.
INT4	1.49 GiB	2.63 GiB	Storage first; substantial quality drift in the tested cases.
W8A8	2.38 GiB	4.41 GiB	Experimental native INT8 compute on M5.

¹ Transformer(s) plus the shared VAE; excludes image encoders, Python dependencies and runtime overhead. Download size is not peak RAM. The VAE is reused across variants. FP16 checkpoints contain FP16 and FP32 tensors; affine INT8/INT4 are weight quantization formats with FP16 computation.

Shared VAE & configs · Optional results dataset · Full preset guide

lean, decoder-precision and reduced-step presets reuse existing checkpoints. They are runtime choices, not additional model downloads. turbo and minimal trade geometric agreement for speed; inspect the comparisons before using them for detailed work. Generic mlx-lm loaders do not implement this pipeline.

Measured performance

In the original three-case 512³ / 25-step cohort, MLX FP16 ran 5.37–6.96× faster than the local PyTorch-MPS FP32 reference. This compares different precision configurations on the same recorded M5 / 32 GiB machine; it is not an NVIDIA comparison or a universal speed guarantee.

Case	PyTorch-MPS FP32	MLX FP16	Speedup	FP16 parent peak²	Surface F-score @ 0.002³
Dragon	663.3 s	95.3 s	6.96×	6.46 GiB	0.9994
Bust	679.6 s	126.6 s	5.37×	6.68 GiB	0.9996
Locomotive	693.4 s	128.4 s	5.40×	6.69 GiB	0.9877

One historical run per case/configuration. Times include model loading, image conditioning, refinement and postprocessing, and exclude downloads, initial coarse generation and final file export. ² Parent-process physical footprint excludes child encoder processes and is not a whole-system memory requirement. ³ Agreement with the local FP32 reference after normalization, not a ground-truth reconstruction score. See methodology, quality tradeoffs and fresh validation.

Explore, reproduce, contribute

• Use the weights: the CLI downloads only the files needed for your preset and resolution and verifies their SHA-256 hashes.
• Inspect results: download the optional results dataset for local wipe/flip comparison galleries and GLB files.
• Report a result or issue: use Community discussions. Include chip, memory, macOS, preset, resolution and the generated metrics file.
• Follow the release: like this repository and follow devin-lai for future Apple-silicon releases.

Inference source is in src/, with regression and numerical tests in tests/. Release validation and fixes · Machine-readable catalog · Repository map.

Attribution and license

Community MLX adaptation by Devin Lai, based on Hi3D v1.0 and the Sparc3D architecture. This is not an official upstream release or endorsement. Powered by Hi3D 1.0.

The Hi3D Open License Agreement v1.0 and all retained third-party terms apply. It includes use, attribution, branding and scale conditions; this release does not replace them with MIT or Apache terms. See NOTICE, THIRD_PARTY_LICENSES.md and modifications. DINOv2, CLIP and saved Hunyuan-derived example assets retain their separate terms. Inference code and optimized weights are public; the converter and conversion research remain private.