@d5techs/3dgs-lib 1.0.0

package/dist/core/gizmo/PlaneShape.d.ts

@@ -0,0 +1,48 @@
+import { Vec3 } from "../math/Vec3";
+import { Shape, ShapeConfig } from "./Shape";
+/**
+ * PlaneShapeConfig - 平面形状配置
+ */
+export interface PlaneShapeConfig extends ShapeConfig {
+    size?: number;
+    gap?: number;
+}
+/**
+ * PlaneShape - 平面形状（用于双轴平移）
+ * 参考 PlayCanvas 引擎的 PlaneShape 实现
+ */
+export declare class PlaneShape extends Shape {
+    private _size;
+    private _gap;
+    private _geometryCache;
+    private _currentFlipKey;
+    constructor(config: PlaneShapeConfig);
+    get size(): number;
+    set size(value: number);
+    get gap(): number;
+    set gap(value: number);
+    /**
+     * 更新碰撞数据
+     */
+    private _updateTriData;
+    /**
+     * 创建单位平面几何体
+     */
+    private createPlaneGeometry;
+    /**
+     * 创建渲染用的 GPU 几何体
+     */
+    createGeometry(device: GPUDevice): void;
+    /**
+     * 清除几何缓存
+     */
+    private _clearGeometryCache;
+    /**
+     * 更新翻转状态
+     */
+    setFlipped(newFlipped: Vec3): void;
+    /**
+     * 销毁 GPU 资源
+     */
+    destroy(): void;
+}

package/dist/core/gizmo/Shape.d.ts

