斯普兹语name

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

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

内部

坐标系统

默认情况下, SPZ 在 OpenGL 和 3.js 之后的 RUB 坐标系统中存储数据 公约。 这可以通过 SPZ_ADOBE_coordinate_system 扩展,允许 数据将存储在任何指定的坐标系统中(参见 扩展/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 这里。 。 。 .

在标记环境中,可通过以下方式生成 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 (来源)或 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版)

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: 斯普拉德受训 反变相。 。 。 .
   • 0x2:信头区包含针对供应商的扩展记录(见 扩展) (中文(简体) ).
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。 。 。 .

相机轨道限制

带有扩展 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 库提供用 纳米槽 这为加载、操纵和从Python中保存3D高斯平板提供了方便的界面.

安装

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

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

网络工具

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