@sparkjsdev/spark 0.1.0

package/dist/types/splatConstructors.d.ts

@@ -0,0 +1,46 @@
+import { PackedSplats } from './PackedSplats';
+import { SplatMesh } from './SplatMesh';
+import * as THREE from "three";
+export declare function constructGrid({ splats, extents, stepSize, pointRadius, pointShadowScale, opacity, color, }: {
+    splats: PackedSplats;
+    extents: THREE.Box3;
+    stepSize?: number;
+    pointRadius?: number;
+    pointShadowScale?: number;
+    opacity?: number;
+    color?: THREE.Color | ((color: THREE.Color, point: THREE.Vector3) => void);
+}): void;
+export declare function constructAxes({ splats, scale, axisRadius, axisShadowScale, origins, }: {
+    splats: PackedSplats;
+    scale?: number;
+    axisRadius?: number;
+    axisShadowScale?: number;
+    origins?: THREE.Vector3[];
+}): void;
+export declare function constructSpherePoints({ splats, origin, radius, maxDepth, filter, pointRadius, pointThickness, color, }: {
+    splats: PackedSplats;
+    origin?: THREE.Vector3;
+    radius?: number;
+    maxDepth?: number;
+    filter?: ((point: THREE.Vector3) => boolean) | null;
+    pointRadius?: number;
+    pointThickness?: number;
+    color?: THREE.Color | ((color: THREE.Color, point: THREE.Vector3) => void);
+}): void;
+export declare function textSplats({ text, font, fontSize, color, rgb, dotRadius, textAlign, lineHeight, objectScale, }: {
+    text: string;
+    font?: string;
+    fontSize?: number;
+    color?: THREE.Color;
+    rgb?: THREE.Color;
+    dotRadius?: number;
+    textAlign?: "left" | "center" | "right" | "start" | "end";
+    lineHeight?: number;
+    objectScale?: number;
+}): SplatMesh;
+export declare function imageSplats({ url, dotRadius, subXY, forEachSplat, }: {
+    url: string;
+    dotRadius?: number;
+    subXY?: number;
+    forEachSplat?: (width: number, height: number, index: number, center: THREE.Vector3, scales: THREE.Vector3, quaternion: THREE.Quaternion, opacity: number, color: THREE.Color) => number | null;
+}): SplatMesh;

package/dist/types/splatWorker.d.ts

@@ -0,0 +1,20 @@
+export declare class SplatWorker {
+    worker: Worker;
+    messages: Record<number, {
+        resolve: (value: unknown) => void;
+        reject: (reason?: unknown) => void;
+    }>;
+    messageIdNext: number;
+    constructor();
+    makeMessageId(): number;
+    makeMessagePromiseId(): {
+        id: number;
+        promise: Promise<unknown>;
+    };
+    onMessage(event: MessageEvent): void;
+    call(name: string, args: unknown): Promise<unknown>;
+}
+export declare function setWorkerPool(count?: number): void;
+export declare function allocWorker(): Promise<SplatWorker>;
+export declare function freeWorker(worker: SplatWorker): void;
+export declare function withWorker<T>(callback: (worker: SplatWorker) => Promise<T>): Promise<T>;

package/dist/types/spz.d.ts