@@ -0,0 +1,117 @@
+import { Vec3 } from "../math/Vec3";
+import { Ray } from "../math/Ray";
+import { Mat4 } from "../math/Mat4";
+/**
+ * GizmoAxis - 轴类型枚举
+ */
+export type GizmoAxisType = 'x' | 'y' | 'z' | 'xy' | 'xz' | 'yz' | 'xyz';
+/**
+ * Vec4Color - 带透明度的颜色
+ */
+export interface Vec4Color {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * ShapeConfig - Shape 配置
+ */
+export interface ShapeConfig {
+    axis: GizmoAxisType;
+    defaultColor: Vec3;
+    hoverColor: Vec3;
+    disabledColor: Vec3;
+    defaultAlpha?: number;
+    hoverAlpha?: number;
+    rotation?: Vec3;
+}
+/**
+ * TriData - 三角形碰撞数据
+ */
+export interface TriData {
+    vertices: Float32Array;
+    indices: Uint16Array;
+    transform: Mat4;
+    priority: number;
+}
+/**
+ * Shape - Gizmo 形状基类
+ * 参考 PlayCanvas 引擎的 Shape 实现
+ */
+export declare abstract class Shape {
+    axis: GizmoAxisType;
+    protected _disabled: boolean;
+    protected _visible: boolean;
+    protected _hovered: boolean;
+    protected _interactable: boolean;
+    protected _defaultColor: Vec3;
+    protected _hoverColor: Vec3;
+    protected _disabledColor: Vec3;
+    protected _defaultAlpha: number;
+    protected _hoverAlpha: number;
+    protected _position: Vec3;
+    protected _rotation: Vec3;
+    protected _scale: Vec3;
+    triData: TriData[];
+    protected device: GPUDevice | null;
+    protected vertexBuffer: GPUBuffer | null;
+    protected indexBuffer: GPUBuffer | null;
+    protected vertexCount: number;
+    protected indexCount: number;
+    flipped: Vec3;
+    constructor(config: ShapeConfig);
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    get visible(): boolean;
+    set visible(value: boolean);
+    get interactable(): boolean;
+    set interactable(value: boolean);
+    /**
+     * 设置 hover 状态
+     */
+    hover(state: boolean): void;
+    /**
+     * 获取当前颜色（包含透明度）
+     */
+    getColor(): Vec4Color;
+    /**
+     * 获取局部变换矩阵
+     */
+    getLocalTransform(): Mat4;
+    /**
+     * 射线碰撞检测
+     * @param ray - 世界空间射线
+     * @param parentTransform - 父级变换矩阵（gizmo 的世界变换）
+     * @returns 碰撞距离，null 表示未碰撞
+     */
+    intersect(ray: Ray, parentTransform: Mat4): number | null;
+    /**
+     * 射线与三角形列表碰撞检测
+     */
+    protected intersectTriangles(ray: Ray, vertices: Float32Array, indices: Uint16Array): number | null;
+    /**
+     * 创建 GPU 资源
+     */
+    abstract createGeometry(device: GPUDevice): void;
+    /**
+     * 获取顶点缓冲区
+     */
+    getVertexBuffer(): GPUBuffer | null;
+    /**
+     * 获取索引缓冲区
+     */
+    getIndexBuffer(): GPUBuffer | null;
+    /**
+     * 获取索引数量
+     */
+    getIndexCount(): number;
+    /**
+     * 销毁 GPU 资源
+     */
+    destroy(): void;
+    /**
+     * 创建 GPU 缓冲区
+     */
+    protected createBuffers(device: GPUDevice, vertices: Float32Array, indices: Uint16Array): void;
+}

package/dist/core/gizmo/SphereShape.d.ts

@@ -0,0 +1,29 @@
+import { Shape, ShapeConfig } from "./Shape";
+/**
+ * SphereShapeConfig - 球体形状配置
+ */
+export interface SphereShapeConfig extends ShapeConfig {
+    radius?: number;
+}
+/**
+ * SphereShape - 球体形状（用于统一缩放/中心选择）
+ * 参考 PlayCanvas 引擎的 SphereShape 实现
+ */
+export declare class SphereShape extends Shape {
+    private _radius;
+    constructor(config: SphereShapeConfig);
+    get radius(): number;
+    set radius(value: number);
+    /**
+     * 更新碰撞数据
+     */
+    private _updateTriData;
+    /**
+     * 创建单位球体几何体（半径0.5，中心在原点）
+     */
+    private createSphereGeometry;
+    /**
+     * 创建渲染用的 GPU 几何体
+     */
+    createGeometry(device: GPUDevice): void;
+}

package/dist/core/gizmo/TransformGizmoV2.d.ts

@@ -0,0 +1,203 @@
+import { Renderer } from "../Renderer";
+import { Camera } from "../Camera";
+import { Vec3 } from "../math/Vec3";
+/**
+ * GizmoMode - Gizmo 操作模式
+ */
+export declare enum GizmoMode {
+    Translate = "translate",
+    Rotate = "rotate",
+    Scale = "scale"
+}
+/**
+ * GizmoSpace - 坐标空间
+ */
+export type GizmoSpace = 'world' | 'local';
+/**
+ * GizmoDragMode - 拖拽时的显示模式
+ */
+export type GizmoDragMode = 'show' | 'hide' | 'selected';
+/**
+ * TransformableObject - 可变换对象接口
+ */
+export interface TransformableObject {
+    position: [number, number, number] | Float32Array;
+    rotation: [number, number, number] | Float32Array;
+    scale: [number, number, number] | Float32Array;
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+}
+/**
+ * GizmoTheme - Gizmo 主题颜色
+ */
+export interface GizmoTheme {
+    shapeBase: {
+        x: Vec3;
+        y: Vec3;
+        z: Vec3;
+        xyz: Vec3;
+        f: Vec3;
+    };
+    shapeHover: {
+        x: Vec3;
+        y: Vec3;
+        z: Vec3;
+        xyz: Vec3;
+        f: Vec3;
+    };
+    guideBase: {
+        x: Vec3;
+        y: Vec3;
+        z: Vec3;
+    };
+    disabled: Vec3;
+}
+/**
+ * TransformGizmoConfig - Gizmo 配置
+ */
+export interface TransformGizmoConfig {
+    renderer: Renderer;
+    camera: Camera;
+    canvas: HTMLCanvasElement;
+    size?: number;
+    snap?: boolean;
+    snapIncrement?: number;
+}
+/**
+ * TransformGizmoV2 - 重构后的变换 Gizmo
+ * 参考 PlayCanvas 引擎的 TransformGizmo 实现
+ */
+export declare class TransformGizmoV2 {
+    private renderer;
+    private camera;
+    private canvas;
+    private _size;
+    private _scale;
+    private _mode;
+    private _coordSpace;
+    private _theme;
+    snap: boolean;
+    snapIncrement: number;
+    dragMode: GizmoDragMode;
+    flipPlanes: boolean;
+    private _target;
+    private _shapes;
+    private _hoverAxis;
+    private _selectedAxis;
+    private _hoverIsPlane;
+    private _selectedIsPlane;
+    private _dragging;
+    private _rootStartPos;
+    private _rootStartRot;
+    private _selectionStartPoint;
+    private _dragStartTransform;
+    private _facingDir;
+    private _onDragStateChange;
+    private pipeline;
+    private linePipeline;
+    private uniformBuffer;
+    private bindGroup;
+    private bindGroupLayout;
+    private shapeUniformBuffers;
+    private shapeBindGroups;
+    private guideLineBuffer;
+    private guideLineBindGroup;
+    constructor(config: TransformGizmoConfig);
+    /**
+     * 初始化 Gizmo
+     */
+    init(): void;
+    /**
+     * 创建 WebGPU 渲染管线
+     */
+    private createPipeline;
+    /**
+     * 创建辅助线渲染管线
+     */
+    private createLinePipeline;
+    /**
+     * 创建形状
+     */
+    private createShapes;
+    /**
+     * 为每个 Shape 创建独立的 uniform buffer 和 bind group
+     */
+    private createShapeUniformBuffers;
+    /**
+     * 创建平移模式的形状
+     */
+    private createTranslateShapes;
+    /**
+     * 创建旋转模式的形状
+     */
+    private createRotateShapes;
+    /**
+     * 创建缩放模式的形状
+     */
+    private createScaleShapes;
+    get mode(): GizmoMode;
+    set mode(value: GizmoMode);
+    get coordSpace(): GizmoSpace;
+    set coordSpace(value: GizmoSpace);
+    get size(): number;
+    set size(value: number);
+    get target(): TransformableObject | null;
+    get isDragging(): boolean;
+    setTarget(object: TransformableObject | null): void;
+    setOnDragStateChange(callback: ((isDragging: boolean) => void) | null): void;
+    private _clearInteractionState;
+    private getGizmoPosition;
+    /**
+     * 获取 Gizmo 的视觉旋转（用于渲染形状）
+     * - 平移模式：根据 coordSpace 设置
+     * - 旋转模式：始终使用世界坐标（三个轴保持正交）
+     * - 缩放模式：始终使用本地坐标（跟随物体旋转）
+     */
+    private getGizmoRotation;
+    private updateScale;
+    /**
+     * 获取面向相机的方向（从 Gizmo 指向相机）
+     */
+    private getFacingDir;
+    /**
+     * 更新形状以面向相机
+     * 参考 PlayCanvas 的 _shapesLookAtCamera
+     */
+    private _shapesLookAtCamera;
+    /**
+     * 更新平移形状
+     */
+    private _updateTranslateShapesForCamera;
+    /**
+     * 更新旋转形状
+     */
+    private _updateRotateShapesForCamera;
+    /**
+     * 拖拽时更新形状显示
+     */
+    private _updateDragVisibility;
+    private _updateRotateDragVisibility;
+    private _updateTranslateDragVisibility;
+    private _updateScaleDragVisibility;
+    private screenToRay;
+    private performHitTest;
+    onPointerMove(event: PointerEvent): void;
+    onPointerDown(event: PointerEvent): void;
+    onPointerUp(event: PointerEvent): void;
+    private _updateHover;
+    private _screenToPoint;
+    private _createRotationPlane;
+    private _createFacingPlane;
+    private _createInteractionPlane;
+    private _projectToAxis;
+    private _applyTransform;
+    private _applyTranslation;
+    private _applyRotation;
+    private _applyFacingRotation;
+    private _applyScale;
+    private getShapeModelMatrix;
+    private updateUniformsForShape;
+    render(pass: GPURenderPassEncoder): void;
+    destroy(): void;
+}

package/dist/core/gizmo/index.d.ts

@@ -0,0 +1,14 @@
+export { Shape } from "./Shape";
+export type { GizmoAxisType, ShapeConfig, TriData, Vec4Color } from "./Shape";
+export { ArrowShape } from "./ArrowShape";
+export type { ArrowShapeConfig } from "./ArrowShape";
+export { PlaneShape } from "./PlaneShape";
+export type { PlaneShapeConfig } from "./PlaneShape";
+export { SphereShape } from "./SphereShape";
+export type { SphereShapeConfig } from "./SphereShape";
+export { ArcShape } from "./ArcShape";
+export type { ArcShapeConfig, ArcDisplayMode } from "./ArcShape";
+export { BoxLineShape } from "./BoxLineShape";
+export type { BoxLineShapeConfig } from "./BoxLineShape";
+export { TransformGizmoV2, GizmoMode } from "./TransformGizmoV2";
+export type { TransformGizmoConfig, TransformableObject, GizmoSpace, GizmoDragMode, GizmoTheme, } from "./TransformGizmoV2";

package/dist/core/math/Mat4.d.ts

@@ -0,0 +1,38 @@
+import { Vec3 } from "./Vec3";
+import { Quat } from "./Quat";
+/**
+ * Mat4 - 4x4 Matrix utility class
+ * Provides matrix operations for 3D transformations
+ * Storage is column-major order (OpenGL/WebGPU convention)
+ */
+export declare class Mat4 {
+    elements: Float32Array;
+    constructor();
+    static identity(): Mat4;
+    static fromTranslation(v: Vec3): Mat4;
+    static fromRotation(q: Quat): Mat4;
+    static fromScale(v: Vec3): Mat4;
+    static compose(position: Vec3, rotation: Quat, scale: Vec3): Mat4;
+    multiply(m: Mat4): Mat4;
+    multiplyInPlace(m: Mat4): Mat4;
+    inverse(): Mat4 | null;
+    transpose(): Mat4;
+    decompose(): {
+        position: Vec3;
+        rotation: Quat;
+        scale: Vec3;
+    } | null;
+    transformPoint(v: Vec3): Vec3;
+    transformDirection(v: Vec3): Vec3;
+    /**
+     * Transform a vector (direction) by this matrix (ignores translation)
+     * Alias for transformDirection for compatibility
+     */
+    transformVector(v: Vec3): Vec3;
+    /**
+     * Returns the inverse of this matrix
+     * Returns identity matrix if singular (non-invertible)
+     */
+    invert(): Mat4;
+    clone(): Mat4;
+}

package/dist/core/math/Quat.d.ts

@@ -0,0 +1,52 @@
+import { Vec3 } from "./Vec3";
+/**
+ * Quat - Quaternion utility class
+ * Provides quaternion operations for 3D rotations
+ */
+export declare class Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+    constructor(x?: number, y?: number, z?: number, w?: number);
+    static identity(): Quat;
+    /**
+     * Create quaternion from Euler angles (ZYX order)
+     * @param x - Rotation around X axis in radians
+     * @param y - Rotation around Y axis in radians
+     * @param z - Rotation around Z axis in radians
+     */
+    static fromEuler(x: number, y: number, z: number): Quat;
+    /**
+     * Create quaternion from axis-angle representation
+     * @param axis - Rotation axis (should be normalized)
+     * @param angle - Rotation angle in radians
+     */
+    static fromAxisAngle(axis: Vec3, angle: number): Quat;
+    /**
+     * Multiply this quaternion by another (this * q)
+     */
+    multiply(q: Quat): Quat;
+    /**
+     * Convert quaternion to Euler angles (ZYX order)
+     */
+    toEuler(): Vec3;
+    normalize(): Quat;
+    normalizeInPlace(): Quat;
+    /**
+     * Spherical linear interpolation between this quaternion and another
+     * @param q - Target quaternion
+     * @param t - Interpolation factor (0 to 1)
+     */
+    slerp(q: Quat, t: number): Quat;
+    clone(): Quat;
+    /**
+     * Get the inverse (conjugate for unit quaternions) of this quaternion
+     */
+    inverse(): Quat;
+    /**
+     * Transform a vector by this quaternion
+     * @param v - Vector to transform
+     */
+    transformVector(v: Vec3): Vec3;
+}

