@loaders.gl/splats 5.0.0-alpha.1

package/src/lib/parse-spz.ts

@@ -0,0 +1,368 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ZstdCompression} from '@loaders.gl/compression';
+import type {MeshArrowTable} from '@loaders.gl/schema';
+import type {GaussianSplats, SplatsLoaderOptions} from '../types';
+import {makeGaussianSplatsArrowTable} from './splats-arrow-table';
+import {normalizeQuaternion} from './splat-utils';
+
+const SPZ_HEADER_BYTE_LENGTH = 32;
+const SPZ_MAGIC = 0x5053474e;
+const SPZ_VERSION = 4;
+const SPZ_EXTENSION_FLAG = 0x2;
+const SPZ_COLOR_SCALE = 0.15;
+const SPZ_ROTATION_COMPONENT_SCALE = Math.SQRT1_2;
+const SPZ_ROTATION_COMPONENT_MASK = (1 << 9) - 1;
+
+type SPZHeader = {
+  magic: number;
+  version: number;
+  numPoints: number;
+  shDegree: number;
+  fractionalBits: number;
+  flags: number;
+  numStreams: number;
+  tocByteOffset: number;
+};
+
+type SPZStreamInfo = {
+  compressedSize: number;
+  uncompressedSize: number;
+  compressedOffset: number;
+};
+
+/** Parses a Niantic Spatial `.spz` ArrayBuffer into a Mesh Arrow table. */
+export async function parseSPZ(
+  data: ArrayBuffer,
+  options?: SplatsLoaderOptions
+): Promise<MeshArrowTable> {
+  return makeGaussianSplatsArrowTable(await parseSPZToGaussianSplats(data, options));
+}
+
+/** Parses a Niantic Spatial `.spz` ArrayBuffer into decoded Gaussian splat values. */
+export async function parseSPZToGaussianSplats(
+  data: ArrayBuffer,
+  options?: SplatsLoaderOptions
+): Promise<GaussianSplats> {
+  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 streams = await Promise.all(
+    compressedStreams.map((compressedStream, streamIndex) =>
+      compression.decompress(compressedStream, streamInfos[streamIndex].uncompressedSize)
+    )
+  );
+
+  validateSPZStreamLengths(streams, streamInfos);
+  return decodeSPZStreams(header, streams, data);
+}
+
+/** Parses and validates the SPZ v4 plaintext header. */
+function parseSPZHeader(data: ArrayBuffer): SPZHeader {
+  if (data.byteLength < SPZ_HEADER_BYTE_LENGTH) {
+    throw new Error(`SPZLoader: file must contain a ${SPZ_HEADER_BYTE_LENGTH}-byte header.`);
+  }
+
+  const dataView = new DataView(data);
+  const header: SPZHeader = {
+    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),
+    numStreams: dataView.getUint8(15),
+    tocByteOffset: dataView.getUint32(16, true)
+  };
+
+  if (header.magic !== SPZ_MAGIC) {
+    throw new Error('SPZLoader: NGSP magic header not found.');
+  }
+  if (header.version !== SPZ_VERSION) {
+    throw new Error(`SPZLoader: version ${header.version} is not supported.`);
+  }
+  if (header.shDegree > 4) {
+    throw new Error(`SPZLoader: spherical harmonics degree ${header.shDegree} is not supported.`);
+  }
+  if (header.tocByteOffset < SPZ_HEADER_BYTE_LENGTH || header.tocByteOffset > data.byteLength) {
+    throw new Error('SPZLoader: invalid table of contents byte offset.');
+  }
+
+  return header;
+}
+
+/** Parses the SPZ stream table of contents and validates expected stream sizes. */
+function parseSPZStreamInfos(
+  data: ArrayBuffer,
+  header: SPZHeader,
+  expectedUncompressedSizes: number[]
+): SPZStreamInfo[] {
+  if (header.numStreams !== expectedUncompressedSizes.length) {
+    throw new Error(
+      `SPZLoader: expected ${expectedUncompressedSizes.length} streams, found ${header.numStreams}.`
+    );
+  }
+
+  const tocByteLength = header.numStreams * 16;
+  const tocEnd = header.tocByteOffset + tocByteLength;
+  if (tocEnd > data.byteLength) {
+    throw new Error('SPZLoader: table of contents exceeds file byte length.');
+  }
+
+  const dataView = new DataView(data);
+  let compressedOffset = tocEnd;
+  const streamInfos: SPZStreamInfo[] = [];
+  for (let streamIndex = 0; streamIndex < header.numStreams; streamIndex++) {
+    const tocOffset = header.tocByteOffset + streamIndex * 16;
+    const compressedSize = readSafeUint64(dataView, tocOffset);
+    const uncompressedSize = readSafeUint64(dataView, tocOffset + 8);
+    const expectedUncompressedSize = expectedUncompressedSizes[streamIndex];
+
+    if (uncompressedSize !== expectedUncompressedSize) {
+      throw new Error(
+        `SPZLoader: stream ${streamIndex} has ${uncompressedSize} uncompressed bytes, expected ${expectedUncompressedSize}.`
+      );
+    }
+    if (compressedOffset + compressedSize > data.byteLength) {
+      throw new Error(`SPZLoader: stream ${streamIndex} exceeds file byte length.`);
+    }
+
+    streamInfos.push({compressedSize, uncompressedSize, compressedOffset});
+    compressedOffset += compressedSize;
+  }
+
+  if (compressedOffset !== data.byteLength) {
+    throw new Error('SPZLoader: compressed stream byte lengths do not match file byte length.');
+  }
+
+  return streamInfos;
+}
+
+/** Converts a little-endian uint64 to a safe JavaScript number. */
+function readSafeUint64(dataView: DataView, byteOffset: number): number {
+  const value = dataView.getBigUint64(byteOffset, true);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error('SPZLoader: stream byte length exceeds Number.MAX_SAFE_INTEGER.');
+  }
+  return Number(value);
+}
+
+/** Returns expected SPZ v4 stream byte lengths, skipping zero-length SH data. */
+function getSPZStreamByteLengths(header: SPZHeader): number[] {
+  return [
+    header.numPoints * 9,
+    header.numPoints,
+    header.numPoints * 3,
+    header.numPoints * 3,
+    header.numPoints * 4,
+    header.numPoints * getSphericalHarmonicsComponentCount(header.shDegree)
+  ].filter(byteLength => byteLength > 0);
+}
+
+/** Validates that decompressed stream lengths match the TOC. */
+function validateSPZStreamLengths(streams: ArrayBuffer[], streamInfos: SPZStreamInfo[]): void {
+  for (let streamIndex = 0; streamIndex < streams.length; streamIndex++) {
+    if (streams[streamIndex].byteLength !== streamInfos[streamIndex].uncompressedSize) {
+      throw new Error(`SPZLoader: decompressed stream ${streamIndex} has unexpected byte length.`);
+    }
+  }
+}
+
+/** Decodes decompressed SPZ streams into shared Gaussian splat arrays. */
+function decodeSPZStreams(
+  header: SPZHeader,
+  streams: ArrayBuffer[],
+  sourceData: ArrayBuffer
+): GaussianSplats {
+  const splatCount = header.numPoints;
+  const positions = new Float32Array(splatCount * 3);
+  const scales = new Float32Array(splatCount * 3);
+  const rotations = new Float32Array(splatCount * 4);
+  const colors = new Uint8Array(splatCount * 3);
+  const sphericalHarmonicDcs = new Float32Array(splatCount * 3);
+  const opacities = new Float32Array(splatCount);
+  const sphericalHarmonicsComponentCount = getSphericalHarmonicsComponentCount(header.shDegree);
+  const sphericalHarmonics = sphericalHarmonicsComponentCount
+    ? new Float32Array(splatCount * sphericalHarmonicsComponentCount)
+    : undefined;
+  const [
+    positionStream,
+    alphaStream,
+    colorStream,
+    scaleStream,
+    rotationStream,
+    sphericalHarmonicsStream
+  ] = streams.map(stream => new Uint8Array(stream));
+
+  decodeSPZPositions(positionStream, positions, header.fractionalBits);
+  decodeSPZScales(scaleStream, scales);
+  decodeSPZRotations(rotationStream, rotations);
+  decodeSPZColors(colorStream, colors, sphericalHarmonicDcs);
+  decodeSPZOpacities(alphaStream, opacities);
+  if (sphericalHarmonics && sphericalHarmonicsStream) {
+    decodeSPZSphericalHarmonics(sphericalHarmonicsStream, sphericalHarmonics);
+  }
+
+  return {
+    format: 'spz',
+    splatCount,
+    positions,
+    scales,
+    rotations,
+    colors,
+    sphericalHarmonicDcs,
+    opacities,
+    sphericalHarmonics,
+    sphericalHarmonicsComponentCount,
+    loaderData: {
+      format: 'spz',
+      ...header,
+      antialiased: Boolean(header.flags & 0x1),
+      extensionByteLength: getSPZExtensionByteLength(header),
+      extensionBytes: getSPZExtensionBytes(sourceData, header)
+    }
+  };
+}
+
+/** Decodes 24-bit signed fixed-point SPZ positions. */
+function decodeSPZPositions(
+  positionStream: Uint8Array,
+  positions: Float32Array,
+  fractionalBits: number
+): void {
+  const scale = 1 / 2 ** fractionalBits;
+  for (let componentIndex = 0; componentIndex < positions.length; componentIndex++) {
+    const byteOffset = componentIndex * 3;
+    let fixed32 =
+      positionStream[byteOffset] |
+      (positionStream[byteOffset + 1] << 8) |
+      (positionStream[byteOffset + 2] << 16);
+    fixed32 |= fixed32 & 0x800000 ? 0xff000000 : 0;
+    positions[componentIndex] = fixed32 * scale;
+  }
+}
+
+/** Decodes SPZ log-encoded scales to linear standard deviations. */
+function decodeSPZScales(scaleStream: Uint8Array, scales: Float32Array): void {
+  for (let componentIndex = 0; componentIndex < scales.length; componentIndex++) {
+    scales[componentIndex] = Math.exp(scaleStream[componentIndex] / 16 - 10);
+  }
+}
+
+/** Decodes SPZ smallest-three quaternion rotations into `[w, x, y, z]` order. */
+function decodeSPZRotations(rotationStream: Uint8Array, rotations: Float32Array): void {
+  for (let splatIndex = 0; splatIndex < rotations.length / 4; splatIndex++) {
+    const byteOffset = splatIndex * 4;
+    const component =
+      rotationStream[byteOffset] |
+      (rotationStream[byteOffset + 1] << 8) |
+      (rotationStream[byteOffset + 2] << 16) |
+      (rotationStream[byteOffset + 3] << 24);
+    const xyzw = decodeSPZQuaternion(component >>> 0);
+    const [w, x, y, z] = normalizeQuaternion(xyzw[3], xyzw[0], xyzw[1], xyzw[2]);
+    const rotationOffset = splatIndex * 4;
+    rotations[rotationOffset + 0] = w;
+    rotations[rotationOffset + 1] = x;
+    rotations[rotationOffset + 2] = y;
+    rotations[rotationOffset + 3] = z;
+  }
+}
+
+/** Decodes one SPZ smallest-three quaternion into `[x, y, z, w]` order. */
+function decodeSPZQuaternion(component: number): [number, number, number, number] {
+  const rotation: [number, number, number, number] = [0, 0, 0, 0];
+  const largestComponent = component >>> 30;
+  let remainingBits = component;
+  let sumSquares = 0;
+
+  for (let componentIndex = 3; componentIndex >= 0; componentIndex--) {
+    if (componentIndex !== largestComponent) {
+      const magnitude = remainingBits & SPZ_ROTATION_COMPONENT_MASK;
+      const isNegative = (remainingBits >>> 9) & 0x1;
+      remainingBits >>>= 10;
+      let value = (SPZ_ROTATION_COMPONENT_SCALE * magnitude) / SPZ_ROTATION_COMPONENT_MASK;
+      if (isNegative) {
+        value = -value;
+      }
+      rotation[componentIndex] = value;
+      sumSquares += value * value;
+    }
+  }
+
+  rotation[largestComponent] = Math.sqrt(Math.max(0, 1 - sumSquares));
+  return rotation;
+}
+
+/** Decodes SPZ color bytes into display RGB bytes and direct SH DC coefficients. */
+function decodeSPZColors(
+  colorStream: Uint8Array,
+  colors: Uint8Array,
+  sphericalHarmonicDcs: Float32Array
+): void {
+  for (let componentIndex = 0; componentIndex < colors.length; componentIndex++) {
+    sphericalHarmonicDcs[componentIndex] =
+      (colorStream[componentIndex] / 255 - 0.5) / SPZ_COLOR_SCALE;
+    colors[componentIndex] = normalizeColorByte(sphericalHarmonicDcs[componentIndex]);
+  }
+}
+
+/** Decodes SPZ alpha bytes into linear opacity. */
+function decodeSPZOpacities(alphaStream: Uint8Array, opacities: Float32Array): void {
+  for (let splatIndex = 0; splatIndex < opacities.length; splatIndex++) {
+    opacities[splatIndex] = alphaStream[splatIndex] / 255;
+  }
+}
+
+/** Decodes SPZ quantized SH rest coefficients. */
+function decodeSPZSphericalHarmonics(
+  sphericalHarmonicsStream: Uint8Array,
+  sphericalHarmonics: Float32Array
+): void {
+  for (let componentIndex = 0; componentIndex < sphericalHarmonics.length; componentIndex++) {
+    sphericalHarmonics[componentIndex] = (sphericalHarmonicsStream[componentIndex] - 128) / 128;
+  }
+}
+
+/** Converts an SH DC coefficient to a fallback RGB byte for preview paths. */
+function normalizeColorByte(sphericalHarmonicDc: number): number {
+  return Math.min(
+    Math.max(Math.round((sphericalHarmonicDc * SPZ_COLOR_SCALE + 0.5) * 255), 0),
+    255
+  );
+}
+
+/** Returns the number of SH rest coefficients per splat for an SPZ degree. */
+function getSphericalHarmonicsComponentCount(shDegree: number): number {
+  switch (shDegree) {
+    case 0:
+      return 0;
+    case 1:
+      return 9;
+    case 2:
+      return 24;
+    case 3:
+      return 45;
+    case 4:
+      return 72;
+    default:
+      throw new Error(`SPZLoader: spherical harmonics degree ${shDegree} is not supported.`);
+  }
+}
+
+/** Returns the plaintext SPZ extension byte count. */
+function getSPZExtensionByteLength(header: SPZHeader): number {
+  return header.flags & SPZ_EXTENSION_FLAG ? header.tocByteOffset - SPZ_HEADER_BYTE_LENGTH : 0;
+}
+
+/** Returns a copy of plaintext SPZ extension bytes when extension records are present. */
+function getSPZExtensionBytes(data: ArrayBuffer, header: SPZHeader): Uint8Array | undefined {
+  const extensionByteLength = getSPZExtensionByteLength(header);
+  return extensionByteLength
+    ? new Uint8Array(data.slice(SPZ_HEADER_BYTE_LENGTH, header.tocByteOffset))
+    : undefined;
+}

