oxide-lab
/

Pi3X-GGUF

@@ -1,105 +0,0 @@
----
-license: cc-by-nc-4.0
-base_model:
-- yyfz233/Pi3X
-tags:
-- gguf
-- lux3d
-- pi3x
-- point-cloud
-- image-to-3d
-library_name: lux3d
----
-# Pi3X — GGUF quantizations (Lux3D)
-Standalone GGUF builds of the **Pi3X** point-cloud reconstruction model,
-quantized from the canonical [oxide-lab/Pi3X](https://huggingface.co/oxide-lab/Pi3X)
-F32 package by [Lux3D](https://github.com/oxide-lab/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`](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 |
-Q8_0 is stable across backends: F@1% is 1.000 on CUDA, Vulkan, WGPU and CPU.
-The lower-bit results are not monotonic because the model is highly sensitive
-to small weight perturbations. 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
-```bash
-# 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
-```bash
-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`](LICENSE). Commercial use requires a separate license from the
-rights holder. The Lux3D conversion does not change the upstream terms.