@viggle/splat-engine-three 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -71,6 +71,7 @@ import {
71
71
  SplatPLYLoader,
72
72
  SplatQuality,
73
73
  SplatRelight,
74
+ SplatSOGLoader,
74
75
  SplatSPZLoader,
75
76
  SpriteLayerRenderer,
76
77
  SunLight,
@@ -140,7 +141,7 @@ import {
140
141
  setShareSplatResources,
141
142
  uninstallFetchInterceptor,
142
143
  validateShaderGLSL
143
- } from "./chunks/chunk-SASRTGRD.js";
144
+ } from "./chunks/chunk-NNGE5LDC.js";
144
145
  export {
145
146
  ALL_BODY_PARTS,
146
147
  Animation,
@@ -215,6 +216,7 @@ export {
215
216
  SplatPLYLoader,
216
217
  SplatQuality,
217
218
  SplatRelight,
219
+ SplatSOGLoader,
218
220
  SplatSPZLoader,
219
221
  SpriteLayerRenderer,
220
222
  SunLight,
@@ -111,8 +111,9 @@ export declare class Environment {
111
111
  /**
112
112
  * Fetch, decode and add an environment splat.
113
113
  *
114
- * Reads uncompressed 3D Gaussian Splatting `.ply`, `.spz` (versions 1 to
115
- * 4), and SOG (a `.sog` bundle or an unbundled `meta.json`). The format is
114
+ * Reads 3D Gaussian Splatting `.ply` (uncompressed, or PlayCanvas's
115
+ * `.compressed.ply`), `.spz` (versions 1 to 4), and SOG (a `.sog` bundle or
116
+ * an unbundled `meta.json`). The format is
116
117
  * told by the file name: pass `filename` when the URL does not end in one.
117
118
  * `.spz` and SOG decode in a worker.
118
119
  *
@@ -19,6 +19,7 @@ export { Mat4, Quat, Vec3 } from './math';
19
19
  export { Environment } from './environment';
20
20
  export type { LoadEnvironmentOptions, LoadLodBundleOptions } from './environment';
21
21
  export { SplatSPZLoader } from './three/spz-loader';
22
+ export { SplatSOGLoader } from './three/sog-loader';
22
23
  export { decodeSplatFile, loadSplatAsset, loadSplatSource, setShareSplatResources } from './loader/shared/asset-loader';
23
24
  export { decodeSpz } from './loader/environment/spz';
24
25
  export { Splat } from './splat/splat';
@@ -0,0 +1,40 @@
1
+ /**
2
+ * PlayCanvas's quantised `.compressed.ply` - the layout SuperSplat and
3
+ * splat-transform write, and the PlayCanvas build reads natively:
4
+ *
5
+ * - `element chunk` - one per 256 splats, float ranges: `min_x/y/z`,
6
+ * `max_x/y/z`, `min_scale_x/y/z`, `max_scale_x/y/z`, and optionally
7
+ * `min_r/g/b`, `max_r/g/b`.
8
+ * - `element vertex` - four `uint`s per splat: `packed_position` (11/10/11
9
+ * unorm, within the chunk's range), `packed_rotation` (2-bit largest
10
+ * component + three 10-bit smallest components), `packed_scale` (11/10/11
11
+ * unorm log-scale, within the chunk's range), `packed_color` (8888 unorm:
12
+ * colour, within the chunk's colour range when it has one, and opacity).
13
+ * - `element sh` (optional) - `uchar f_rest_*`; skipped, as for the float
14
+ * PLY: splats here are lit flat, by their DC colour.
15
+ *
16
+ * Decoded into the same {@link SplatAttributes} the float PLY gives, with the
17
+ * arithmetic of PlayCanvas's `GSplatCompressedData.decompress`, so both builds
18
+ * draw the same splats from the same file.
19
+ */
20
+ import type { SplatAttributes } from '../character/types';
21
+ /**
22
+ * Whether a PLY header (the text before `end_header`) declares the
23
+ * compressed layout: a `chunk` element and a `vertex` element of packed
24
+ * `uint`s. Told by the header, not the file name, so a compressed file
25
+ * renamed to plain `.ply` still reads.
26
+ */
27
+ export declare function isCompressedPlyHeader(header: string): boolean;
28
+ /**
29
+ * Decode a `.compressed.ply` into float splat attributes.
30
+ *
31
+ * @param file - The whole file.
32
+ * @param headerText - The header up to (not including) `end_header`.
33
+ * @param dataStart - Byte offset of the first element's data.
34
+ * @throws If the file is not binary little-endian, lacks a property the layout needs, or is truncated.
35
+ * @internal Reached through {@link parseGaussianPly}, which recognises the layout.
36
+ */
37
+ export declare function parseCompressedPly(file: ArrayBuffer, headerText: string, dataStart: number): {
38
+ numSplats: number;
39
+ splats: SplatAttributes;
40
+ };
@@ -8,6 +8,9 @@ import type { SplatAttributes } from '../character/types';
8
8
  * Higher-order SH (`f_rest_*`) and normals are skipped: splats here are lit
9
9
  * flat, by their DC colour.
10
10
  *
11
+ * PlayCanvas's quantised `.compressed.ply` (SuperSplat / splat-transform) is
12
+ * read too, recognised from its header, and decoded to the same attributes.
13
+ *
11
14
  * @throws If the file is not a binary little-endian PLY, or lacks a required property.
12
15
  */
13
16
  export declare function parseGaussianPly(file: ArrayBuffer): {
@@ -45,8 +45,9 @@ export declare function sharedDecode<T>(kind: string, url: string, decode: () =>
45
45
  */
46
46
  export declare function decodeSplatFile(data: ArrayBuffer, filename: string): Promise<SplatSource>;
47
47
  /**
48
- * Fetch and decode a splat file: `.ply` (uncompressed 3D Gaussian Splatting),
49
- * `.spz` (versions 1-4), `.sog`, or an unbundled SOG's `meta.json`.
48
+ * Fetch and decode a splat file: `.ply` (uncompressed 3D Gaussian Splatting,
49
+ * or PlayCanvas's `.compressed.ply`), `.spz` (versions 1-4), `.sog`, or an
50
+ * unbundled SOG's `meta.json`.
50
51
  *
51
52
  * The bytes go through the asset cache (`cachedFetch`). With
52
53
  * {@link setShareSplatResources} on, repeated loads of one file share one decode.
@@ -5,8 +5,13 @@
5
5
  * the decode worker's (`sog-decode.ts`).
6
6
  */
7
7
  import type { PackedSplats } from '../../splat/packed-splats';
8
+ import type { SogMeta } from './sog-decode';
8
9
  /** `url` resolved against `base`, itself resolved against the page. */
9
10
  export declare function resolveUrl(url: string, base: string): string;
11
+ /** Decode a SOG's images, given in {@link sogImageFiles} order, in the decode worker. */
12
+ export declare function decodeImages(meta: SogMeta, images: Uint8Array[]): Promise<PackedSplats>;
13
+ /** The image files a DC-only decode reads, in `SogPixels` order. */
14
+ export declare function imageFiles(meta: SogMeta): string[];
10
15
  /**
11
16
  * Fetch and decode an unbundled SOG from its `meta.json`; the images are
12
17
  * fetched from beside it. Higher SH bands (`shN`) are not fetched: splats here
@@ -55,8 +55,10 @@ export declare class SplatClipLoader extends SplatLoaderBase<Animation> {
55
55
  parseAsync(data: ArrayBuffer, name?: string): Promise<Animation>;
56
56
  }
57
57
  /**
58
- * Loads an uncompressed 3D Gaussian Splatting `.ply` as a static
59
- * {@link SplatMesh} - an environment, a prop, a scanned object.
58
+ * Loads a 3D Gaussian Splatting `.ply` as a static {@link SplatMesh} - an
59
+ * environment, a prop, a scanned object. Reads the uncompressed layout and
60
+ * PlayCanvas's quantised `.compressed.ply` (SuperSplat / splat-transform),
61
+ * told apart by the file's header.
60
62
  *
61
63
  * ```ts
62
64
  * const room = await new SplatPLYLoader().loadAsync('/assets/room.ply');
@@ -0,0 +1,50 @@
1
+ import { Loader } from 'three';
2
+ import type { LoadingManager } from 'three';
3
+ import { SplatEngine } from '../engine';
4
+ import type { SplatMesh } from '../splat/splat-mesh';
5
+ /**
6
+ * Loads a SOG Gaussian-splat scene - a `.sog` bundle, or an unbundled
7
+ * `meta.json` with its WebP images beside it, as splat-transform writes
8
+ * either - as a static {@link SplatMesh}, the way {@link SplatPLYLoader}
9
+ * loads a `.ply`.
10
+ *
11
+ * ```ts
12
+ * const room = await new SplatSOGLoader().loadAsync('/assets/room.sog');
13
+ * scene.add(room);
14
+ *
15
+ * // Unbundled: the images are fetched from beside the meta.json.
16
+ * const hall = await new SplatSOGLoader().setPath('/assets/hall/').loadAsync('meta.json');
17
+ * ```
18
+ *
19
+ * Every file is fetched through a `FileLoader`, so the `LoadingManager`
20
+ * (including its URL modifier), base path, request headers and credentials
21
+ * mode apply to the images of an unbundled scene as well. The images decode
22
+ * in a worker. Higher SH bands (`shN`) are not fetched: splats here are lit
23
+ * by their DC colour. The mesh is given `renderOrder = -1` so it draws before
24
+ * characters, as {@link SplatPLYLoader}'s is.
25
+ *
26
+ * SOG stores the axes splat-transform wrote and none are changed here; turn
27
+ * a Y-down capture upright with `mesh.rotation.x = Math.PI`.
28
+ *
29
+ * @group Loaders
30
+ */
31
+ export declare class SplatSOGLoader extends Loader<SplatMesh> {
32
+ /**
33
+ * The engine loaded meshes belong to: the lights they respond to. Leave
34
+ * unset to use {@link SplatEngine.shared}.
35
+ */
36
+ engine: SplatEngine | null;
37
+ constructor(manager?: LoadingManager);
38
+ setEngine(engine: SplatEngine | null): this;
39
+ /**
40
+ * Decode a `.sog` bundle already in memory. `name` labels the mesh; for a
41
+ * loaded file it is the file's base name. An unbundled `meta.json` cannot
42
+ * be parsed this way, since its images are separate files: {@link load} it.
43
+ */
44
+ parseAsync(data: ArrayBuffer, name?: string): Promise<SplatMesh>;
45
+ load(url: string, onLoad: (result: SplatMesh) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
46
+ private _loadMeta;
47
+ /** A `FileLoader` carrying this loader's manager, headers and credentials mode. */
48
+ private _fileLoader;
49
+ private _toMesh;
50
+ }
package/dist/webgpu.js CHANGED
@@ -71,6 +71,7 @@ import {
71
71
  SplatPLYLoader,
72
72
  SplatQuality,
73
73
  SplatRelight,
74
+ SplatSOGLoader,
74
75
  SplatSPZLoader,
75
76
  SpriteLayerRenderer,
76
77
  SunLight,
@@ -151,7 +152,7 @@ import {
151
152
  setShareSplatResources,
152
153
  uninstallFetchInterceptor,
153
154
  validateShaderGLSL
154
- } from "./chunks/chunk-SASRTGRD.js";
155
+ } from "./chunks/chunk-NNGE5LDC.js";
155
156
 
156
157
  // src/webgpu.ts
157
158
  import { WebGPURenderer } from "three/webgpu";
@@ -1786,6 +1787,7 @@ export {
1786
1787
  SplatPLYLoader,
1787
1788
  SplatQuality,
1788
1789
  SplatRelight,
1790
+ SplatSOGLoader,
1789
1791
  SplatSPZLoader,
1790
1792
  SpriteLayerRenderer,
1791
1793
  SunLight,