package/dist/core/math/Ray.d.ts

@@ -0,0 +1,65 @@
+import { Vec3 } from "./Vec3";
+import { Camera } from "../Camera";
+/**
+ * Ray - Ray utility class
+ * Provides ray operations for 3D picking and intersection tests
+ */
+export declare class Ray {
+    origin: Vec3;
+    direction: Vec3;
+    constructor(origin: Vec3, direction: Vec3);
+    /**
+     * Create a ray from screen coordinates
+     * @param screenX - Screen X coordinate (0 to canvasWidth)
+     * @param screenY - Screen Y coordinate (0 to canvasHeight)
+     * @param canvasWidth - Canvas width in pixels
+     * @param canvasHeight - Canvas height in pixels
+     * @param camera - Camera instance
+     */
+    static fromScreenPoint(screenX: number, screenY: number, canvasWidth: number, canvasHeight: number, camera: Camera): Ray;
+    /**
+     * Get point at distance along ray
+     * @param distance - Distance along ray
+     */
+    at(distance: number): Vec3;
+    /**
+     * Intersect ray with plane
+     * @param planeOrigin - Point on the plane
+     * @param planeNormal - Normal vector of the plane (should be normalized)
+     * @returns Distance along ray to intersection, or null if parallel/no intersection
+     */
+    intersectPlane(planeOrigin: Vec3, planeNormal: Vec3): number | null;
+    /**
+     * Compute distance from ray to a point
+     * @param point - Point in 3D space
+     */
+    distanceToPoint(point: Vec3): number;
+    /**
+     * Compute distance from ray to a line segment (for capsule hit testing)
+     * @param segmentStart - Start point of line segment
+     * @param segmentEnd - End point of line segment
+     */
+    distanceToSegment(segmentStart: Vec3, segmentEnd: Vec3): number;
+    /**
+     * Clone this ray
+     */
+    clone(): Ray;
+    /**
+     * Transform ray by a matrix
+     * @param matrix - Transformation matrix
+     */
+    transform(matrix: {
+        transformPoint(v: Vec3): Vec3;
+        transformVector(v: Vec3): Vec3;
+    }): Ray;
+    /**
+     * Intersect ray with triangle using Möller–Trumbore algorithm
+     * @param v0 - First vertex of triangle
+     * @param v1 - Second vertex of triangle
+     * @param v2 - Third vertex of triangle
+     * @returns Distance to intersection, or null if no intersection
+     */
+    intersectTriangle(v0: Vec3, v1: Vec3, v2: Vec3): number | null;
+    private static invertMatrix;
+    private static transformPoint;
+}

