mousebar01/Pixal3D.cpp-GGUF

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

English · 简体中文

English

This repository contains F16 GGUF conversion packs for Pixal3D.cpp, a native C++17/ggml implementation of the TencentARC/Pixal3D image-to-3D pipeline. These files are model weights, not a standalone Transformers checkpoint; use them with Pixal3D.cpp.

For complete build instructions, CLI options, condition-bundle tools, and backend notes, see the Pixal3D.cpp repository.

Files

file	contents	size	SHA-256
pixal3d-shared-f16.gguf	Shared sparse-structure, shape, and texture decoders	1.90 GiB	4582ed1af57836974f59b46a896b735b31e245f1a8c706243f0e91e7b151d32d
pixal3d-base-flow-f16.gguf	Four single-view flow stages: structure, shape 512, shape 1024, and texture 1024	10.36 GiB	e4b2478f4410f82f623327e10f319643d536ecdd5398d13065f3f96d98c409a7
pixal3d-mv-flow-f16.gguf	Four multi-view conditioned flow stages	10.36 GiB	c9353d31515180dbd30429d57ed6ce57be170fb273dda6bc8ea9c6224ce342a7

The 512 and 1024 shape/texture stages are cascade stages, not duplicate model packs. Each file contains all of the stages listed above, with namespaced GGUF metadata. Pixal3D.cpp can inspect a pack with:

./build/bin/pixal3d inspect-pack pixal3d-shared-f16.gguf

Download

Download all three packs with the Hugging Face CLI:

pip install -U huggingface_hub
hf download mousebar01/Pixal3D.cpp-GGUF \
  --local-dir Pixal3D.cpp-GGUF

Individual files can be selected with additional --include arguments.

Compatibility and quick usage

Pixal3D.cpp command	Required files
run-image	pixal3d-shared-f16.gguf, pixal3d-base-flow-f16.gguf, DINOv3 GGUF, NAF GGUF, and MoGe-2
run-cascade	pixal3d-shared-f16.gguf, pixal3d-base-flow-f16.gguf, and a .p3dcond condition file
run-cascade-mv	pixal3d-shared-f16.gguf, pixal3d-mv-flow-f16.gguf, and a .p3dmvcon condition file

Example with a precomputed single-view condition bundle:

./build/bin/pixal3d run-cascade \
  pixal3d-shared-f16.gguf pixal3d-base-flow-f16.gguf \
  conditions.p3dcond output.glb

Example with multi-view conditioning:

./build/bin/pixal3d run-cascade-mv \
  pixal3d-shared-f16.gguf pixal3d-mv-flow-f16.gguf \
  views.p3dmvcon output.glb

run-image performs per-image camera estimation through MoGe-2 and also needs the companion vision models below. See the CLI reference for all commands and options.

Companion models

The helper models are not hosted in this repository. Convert or download them locally and follow their own license terms:

model	source	license	project workflow
DINOv3 ViT-L/16	facebook/dinov3-vitl16-pretrain-lvd1689m (gated), or the validated public mirror camenduru/dinov3-vitl16-pretrain-lvd1689m	DINOv3 license (other)	Convert a compatible model.safetensors and config.json with --component dino
NAF upsampler	valeoai/NAF	Apache-2.0	Run download_naf_weights.sh, then convert_naf_checkpoint.py
MoGe-2 camera estimator	Ruicheng/moge-2-vitl-normal-onnx	MIT	Run download_moge_weights.sh; use the ONNX model as downloaded

The exact commands and paths are documented in Models and inputs.

Precision and provenance

These packs use the converter's F16 storage policy (--ftype 1): eligible matrix tensors are stored as F16, while sensitive, scalar, and small tensors remain F32. The project's default --ftype auto policy is different (F32 flow, F16 decoder); use --ftype 0 for all-F32 numerical reference conversions.

The packs in this repository were generated from Pixal3D.cpp commit 344a0dc. The upstream flow checkpoints use a _bf16 filename suffix, but their payload is F32; the F16 packs are a true F32-to-F16 conversion of those tensors.

Validation scope

These files are GGUF conversions for Pixal3D.cpp, not the original Python checkpoints. The release has been checked for file integrity and selected comparisons against corresponding F32 conversions, but it has not been evaluated for full numerical equivalence with the upstream Python pipeline or for production-quality image and mesh benchmarks.

CPU and GPU executions may produce different mesh results because backend execution and native export/post-processing paths can differ. Exact, bit-for- bit CPU/GPU mesh equivalence is not guaranteed.

Limitations

• The final supported cascade target is 1024³; 512³ is an internal cascade stage.
• GLB remesh, QEM, xatlas, and texture baking are native export paths. Remesh and xatlas remain CPU host-side operations.
• GPU execution is capability-driven and partial. Forced GPU policies can fail when a required operation is unavailable; auto may fall back with a diagnostic.
• RGB/JPEG inputs do not receive automatic rembg foreground removal. RGBA PNG inputs follow the reference crop/matte path; photographs may need preprocessing.
• The GGUF files and generated outputs are not a substitute for the upstream Python implementation or its original checkpoints.

Sources and licenses

The converted Pixal3D checkpoints originate from TencentARC/Pixal3D, whose project and model files are released under MIT. Companion models retain their respective licenses. See the Pixal3D.cpp source repository for project notices and implementation details.

References and acknowledgments

• Original Pixal3D code
• Official Pixal3D models
• Pixal3D paper, arXiv:2605.10922
• Pixal3D project page
• ggml, used for GGUF loading and tensor backends

---

简体中文

本仓库提供用于 Pixal3D.cpp 的 F16 GGUF 模型包。 Pixal3D.cpp 是 TencentARC/Pixal3D 图像到 3D 流程的原生 C++17/ggml 实现。这些文件是模型权重，不是可以直接交给 Transformers 使用的独立 checkpoint；请配合 Pixal3D.cpp 使用。

