Metadata-Version: 2.2
Name: alspz
Version: 0.2.0
Summary: spz (Niantic 3D Gaussian splat format) Cython bindings for ALTiler (3DGS input/output)
Requires-Python: <3.15,>=3.11
Requires-Dist: numpy>=2.0.1
Description-Content-Type: text/markdown

# alspz

[spz](https://github.com/nianticlabs/spz)（Niantic 3D Gaussian Splat 压缩格式，
MIT）的 Cython 绑定，供 ALTiler 3DGS 管线（T-063 输入 / T-069 GS5 SPZ 输出）使用。

## 构建

```powershell
cd extern_build/alspz
uv build
```

依赖：CMake ≥3.15、Cython、numpy；zlib/zstd 缺失时经 FetchContent 自动下载
（需网络，代理环境变量 HTTPS_PROXY 生效）。

## 值约定（`save_spz` / `load_spz` = niantic `GaussianCloud` 空间）

**不是** GSIR 线性空间，也不是 Cesium 最终显示值。完整链见仓库
[`docs/31_output_gs3dtiles.md`](../../docs/31_output_gs3dtiles.md)
（wasm unpack 之后 JS 还要对 scale 做 `exp`、对 alpha 做 `sigmoid`）。
`load_spz` 还原的是本表，**不要**用「alphas ∈ [0,1]」当 Cesium 验收。

| 字段 | 约定 |
| --- | --- |
| scale | **log**（m 的自然对数）——wasm 还原 log，Cesium JS `Math.exp` 后才进协方差 |
| alpha | **logit**（sigmoid 前）——wasm `invSigmoid` 还原 logit，Cesium JS 再 `sigmoid` 后 `×255`；传线性会把近 0 噪声抬到 ~0.5 |
| color | **SH DC `f_dc`**（禁止 `0.5+C0·f_dc`；pack 为 `f_dc*0.15*255+127.5`） |
| rot | 单位四元数 xyzw |
| sh | `(系数, RGB)` 交织 = 3DGS f_rest 顺序；degree 0/1/2/3/4 |
| 坐标 | `UNSPECIFIED`（无转换，约定处理在 Python 侧；对齐 CesiumJS GltfSpzLoader 的解码参数） |

## 注意事项

- 构建启用 `SPZ_BUILD_EXTENSIONS`（读第三方带坐标扩展的 spz 时可正确转换）。
- 绑定不按值返回任何 C++ struct（AGENTS.md §5.4.21 教训），全部指针传出。