@@ -0,0 +1,50 @@
+import { TranscodeSpzInput } from './SplatLoader';
+import { GunzipReader } from './utils';
+export declare class SpzReader {
+    fileBytes: Uint8Array;
+    reader: GunzipReader;
+    version: number;
+    numSplats: number;
+    shDegree: number;
+    fractionalBits: number;
+    flags: number;
+    flagAntiAlias: boolean;
+    reserved: number;
+    parsed: boolean;
+    constructor({ fileBytes }: {
+        fileBytes: Uint8Array | ArrayBuffer;
+    });
+    parseSplats(centerCallback?: (index: number, x: number, y: number, z: number) => void, alphaCallback?: (index: number, alpha: number) => void, rgbCallback?: (index: number, r: number, g: number, b: number) => void, scalesCallback?: (index: number, scaleX: number, scaleY: number, scaleZ: number) => void, quatCallback?: (index: number, quatX: number, quatY: number, quatZ: number, quatW: number) => void, shCallback?: (index: number, sh1: Float32Array, sh2?: Float32Array, sh3?: Float32Array) => void): void;
+}
+export declare const SPZ_MAGIC = 1347635022;
+export declare const SPZ_VERSION = 2;
+export declare const FLAG_ANTIALIASED = 1;
+export declare class SpzWriter {
+    buffer: ArrayBuffer;
+    view: DataView;
+    numSplats: number;
+    shDegree: number;
+    fractionalBits: number;
+    fraction: number;
+    flagAntiAlias: boolean;
+    clippedCount: number;
+    constructor({ numSplats, shDegree, fractionalBits, flagAntiAlias, }: {
+        numSplats: number;
+        shDegree: number;
+        fractionalBits?: number;
+        flagAntiAlias?: boolean;
+    });
+    setCenter(index: number, x: number, y: number, z: number): void;
+    setAlpha(index: number, alpha: number): void;
+    static scaleRgb(r: number): number;
+    setRgb(index: number, r: number, g: number, b: number): void;
+    setScale(index: number, scaleX: number, scaleY: number, scaleZ: number): void;
+    setQuat(index: number, quatX: number, quatY: number, quatZ: number, quatW: number): void;
+    static quantizeSh(sh: number, bits: number): number;
+    setSh(index: number, sh1: Float32Array, sh2?: Float32Array, sh3?: Float32Array): void;
+    finalize(): Promise<Uint8Array>;
+}
+export declare function transcodeSpz(input: TranscodeSpzInput): Promise<{
+    fileBytes: Uint8Array<ArrayBufferLike>;
+    clippedCount: number;
+}>;

package/dist/types/utils.d.ts

