cg-vue-splat

A Vue 3 component wrapper for the @mkkellogg/gaussian-splats-3d library, making it easy to integrate 3D Gaussian Splat rendering in your Vue applications.

Installation

npm install cg-vue-splat

Usage

Global Registration

import { createApp } from "vue";
import CGVueSplat from "cg-vue-splat";
import App from "./App.vue";

const app = createApp(App);
app.use(CGVueSplat);
app.mount("#app");

Local Registration

import { GaussianSplat } from "cg-vue-splat";

export default {
  components: {
    GaussianSplat,
  },
};

Basic Example

<template>
  <div style="width: 800px; height: 600px;">
    <!-- Simplified usage - just provide the src! -->
    <GaussianSplat
      src="your-splat-file.splat"
      @loaded="onSplatLoaded"
      @error="onSplatError"
    />
  </div>
</template>

<script setup>
  import { GaussianSplat } from "cg-vue-splat";

  const onSplatLoaded = () => {
    console.log("Splat loaded successfully!");
  };

  const onSplatError = (error) => {
    console.error("Error loading splat:", error);
  };
</script>

Loading External URLs

You can also load .splat files from external URLs:

<template>
  <div style="width: 800px; height: 600px;">
    <GaussianSplat
      src="https://storage.googleapis.com/reefos-3d/splats/reef-full.splat"
      @loaded="onSplatLoaded"
      @error="onSplatError"
    />
  </div>
</template>

Note: External URLs must be CORS-enabled to work properly. See the CORS Considerations section below.

Props

All props have sensible defaults, so you only need to specify src to get started!

| Prop | Type | Default | Description | | ----------------------------- | ------- | ------------ | ------------------------------------------------- | | src | String | Required | Path or URL to the .splat file | | position | Array | [0, 0, 0] | Position of the splat in 3D space [x, y, z] | | rotation | Array | [0, 0, 0, 1] | Quaternion rotation [x, y, z, w] | | scale | Array | [1, 1, 1] | Scale of the splat [x, y, z] | | cameraPosition | Array | [0, 0, 3] | Initial camera position [x, y, z] | | cameraLookAt | Array | [0, 0, 0] | Point where the camera is looking at [x, y, z] | | cameraUp | Array | [0, -1, 0] | Camera up vector [x, y, z] | | fov | Number | 45 | Field of view in degrees | | showLoadingUI | Boolean | true | Whether to show loading UI | | splatAlphaRemovalThreshold | Number | 5 | Alpha threshold for splat removal | | selfDrivenMode | Boolean | true | Whether the viewer manages its own rendering loop | | gpuAcceleratedSort | Boolean | false | Use GPU for splat sorting | | enableSIMDInSort | Boolean | true | Use SIMD instructions for sorting where available | | sharedMemoryForWorkers | Boolean | false | Use shared memory for worker threads | | integerBasedSort | Boolean | true | Use integer-based sorting | | halfPrecisionCovariancesOnGPU | Boolean | false | Use half precision for covariances on GPU | | antialiased | Boolean | true | Enable antialiasing | | dynamicScene | Boolean | false | Optimize for dynamic scenes | | progressiveLoad | Boolean | true | Enable progressive loading | | focusDistance | Number | 1.2 | Distance at which the camera is focused | | sphericalHarmonicsDegree | Number | 0 | Degree of spherical harmonics used (0, 1, or 2) | | maxScreenSpaceSplatSize | Number | 2048 | Maximum screen space splat size in pixels | | kernel2DSize | Number | 0.5 | Size of the 2D kernel | | autoRotate | Boolean | false | Enable auto-rotation of the camera | | autoRotateSpeed | Number | 0.5 | Speed of auto-rotation | | showFps | Boolean | false | Show FPS counter | | responsive | Boolean | true | Automatically resize on container changes | | enableControls | Boolean | true | Enable default camera controls |

Events

| Event | Description | | ------ | ------------------------------------------------ | | loaded | Emitted when the splat is successfully loaded | | error | Emitted when an error occurs, with error details |

CORS Considerations

When loading .splat files from external URLs, you need to ensure the server hosting the files has proper CORS headers configured. The GaussianSplats3D library requires shared memory support, which needs specific CORS headers:

• Cross-Origin-Embedder-Policy: require-corp
• Cross-Origin-Opener-Policy: same-origin

Vite Configuration

If you're using Vite, you can add these headers by installing the vite-plugin-cross-origin-isolation plugin:

npm install vite-plugin-cross-origin-isolation --save-dev

Then add the following to your vite.config.js file:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import crossOriginIsolation from "vite-plugin-cross-origin-isolation";

export default defineConfig({
  plugins: [vue(), crossOriginIsolation()],
});

Or manually configure the headers:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue(),
    {
      name: "configure-response-headers",
      configureServer: (server) => {
        server.middlewares.use((_req, res, next) => {
          res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
          res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
          next();
        });
      },
    },
  ],
});

Advanced Usage

Controlling the Splat Position Dynamically

<template>
  <GaussianSplat
    :src="splatUrl"
    :position="position"
    :rotation="rotation"
    :scale="scale"
  />

  <div class="controls">
    <button @click="moveLeft">Move Left</button>
    <button @click="moveRight">Move Right</button>
    <button @click="rotateModel">Rotate</button>
  </div>
</template>

<script setup>
  import { ref } from "vue";
  import { GaussianSplat } from "cg-vue-splat";

  const splatUrl = "your-splat-file.splat";
  const position = ref([0, 0, 0]);
  const rotation = ref([0, 0, 0, 1]);
  const scale = ref([1, 1, 1]);

  const moveLeft = () => {
    position.value = [
      position.value[0] - 0.5,
      position.value[1],
      position.value[2],
    ];
  };

  const moveRight = () => {
    position.value = [
      position.value[0] + 0.5,
      position.value[1],
      position.value[2],
    ];
  };

  const rotateModel = () => {
    // Example quaternion rotation around Y axis
    rotation.value = [0, Math.sin(Math.PI / 4), 0, Math.cos(Math.PI / 4)];
  };
</script>

Acknowledgments

This component is built on top of the Gaussian Splats 3D library created by Mark Kellogg. This project simply provides a Vue.js wrapper to make it easier to use within Vue applications.

License

MIT

Changelog

v0.2.6

• Added back button to return to model selection screen
• Enhanced error handling with a Go Back button
• Refined demo UI with improved button styles and interactions

v0.2.5

• Added live demo site at cg-vue-splat.vercel.app
• Improved UI with dark theme and better visual design
• Updated favicon to match the dark theme
• Enhanced demo page with responsive layout and better user experience
• Fixed deployment issues to Vercel

v0.2.4

• Added full support for loading .splat files from external URLs
• Added CORS headers configuration in development environment to support shared memory features
• Enhanced example in App.vue with options to load both local and external splat files

v0.2.3

• Updated default camera position from [0, 0, 5] to [0, 0, 3]
• Added new props with sensible defaults:
  • fov: 45 (field of view in degrees)
  • autoRotate: false
  • autoRotateSpeed: 0.5
  • showFps: false
  • responsive: true
  • enableControls: true
• Added support for loading .splat files from external URLs

v0.2.2

• Fixed container sizing issue: The component now automatically fills its parent container completely
• Added ResizeObserver to handle container size changes dynamically

v0.2.1

• Previous stable release

v0.1.4

• Initial packaging improvements

v0.1.3

• Initial public release