mousebar01/Pixal3D.cpp-GGUF

Pixal3D GGUF (F16) — C++/ggml image-to-3D weights

GGUF weight packs for Pixal3D.cpp, a C++17/ggml port of the TencentARC/Pixal3D image-to-3D pipeline (single-image and multi-view conditioned mesh generation with texture). All files on this page are F16-precision GGUF conversions of the upstream checkpoints.

Files

file	contents	size	SHA-256
pixal3d-shared-f16.gguf	3 decoders: sparse-structure (ss_dec_conv3d_16l8), shape (shape_dec_next_dc_f16c32, FlexiDualGrid), texture (tex_dec_next_dc_f16c32)	1.90 GiB	4582ed1af57836974f59b46a896b735b31e245f1a8c706243f0e91e7b151d32d
pixal3d-base-flow-f16.gguf	4 single-view flow DiTs: ss_flow_img_dit_1_3B_64, slat_flow_img2shape_dit_1_3B_512, slat_flow_img2shape_dit_1_3B_1024, slat_flow_imgshape2tex_dit_1_3B_1024	10.36 GiB	e4b2478f4410f82f623327e10f319643d536ecdd5398d13065f3f96d98c409a7
pixal3d-mv-flow-f16.gguf	the same 4 flow stages, multi-view conditioned (*_mv checkpoints)	10.36 GiB	c9353d31515180dbd30429d57ed6ce57be170fb273dda6bc8ea9c6224ce342a7

Every pack stores all four (or three) stages in one file; the 512 and 1024 shape/tex flow stages are cascade stages, not duplicates. GGUF metadata is namespaced per component (ss_flow, shape_flow_512, shape_flow_1024, texture_flow_1024, …) and can be checked with ./build/bin/pixal3d inspect-pack <file>.

Precision

All packs use the converter's F16 storage policy (--ftype 1): eligible matrix tensors are stored as F16; sensitive, scalar, and small tensors remain F32. Validated against the lossless F32 conversion (--ftype 0) of the same checkpoints:

• flow sampler outputs agree with F32 weights to ~2e-4 relative L2 error;
• an end-to-end A/B (same input, same seed, multi-view cascade, 2048 texture) produced visually indistinguishable results: render RMSE against the original Python pipeline is 0.040 (F16) vs 0.041 (F32), and the two C++ variants differ from each other by 0.021 — less than either differs from the Python reference.

Note on provenance: the upstream flow checkpoints carry a _bf16 filename suffix but their payload is F32; the decoders are FP16/F32 mixes. The F16 packs are therefore a true F32→F16 downcast of the flow weights, quantified above. For numerical porting work the project's converter default stays --ftype auto ("F32 flow, F16 decoder" per-component storage) and --ftype 0 produces all-F32 packs for reference comparisons.

Usage

Build Pixal3D.cpp (see the repository README), then point the CLI at these packs:

# single image -> textured GLB (needs the two helper GGUFs below)
./build/bin/pixal3d run-image pixal3d-shared-f16.gguf pixal3d-base-flow-f16.gguf \
    dinov3-vitl16-pretrain-lvd1689m-f32.gguf naf_release-f32.gguf input.png output.glb

# precomputed condition bundle -> textured GLB
./build/bin/pixal3d run-cascade pixal3d-shared-f16.gguf pixal3d-base-flow-f16.gguf \
    conditions.p3dcond output.glb

# multi-view conditioned -> textured GLB
./build/bin/pixal3d run-cascade-mv pixal3d-shared-f16.gguf pixal3d-mv-flow-f16.gguf \
    views.p3dmvcon output.glb

inspect-pack, inspect-condition, estimate-model, and other diagnostics accept the same files. The condition-bundle exporters live in scripts/export_pixal3d_condition_bundle.py and scripts/export_pixal3d_multiview_condition_bundle.py.

Helper models (not hosted here)

run-image additionally needs two converted vision models. Their upstream licenses restrict or complicate redistribution, so convert them locally:

model	upstream	license	how to get it
DINOv3 ViT-L/16	facebook/dinov3-vitl16-pretrain-lvd1689m (gated) or the public mirror we validated against, camenduru/dinov3-vitl16-pretrain-lvd1689m	DINOv3 license (other)	download model.safetensors + config.json, then python3 scripts/convert_pixal3d_to_gguf.py --component dino --model <dir>/model.safetensors --config <dir>/config.json
NAF upsampler	valeoai/NAF GitHub release	Apache-2.0	./scripts/download_naf_weights.sh (pinned, SHA-256 verified), then python3 scripts/convert_pixal3d_to_gguf.py --component naf --model weights/NAF/naf_release.pth
MoGe-2 camera estimator	Ruicheng/moge-2-vitl-normal-onnx	MIT	./scripts/download_moge_weights.sh (pinned, verified; used as-is, no conversion)

Source models and licenses

The converted Pixal3D checkpoints originate from TencentARC/Pixal3D (MIT license). This repository hosts only derivative GGUF conversions produced by scripts/convert_pixal3d_to_gguf.py at Pixal3D.cpp commit 344a0dc; the DINOv3 conversion is deliberately not hosted because its upstream license does not permit redistribution.

Acknowledgments

• TencentARC/Pixal3D / project page / arXiv:2605.10922 — original model, weights, and Python reference implementation (SIGGRAPH 2026)
• ggml — GGUF format, tensor library, and backend architecture
• pwilkin/trellis.cpp — reference for the textured-mesh postprocessing chain (QEM decimation, xatlas UV unwrap, voxel-PBR bake)