| --- |
| license: mit |
| base_model: TencentARC/Pixal3D |
| pipeline_tag: image-to-3d |
| tags: |
| - image-to-3d |
| - ggml |
| - gguf |
| - 3d-generation |
| - mesh-generation |
| - cpp |
| --- |
| |
| # Pixal3D GGUF (F16) — C++/ggml image-to-3D model packs |
|
|
| [English](#english) · [简体中文](#简体中文) |
|
|
| <a id="english"></a> |
|
|
| ## English |
|
|
| This repository contains F16 GGUF conversion packs for |
| [Pixal3D.cpp](https://github.com/mousebar01/Pixal3D.cpp), a native C++17/ggml |
| implementation of the [TencentARC/Pixal3D](https://github.com/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](https://github.com/mousebar01/Pixal3D.cpp). |
|
|
| ## 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: |
|
|
| ```sh |
| ./build/bin/pixal3d inspect-pack pixal3d-shared-f16.gguf |
| ``` |
|
|
| ## Download |
|
|
| Download all three packs with the Hugging Face CLI: |
|
|
| ```sh |
| 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: |
|
|
| ```sh |
| ./build/bin/pixal3d run-cascade \ |
| pixal3d-shared-f16.gguf pixal3d-base-flow-f16.gguf \ |
| conditions.p3dcond output.glb |
| ``` |
|
|
| Example with multi-view conditioning: |
|
|
| ```sh |
| ./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](https://github.com/mousebar01/Pixal3D.cpp/blob/master/docs/cli_reference.md) |
| 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`](https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m) (gated), or the validated public mirror [`camenduru/dinov3-vitl16-pretrain-lvd1689m`](https://huggingface.co/camenduru/dinov3-vitl16-pretrain-lvd1689m) | DINOv3 license (`other`) | Convert a compatible `model.safetensors` and `config.json` with `--component dino` | |
| | NAF upsampler | [`valeoai/NAF`](https://github.com/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`](https://huggingface.co/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](https://github.com/mousebar01/Pixal3D.cpp/blob/master/docs/models_and_inputs.md). |
|
|
| ## 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`](https://github.com/mousebar01/Pixal3D.cpp/commit/344a0dc8b50426411691d6b3fb6f6cdb801451bf). 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](https://huggingface.co/TencentARC/Pixal3D), whose project and |
| model files are released under MIT. Companion models retain their respective |
| licenses. See the |
| [Pixal3D.cpp source repository](https://github.com/mousebar01/Pixal3D.cpp) for |
| project notices and implementation details. |
|
|
| ## References and acknowledgments |
|
|
| - [Original Pixal3D code](https://github.com/TencentARC/Pixal3D) |
| - [Official Pixal3D models](https://huggingface.co/TencentARC/Pixal3D) |
| - [Pixal3D paper, arXiv:2605.10922](https://arxiv.org/abs/2605.10922) |
| - [Pixal3D project page](https://ldyang694.github.io/projects/pixal3d/) |
| - [ggml](https://github.com/ggml-org/ggml), used for GGUF loading and tensor |
| backends |
|
|
| --- |
|
|
| <a id="简体中文"></a> |
|
|
| ## 简体中文 |
|
|
| 本仓库提供用于 |
| [Pixal3D.cpp](https://github.com/mousebar01/Pixal3D.cpp) 的 F16 GGUF 模型包。 |
| Pixal3D.cpp 是 [TencentARC/Pixal3D](https://github.com/TencentARC/Pixal3D) 图像到 |
| 3D 流程的原生 C++17/ggml 实现。这些文件是模型权重，不是可以直接交给 |
| Transformers 使用的独立 checkpoint；请配合 Pixal3D.cpp 使用。 |
|
|
| 完整的构建方法、CLI 参数、condition bundle 工具和 backend 说明，请参阅 |
| [Pixal3D.cpp 项目仓库](https://github.com/mousebar01/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。可以使用 |
| 以下命令检查模型包： |
|
|
| ```sh |
| ./build/bin/pixal3d inspect-pack pixal3d-shared-f16.gguf |
| ``` |
|
|
| ## 下载 |
|
|
| 使用 Hugging Face CLI 下载全部三个模型包： |
|
|
| ```sh |
| 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： |
|
|
| ```sh |
| ./build/bin/pixal3d run-cascade \ |
| pixal3d-shared-f16.gguf pixal3d-base-flow-f16.gguf \ |
| conditions.p3dcond output.glb |
| ``` |
|
|
| 使用多视图 condition： |
|
|
| ```sh |
| ./build/bin/pixal3d run-cascade-mv \ |
| pixal3d-shared-f16.gguf pixal3d-mv-flow-f16.gguf \ |
| views.p3dmvcon output.glb |
| ``` |
|
|
| `run-image` 会通过 MoGe-2 逐图估计相机，并且还需要下面列出的辅助视觉 |
| 模型。完整命令和参数请参阅 |
| [CLI 参考](https://github.com/mousebar01/Pixal3D.cpp/blob/master/docs/cli_reference.md)。 |
|
|
| ## 辅助模型 |
|
|
| 辅助模型不托管在本仓库中。请在本地下载或转换，并遵守各自的许可证： |
|
|
| | 模型 | 来源 | 许可证 | 项目流程 | |
| |---|---|---|---| |
| | DINOv3 ViT-L/16 | [`facebook/dinov3-vitl16-pretrain-lvd1689m`](https://huggingface.co/facebook/dinov3-vitl16-pretrain-lvd1689m)（需授权），或已验证的公开镜像 [`camenduru/dinov3-vitl16-pretrain-lvd1689m`](https://huggingface.co/camenduru/dinov3-vitl16-pretrain-lvd1689m) | DINOv3 license（`other`） | 准备兼容的 `model.safetensors` 和 `config.json`，使用 `--component dino` 转换 | |
| | NAF 上采样器 | [`valeoai/NAF`](https://github.com/valeoai/NAF) | Apache-2.0 | 运行 `download_naf_weights.sh`，再运行 `convert_naf_checkpoint.py` | |
| | MoGe-2 相机估计器 | [`Ruicheng/moge-2-vitl-normal-onnx`](https://huggingface.co/Ruicheng/moge-2-vitl-normal-onnx) | MIT | 运行 `download_moge_weights.sh`，直接使用下载的 ONNX 模型 | |
|
|
| 具体命令和路径见 |
| [模型和输入](https://github.com/mousebar01/Pixal3D.cpp/blob/master/docs/models_and_inputs.md)。 |
|
|
| ## 精度和来源 |
|
|
| 这些模型包使用转换器的 F16 存储策略（`--ftype 1`）：符合条件的矩阵张量 |
| 存储为 F16，敏感张量、标量和小张量保留为 F32。项目默认的 `--ftype auto` |
| 策略不同（`F32 flow，F16 decoder`）；进行全 F32 数值参考转换时使用 |
| `--ftype 0`。 |
|
|
| 本仓库中的模型包由 Pixal3D.cpp 提交 |
| [`344a0dc`](https://github.com/mousebar01/Pixal3D.cpp/commit/344a0dc8b50426411691d6b3fb6f6cdb801451bf) 生成。上游 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](https://huggingface.co/TencentARC/Pixal3D)，其项目和模型 |
| 文件采用 MIT License。辅助模型仍分别遵循各自的许可证。项目通知和实现 |
| 细节请参阅 [Pixal3D.cpp 源码仓库](https://github.com/mousebar01/Pixal3D.cpp)。 |
|
|
| ## 参考资料和致谢 |
|
|
| - [Pixal3D 原始代码](https://github.com/TencentARC/Pixal3D) |
| - [官方 Pixal3D 模型](https://huggingface.co/TencentARC/Pixal3D) |
| - [Pixal3D 论文，arXiv:2605.10922](https://arxiv.org/abs/2605.10922) |
| - [Pixal3D 项目主页](https://ldyang694.github.io/projects/pixal3d/) |
| - [ggml](https://github.com/ggml-org/ggml)，用于 GGUF 加载和张量 backend |
|
|
