@realsee/five-webgpu 1.0.0-alpha.1

package/five/model/loaders/protobuf/pbm.d.ts

@@ -0,0 +1,203 @@
+import * as $protobuf from "protobufjs";
+import Long = require("long");
+/** Properties of a Model. */
+export interface IModel {
+
+    /** Model chunks */
+    chunks?: (IChunk[]|null);
+
+    /** Model createAt */
+    createAt?: (number|null);
+
+    /** Model description */
+    description?: (string|null);
+}
+
+/** Represents a Model. */
+export class Model implements IModel {
+
+    /**
+     * Constructs a new Model.
+     * @param [properties] Properties to set
+     */
+    constructor(properties?: IModel);
+
+    /** Model chunks. */
+    public chunks: IChunk[];
+
+    /** Model createAt. */
+    public createAt: number;
+
+    /** Model description. */
+    public description: string;
+
+    /**
+     * Decodes a Model message from the specified reader or buffer.
+     * @param reader Reader or buffer to decode from
+     * @param [length] Message length if known beforehand
+     * @returns Model
+     * @throws {Error} If the payload is not a reader or valid buffer
+     * @throws {$protobuf.util.ProtocolError} If required fields are missing
+     */
+    public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): Model;
+
+    /**
+     * Gets the default type url for Model
+     * @param [typeUrlPrefix] your custom typeUrlPrefix(default "type.googleapis.com")
+     * @returns The default type url
+     */
+    public static getTypeUrl(typeUrlPrefix?: string): string;
+}
+
+/** Properties of a Chunk. */
+export interface IChunk {
+
+    /** Chunk vertices */
+    vertices: IVertices;
+
+    /** Chunk faces */
+    faces: IFaces;
+
+    /** Chunk name */
+    name: string;
+
+    /** Chunk texture */
+    texture?: (string|null);
+}
+
+/** Represents a Chunk. */
+export class Chunk implements IChunk {
+
+    /**
+     * Constructs a new Chunk.
+     * @param [properties] Properties to set
+     */
+    constructor(properties?: IChunk);
+
+    /** Chunk vertices. */
+    public vertices: IVertices;
+
+    /** Chunk faces. */
+    public faces: IFaces;
+
+    /** Chunk name. */
+    public name: string;
+
+    /** Chunk texture. */
+    public texture: string;
+
+    /**
+     * Decodes a Chunk message from the specified reader or buffer.
+     * @param reader Reader or buffer to decode from
+     * @param [length] Message length if known beforehand
+     * @returns Chunk
+     * @throws {Error} If the payload is not a reader or valid buffer
+     * @throws {$protobuf.util.ProtocolError} If required fields are missing
+     */
+    public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): Chunk;
+
+    /**
+     * Gets the default type url for Chunk
+     * @param [typeUrlPrefix] your custom typeUrlPrefix(default "type.googleapis.com")
+     * @returns The default type url
+     */
+    public static getTypeUrl(typeUrlPrefix?: string): string;
+}
+
+/** Properties of a Vertices. */
+export interface IVertices {
+
+    /** Vertices xyz */
+    xyz?: (number[]|null);
+
+    /** Vertices uvs */
+    uvs?: (number[]|null);
+
+    /** Vertices marks */
+    marks?: (VertexMark[]|null);
+}
+
+/** Represents a Vertices. */
+export class Vertices implements IVertices {
+
+    /**
+     * Constructs a new Vertices.
+     * @param [properties] Properties to set
+     */
+    constructor(properties?: IVertices);
+
+    /** Vertices xyz. */
+    public xyz: number[];
+
+    /** Vertices uvs. */
+    public uvs: number[];
+
+    /** Vertices marks. */
+    public marks: VertexMark[];
+
+    /**
+     * Decodes a Vertices message from the specified reader or buffer.
+     * @param reader Reader or buffer to decode from
+     * @param [length] Message length if known beforehand
+     * @returns Vertices
+     * @throws {Error} If the payload is not a reader or valid buffer
+     * @throws {$protobuf.util.ProtocolError} If required fields are missing
+     */
+    public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): Vertices;
+
+    /**
+     * Gets the default type url for Vertices
+     * @param [typeUrlPrefix] your custom typeUrlPrefix(default "type.googleapis.com")
+     * @returns The default type url
+     */
+    public static getTypeUrl(typeUrlPrefix?: string): string;
+}
+
+/** Properties of a Faces. */
+export interface IFaces {
+
+    /** Faces indices */
+    indices?: (number[]|null);
+
+    /** Faces normals */
+    normals?: (number[]|null);
+}
+
+/** Represents a Faces. */
+export class Faces implements IFaces {
+
+    /**
+     * Constructs a new Faces.
+     * @param [properties] Properties to set
+     */
+    constructor(properties?: IFaces);
+
+    /** Faces indices. */
+    public indices: number[];
+
+    /** Faces normals. */
+    public normals: number[];
+
+    /**
+     * Decodes a Faces message from the specified reader or buffer.
+     * @param reader Reader or buffer to decode from
+     * @param [length] Message length if known beforehand
+     * @returns Faces
+     * @throws {Error} If the payload is not a reader or valid buffer
+     * @throws {$protobuf.util.ProtocolError} If required fields are missing
+     */
+    public static decode(reader: ($protobuf.Reader|Uint8Array), length?: number): Faces;
+
+    /**
+     * Gets the default type url for Faces
+     * @param [typeUrlPrefix] your custom typeUrlPrefix(default "type.googleapis.com")
+     * @returns The default type url
+     */
+    public static getTypeUrl(typeUrlPrefix?: string): string;
+}
+
+/** VertexMark enum. */
+export enum VertexMark {
+    VERTEX_MARK_UNSPECIFIED = 0,
+    VERTEX_MARK_ROOF = 1
+}