package/src/lib/splat-utils.ts

@@ -0,0 +1,49 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export const SH_C0 = 0.28209479177387814;
+
+/** Converts a normalized RGB value to a spherical harmonic DC coefficient. */
+export function convertColorByteToSphericalHarmonicDc(colorByte: number): number {
+  return (colorByte / 255 - 0.5) / SH_C0;
+}
+
+/** Converts an unorm8 alpha byte to linear opacity. */
+export function convertAlphaByteToLinearOpacity(alphaByte: number): number {
+  return Math.min(Math.max(alphaByte / 255, 0), 1);
+}
+
+/** Returns a normalized quaternion, falling back to identity when invalid. */
+export function normalizeQuaternion(
+  w: number,
+  x: number,
+  y: number,
+  z: number
+): [number, number, number, number] {
+  const length = Math.hypot(w, x, y, z);
+  if (!Number.isFinite(length) || length <= Number.EPSILON) {
+    return [1, 0, 0, 0];
+  }
+  return [w / length, x / length, y / length, z / length];
+}
+
+/** Decodes the GaussianSplats3D uint8 quaternion component encoding. */
+export function decodeQuaternionByte(byte: number): number {
+  return (byte - 128) / 128;
+}
+
+/** Decodes an IEEE 754 binary16 value. */
+export function decodeFloat16(value: number): number {
+  const sign = value & 0x8000 ? -1 : 1;
+  const exponent = (value >> 10) & 0x1f;
+  const fraction = value & 0x03ff;
+
+  if (exponent === 0) {
+    return sign * Math.pow(2, -14) * (fraction / 1024);
+  }
+  if (exponent === 0x1f) {
+    return fraction ? Number.NaN : sign * Number.POSITIVE_INFINITY;
+  }
+  return sign * Math.pow(2, exponent - 15) * (1 + fraction / 1024);
+}

