@loaders.gl/splats 5.0.0-alpha.1 → 5.0.0-alpha.11

package/src/lib/parse-spz.ts

@@ -2,9 +2,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {ZstdCompression} from '@loaders.gl/compression';
+import {GZipDecompressor, ZstdDecompressor} from '@loaders.gl/compression';
 import type {MeshArrowTable} from '@loaders.gl/schema';
-import type {GaussianSplats, SplatsLoaderOptions} from '../types';
+import type {GaussianSplats, SPZCoordinateSystem, SplatsLoaderOptions} from '../types';
 import {makeGaussianSplatsArrowTable} from './splats-arrow-table';
 import {normalizeQuaternion} from './splat-utils';
 
@@ -46,20 +46,205 @@ export async function parseSPZToGaussianSplats(
   data: ArrayBuffer,
   options?: SplatsLoaderOptions
 ): Promise<GaussianSplats> {
+  const version = detectSPZVersion(data);
+  if (version === 0) {
+    return await parseLegacySPZ(data, options);
+  }
+  if (version !== SPZ_VERSION) {
+    throw new Error(`SPZLoader: version ${version} is not supported.`);
+  }
   const header = parseSPZHeader(data);
   const streamInfos = parseSPZStreamInfos(data, header, getSPZStreamByteLengths(header));
   const compressedStreams = streamInfos.map(streamInfo =>
     data.slice(streamInfo.compressedOffset, streamInfo.compressedOffset + streamInfo.compressedSize)
   );
-  const compression = new ZstdCompression({modules: options?.modules});
+  const decompressor = new ZstdDecompressor({modules: options?.modules});
   const streams = await Promise.all(
     compressedStreams.map((compressedStream, streamIndex) =>
-      compression.decompress(compressedStream, streamInfos[streamIndex].uncompressedSize)
+      decompressor.decompress(compressedStream, streamInfos[streamIndex].uncompressedSize)
     )
   );
 
   validateSPZStreamLengths(streams, streamInfos);
-  return decodeSPZStreams(header, streams, data);
+  return applySPZCoordinateSystem(
+    decodeSPZStreams(header, streams, data),
+    options?.splats?.sourceCoordinateSystem ?? 'RUB',
+    options?.splats?.targetCoordinateSystem ?? options?.splats?.sourceCoordinateSystem ?? 'RUB'
+  );
+}
+
+/** Detects the SPZ generation from either the legacy gzip or v4 plaintext header. */
+function detectSPZVersion(data: ArrayBuffer): number {
+  if (data.byteLength < 8) {
+    throw new Error('SPZLoader: file must contain at least an 8-byte header.');
+  }
+  const bytes = new Uint8Array(data);
+  if (bytes[0] === 0x1f && bytes[1] === 0x8b) {
+    // Legacy files carry their 16-byte header inside the gzip stream. The
+    // version is therefore read by parseLegacySPZ after decompression.
+    return 0;
+  }
+  if (data.byteLength < SPZ_HEADER_BYTE_LENGTH) {
+    throw new Error('SPZLoader: file must contain a 32-byte header.');
+  }
+  return new DataView(data).getUint32(4, true);
+}
+
+/** Decodes the single-stream SPZ v2/v3 container. */
+async function parseLegacySPZ(
+  data: ArrayBuffer,
+  options?: SplatsLoaderOptions
+): Promise<GaussianSplats> {
+  const decompressed = await new GZipDecompressor({
+    modules: options?.modules,
+    useNative: true
+  }).decompress(data);
+  if (decompressed.byteLength < 16) {
+    throw new Error('SPZLoader: legacy payload must contain a 16-byte header.');
+  }
+  const dataView = new DataView(decompressed);
+  const header = {
+    magic: dataView.getUint32(0, true),
+    version: dataView.getUint32(4, true),
+    numPoints: dataView.getUint32(8, true),
+    shDegree: dataView.getUint8(12),
+    fractionalBits: dataView.getUint8(13),
+    flags: dataView.getUint8(14)
+  };
+  if (header.magic !== SPZ_MAGIC) {
+    throw new Error('SPZLoader: NGSP magic header not found.');
+  }
+  if (header.version !== 2 && header.version !== 3) {
+    throw new Error(`SPZLoader: version ${header.version} is not supported.`);
+  }
+  if (dataView.getUint8(15) !== 0) {
+    throw new Error('SPZLoader: legacy header reserved byte must be zero.');
+  }
+  if (header.shDegree > 3) {
+    throw new Error(`SPZLoader: spherical harmonics degree ${header.shDegree} is not supported.`);
+  }
+
+  const count = header.numPoints;
+  const shComponentCount = getSphericalHarmonicsComponentCount(header.shDegree);
+  const positionByteLength = count * 9;
+  const alphaByteLength = count;
+  const colorByteLength = count * 3;
+  const scaleByteLength = count * 3;
+  const rotationByteLength = count * (header.version === 2 ? 3 : 4);
+  const shByteLength = count * shComponentCount;
+  const payloadByteLength =
+    positionByteLength +
+    alphaByteLength +
+    colorByteLength +
+    scaleByteLength +
+    rotationByteLength +
+    shByteLength;
+  if (decompressed.byteLength - 16 !== payloadByteLength) {
+    throw new Error(
+      `SPZLoader: legacy payload has ${decompressed.byteLength - 16} bytes, expected ${payloadByteLength}.`
+    );
+  }
+
+  let offset = 16;
+  const positions = new Float32Array(count * 3);
+  const opacities = new Float32Array(count);
+  const colors = new Uint8Array(count * 3);
+  const scales = new Float32Array(count * 3);
+  const rotations = new Float32Array(count * 4);
+  const sphericalHarmonicDcs = new Float32Array(count * 3);
+  const sphericalHarmonics = shComponentCount
+    ? new Float32Array(count * shComponentCount)
+    : undefined;
+  decodeSPZPositions(
+    new Uint8Array(decompressed, offset, positionByteLength),
+    positions,
+    header.fractionalBits
+  );
+  offset += positionByteLength;
+  decodeSPZOpacities(new Uint8Array(decompressed, offset, alphaByteLength), opacities);
+  offset += alphaByteLength;
+  decodeSPZColors(
+    new Uint8Array(decompressed, offset, colorByteLength),
+    colors,
+    sphericalHarmonicDcs
+  );
+  offset += colorByteLength;
+  decodeSPZScales(new Uint8Array(decompressed, offset, scaleByteLength), scales);
+  offset += scaleByteLength;
+  if (header.version === 2) {
+    decodeLegacySPZRotations(new Uint8Array(decompressed, offset, rotationByteLength), rotations);
+  } else {
+    decodeSPZRotations(new Uint8Array(decompressed, offset, rotationByteLength), rotations);
+  }
+  offset += rotationByteLength;
+  if (sphericalHarmonics) {
+    decodeSPZSphericalHarmonics(
+      new Uint8Array(decompressed, offset, shByteLength),
+      sphericalHarmonics
+    );
+  }
+
+  return applySPZCoordinateSystem(
+    {
+      format: 'spz',
+      splatCount: count,
+      positions,
+      scales,
+      rotations,
+      colors,
+      sphericalHarmonicDcs,
+      opacities,
+      sphericalHarmonics,
+      sphericalHarmonicsComponentCount: shComponentCount || undefined,
+      loaderData: {...header, legacy: true}
+    },
+    options?.splats?.sourceCoordinateSystem ?? 'RUB',
+    options?.splats?.targetCoordinateSystem ?? options?.splats?.sourceCoordinateSystem ?? 'RUB'
+  );
+}
+
+/** Decodes the three signed bytes used by SPZ v2 rotations. */
+function decodeLegacySPZRotations(rotationStream: Uint8Array, rotations: Float32Array): void {
+  for (let splatIndex = 0; splatIndex < rotations.length / 4; splatIndex++) {
+    const byteOffset = splatIndex * 3;
+    const x = signedByte(rotationStream[byteOffset]) / 127;
+    const y = signedByte(rotationStream[byteOffset + 1]) / 127;
+    const z = signedByte(rotationStream[byteOffset + 2]) / 127;
+    const w = Math.sqrt(Math.max(0, 1 - x * x - y * y - z * z));
+    const normalized = normalizeQuaternion(w, x, y, z);
+    rotations.set(normalized, splatIndex * 4);
+  }
+}
+
+/** Converts an unsigned byte containing a signed int8 value. */
+function signedByte(value: number): number {
+  return value > 127 ? value - 256 : value;
+}
+
+/** Applies the explicitly requested SPZ coordinate conversion. */
+function applySPZCoordinateSystem(
+  splats: GaussianSplats,
+  source: SPZCoordinateSystem,
+  target: SPZCoordinateSystem
+): GaussianSplats {
+  if (source === target || source === 'UNSPECIFIED' || target === 'UNSPECIFIED') {
+    return splats;
+  }
+  if (source === 'RUB' && target === 'LUF') {
+    for (let index = 0; index < splats.positions.length; index += 3) {
+      splats.positions[index] = -splats.positions[index];
+      splats.positions[index + 2] = -splats.positions[index + 2];
+    }
+    for (let index = 0; index < splats.rotations.length; index += 4) {
+      splats.rotations[index + 1] = -splats.rotations[index + 1];
+      splats.rotations[index + 3] = -splats.rotations[index + 3];
+    }
+    return splats;
+  }
+  if (source === 'LUF' && target === 'RUB') {
+    return applySPZCoordinateSystem(splats, 'RUB', 'LUF');
+  }
+  throw new Error(`SPZLoader: coordinate conversion ${source} -> ${target} is not supported.`);
 }
 
 /** Parses and validates the SPZ v4 plaintext header. */