@@ -0,0 +1,150 @@
+import { Gunzip } from 'fflate';
+import * as THREE from "three";
+export declare function floatBitsToUint(f: number): number;
+export declare function uintBitsToFloat(u: number): number;
+export declare function toHalf(f: number): number;
+export declare function fromHalf(h: number): number;
+export declare function floatToUint8(v: number): number;
+export declare function floatToSint8(v: number): number;
+export declare function Uint8ToFloat(v: number): number;
+export declare function Sint8ToFloat(v: number): number;
+export declare class DataCache {
+    maxItems: number;
+    asyncFetch: (key: string) => Promise<unknown>;
+    items: {
+        key: string;
+        data: unknown;
+    }[];
+    constructor({ asyncFetch, maxItems, }: {
+        asyncFetch: (key: string) => Promise<unknown>;
+        maxItems?: number;
+    });
+    getFetch(key: string): Promise<unknown>;
+}
+export declare function mapObject(obj: Record<string, unknown>, fn: (value: unknown, key: string) => unknown): Record<string, unknown>;
+export declare function mapFilterObject(obj: Record<string, unknown>, fn: (value: unknown, key: string) => unknown): Record<string, unknown>;
+export declare function getArrayBuffers(ctx: unknown): Transferable[];
+export declare function newArray<T>(n: number, initFunction: (index: number) => T): T[];
+export declare class FreeList<T, Args> {
+    items: T[];
+    allocate: (args: Args) => T;
+    dispose?: (item: T) => void;
+    valid: (item: T, args: Args) => boolean;
+    constructor({ allocate, dispose, valid, }: {
+        allocate: (args: Args) => T;
+        dispose?: (item: T) => void;
+        valid: (item: T, args: Args) => boolean;
+    });
+    alloc(args: Args): T;
+    free(item: T): void;
+    disposeAll(): void;
+}
+export declare function setPackedSplat(packedSplats: Uint32Array, index: number, x: number, y: number, z: number, scaleX: number, scaleY: number, scaleZ: number, quatX: number, quatY: number, quatZ: number, quatW: number, opacity: number, r: number, g: number, b: number): void;
+export declare function setPackedSplatCenter(packedSplats: Uint32Array, index: number, x: number, y: number, z: number): void;
+export declare function setPackedSplatScales(packedSplats: Uint32Array, index: number, scaleX: number, scaleY: number, scaleZ: number): void;
+export declare function setPackedSplatQuat(packedSplats: Uint32Array, index: number, quatX: number, quatY: number, quatZ: number, quatW: number): void;
+export declare function setPackedSplatRgb(packedSplats: Uint32Array, index: number, r: number, g: number, b: number): void;
+export declare function setPackedSplatOpacity(packedSplats: Uint32Array, index: number, opacity: number): void;
+export declare function unpackSplat(packedSplats: Uint32Array, index: number): {
+    center: THREE.Vector3;
+    scales: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+    color: THREE.Color;
+    opacity: number;
+};
+export declare function getTextureSize(numSplats: number): {
+    width: number;
+    height: number;
+    depth: number;
+    maxSplats: number;
+};
+export declare function computeMaxSplats(numSplats: number): number;
+export declare function isMobile(): boolean;
+export declare function isAndroid(): boolean;
+export declare function isOculus(): boolean;
+export declare function flipPixels(pixels: Uint8Array, width: number, height: number): Uint8Array;
+export declare function pixelsToPngUrl(pixels: Uint8Array, width: number, height: number): string;
+export declare function cloneClock(clock: THREE.Clock): THREE.Clock;
+export declare function omitUndefined<T extends object>(obj: T): Partial<T>;
+export declare const IDENT_VERTEX_SHADER: string;
+export declare function averagePositions(positions: THREE.Vector3[]): THREE.Vector3;
+export declare function averageQuaternions(quaternions: THREE.Quaternion[]): THREE.Quaternion;
+export declare function coinciDist(matrix1: THREE.Matrix4, matrix2: THREE.Matrix4): {
+    distance: number;
+    coincidence: number;
+};
+export declare function withinDist({ matrix1, matrix2, maxDistance, }: {
+    matrix1: THREE.Matrix4;
+    matrix2: THREE.Matrix4;
+    maxDistance: number;
+}): boolean;
+export declare function withinCoinciDist({ matrix1, matrix2, maxDistance, minCoincidence, }: {
+    matrix1: THREE.Matrix4;
+    matrix2: THREE.Matrix4;
+    maxDistance: number;
+    minCoincidence?: number;
+}): boolean;
+export declare function coorientDist(matrix1: THREE.Matrix4, matrix2: THREE.Matrix4): {
+    distance: number;
+    coorient: number;
+};
+export declare function withinCoorientDist({ matrix1, matrix2, maxDistance, minCoorient, }: {
+    matrix1: THREE.Matrix4;
+    matrix2: THREE.Matrix4;
+    maxDistance: number;
+    minCoorient?: number;
+}): boolean;
+export declare function epsilonSign(value: number, epsilon?: number): number;
+export declare function encodeQuatXyz888(q: THREE.Quaternion): number;
+export declare function decodeQuatXyz888(encoded: number, out: THREE.Quaternion): THREE.Quaternion;
+/**
+ * Encodes a THREE.Quaternion into a 24‐bit integer.
+ *
+ * Bit layout (LSB → MSB):
+ *   - Bits  0–7:  quantized U (8 bits)
+ *   - Bits  8–15: quantized V (8 bits)
+ *   - Bits 16–23: quantized angle θ (8 bits) from [0,π]
+ *
+ * This version uses folded octahedral mapping (all inline).
+ */
+export declare function encodeQuatOctXy88R8(q: THREE.Quaternion): number;
+/**
+ * Decodes a 24‐bit encoded quaternion (packed in a number) back to a THREE.Quaternion.
+ *
+ * Assumes the same bit layout as in encodeQuatOctXy88R8.
+ */
+export declare function decodeQuatOctXy88R8(encoded: number, out: THREE.Quaternion): THREE.Quaternion;
+/**
+ * Encodes a THREE.Quaternion into a 24‑bit unsigned integer
+ * by converting it to Euler angles (roll, pitch, yaw).
+ * The Euler angles are assumed to be in radians in the range [-π, π].
+ * Each angle is normalized to [0,1] and quantized to 8 bits.
+ * Bit layout (LSB→MSB):
+ *   - Bits 0–7:   roll (quantized)
+ *   - Bits 8–15:  pitch (quantized)
+ *   - Bits 16–23: yaw (quantized)
+ */
+export declare function encodeQuatEulerXyz888(q: THREE.Quaternion): number;
+/**
+ * Decodes a 24‑bit unsigned integer into a THREE.Quaternion
+ * by unpacking three 8‑bit values (roll, pitch, yaw) in the range [0,255]
+ * and then converting them back to Euler angles in [-π, π] and to a quaternion.
+ */
+export declare function decodeQuatEulerXyz888(encoded: number, out: THREE.Quaternion): THREE.Quaternion;
+export declare function encodeSh1Rgb(sh1Array: Uint32Array, index: number, sh1Rgb: Float32Array): void;
+export declare function encodeSh2Rgb(sh2Array: Uint32Array, index: number, sh2Rgb: Float32Array): void;
+export declare function encodeSh3Rgb(sh3Array: Uint32Array, index: number, sh3Rgb: Float32Array): void;
+export declare function decompressPartialGzip(fileBytes: Uint8Array, numBytes: number): Uint8Array;
+export declare class GunzipReader {
+    fileBytes: Uint8Array;
+    chunkBytes: number;
+    offset: number;
+    chunks: Uint8Array[];
+    totalBytes: number;
+    gunzip: Gunzip;
+    constructor({ fileBytes, chunkBytes, }: {
+        fileBytes: Uint8Array;
+        chunkBytes?: number;
+    });
+    read(numBytes: number): Uint8Array;
+}