package/src/lib/splats-arrow-table.ts

@@ -0,0 +1,188 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import * as arrow from 'apache-arrow';
+import type {Field, MeshArrowTable, Schema} from '@loaders.gl/schema';
+import type {GaussianSplats} from '../types';
+import {convertColorByteToSphericalHarmonicDc} from './splat-utils';
+
+/** Builds a Mesh Arrow table from decoded Gaussian splat values. */
+export function makeGaussianSplatsArrowTable(splats: GaussianSplats): MeshArrowTable {
+  const columns: Record<string, arrow.Vector> = {};
+  const fields: arrow.Field[] = [];
+  const schemaFields: Field[] = [];
+
+  addColumn(
+    columns,
+    fields,
+    schemaFields,
+    'POSITION',
+    makeFixedSizeListVector(splats.positions, 3),
+    {
+      type: 'fixed-size-list',
+      listSize: 3,
+      children: [{name: 'value', type: 'float32'}]
+    }
+  );
+
+  const colorCoefficients = getColorCoefficients(splats);
+  addScalarColumn(columns, fields, schemaFields, 'f_dc_0', colorCoefficients[0], {
+    'loaders_gl.gaussian_splats.semantic': 'spherical_harmonic_dc',
+    'loaders_gl.gaussian_splats.component': '0',
+    'loaders_gl.gaussian_splats.encoding': 'coefficient'
+  });
+  addScalarColumn(columns, fields, schemaFields, 'f_dc_1', colorCoefficients[1], {
+    'loaders_gl.gaussian_splats.semantic': 'spherical_harmonic_dc',
+    'loaders_gl.gaussian_splats.component': '1',
+    'loaders_gl.gaussian_splats.encoding': 'coefficient'
+  });
+  addScalarColumn(columns, fields, schemaFields, 'f_dc_2', colorCoefficients[2], {
+    'loaders_gl.gaussian_splats.semantic': 'spherical_harmonic_dc',
+    'loaders_gl.gaussian_splats.component': '2',
+    'loaders_gl.gaussian_splats.encoding': 'coefficient'
+  });
+
+  addScalarColumn(columns, fields, schemaFields, 'opacity', splats.opacities, {
+    'loaders_gl.gaussian_splats.semantic': 'opacity',
+    'loaders_gl.gaussian_splats.encoding': 'linear'
+  });
+  addVectorComponents(columns, fields, schemaFields, 'scale', splats.scales, 3, {
+    'loaders_gl.gaussian_splats.semantic': 'scale',
+    'loaders_gl.gaussian_splats.encoding': 'linear'
+  });
+  addVectorComponents(columns, fields, schemaFields, 'rot', splats.rotations, 4, {
+    'loaders_gl.gaussian_splats.semantic': 'rotation',
+    'loaders_gl.gaussian_splats.encoding': 'quaternion'
+  });
+
+  if (splats.sphericalHarmonics && splats.sphericalHarmonicsComponentCount) {
+    addSphericalHarmonicRestColumns(
+      columns,
+      fields,
+      schemaFields,
+      splats.sphericalHarmonics,
+      splats.sphericalHarmonicsComponentCount
+    );
+  }
+
+  const metadata = new Map<string, string>([
+    ['loaders_gl.semantic_type', 'gaussian-splats'],
+    ['loaders_gl.gaussian_splats.version', '1'],
+    ['loaders_gl.gaussian_splats.source_format', splats.format],
+    ['topology', 'point-list'],
+    ['mode', '0']
+  ]);
+  const arrowSchema = new arrow.Schema(fields, metadata);
+  const schema: Schema = {
+    fields: schemaFields,
+    metadata: Object.fromEntries(metadata)
+  };
+
+  return {
+    shape: 'arrow-table',
+    schema,
+    data: new arrow.Table(arrowSchema, columns),
+    topology: 'point-list',
+    loaderData: splats.loaderData
+  } as MeshArrowTable;
+}
+
+/** Adds one scalar Arrow column per component of an interleaved vector array. */
+function addVectorComponents(
+  columns: Record<string, arrow.Vector>,
+  fields: arrow.Field[],
+  schemaFields: Field[],
+  prefix: string,
+  values: Float32Array,
+  size: number,
+  metadata: Record<string, string>
+): void {
+  for (let component = 0; component < size; component++) {
+    const componentValues = new Float32Array(values.length / size);
+    for (let rowIndex = 0; rowIndex < componentValues.length; rowIndex++) {
+      componentValues[rowIndex] = values[rowIndex * size + component];
+    }
+    addScalarColumn(columns, fields, schemaFields, `${prefix}_${component}`, componentValues, {
+      ...metadata,
+      'loaders_gl.gaussian_splats.component': String(component)
+    });
+  }
+}
+
+/** Adds one scalar Arrow column per spherical harmonic rest component. */
+function addSphericalHarmonicRestColumns(
+  columns: Record<string, arrow.Vector>,
+  fields: arrow.Field[],
+  schemaFields: Field[],
+  sphericalHarmonics: Float32Array,
+  componentCount: number
+): void {
+  for (let component = 0; component < componentCount; component++) {
+    const componentValues = new Float32Array(sphericalHarmonics.length / componentCount);
+    for (let rowIndex = 0; rowIndex < componentValues.length; rowIndex++) {
+      componentValues[rowIndex] = sphericalHarmonics[rowIndex * componentCount + component];
+    }
+    addScalarColumn(columns, fields, schemaFields, `f_rest_${component}`, componentValues, {
+      'loaders_gl.gaussian_splats.semantic': 'spherical_harmonic_rest',
+      'loaders_gl.gaussian_splats.component': String(component),
+      'loaders_gl.gaussian_splats.encoding': 'coefficient'
+    });
+  }
+}
+
+/** Adds a Float32 scalar Arrow column and matching loaders.gl schema field. */
+function addScalarColumn(
+  columns: Record<string, arrow.Vector>,
+  fields: arrow.Field[],
+  schemaFields: Field[],
+  name: string,
+  values: Float32Array,
+  metadata: Record<string, string>
+): void {
+  addColumn(columns, fields, schemaFields, name, arrow.makeVector(values), 'float32', metadata);
+}
+
+/** Adds an Arrow column, Arrow field, and loaders.gl schema field. */
+function addColumn(
+  columns: Record<string, arrow.Vector>,
+  fields: arrow.Field[],
+  schemaFields: Field[],
+  name: string,
+  column: arrow.Vector,
+  schemaType: Field['type'],
+  metadata: Record<string, string> = {}
+): void {
+  columns[name] = column;
+  fields.push(new arrow.Field(name, column.type, false, new Map(Object.entries(metadata))));
+  schemaFields.push({name, type: schemaType, nullable: false, metadata});
+}
+
+/** Builds a FixedSizeList Arrow vector from an interleaved Float32 array. */
+function makeFixedSizeListVector(value: Float32Array, size: number): arrow.Vector {
+  const values = arrow.makeVector(value);
+  const child = values.data[0];
+  const type = new arrow.FixedSizeList(size, new arrow.Field('value', child.type, false));
+  const data = new arrow.Data(type, 0, value.length / size, 0, {}, [child]);
+  return new arrow.Vector([data]);
+}
+
+/** Returns separate SH DC coefficient arrays from direct coefficients or RGB bytes. */
+function getColorCoefficients(splats: GaussianSplats): [Float32Array, Float32Array, Float32Array] {
+  const rowCount = splats.splatCount;
+  const fdc0 = new Float32Array(rowCount);
+  const fdc1 = new Float32Array(rowCount);
+  const fdc2 = new Float32Array(rowCount);
+  for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+    if (splats.sphericalHarmonicDcs) {
+      fdc0[rowIndex] = splats.sphericalHarmonicDcs[rowIndex * 3 + 0];
+      fdc1[rowIndex] = splats.sphericalHarmonicDcs[rowIndex * 3 + 1];
+      fdc2[rowIndex] = splats.sphericalHarmonicDcs[rowIndex * 3 + 2];
+    } else {
+      fdc0[rowIndex] = convertColorByteToSphericalHarmonicDc(splats.colors[rowIndex * 3 + 0]);
+      fdc1[rowIndex] = convertColorByteToSphericalHarmonicDc(splats.colors[rowIndex * 3 + 1]);
+      fdc2[rowIndex] = convertColorByteToSphericalHarmonicDc(splats.colors[rowIndex * 3 + 2]);
+    }
+  }
+  return [fdc0, fdc1, fdc2];
+}

