Pi3X — GGUF quantizations (Lux3D)

Standalone GGUF builds of the Pi3X point-cloud reconstruction model, quantized from the canonical oxide-lab/Pi3X F32 package by Lux3D.

Each file is a complete package: resolved_config.json is embedded in the GGUF metadata, so --model-path accepts the file directly. No sibling manifest.json, checksums.json or safetensors file is required.

Files

file	dtype	size	status
`pi3x-q8_0.gguf`	Q8_0, F16 fallback	1.365 GiB	recommended
`pi3x-q6_k.gguf`	Q6_K, F16 fallback	1.064 GiB	not recommended
`pi3x-q5_k.gguf`	Q5_K, F16 fallback	0.898 GiB	not recommended
`pi3x-q4_k.gguf`	Q4_K, F16 fallback	0.742 GiB	not recommended

Canonical F32 package size: 5.07 GiB. SHA-256 and exact byte sizes are in checksums.json. Quantized matrices: 466 per variant.

Evaluation

Reference: the same CUDA backend running the canonical F32 package. Input: the three 512x512 synthetic frames in the Lux3D test assets. Metrics are drift against F32, not ground-truth accuracy: Chamfer-L1 relative to the reference bbox diagonal and symmetric F-score at 0.5%/1% of that diagonal.

variant	CD rel	F@0.5%	F@1%	F@2%
q8_0	0.081%	0.99999	1.000	1.000
q6_k	0.873%	0.129	0.598	1.000
q5_k	2.279%	0.000	0.000	0.195
q4_k	0.789%	0.274	0.719	0.986

Cross-backend F@1%, each run against that backend's own F32 reference:

variant	CUDA	Vulkan	WGPU	CPU
q8_0	1.000	1.000	1.000	1.000
q6_k	0.598	0.070	0.237	0.089
q5_k	0.000	0.000	0.000	0.000
q4_k	0.719	0.947	0.930	0.938

Q8_0 is stable across all four backends. The lower-bit results are not monotonic because the model is highly sensitive to small weight perturbations, and they vary by backend; none of them matches Q8_0. The image encoder. is the main hotspot: with that module kept in F16, Q6_K recovers F@1% from 0.598 to 0.99996, but the resulting package is 1.40 GiB versus 1.37 GiB for all-Q8_0, so Q8_0 is the better choice. Publish Q8_0 only for production use.

Usage

# download
hf download oxide-lab/Pi3X-GGUF pi3x-q8_0.gguf --local-dir .

# point cloud from a frame directory
lux3d-cli run pi3x --device cuda \
  --model-path pi3x-q8_0.gguf \
  --source ./frames \
  --output cloud.ply

# optional conditions file (depth/pose/ray/intrinsic injection)
lux3d-cli run pi3x --device cuda \
  --model-path pi3x-q8_0.gguf \
  --source ./frames \
  --conditions ./condition.npz \
  --output cloud.ply

# VO mode
lux3d-cli run pi3x --device cuda \
  --model-path pi3x-q8_0.gguf \
  --source ./video.mp4 --vo \
  --chunk-size 8 --overlap 4 --conf-threshold 0.05 \
  --output cloud.ply

The result is an ASCII PLY with positions and RGB colors. .xyz is also accepted as a plain-text alternative.

Conversion

lux3d-cli weights quantize pi3x \
  --source /path/to/canonical-pi3x/model.safetensors \
  --output pi3x-q8_0.gguf \
  --dtype q8_0 --fallback-dtype f16

Only rank-2 *.weight matrices are quantized; norms, biases, embeddings, convolutions and rows that do not divide into the dtype block stay in F16. Quantized linears run through QMatMul.

License

Pi3X weights are distributed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) license; see LICENSE. Commercial use requires a separate license from the rights holder. The Lux3D conversion does not change the upstream terms.