package/five/model/loaders/shared.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from 'three/webgpu';
+export type LoadResultType<Scene = THREE.Object3D> = {
+    type: 'unknown' | 'b3dm' | 'pnts' | 'at3d' | 'pbm' | 'dome' | 'domez' | 'gltf' | 'ply' | 'obj' | 'fbx' | 'x3p' | 'spz' | 'splat';
+    modelUpAxis: 'Y' | 'Z';
+    upAxis: 'Y' | 'Z';
+    byteLength: number;
+    memoryUsage: number;
+    uri: string;
+    scene: Scene;
+    textures: THREE.Texture[];
+    animations: THREE.AnimationClip[];
+    rtcCenter?: THREE.Vector3;
+    dispose: () => void;
+};
+export declare const ROTATE_X_MATRIX: THREE.Matrix4;
+export declare const ROTATE_X_MATRIX_INVERSE: THREE.Matrix4;

package/five/model/loaders/splat.d.ts

@@ -0,0 +1,8 @@
+import { Fetcher } from "../../utils/ajax";
+import { LoadResultType } from './shared';
+export declare function loadSplat(url: string, options?: {
+    modelUpAxis?: 'Y' | 'Z';
+    upAxis?: 'Y' | 'Z';
+    fetcher?: Fetcher;
+    onDownloadProgress?: (percent: number, loaded?: number, total?: number) => void;
+}): Promise<LoadResultType>;

package/five/model/loaders/spz.d.ts

@@ -0,0 +1,14 @@
+import { Fetcher } from "../../utils/ajax";
+import { PBMGaussianSplattingObject } from '../objects/pbmGaussianSplattingObject';
+import { LoadResultType } from './shared';
+/**
+ * 加载spz格式的数据
+ * @returns Promise<PBMGaussianSplattingObject>
+ */
+export declare function parseSpz(fileBytes: Uint8Array | ArrayBuffer): Promise<PBMGaussianSplattingObject>;
+export declare function loadSpz(url: string, options?: {
+    modelUpAxis?: 'Y' | 'Z';
+    upAxis?: 'Y' | 'Z';
+    fetcher?: Fetcher;
+    onDownloadProgress?: (percent: number, loaded?: number, total?: number) => void;
+}): Promise<LoadResultType>;

package/five/model/loaders/tile3d-helpers/feature-table.d.ts