package/src/rad-zod-schema.ts

@@ -0,0 +1,83 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {z} from 'zod';
+import type {
+  RADChunkMetadataJSON,
+  RADChunkProperty,
+  RADChunkRange,
+  RADMetadataJSON,
+  RADSplatEncoding
+} from './lib/parse-rad';
+
+const nonNegativeSafeIntegerSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+
+/** Zod schema for Spark RAD splat quantization and shader decode ranges. */
+export const RADSplatEncodingSchema = z
+  .object({
+    rgbMin: z.number().finite().optional(),
+    rgbMax: z.number().finite().optional(),
+    lnScaleMin: z.number().finite().optional(),
+    lnScaleMax: z.number().finite().optional(),
+    sh1Max: z.number().finite().optional(),
+    sh2Max: z.number().finite().optional(),
+    sh3Max: z.number().finite().optional(),
+    lodOpacity: z.boolean().optional()
+  })
+  .passthrough() satisfies z.ZodType<RADSplatEncoding>;
+
+/** Zod schema for one chunk-table entry in top-level RAD metadata. */
+export const RADChunkRangeSchema = z
+  .object({
+    offset: nonNegativeSafeIntegerSchema,
+    bytes: nonNegativeSafeIntegerSchema,
+    base: nonNegativeSafeIntegerSchema.optional(),
+    count: nonNegativeSafeIntegerSchema.optional(),
+    filename: z.string().optional()
+  })
+  .passthrough() satisfies z.ZodType<RADChunkRange>;
+
+/** Zod schema for raw JSON metadata stored in a Spark RAD header. */
+export const RADMetadataJSONSchema = z
+  .object({
+    version: z.literal(1),
+    type: z.literal('gsplat'),
+    count: nonNegativeSafeIntegerSchema,
+    maxSh: nonNegativeSafeIntegerSchema.optional(),
+    lodTree: z.boolean().optional(),
+    chunkSize: nonNegativeSafeIntegerSchema.optional(),
+    allChunkBytes: nonNegativeSafeIntegerSchema.optional(),
+    chunks: z.array(RADChunkRangeSchema),
+    splatEncoding: RADSplatEncodingSchema.optional(),
+    shCodeCount: nonNegativeSafeIntegerSchema.optional(),
+    comment: z.string().optional()
+  })
+  .passthrough() satisfies z.ZodType<RADMetadataJSON>;
+
+/** Zod schema for one property-table entry in RADC metadata. */
+export const RADChunkPropertySchema = z
+  .object({
+    offset: nonNegativeSafeIntegerSchema,
+    bytes: nonNegativeSafeIntegerSchema,
+    property: z.string(),
+    encoding: z.string(),
+    compression: z.string().optional(),
+    min: z.number().finite().optional(),
+    max: z.number().finite().optional()
+  })
+  .passthrough() satisfies z.ZodType<RADChunkProperty>;
+
+/** Zod schema for raw JSON metadata stored in a Spark RADC chunk header. */
+export const RADChunkMetadataJSONSchema = z
+  .object({
+    version: z.literal(1),
+    base: nonNegativeSafeIntegerSchema,
+    count: nonNegativeSafeIntegerSchema,
+    payloadBytes: nonNegativeSafeIntegerSchema,
+    maxSh: nonNegativeSafeIntegerSchema.optional(),
+    lodTree: z.boolean().optional(),
+    splatEncoding: RADSplatEncodingSchema.optional(),
+    properties: z.array(RADChunkPropertySchema)
+  })
+  .passthrough() satisfies z.ZodType<RADChunkMetadataJSON>;

package/src/types.ts

@@ -9,9 +9,16 @@ export type SplatsLoaderOptions = LoaderOptions & {
   splats?: {
     /** Output shape. V1 supports loaders.gl Mesh Arrow tables. */
     shape?: 'arrow-table';
+    /** Coordinate frame stored in the source SPZ payload. */
+    sourceCoordinateSystem?: SPZCoordinateSystem;
+    /** Coordinate frame expected by the caller. Defaults to the source frame. */
+    targetCoordinateSystem?: SPZCoordinateSystem;
   };
 };
 
+/** Coordinate-system labels used by the SPZ container and glTF bridge. */
+export type SPZCoordinateSystem = 'RUB' | 'LUF' | 'RUF' | 'UNSPECIFIED';
+
 /** Linear Gaussian splat values before Arrow table construction. */
 export type GaussianSplats = {
   /** Source format identifier. */