package/src/rad-loader-types.ts

@@ -0,0 +1,27 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Loader, LoaderOptions} from '@loaders.gl/loader-utils';
+import {RADFormat} from './splats-format';
+import type {RADMetadata} from './lib/parse-rad';
+
+// __VERSION__ is injected by babel-plugin-version-inline
+// @ts-ignore TS2304: Cannot find name '__VERSION__'.
+const VERSION = typeof __VERSION__ !== 'undefined' ? __VERSION__ : 'latest';
+
+/** Preloads the parser-bearing RAD loader implementation. */
+async function preload() {
+  const {RADLoaderWithParser} = await import('./rad-loader');
+  return RADLoaderWithParser;
+}
+
+/** Metadata-only loader for Spark `.rad` paged LoD Gaussian splat containers. */
+export const RADLoader = {
+  dataType: null as unknown as RADMetadata,
+  batchType: null as never,
+  ...RADFormat,
+  version: VERSION,
+  options: {},
+  preload
+} as const satisfies Loader<RADMetadata, never, LoaderOptions>;

package/src/rad-loader.ts

@@ -0,0 +1,24 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import {parseRADHeader} from './lib/parse-rad';
+import type {RADMetadata} from './lib/parse-rad';
+import {RADLoader as RADLoaderMetadata} from './rad-loader-types';
+
+export {parseRADChunkHeader, parseRADHeader, tryParseRADHeader} from './lib/parse-rad';
+export {
+  parseRADChunk,
+  parseRADChunkToGaussianSplats,
+  type RADChunkDecodeOptions
+} from './lib/parse-rad-chunk';
+
+const {preload: _RADLoaderPreload, ...RADLoaderMetadataWithoutPreload} = RADLoaderMetadata;
+
+/** Parser-bearing loader for Spark `.rad` paged LoD Gaussian splat container metadata. */
+export const RADLoaderWithParser = {
+  ...RADLoaderMetadataWithoutPreload,
+  parse: async (arrayBuffer: ArrayBuffer) => parseRADHeader(arrayBuffer),
+  parseSync: (arrayBuffer: ArrayBuffer) => parseRADHeader(arrayBuffer)
+} as const satisfies LoaderWithParser<RADMetadata, never, LoaderOptions>;