@@ -0,0 +1,15 @@
+import { GL_TYPE, TypedArray } from './gl-type';
+export declare class FeatureTable {
+    json: Record<string, any>;
+    buffer: Uint8Array;
+    featuresLength: number;
+    private cachedTypedArrays;
+    constructor(featureTableJson: Record<string, any>, featureTableBinary: Uint8Array);
+    getExtension(extensionName: string): any;
+    hasProperty(propertyName: string): boolean;
+    getGlobalProperty<T extends GL_TYPE>(propertyName: string, componentType: T, componentLength: number): TypedArray<T> | null;
+    getPropertyArray<T extends GL_TYPE>(propertyName: string, componentType: T, componentLength: number): TypedArray<T>;
+    getProperty<T extends GL_TYPE>(propertyName: string, componentType: T, componentLength: number, featureId: number, result: TypedArray<T>): TypedArray<T> | null;
+    private getTypedArrayFromBinary;
+    private getTypedArrayFromArray;
+}

package/five/model/loaders/tile3d-helpers/gl-type.d.ts

@@ -0,0 +1,20 @@
+export declare enum GL_TYPE {
+    BYTE = 5120,
+    UNSIGNED_BYTE = 5121,
+    SHORT = 5122,
+    UNSIGNED_SHORT = 5123,
+    INT = 5124,
+    UNSIGNED_INT = 5125,
+    FLOAT = 5126,
+    DOUBLE = 5130
+}
+export type AnyTypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Uint8ClampedArray | Float32Array | Float64Array;
+export type TypedArray<T extends GL_TYPE> = T extends GL_TYPE.DOUBLE ? Float64Array : T extends GL_TYPE.FLOAT ? Float32Array : T extends GL_TYPE.UNSIGNED_SHORT ? Uint16Array : T extends GL_TYPE.UNSIGNED_INT ? Uint32Array : T extends GL_TYPE.UNSIGNED_BYTE ? Uint8Array : T extends GL_TYPE.BYTE ? Int8Array : T extends GL_TYPE.SHORT ? Int16Array : T extends GL_TYPE.INT ? Int32Array : never;
+export type TypedArrayConstructor<T extends GL_TYPE> = T extends GL_TYPE.DOUBLE ? typeof Float64Array : T extends GL_TYPE.FLOAT ? typeof Float32Array : T extends GL_TYPE.UNSIGNED_SHORT ? typeof Uint16Array : T extends GL_TYPE.UNSIGNED_INT ? typeof Uint32Array : T extends GL_TYPE.UNSIGNED_BYTE ? typeof Uint8Array : T extends GL_TYPE.BYTE ? typeof Int8Array : T extends GL_TYPE.SHORT ? typeof Int16Array : T extends GL_TYPE.INT ? typeof Int32Array : never;
+export declare const GL_TYPE_TO_ARRAY_TYPE: {
+    [key in GL_TYPE]: TypedArrayConstructor<key>;
+};
+export declare function getArrayType<T extends GL_TYPE>(glType: T): TypedArrayConstructor<T>;
+export declare function getByteSize(glType: number): number;
+export declare function createTypedArray<T extends GL_TYPE>(glType: T, buffer: ArrayBuffer, byteOffset?: number, length?: number): TypedArray<T>;
+export declare function glTypeFromName(name: string): GL_TYPE;

package/five/model/loaders/tile3d-helpers/parse-gltf-array-buffer.d.ts

@@ -0,0 +1,2 @@
+import { Tile3DB3dmData } from './tile3d-type';
+export declare function parseGlTFArrayBuffer(data: Tile3DB3dmData, arrayBuffer: ArrayBuffer, byteOffset: number): number;

package/five/model/loaders/tile3d-helpers/parse-header.d.ts

@@ -0,0 +1,2 @@
+import { Tile3DContentData } from './tile3d-type';
+export declare function parseHeader(data: Tile3DContentData, arrayBuffer: ArrayBuffer, byteOffset: number): number;

package/five/model/loaders/tile3d-helpers/parse-point-cloud-attributes.d.ts

@@ -0,0 +1,2 @@
+import { type Tile3DPntsData } from './tile3d-type';
+export declare function parsePointCloud(data: Tile3DPntsData, _arrayBuffer: ArrayBuffer, byteOffset: number): Promise<number>;

