# @adobe/spz 中文文档

规范地址：https://npmcn.com/package/%40adobe/spz/

版本：0\.2\.3
npm 元数据更新时间：2026-10-01T01:34:43.662Z
中文译文更新时间：2026-11-05T17:43:54.369Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adobe/spz
原文对照：https://npmcn.com/package/%40adobe/spz/?lang=original
项目主页：https://github.com/nianticlabs/spz

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：886 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-03-26T03:05:26.219Z
- 最新版本发布：2026-09-01T22:59:37.918Z
- 近 30 天下载量：164258（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

装入高斯克平板文件的 WebAssembly 模块

## 安装

```sh
npm install @adobe/spz
```

也可以使用：`pnpm add @adobe/spz`、`yarn add @adobe/spz`、`bun add @adobe/spz`

## README

# 斯普兹语name

`.spz` 是一个用于压缩 3D gaussian splats 的文件格式。 此目录包含 C++ 库 用于以.spz格式保存和载入数据.

spz编码后平板通常比相应的.ply文件小10x左右, 两者的视觉差异很小.

## 内部

### 坐标系统

默认情况下, SPZ 在 OpenGL 和 3.js 之后的 RUB 坐标系统中存储数据 公约。 这可以通过 `SPZ_ADOBE_coordinate_system` 扩展,允许 数据将存储在任何指定的坐标系统中(参见 [扩展/README.md](https://npmcn.com/package/%40adobe/spz/extensions/README.md)) (中文(简体) ). 这与其他数据格式不同,如PLY(通常使用RDF),GLB(GLB)等 通常使用LUF),或Unity(一般使用联阵). 为协助协调系统转换, 呼叫者在保存时应当指定其高斯云数据所代表的坐标系统 以及他们的渲染系统在加载时所使用的协调系统。 这些规定载于 包装选项和外包装选项。 如果坐标系是 `UNSPECIFIED`,数据将 在不转换的情况下保存和加载,这可能损害互操作性.

有16个命名的坐标系统在两个家庭组织:

-   **标准家庭** ——字母表示X,Y,Z轴方向(例如. `RUB` 对,上,后: `LDB`, (中文(简体) ), `RDB`, (中文(简体) ), `LUB`, (中文(简体) ), `RUB`, (中文(简体) ), `LDF`, (中文(简体) ), `RDF`, (中文(简体) ), `LUF`, (中文(简体) ), `RUF`
-   **旋转家族** ——轴由90度旋转相接X(Y和Z相接: `LFD`, (中文(简体) ), `RFD`, (中文(简体) ), `LFU`, (中文(简体) ), `RFU`, (中文(简体) ), `LBD`, (中文(简体) ), `RBD`, (中文(简体) ), `LBU`, (中文(简体) ), `RBU`

家庭之间的转换除任何轴外,还应用了X轴的90度旋转 翻转,也通过相适应的Wigner D-matrix来旋转球-谐振系数.

## 执行情况

### C++ 组合

要求数 `libz` 财务报告和审定财务报表 `libzstd` 作为附属库,否则代码是完全自成一体的. 为方便起见,提供CMake建设系统.

**说明:** 若为 `libz` 或者说 `libzstd` 在系统上找不到, CMake 构建系统将使用 FackContent 自动下载。 这确保了在不同环境中建立一致的结构.

### 字体

为了通过Web-Assem(WASM)来构建Typescription接口,在编译前需要设置一个Emplicten环境. 可以按照指示安装标记 SDK [这里](https://emscripten.org/docs/getting_started/downloads.html)。 。 。 .

在标记环境中,可通过以下方式生成 Makefile:

```
emcmake cmake -B build-wasm .
```

那样的话,我们就能继续建设了

```
cmake --build build-wasm
```

软件包将建入 `dist` 文件夹.

## API 密码

### C++ 组合

```
bool saveSpz(
   const GaussianCloud &gaussians, const PackOptions &options, std::vector<uint8_t> *output);
```

将高斯云转换为 `.spz` 格式,并将结果写入字节的矢量.

-   `gaussians`: 要保存的高斯人
-   `options`:控制包装行为的旗帜,包括SH量化参数.
-   `output`: 将包含以.spz格式编码的字节的向量
-   成功归来,失败归来.

* * *

```
bool saveSpz(
   const GaussianCloud &gaussians, const PackOptions &options, const std::string
&filename);
```

保存高斯山脉一朵云 `.spz` 文件的格式

-   `gaussians`: 要保存的高斯人
-   `options`:控制包装行为的旗帜,包括SH量化参数.
-   `filename`: 要保存的文件路径 .
-   成功归来,失败归来.

* * *

```
GaussianCloud loadSpz(const std::vector<uint8_t> &data, const UnpackOptions &opti
ons);
```

从字节中装入高斯的云 `.spz` 格式.

-   `data`: 含有编码后 spz 数据的向量
-   `options`:控制打包行为的旗帜.
-   回返a `GaussianCloud` 从向量解码。 如果出错, 将会返回 结果是没有高卢人

* * *

```
GaussianCloud loadSpz(const std::string &filename, const UnpackOptions &options);
```

从文件中装入高斯的云 `.spz` 格式.

-   `filename`: 要从中加载文件的路径 .
-   `options`:控制打包行为的旗帜.
-   回返a `GaussianCloud` 从文件中解码 。 如果出错, 将会返回 结果是没有高卢人

### 字体

检查 [缩写/缩写/spz.d.ts.in](https://npmcn.com/package/%40adobe/spz/src/emscripten/spz.d.ts.in) (来源)或 `dist/spz.d.ts` (与 CMake 相建后)用于 TypeScript 接口. 由于Emscripten和Javascript内存是分开处理的,所以我们只暴露出Typescript接口的有限功能.

### 包选项

这个 `PackOptions` 结构支持以下字段:

-   `from`: 源坐标系统(默认: `UNSPECIFIED`(中文(简体) )
-   `version`: 包装格式的版本(默认: `4`(中文(简体) )
-   `sh1Bits`: SH 度 1 系数的量化位数( 默认: 5, 范围: 1-8)
-   `shRestBits`: SH 度 2+系数的量化比特数( 默认: 4, 范围:1-8)

## 文件格式

版本4使用ZSTD压缩并使用32字节的平正字头. 每个属性流独立并平行地被压缩,既能改善压缩,又能降低压缩吞吐量. 1–3(gzip-compressed single-stream格式)版本的文件仍然可以读取. 装入时没有执行最大点数 .

### 文件布局( 第4版)

```
Bytes  0–31:              NgspFileHeader (32 bytes, plaintext)
Bytes  32..(tbo-1):       Extension ILV records, if flags & 0x2  (variable)
Bytes  tbo..(tbo+N*16-1): TOC — N × [compressedSize u64, uncompressedSize u64]
Bytes  (tbo+N*16)..end:   N independent ZSTD-compressed attribute streams
```

`tbo` =: `tocByteOffset` 从头。 当没有扩展时, `tbo = 32`。 。 。 .

### 页眉( 第4版)

```c
struct NgspFileHeader {        // 32 bytes, all fields little-endian
  uint32_t magic;              // 0x5053474e ("NGSP")
  uint32_t version;            // 4
  uint32_t numPoints;
  uint8_t  shDegree;
  uint8_t  fractionalBits;
  uint8_t  flags;
  uint8_t  numStreams;         // number of ZSTD-compressed attribute streams (typically 6)
  uint32_t tocByteOffset;     // byte offset from file start to the TOC
  uint8_t  reserved[12];      // zero, reserved for future use
};
```

所有价值都是小-endian.

1.  **魔术**: 永远 `0x5053474e` (字节) `N`, (中文(简体) ), `G`, (中文(简体) ), `S`, (中文(简体) ), `P` (按文件顺序排列).
2.  **版本**: 4 (现). 1–3版本使用遗留gzip格式(只读).
3.  **数字点**:高斯人之数.
4.  **sH德格里语Name**:球形口琴的分级. 必须在0到4之间(含).
5.  **分数**:固定点坐标分数所用的比特数.
6.  **旗帜**: 位场.
    -   `0x1`: 斯普拉德受训 [反变相](https://niujinshuchong.github.io/mip-splatting/)。 。 。 .
    -   `0x2`:信头区包含针对供应商的扩展记录(见 [扩展](https://npmcn.com/package/%40adobe/spz/#readme-extensions)) (中文(简体) ).
7.  **数字结构**: TOC后ZSTD压缩属性流的数量. 一般为6(位置,α,颜色,鳞片,自转,球形口音).
8.  **tocByteOffset (英语)**: 字节从文件开始到目录。 之前的一切,都一样 `tocByteOffset` 是纯文本.
9.  **保留**: 必须是零.

### 格式检测( 装入路径)

```
bytes[0..3] == "NGSP"  →  version 4 ZSTD format
bytes[0..1] == 0x1f 0x8b  →  legacy gzip format (versions 1–3, read-only)
```

### 职位

职位如下: `(x, y, z)` 坐标,每个都作为24位固定点签名整数. 分数位由 `fractionalBits` 字段中的字段.

### 缩放

天平显示为 `(x, y, z)` 元件,每个元件以8位对数编码整数表示.

### 旋转

在版本3和4中,为优化旋转精度,旋转被作为正态旋转之四最小的三个组成部分来表示. 最大的组件可以从其他组件中衍生出来,而不被存储. 它的索引存储在 2 比特 并且最小的3个组件的每个被编码为10位签名整数.

在第二版中,轮换作为 `(x, y, z)` 参数。 这个 `w` 组件可以来自其他组件,而不存储。 每个组件编码为: 8位签名整数.

### 阿尔法

阿尔法以8位无符号整数表示.

### 颜色

颜色为 `(r, g, b)` 值,将每个颜色组件作为 未签名的 8 位整数 .

### 球形谐波

视花板球形口琴的大小不同,可含有0(为0等), 9(为一等分),24(为二等分),45(为三等分),或72(为四等分)每高斯系数.

Gaussian的系数排列为:颜色通道为内(更快) )轴,而系数是外(更低的可变)轴,即一级, 9个值的顺序是:

```
sh1n1_r, sh1n1_g, sh1n1_b, sh10_r, sh10_g, sh10_b, sh1p1_r, sh1p1_g, sh1p1_b
```

每个系数作为8位签名整数表示.

**量化 :**

SPZ支持可配置的球形口口腔分解. 默认情况下,采用固定精度量化:

-   假设SH系数在\[-1, 1\]范围内
-   1等分5个精度,2、3和4等分4个精度
-   为后向相容性维护

量化精度可以通过 `PackOptions`数字 :

-   `sh1Bits`: SH 度 1 系数的量化位数( 默认: 5, 范围: 1-8)
-   `shRestBits`: SH 度 2+系数的量化比特数( 默认: 4, 范围:1-8)

**说明:** 量子化比特只在打包时使用来减少信息py以更好地压缩. 解包过程不需要知道准确的量化比特,因为解压会自动地填入零比特来进行定量数据.

这使得用户可以在文件大小和质量之间互换. 库与默认的量化设置保持了完全后向相容.

### 扩展

SPZ支持特定供应商的扩展(如相机限制),因此多个供应商可以共存在同一文件中. 在版本4中,扩展被作为ILV(类型+长度+值)记录被存储在固定头和TOC之间的平面头区间——不识别扩展类型的解析器按长度跳过. 关于扩展格式以及如何添加或使用扩展,参见 [扩展/README.md](https://npmcn.com/package/%40adobe/spz/extensions/README.md)。 。 。 .

### 相机轨道限制

带有扩展 `SPZ_ADOBE_safe_orbit_camera`,SPZ支持存储相机限制,用于限制渲染中的视图。 该扩展包括:

**属性**

此扩展名有以下属性和默认值:

```
  float safeOrbitElevationMin = 0.0f;  // Minimum elevation for safe orbit (radians)
  float safeOrbitElevationMax = 0.0f;  // Maximum elevation for safe orbit (radians)
  float safeOrbitRadiusMin = 0.0f;     // Minimum radius for safe orbit
```

## Python 绑定

SPZ 库提供用 [纳米槽](https://nanobind.readthedocs.io/) 这为加载、操纵和从Python中保存3D高斯平板提供了方便的界面.

### 安装

```bash
git clone https://github.com/nianticlabs/spz.git
cd spz
pip install .
```

更多信息和使用示例请参见 src/python/README.md

## 网络工具

基于浏览器的实用工具在 [nianticlabs.github.io/spz 互联网档案馆的存檔,存档日期2013-12-02](https://nianticlabs.github.io/spz)它使用最新的WASM构建,并允许您检查文件元数据 `.spz` 财务报告和审定财务报表 `.ply` 文档并在两种格式之间转换,而不安装任何东西。 由于它完全运行在浏览器中,因此它受浏览器内存限制,并用于可达2GB左右的文件. 对于更大的文件,克隆寄存器并直接使用命令行工具.

## 常见问题

### @adobe/spz 是什么？

装入高斯克平板文件的 WebAssembly 模块

### 如何安装 @adobe/spz？

在项目目录运行 npm install @adobe/spz，或使用 pnpm add / yarn add / bun add。

### @adobe/spz 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adobe/spz 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @adobe/spz 可以商用吗？

@adobe/spz 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adobe/spz 的下载量有多少？

根据 npm 官方下载统计，@adobe/spz 在 2026/10/05 – 2026/11/03 这 30 天内被下载 164,258 次，日均约 5,475 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adobe/spz 还在维护吗？

最新版本 0\.2\.3 发布于 2026/09/02（2 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/03/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。