package/dist/types/vrButton.d.ts

@@ -0,0 +1,6 @@
+import type * as THREE from "three";
+export declare class VRButton {
+    static createButton(renderer: THREE.WebGLRenderer, sessionInit?: XRSessionInit): HTMLElement | null;
+    static registerSessionGrantedListener(): null | undefined;
+    static xrSessionIsGranted: boolean;
+}

package/dist/types/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@sparkjsdev/spark",
+  "version": "0.1.0",
+  "description": "An advanced 3D Gaussian Splatting renderer for THREE.js",
+  "homepage": "https://sparkjs.dev/",
+  "type": "module",
+  "main": "./dist/spark.cjs.js",
+  "module": "./dist/spark.module.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/spark.module.js",
+      "require": "./dist/spark.cjs.js"
+    }
+  },
+  "scripts": {
+    "assets:clean": "node scripts/clean-assets.js",
+    "assets:compress": "node scripts/compress-to-spz.js",
+    "assets:download": "node scripts/download-assets.js",
+    "build": "npm run build:production && npm run build:dev",
+    "build:dev": "vite build --mode dev",
+    "build:production": "vite build --mode production",
+    "build:wasm": "node rust/build_wasm.js",
+    "build:watch": "onchange 'src/**/*.{ts,glsl}' -- npm run build:dev",
+    "clean": "rm -rf dist/ && rm -rf node_modules/ && rm -rf rust/target/ && rm -rf rust/forge-internal-rs/pkg/ && npm run assets:clean",
+    "dev": "npm run build:dev && (vite --host & npm run build:watch)",
+    "docs": "node scripts/clean-site-files.js && node scripts/copy-site-files.js && mkdocs serve",
+    "format": "biome format .",
+    "format:fix": "biome format . --fix",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --fix",
+    "lint:summary": "biome check --reporter=summary",
+    "prepare": "npm run build:wasm && lefthook install",
+    "site:build": "npm run build && npm run site:clean && mkdocs build && node scripts/copy-site-files.js",
+    "site:clean": "node scripts/clean-site.js",
+    "site:deploy": "node scripts/deploy-site.js",
+    "site:serve": "node scripts/serve-site.js site",
+    "start": "npm run dev",
+    "test": "node --no-warnings --loader ts-node/esm --test test/**/*.test.ts"
+  },
+  "repository": "sparkjs/spark",
+  "files": ["dist"],
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@types/three": "0.172.0",
+    "lefthook": "1.11.12",
+    "lil-gui": "^0.20.0",
+    "onchange": "7.1.0",
+    "stats.js": "^0.17.0",
+    "three": "^0.172.0",
+    "ts-node": "10.9.2",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.11",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-glsl": "^1.3.1"
+  },
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "forge-internal-rs": "file:rust/forge-internal-rs/pkg"
+  },
+  "keywords": ["3d", "three.js", "gsplats", "3dgs", "gaussian", "splats"]
+}