package/five/model/loaders/tile3d-helpers/parse-point-cloud-attributes.worker.d.ts

@@ -0,0 +1,6 @@
+import { WorkerType } from '../../../utils/worker';
+import type { Tile3DPntsDataAttributes } from './tile3d-type';
+export type AttrbuteWorkType = WorkerType<{
+    featureTableJson: Record<string, any>;
+    featureTableBinary: Uint8Array;
+}, Tile3DPntsDataAttributes>;

package/five/model/loaders/tile3d-helpers/parse-table.d.ts

@@ -0,0 +1,3 @@
+import { Tile3DContentData } from './tile3d-type';
+export declare function getStringFromArrayBuffer(arrayBuffer: ArrayBuffer, byteOffset: number, byteLength: number): string;
+export declare function parseTable(data: Tile3DContentData, arrayBuffer: ArrayBuffer, byteOffset: number): number;

package/five/model/loaders/tile3d-helpers/tile3d-type.d.ts

@@ -0,0 +1,36 @@
+import { TypedArray } from "three";
+export interface Tile3DContentData {
+    type: string;
+    uri: string;
+    version: number;
+    magic: number;
+    byteLength: number;
+    header: {
+        featureTableJsonByteLength: number;
+        featureTableBinaryByteLength: number;
+        batchTableJsonByteLength: number;
+        batchTableBinaryByteLength: number;
+        batchLength: number;
+    };
+    featureTableJson: Record<string, any>;
+    featureTableBinary: Uint8Array;
+    batchTableJson: Record<string, any>;
+    batchTableBinary: Uint8Array;
+    rtcCenter?: [number, number, number];
+}
+export interface Tile3DB3dmData extends Tile3DContentData {
+    gltfArrayBuffer: ArrayBuffer;
+}
+export interface Tile3DPntsData extends Tile3DContentData {
+    attributes: Tile3DPntsDataAttributes;
+}
+export interface Tile3DPntsDataAttributes {
+    position: Attribute<TypedArray> | null;
+    color: Attribute<TypedArray> | null;
+    normal: Attribute<TypedArray> | null;
+}
+export interface Attribute<T extends TypedArray> {
+    array: T;
+    itemSize: number;
+    normalized: boolean;
+}

package/five/model/loaders/x3p.d.ts

@@ -0,0 +1,22 @@
+import * as THREE from "three/webgpu";
+import { LoadResultType } from './shared';
+import { Fetcher } from "../../utils/ajax";
+import { PBMMesh } from "../objects/pbmMesh";
+export declare function loadX3p(url: string, options?: {
+    upAxis?: 'Y' | 'Z';
+    color?: THREE.Color;
+    light?: boolean;
+    fetcher?: Fetcher;
+    onDownloadProgress?: (percent: number, loaded?: number, total?: number) => void;
+}): Promise<LoadResultType>;
+declare function parse(arrayBuffer: Uint8Array, options: {
+    light?: boolean;
+    color?: THREE.Color;
+    resourcePath?: string;
+    search?: string;
+    fetcher: Fetcher;
+}): {
+    object: PBMMesh;
+    dispose: () => void;
+};
+export { parse };

package/five/model/materials/nodes/pbmMeshBasicNodeMaterial.d.ts

@@ -0,0 +1,14 @@
+/**
+ * PBMMeshBasicNodeMaterial — NodeMaterial 渲染侧实现
+ */
+import * as THREE from 'three/webgpu';
+import { type IPBMMaterial } from '../pbmMaterial';
+export interface PBMMeshBasicNodeMaterial extends THREE.MeshBasicNodeMaterial, IPBMMaterial {
+}
+export declare class PBMMeshBasicNodeMaterial extends THREE.MeshBasicNodeMaterial {
+    static get type(): string;
+    readonly isPBMMeshBasicNodeMaterial = true;
+    constructor(parameters?: THREE.MeshBasicNodeMaterialParameters);
+    setup(builder: THREE.NodeBuilder): void;
+    setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
+}

package/five/model/materials/nodes/pbmMeshPanoOnlyNodeMaterial.d.ts