package/dist/core/math/Vec3.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Vec3 - 3D Vector utility class
+ * Provides vector operations for 3D mathematics
+ */
+export declare class Vec3 {
+    x: number;
+    y: number;
+    z: number;
+    constructor(x?: number, y?: number, z?: number);
+    static fromArray(arr: Float32Array | number[], offset?: number): Vec3;
+    static zero(): Vec3;
+    static one(): Vec3;
+    add(v: Vec3): Vec3;
+    subtract(v: Vec3): Vec3;
+    multiply(scalar: number): Vec3;
+    divide(scalar: number): Vec3;
+    addInPlace(v: Vec3): Vec3;
+    subtractInPlace(v: Vec3): Vec3;
+    multiplyInPlace(scalar: number): Vec3;
+    dot(v: Vec3): number;
+    cross(v: Vec3): Vec3;
+    length(): number;
+    lengthSquared(): number;
+    distance(v: Vec3): number;
+    distanceSquared(v: Vec3): number;
+    normalize(): Vec3;
+    normalizeInPlace(): Vec3;
+    clone(): Vec3;
+    toArray(): [number, number, number];
+    set(x: number, y: number, z: number): Vec3;
+    /**
+     * Check if this vector equals another vector
+     */
+    equals(v: Vec3): boolean;
+    /**
+     * Check if this vector approximately equals another vector
+     */
+    equalsApprox(v: Vec3, epsilon?: number): boolean;
+}