@d5techs/3dgs-lib 1.1.3 → 1.3.0

package/dist/3dgs-lib.js

@@ -1698,6 +1698,429 @@ class BoundingBoxRenderer {
     this.bindGroup = null;
   }
 }
+class SceneAidsRenderer {
+  constructor(renderer, camera) {
+    __publicField(this, "renderer");
+    __publicField(this, "camera");
+    // 可见性
+    __publicField(this, "_gridVisible", true);
+    __publicField(this, "_axesVisible", true);
+    // Grid GPU 资源
+    __publicField(this, "gridPipeline", null);
+    __publicField(this, "gridUniformBuffer", null);
+    __publicField(this, "gridBindGroup", null);
+    // Axes GPU 资源
+    __publicField(this, "axesPipeline", null);
+    __publicField(this, "axesUniformBuffer", null);
+    __publicField(this, "axesBindGroup", null);
+    __publicField(this, "axesVertexBuffer", null);
+    this.renderer = renderer;
+    this.camera = camera;
+    this.createGridPipeline();
+    this.createAxesPipeline();
+  }
+  // ─── Grid Pipeline ──────────────────────────────────────
+  createGridPipeline() {
+    const device = this.renderer.device;
+    const shaderCode = (
+      /* wgsl */
+      `
+      struct Uniforms {
+        viewProjection: mat4x4<f32>,
+        invViewProjection: mat4x4<f32>,
+        cameraPos: vec3<f32>,
+        _pad: f32,
+      }
+
+      @group(0) @binding(0) var<uniform> u: Uniforms;
+
+      struct VSOut {
+        @builtin(position) position: vec4<f32>,
+        @location(0) nearPoint: vec3<f32>,
+        @location(1) farPoint: vec3<f32>,
+      }
+
+      // fullscreen triangle positions (NDC)
+      var<private> triPos: array<vec2<f32>, 6> = array<vec2<f32>, 6>(
+        vec2(-1.0, -1.0), vec2(1.0, -1.0), vec2(1.0, 1.0),
+        vec2(-1.0, -1.0), vec2(1.0, 1.0), vec2(-1.0, 1.0),
+      );
+
+      fn unprojectPoint(p: vec3<f32>) -> vec3<f32> {
+        let clip = u.invViewProjection * vec4(p, 1.0);
+        return clip.xyz / clip.w;
+      }
+
+      @vertex
+      fn vertexMain(@builtin(vertex_index) vid: u32) -> VSOut {
+        var out: VSOut;
+        let xy = triPos[vid];
+        out.nearPoint = unprojectPoint(vec3(xy, 0.0));
+        out.farPoint  = unprojectPoint(vec3(xy, 1.0));
+        out.position  = vec4(xy, 0.0, 1.0);
+        return out;
+      }
+
+      struct FSOut {
+        @location(0) color: vec4<f32>,
+        @builtin(frag_depth) depth: f32,
+      }
+
+      fn gridLine(coord: vec2<f32>, scale: f32) -> f32 {
+        let d = abs(fract(coord * scale - 0.5) - 0.5) / fwidth(coord * scale);
+        return 1.0 - min(min(d.x, d.y), 1.0);
+      }
+
+      fn computeDepth(worldPos: vec3<f32>) -> f32 {
+        let clip = u.viewProjection * vec4(worldPos, 1.0);
+        return clip.z / clip.w;
+      }
+
+      @fragment
+      fn fragmentMain(input: VSOut) -> FSOut {
+        // ray-plane intersection with Y=0
+        let t = -input.nearPoint.y / (input.farPoint.y - input.nearPoint.y);
+        let worldPos = input.nearPoint + t * (input.farPoint - input.nearPoint);
+
+        var out: FSOut;
+        out.depth = computeDepth(worldPos);
+
+        // only draw if we actually hit the plane (t > 0) and depth is valid
+        let visible = t > 0.0 && out.depth > 0.0 && out.depth < 1.0;
+
+        if (!visible) {
+          discard;
+        }
+
+        // minor grid (1 unit)
+        let minorGrid = gridLine(worldPos.xz, 1.0);
+        // major grid (10 units)
+        let majorGrid = gridLine(worldPos.xz, 0.1);
+
+        // fade by distance from camera
+        let dist = length(worldPos.xz - u.cameraPos.xz);
+        let fadeFar = 1.0 - smoothstep(30.0, 150.0, dist);
+
+        // base color
+        var color = vec3(0.35);
+        var alpha = minorGrid * 0.15 * fadeFar;
+
+        // major lines brighter
+        alpha = max(alpha, majorGrid * 0.3 * fadeFar);
+
+        // X axis (red line at z=0)
+        let xAxisDist = abs(worldPos.z);
+        let xAxisLine = 1.0 - smoothstep(0.0, fwidth(worldPos.z) * 1.5, xAxisDist);
+        if (xAxisLine > 0.01) {
+          color = mix(color, vec3(0.8, 0.2, 0.2), xAxisLine);
+          alpha = max(alpha, xAxisLine * 0.8 * fadeFar);
+        }
+
+        // Z axis (blue line at x=0)
+        let zAxisDist = abs(worldPos.x);
+        let zAxisLine = 1.0 - smoothstep(0.0, fwidth(worldPos.x) * 1.5, zAxisDist);
+        if (zAxisLine > 0.01) {
+          color = mix(color, vec3(0.2, 0.4, 0.9), zAxisLine);
+          alpha = max(alpha, zAxisLine * 0.8 * fadeFar);
+        }
+
+        out.color = vec4(color, alpha);
+        return out;
+      }
+    `
+    );
+    const shaderModule = device.createShaderModule({ code: shaderCode });
+    this.gridUniformBuffer = device.createBuffer({
+      size: 144,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    });
+    const bindGroupLayout = device.createBindGroupLayout({
+      entries: [{
+        binding: 0,
+        visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+        buffer: { type: "uniform" }
+      }]
+    });
+    this.gridBindGroup = device.createBindGroup({
+      layout: bindGroupLayout,
+      entries: [{ binding: 0, resource: { buffer: this.gridUniformBuffer } }]
+    });
+    const pipelineLayout = device.createPipelineLayout({
+      bindGroupLayouts: [bindGroupLayout]
+    });
+    this.gridPipeline = device.createRenderPipeline({
+      layout: pipelineLayout,
+      vertex: {
+        module: shaderModule,
+        entryPoint: "vertexMain"
+      },
+      fragment: {
+        module: shaderModule,
+        entryPoint: "fragmentMain",
+        targets: [{
+          format: this.renderer.format,
+          blend: {
+            color: {
+              srcFactor: "src-alpha",
+              dstFactor: "one-minus-src-alpha",
+              operation: "add"
+            },
+            alpha: {
+              srcFactor: "one",
+              dstFactor: "one-minus-src-alpha",
+              operation: "add"
+            }
+          }
+        }]
+      },
+      primitive: {
+        topology: "triangle-list",
+        cullMode: "none"
+      },
+      depthStencil: {
+        format: this.renderer.depthFormat,
+        depthWriteEnabled: true,
+        depthCompare: "less-equal"
+      }
+    });
+  }
+  // ─── Axes Pipeline ──────────────────────────────────────
+  createAxesPipeline() {
+    const device = this.renderer.device;
+    const shaderCode = (
+      /* wgsl */
+      `
+      struct Uniforms {
+        viewProjection: mat4x4<f32>,
+      }
+
+      @group(0) @binding(0) var<uniform> uniforms: Uniforms;
+
+      struct VertexInput {
+        @location(0) position: vec3<f32>,
+        @location(1) color: vec3<f32>,
+      }
+
+      struct VertexOutput {
+        @builtin(position) position: vec4<f32>,
+        @location(0) color: vec3<f32>,
+      }
+
+      @vertex
+      fn vertexMain(input: VertexInput) -> VertexOutput {
+        var output: VertexOutput;
+        output.position = uniforms.viewProjection * vec4(input.position, 1.0);
+        output.color = input.color;
+        return output;
+      }
+
+      @fragment
+      fn fragmentMain(input: VertexOutput) -> @location(0) vec4<f32> {
+        return vec4(input.color, 1.0);
+      }
+    `
+    );
+    const shaderModule = device.createShaderModule({ code: shaderCode });
+    this.axesUniformBuffer = device.createBuffer({
+      size: 64,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    });
+    const bindGroupLayout = device.createBindGroupLayout({
+      entries: [{
+        binding: 0,
+        visibility: GPUShaderStage.VERTEX,
+        buffer: { type: "uniform" }
+      }]
+    });
+    this.axesBindGroup = device.createBindGroup({
+      layout: bindGroupLayout,
+      entries: [{ binding: 0, resource: { buffer: this.axesUniformBuffer } }]
+    });
+    const pipelineLayout = device.createPipelineLayout({
+      bindGroupLayouts: [bindGroupLayout]
+    });
+    this.axesPipeline = device.createRenderPipeline({
+      layout: pipelineLayout,
+      vertex: {
+        module: shaderModule,
+        entryPoint: "vertexMain",
+        buffers: [{
+          arrayStride: 24,
+          attributes: [
+            { shaderLocation: 0, offset: 0, format: "float32x3" },
+            { shaderLocation: 1, offset: 12, format: "float32x3" }
+          ]
+        }]
+      },
+      fragment: {
+        module: shaderModule,
+        entryPoint: "fragmentMain",
+        targets: [{ format: this.renderer.format }]
+      },
+      primitive: {
+        topology: "line-list",
+        cullMode: "none"
+      },
+      depthStencil: {
+        format: this.renderer.depthFormat,
+        depthWriteEnabled: true,
+        depthCompare: "less-equal"
+      }
+    });
+    this.createAxesVertexBuffer();
+  }
+  createAxesVertexBuffer() {
+    const device = this.renderer.device;
+    const L = 100;
+    const verts = new Float32Array([
+      // X axis: red
+      0,
+      0,
+      0,
+      0.9,
+      0.2,
+      0.2,
+      L,
+      0,
+      0,
+      0.9,
+      0.2,
+      0.2,
+      // Y axis: green
+      0,
+      0,
+      0,
+      0.2,
+      0.8,
+      0.2,
+      0,
+      L,
+      0,
+      0.2,
+      0.8,
+      0.2,
+      // Z axis: blue
+      0,
+      0,
+      0,
+      0.3,
+      0.4,
+      0.9,
+      0,
+      0,
+      L,
+      0.3,
+      0.4,
+      0.9
+    ]);
+    this.axesVertexBuffer = device.createBuffer({
+      size: verts.byteLength,
+      usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST
+    });
+    device.queue.writeBuffer(this.axesVertexBuffer, 0, verts);
+  }
+  // ─── Public API ─────────────────────────────────────────
+  get gridVisible() {
+    return this._gridVisible;
+  }
+  set gridVisible(v) {
+    this._gridVisible = v;
+  }
+  get axesVisible() {
+    return this._axesVisible;
+  }
+  set axesVisible(v) {
+    this._axesVisible = v;
+  }
+  // ─── Render ─────────────────────────────────────────────
+  render(pass) {
+    if (this._gridVisible) {
+      this.renderGrid(pass);
+    }
+    if (this._axesVisible) {
+      this.renderAxes(pass);
+    }
+  }
+  renderGrid(pass) {
+    if (!this.gridPipeline || !this.gridBindGroup || !this.gridUniformBuffer) return;
+    const device = this.renderer.device;
+    const vp = new Float32Array(this.camera.viewProjectionMatrix);
+    const invVP = this.invertMatrix4(vp);
+    const camPos = new Float32Array(this.camera.position);
+    const buf = new Float32Array(36);
+    buf.set(vp, 0);
+    buf.set(invVP, 16);
+    buf.set(camPos, 32);
+    device.queue.writeBuffer(this.gridUniformBuffer, 0, buf);
+    pass.setPipeline(this.gridPipeline);
+    pass.setBindGroup(0, this.gridBindGroup);
+    pass.draw(6);
+  }
+  renderAxes(pass) {
+    if (!this.axesPipeline || !this.axesBindGroup || !this.axesUniformBuffer || !this.axesVertexBuffer) return;
+    const device = this.renderer.device;
+    const vpMatrix = new Float32Array(this.camera.viewProjectionMatrix);
+    device.queue.writeBuffer(this.axesUniformBuffer, 0, vpMatrix);
+    pass.setPipeline(this.axesPipeline);
+    pass.setBindGroup(0, this.axesBindGroup);
+    pass.setVertexBuffer(0, this.axesVertexBuffer);
+    pass.draw(6);
+  }
+  // ─── Math helpers ───────────────────────────────────────
+  invertMatrix4(m) {
+    const out = new Float32Array(16);
+    const a00 = m[0], a01 = m[1], a02 = m[2], a03 = m[3];
+    const a10 = m[4], a11 = m[5], a12 = m[6], a13 = m[7];
+    const a20 = m[8], a21 = m[9], a22 = m[10], a23 = m[11];
+    const a30 = m[12], a31 = m[13], a32 = m[14], a33 = m[15];
+    const b00 = a00 * a11 - a01 * a10;
+    const b01 = a00 * a12 - a02 * a10;
+    const b02 = a00 * a13 - a03 * a10;
+    const b03 = a01 * a12 - a02 * a11;
+    const b04 = a01 * a13 - a03 * a11;
+    const b05 = a02 * a13 - a03 * a12;
+    const b06 = a20 * a31 - a21 * a30;
+    const b07 = a20 * a32 - a22 * a30;
+    const b08 = a20 * a33 - a23 * a30;
+    const b09 = a21 * a32 - a22 * a31;
+    const b10 = a21 * a33 - a23 * a31;
+    const b11 = a22 * a33 - a23 * a32;
+    let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
+    if (Math.abs(det) < 1e-10) return out;
+    det = 1 / det;
+    out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det;
+    out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det;
+    out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det;
+    out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det;
+    out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det;
+    out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det;
+    out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det;
+    out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det;
+    out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det;
+    out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det;
+    out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det;
+    out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det;
+    out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det;
+    out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det;
+    out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det;
+    out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det;
+    return out;
+  }
+  // ─── Cleanup ────────────────────────────────────────────
+  destroy() {
+    var _a2, _b2, _c;
+    (_a2 = this.gridUniformBuffer) == null ? void 0 : _a2.destroy();
+    (_b2 = this.axesUniformBuffer) == null ? void 0 : _b2.destroy();
+    (_c = this.axesVertexBuffer) == null ? void 0 : _c.destroy();
+    this.gridUniformBuffer = null;
+    this.axesUniformBuffer = null;
+    this.axesVertexBuffer = null;
+    this.gridPipeline = null;
+    this.axesPipeline = null;
+    this.gridBindGroup = null;
+    this.axesBindGroup = null;
+  }
+}
 class Mesh {
   constructor(vertexBuffer, vertexCount, indexBuffer = null, indexCount = 0, boundingBox) {
     __publicField(this, "vertexBuffer");
@@ -3988,7 +4411,8 @@ function readProperty$1(dataView, baseOffset, prop, littleEndian) {
 function sigmoid$1(x) {
   return 1 / (1 + Math.exp(-x));
 }
-async function loadPLY(url) {
+async function loadPLY(url, options = {}) {
+  const { coordinateSystem = "blender" } = options;
   const response = await fetch(url);
   if (!response.ok) {
     throw new Error(`无法加载 PLY 文件: ${url}`);
@@ -4000,6 +4424,7 @@ async function loadPLY(url) {
     throw new Error("不支持 ASCII 格式的 PLY 文件，请使用 binary_little_endian 或 binary_big_endian 格式");
   }
   const littleEndian = format === "binary_little_endian";
+  const swapYZ = coordinateSystem === "blender";
   const propMap = buildPropertyMap(properties);
   const props = {
     x: propMap.get("x"),
@@ -4065,9 +4490,14 @@ async function loadPLY(url) {
       shRest[dstBase + 2] = srcB < shRestProps.length ? readProperty$1(dataView, base, shRestProps[srcB], littleEndian) : 0;
     }
     splats[i] = {
-      mean: [x, y, z],
-      scale: [scale_0, scale_1, scale_2],
-      rotation: [
+      mean: swapYZ ? [x, z, y] : [x, y, z],
+      scale: swapYZ ? [scale_0, scale_2, scale_1] : [scale_0, scale_1, scale_2],
+      rotation: swapYZ ? [
+        -rot_0 * qnorm,
+        rot_1 * qnorm,
+        rot_3 * qnorm,
+        rot_2 * qnorm
+      ] : [
         rot_0 * qnorm,
         rot_1 * qnorm,
         rot_2 * qnorm,
@@ -4283,7 +4713,8 @@ async function parsePLYBuffer(buffer, options = {}) {
   const {
     maxSplats = 2e5,
     loadSH = false,
-    onProgress
+    onProgress,
+    coordinateSystem = "blender"
   } = options;
   const seed = options.seed ?? buffer.byteLength;
   const { headerText, dataOffset } = extractHeader(buffer);
@@ -4373,27 +4804,41 @@ async function parsePLYBuffer(buffer, options = {}) {
   const opacities = new Float32Array(actualCount);
   const shCoeffs = loadSH ? new Float32Array(actualCount * 45) : void 0;
   const dataView = new DataView(buffer, dataOffset);
+  const swapYZ = coordinateSystem === "blender";
   let outputIdx = 0;
   let lastProgress = 0;
   for (let i = 0; i < actualCount; i++) {
     const srcIdx = sampleIndices ? sampleIndices[i] : i;
     const base = srcIdx * stride;
-    positions[outputIdx * 3 + 0] = offsets.x >= 0 ? readProperty(dataView, base + offsets.x, types.x, littleEndian) : 0;
-    positions[outputIdx * 3 + 1] = offsets.y >= 0 ? readProperty(dataView, base + offsets.y, types.y, littleEndian) : 0;
-    positions[outputIdx * 3 + 2] = offsets.z >= 0 ? readProperty(dataView, base + offsets.z, types.z, littleEndian) : 0;
-    scales[outputIdx * 3 + 0] = offsets.scale_0 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_0, types.scale_0, littleEndian)) : 1;
-    scales[outputIdx * 3 + 1] = offsets.scale_1 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_1, types.scale_1, littleEndian)) : 1;
-    scales[outputIdx * 3 + 2] = offsets.scale_2 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_2, types.scale_2, littleEndian)) : 1;
+    const px = offsets.x >= 0 ? readProperty(dataView, base + offsets.x, types.x, littleEndian) : 0;
+    const py = offsets.y >= 0 ? readProperty(dataView, base + offsets.y, types.y, littleEndian) : 0;
+    const pz = offsets.z >= 0 ? readProperty(dataView, base + offsets.z, types.z, littleEndian) : 0;
+    positions[outputIdx * 3 + 0] = px;
+    positions[outputIdx * 3 + 1] = swapYZ ? pz : py;
+    positions[outputIdx * 3 + 2] = swapYZ ? py : pz;
+    const sx = offsets.scale_0 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_0, types.scale_0, littleEndian)) : 1;
+    const sy = offsets.scale_1 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_1, types.scale_1, littleEndian)) : 1;
+    const sz = offsets.scale_2 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_2, types.scale_2, littleEndian)) : 1;
+    scales[outputIdx * 3 + 0] = sx;
+    scales[outputIdx * 3 + 1] = swapYZ ? sz : sy;
+    scales[outputIdx * 3 + 2] = swapYZ ? sy : sz;
     const rot_0 = offsets.rot_0 >= 0 ? readProperty(dataView, base + offsets.rot_0, types.rot_0, littleEndian) : 1;
     const rot_1 = offsets.rot_1 >= 0 ? readProperty(dataView, base + offsets.rot_1, types.rot_1, littleEndian) : 0;
     const rot_2 = offsets.rot_2 >= 0 ? readProperty(dataView, base + offsets.rot_2, types.rot_2, littleEndian) : 0;
     const rot_3 = offsets.rot_3 >= 0 ? readProperty(dataView, base + offsets.rot_3, types.rot_3, littleEndian) : 0;
     const qlen = Math.sqrt(rot_0 * rot_0 + rot_1 * rot_1 + rot_2 * rot_2 + rot_3 * rot_3);
     const qnorm = qlen > 0 ? 1 / qlen : 1;
-    rotations[outputIdx * 4 + 0] = rot_0 * qnorm;
-    rotations[outputIdx * 4 + 1] = rot_1 * qnorm;
-    rotations[outputIdx * 4 + 2] = rot_2 * qnorm;
-    rotations[outputIdx * 4 + 3] = rot_3 * qnorm;
+    if (swapYZ) {
+      rotations[outputIdx * 4 + 0] = -rot_0 * qnorm;
+      rotations[outputIdx * 4 + 1] = rot_1 * qnorm;
+      rotations[outputIdx * 4 + 2] = rot_3 * qnorm;
+      rotations[outputIdx * 4 + 3] = rot_2 * qnorm;
+    } else {
+      rotations[outputIdx * 4 + 0] = rot_0 * qnorm;
+      rotations[outputIdx * 4 + 1] = rot_1 * qnorm;
+      rotations[outputIdx * 4 + 2] = rot_2 * qnorm;
+      rotations[outputIdx * 4 + 3] = rot_3 * qnorm;
+    }
     const f_dc_0 = offsets.f_dc_0 >= 0 ? readProperty(dataView, base + offsets.f_dc_0, types.f_dc_0, littleEndian) : 0;
     const f_dc_1 = offsets.f_dc_1 >= 0 ? readProperty(dataView, base + offsets.f_dc_1, types.f_dc_1, littleEndian) : 0;
     const f_dc_2 = offsets.f_dc_2 >= 0 ? readProperty(dataView, base + offsets.f_dc_2, types.f_dc_2, littleEndian) : 0;
@@ -13471,6 +13916,7 @@ class App {
     __publicField(this, "sceneManager");
     __publicField(this, "gizmoManager");
     __publicField(this, "hotspotManager");
+    __publicField(this, "sceneAids");
     __publicField(this, "isRunning", false);
     __publicField(this, "animationId", 0);
     // 是否使用移动端渲染器
@@ -13506,6 +13952,7 @@ class App {
       this.controls,
       this.meshRenderer
     );
+    this.sceneAids = new SceneAidsRenderer(this.renderer, this.camera);
     window.addEventListener("resize", this.boundOnResize);
   }
   // ============================================
@@ -13543,8 +13990,12 @@ class App {
   }
   /**
    * 加载 PLY 文件 (3D Gaussian Splatting)
+   * @param urlOrBuffer PLY 文件 URL 或 ArrayBuffer
+   * @param onProgress 进度回调
+   * @param isLocalFile 是否为本地文件
+   * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
    */
-  async addPLY(urlOrBuffer, onProgress, isLocalFile = false) {
+  async addPLY(urlOrBuffer, onProgress, isLocalFile = false, coordinateSystem = "blender") {
     try {
       const isMobile = isMobileDevice();
       let buffer;
@@ -13573,7 +14024,8 @@ class App {
         const compactData = await this.parsePLYBuffer(buffer, {
           maxSplats: Infinity,
           loadSH: false,
-          onProgress: parseProgressCallback
+          onProgress: parseProgressCallback,
+          coordinateSystem
         });
         if (onProgress) onProgress(90, "upload");
         gsRenderer.setCompactData(compactData);
@@ -13587,7 +14039,8 @@ class App {
         const compactData = await this.parsePLYBuffer(buffer, {
           maxSplats: Infinity,
           loadSH: true,
-          onProgress: parseProgressCallback
+          onProgress: parseProgressCallback,
+          coordinateSystem
         });
         if (onProgress) onProgress(90, "upload");
         gsRenderer.setCompactData(compactData);
@@ -13726,6 +14179,7 @@ class App {
       gsRenderer.render(pass);
     }
     this.meshRenderer.render(pass);
+    this.sceneAids.render(pass);
     this.gizmoManager.render(pass);
     this.renderer.endFrame();
     this.hotspotManager.consumeGPUResult();
@@ -14002,6 +14456,24 @@ class App {
     const { parsePLYBuffer: parsePLYBuffer2 } = await Promise.resolve().then(() => PLYLoaderMobile);
     return parsePLYBuffer2(buffer, options);
   }
+  // ============================================
+  // 场景辅助（网格 + 坐标轴）
+  // ============================================
+  setGridVisible(visible) {
+    this.sceneAids.gridVisible = visible;
+  }
+  getGridVisible() {
+    return this.sceneAids.gridVisible;
+  }
+  setAxesVisible(visible) {
+    this.sceneAids.axesVisible = visible;
+  }
+  getAxesVisible() {
+    return this.sceneAids.axesVisible;
+  }
+  getSceneAidsRenderer() {
+    return this.sceneAids;
+  }
   /**
    * 销毁应用及所有资源
    */
@@ -14011,6 +14483,7 @@ class App {
     this.sceneManager.destroy();
     this.gizmoManager.destroy();
     this.hotspotManager.destroy();
+    this.sceneAids.destroy();
     if (this.meshRenderer) {
       this.meshRenderer.destroy();
     }
@@ -14045,6 +14518,7 @@ export {
   OrbitControls,
   Renderer,
   SHMode,
+  SceneAidsRenderer,
   SceneManager,
   SplatBoundingBoxProvider,
   SplatTransformProxy,