@@ -0,0 +1,14 @@
+/**
+ * PBMPanoOnlyNodeMaterial — 纯全景图 NodeMaterial 渲染侧实现
+ */
+import * as THREE from 'three/webgpu';
+import { type IPBMMaterial } from '../pbmMaterial';
+export interface PBMMeshPanoOnlyNodeMaterial extends THREE.MeshBasicNodeMaterial, IPBMMaterial {
+}
+export declare class PBMMeshPanoOnlyNodeMaterial extends THREE.MeshBasicNodeMaterial {
+    static get type(): string;
+    readonly isPBMPanoOnlyNodeMaterial = true;
+    constructor(parameters?: THREE.MeshBasicNodeMaterialParameters);
+    setup(builder: THREE.NodeBuilder): void;
+    setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
+}

package/five/model/materials/nodes/pbmMeshPhongNodeMaterial.d.ts

@@ -0,0 +1,14 @@
+/**
+ * PBMMeshPhongNodeMaterial — NodeMaterial 渲染侧实现
+ */
+import * as THREE from 'three/webgpu';
+import { type IPBMMaterial } from '../pbmMaterial';
+export interface PBMMeshPhongNodeMaterial extends THREE.MeshPhongNodeMaterial, IPBMMaterial {
+}
+export declare class PBMMeshPhongNodeMaterial extends THREE.MeshPhongNodeMaterial {
+    static get type(): string;
+    readonly isPBMMeshPhongNodeMaterial = true;
+    constructor(parameters?: THREE.MeshPhongNodeMaterialParameters);
+    setup(builder: THREE.NodeBuilder): void;
+    setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
+}

package/five/model/materials/nodes/pbmMeshPhysicalNodeMaterial.d.ts

@@ -0,0 +1,14 @@
+/**
+ * PBMMeshPhysicalNodeMaterial — NodeMaterial 渲染侧实现
+ */
+import * as THREE from 'three/webgpu';
+import { type IPBMMaterial } from '../pbmMaterial';
+export interface PBMMeshPhysicalNodeMaterial extends THREE.MeshPhysicalNodeMaterial, IPBMMaterial {
+}
+export declare class PBMMeshPhysicalNodeMaterial extends THREE.MeshPhysicalNodeMaterial {
+    static get type(): string;
+    readonly isPBMMeshPhysicalNodeMaterial = true;
+    constructor(parameters?: THREE.MeshPhysicalNodeMaterialParameters);
+    setup(builder: THREE.NodeBuilder): void;
+    setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
+}

package/five/model/materials/nodes/pbmPointCloudNodeMaterial.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PBMPointCloudNodeMaterial — 点云 NodeMaterial (TSL billboard quad)
+ *
+ * WebGPU 不支持可变大小点图元，因此采用实例化四边形方案：
+ * 每个点渲染为一个面向相机的 billboard quad，在顶点阶段完成展开。
+ *
+ * 配合 PBMPointCloud (THREE.Mesh + InstancedBufferGeometry) 使用。
+ * 几何体中 instancePosition/instanceColor/instanceNormal 由 PBMPointCloud 自动生成。
+ */
+import * as THREE from 'three/webgpu';
+import { type IPBMMaterial } from '../pbmMaterial';
+export interface PBMPointCloudNodeMaterial extends THREE.NodeMaterial, IPBMMaterial {
+}
+export declare class PBMPointCloudNodeMaterial extends THREE.NodeMaterial {
+    static get type(): string;
+    readonly isPBMPointCloudNodeMaterial = true;
+    constructor();
+    customProgramCacheKey(): string;
+    setupVertex(builder: THREE.NodeBuilder): THREE.Node;
+    setup(builder: THREE.NodeBuilder): void;
+    setupObserver(builder: THREE.NodeBuilder): THREE.NodeMaterialObserver;
+}

package/five/model/materials/pbmGaussianSplattingNodeMaterial.d.ts