完整的构建方法、CLI 参数、condition bundle 工具和 backend 说明，请参阅 Pixal3D.cpp 项目仓库。

文件

文件	内容	大小	SHA-256
pixal3d-shared-f16.gguf	shared 稀疏结构、形状和纹理解码器	1.90 GiB	4582ed1af57836974f59b46a896b735b31e245f1a8c706243f0e91e7b151d32d
pixal3d-base-flow-f16.gguf	四个单视图 flow 阶段：结构、形状 512、形状 1024 和纹理 1024	10.36 GiB	e4b2478f4410f82f623327e10f319643d536ecdd5398d13065f3f96d98c409a7
pixal3d-mv-flow-f16.gguf	四个多视图条件 flow 阶段	10.36 GiB	c9353d31515180dbd30429d57ed6ce57be170fb273dda6bc8ea9c6224ce342a7

形状/纹理的 512 和 1024 阶段是级联阶段，不是重复的模型包。每个文件都 包含表中列出的全部阶段，并使用命名空间隔离的 GGUF metadata。可以使用 以下命令检查模型包：

./build/bin/pixal3d inspect-pack pixal3d-shared-f16.gguf

下载

使用 Hugging Face CLI 下载全部三个模型包：

pip install -U huggingface_hub
hf download mousebar01/Pixal3D.cpp-GGUF \
  --local-dir Pixal3D.cpp-GGUF

如需只下载部分文件，可以追加 --include 参数。

兼容性和最短用法

Pixal3D.cpp 命令	所需文件
run-image	pixal3d-shared-f16.gguf、pixal3d-base-flow-f16.gguf、DINOv3 GGUF、NAF GGUF 和 MoGe-2
run-cascade	pixal3d-shared-f16.gguf、pixal3d-base-flow-f16.gguf 和 .p3dcond condition 文件
run-cascade-mv	pixal3d-shared-f16.gguf、pixal3d-mv-flow-f16.gguf 和 .p3dmvcon condition 文件

使用已有的单视图 condition bundle：

./build/bin/pixal3d run-cascade \
  pixal3d-shared-f16.gguf pixal3d-base-flow-f16.gguf \
  conditions.p3dcond output.glb

使用多视图 condition：

./build/bin/pixal3d run-cascade-mv \
  pixal3d-shared-f16.gguf pixal3d-mv-flow-f16.gguf \
  views.p3dmvcon output.glb

run-image 会通过 MoGe-2 逐图估计相机，并且还需要下面列出的辅助视觉 模型。完整命令和参数请参阅 CLI 参考。

辅助模型

辅助模型不托管在本仓库中。请在本地下载或转换，并遵守各自的许可证：

模型	来源	许可证	项目流程
DINOv3 ViT-L/16	facebook/dinov3-vitl16-pretrain-lvd1689m（需授权），或已验证的公开镜像 camenduru/dinov3-vitl16-pretrain-lvd1689m	DINOv3 license（other）	准备兼容的 model.safetensors 和 config.json，使用 --component dino 转换
NAF 上采样器	valeoai/NAF	Apache-2.0	运行 download_naf_weights.sh，再运行 convert_naf_checkpoint.py
MoGe-2 相机估计器	Ruicheng/moge-2-vitl-normal-onnx	MIT	运行 download_moge_weights.sh，直接使用下载的 ONNX 模型

具体命令和路径见 模型和输入。

精度和来源

这些模型包使用转换器的 F16 存储策略（--ftype 1）：符合条件的矩阵张量 存储为 F16，敏感张量、标量和小张量保留为 F32。项目默认的 --ftype auto 策略不同（F32 flow，F16 decoder）；进行全 F32 数值参考转换时使用 --ftype 0。

本仓库中的模型包由 Pixal3D.cpp 提交 344a0dc 生成。上游 flow checkpoint 的文件名带有 _bf16 后缀，但其实际 payload 是 F32；这里的 F16 模型包是对这些张量执行 真正的 F32 到 F16 转换。

验证范围

这些文件是供 Pixal3D.cpp 使用的 GGUF 转换版本，不是上游 Python checkpoint。当前版本已经完成文件完整性检查，并与对应的 F32 转换结果做过 部分对比；但尚未针对上游 Python 流程进行完整数值等价性验证，也没有提供 生产级图像和网格质量基准。

由于 backend 执行方式以及原生导出/后处理路径可能不同，CPU 和 GPU 执行 可能生成不同的网格结果，不保证 CPU/GPU 网格逐位一致。

当前限制

• 当前支持的最终级联目标为 1024³；512³ 是内部级联阶段。
• GLB remesh、QEM、xatlas 和纹理烘焙是原生导出路径；remesh 和 xatlas 仍在 CPU 主机侧执行。
• GPU 执行由能力决定且不完整。必需操作不可用时，强制 GPU 策略会失败； auto 可能在记录诊断后回退。
• RGB/JPEG 输入不会自动执行 rembg 前景分割。RGBA PNG 使用参考实现的裁剪 和黑色背景合成流程；照片可能需要预处理。
• GGUF 文件和生成结果不能替代上游 Python 实现或原始 checkpoint。

来源和许可证

转换后的 Pixal3D checkpoint 来源于 TencentARC/Pixal3D，其项目和模型 文件采用 MIT License。辅助模型仍分别遵循各自的许可证。项目通知和实现 细节请参阅 Pixal3D.cpp 源码仓库。

参考资料和致谢

• Pixal3D 原始代码
• 官方 Pixal3D 模型
• Pixal3D 论文，arXiv:2605.10922
• Pixal3D 项目主页
• ggml，用于 GGUF 加载和张量 backend