@@ -0,0 +1,78 @@
+/**
+ * PBMGaussianSplattingNodeMaterial — 3D Gaussian Splatting TSL NodeMaterial (WebGPU)
+ *
+ * 移植自 five (WebGL2/GLSL) 的 pbm_gaussian_splatting/vertex.glsl + fragment.glsl。
+ * 核心数学：
+ *   - 3D 协方差 Σ = M Mᵀ，M = S R（scale × rotation）
+ *   - 2D 协方差 Σ' = Tᵀ Σ T，T = W J（W=view rot, J=透视雅可比）
+ *   - 2D 椭圆：求 Σ' 特征值 / 特征向量 → 主轴 √(8λ)
+ *   - 片元透明度：exp(-0.5‖δ‖²) (δ 为贴切空间单位化坐标)
+ *
+ * 数据通过 DataTexture 上传：
+ *   - u_texture       RGBA32UI (2048 宽) — 每 splat 16 字节压缩（color / center f16×3 / quat oct / log-scale×3）
+ *   - u_transforms    RGBA32F (9 宽) — 每对象 36 float = matrixWorld16 + selected4 + inverse(matrixWorld)16
+ *   - u_transformIndices R32UI (1024 宽) — 每 splat 的对象索引
+ *   - u_layerIndices  R32UI (1024 宽) — 每 splat 的 viewlayer 索引
+ *   - u_shTexture     RGBA32F — SH 系数（degree 1/2/3 线性展开）
+ */
+import * as THREE from 'three/webgpu';
+export interface PBMGaussianSplattingNodeMaterialOptions {
+    numGsLayers?: number;
+    numGsClippers?: number;
+    maxShDegree?: number;
+}
+export declare class PBMGaussianSplattingNodeMaterial extends THREE.NodeMaterial {
+    readonly isPBMGaussianSplattingMaterial: true;
+    dataTexture: THREE.DataTexture | null;
+    transformsTexture: THREE.DataTexture | null;
+    transformIndicesTexture: THREE.DataTexture | null;
+    layerIndicesTexture: THREE.DataTexture | null;
+    shTexture: THREE.DataTexture | null;
+    shTextureSize: THREE.Vector2;
+    aggregationEnabled: boolean;
+    aggregationProgress: number;
+    aggregationPointDuration: number;
+    aggregationBoundsMin: THREE.Vector3;
+    aggregationBoundsMax: THREE.Vector3;
+    maxShDegree: number;
+    numGsLayers: number;
+    numGsClippers: number;
+    layerClipperRanges: THREE.Vector2[];
+    clipperMatricesInverse: THREE.Matrix4[];
+    private _uDataTex;
+    private _uTransformsTex;
+    private _uTransformIndicesTex;
+    private _uLayerIndicesTex;
+    private _uShTex;
+    private _uShTextureSize;
+    private _uAggregationEnabled;
+    private _uAggregationProgress;
+    private _uAggregationPointDuration;
+    private _uAggregationBoundsMin;
+    private _uAggregationBoundsMax;
+    private _uLayerClipperRanges;
+    private _uClipperMatricesInverse;
+    private _cachedLayerCount;
+    private _cachedClipperCount;
+    constructor(options?: PBMGaussianSplattingNodeMaterialOptions);
+    customProgramCacheKey(): string;
+    /**
+     * 每帧同步动态 uniforms（标量 / 纹理引用）。由 PBMGaussianSplattingRenderMesh
+     * 在 onBeforeRender 中调用——TSL 的 `uniform(1.0)` 创建后，primitive 不会自动反向
+     * 跟踪材质字段，所以必须手动把最新值灌进 `.value`。
+     * Vector2/Vector3 是对象引用，材质字段本身就是同一对象，TSL 会自动读最新值，无需此处处理。
+     */
+    syncDynamicUniforms(): void;
+    /**
+     * 构建 uniform 节点；需要在 setup() 前确保 dataTexture 等已就绪，
+     * 否则会创建占位 EmptyTexture；之后通过 `.value = newTex` 替换即可。
+     */
+    private _ensureUniforms;
+    /**
+     * 计算 SH 纹理 UV（整数行列）——与 GLSL getSHDataUV 逻辑一致
+     * paddedComponentCount = ceil(shComponentCount/4)*4
+     */
+    private _buildSHUv;
+    setup(builder: THREE.NodeBuilder): void;
+    copy(source: PBMGaussianSplattingNodeMaterial): this;
+}