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>

Making it Responsive

The component is designed to be fully responsive and will automatically adapt to the size of its parent container. Here are some approaches to ensure responsive behavior:

Fullscreen Container

For a fullscreen viewer:

<template>
  <div class="fullscreen-container">
    <GaussianSplat src="your-splat-file.splat" @resize="onResize" />
  </div>
</template>

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

  const onResize = (dimensions) => {
    console.log(
      `Viewer resized to: ${dimensions.width}x${dimensions.height}, aspect ratio: ${dimensions.aspectRatio}`
    );
  };
</script>

<style>
  .fullscreen-container {
    position: fixed;
    top: 0;
    left: 0;
    width: 100vw;
    height: 100vh;
  }
</style>

Responsive Aspect Ratio

You can also explicitly control the aspect ratio by providing the aspectRatio prop:

<template>
  <div class="responsive-container">
    <GaussianSplat src="your-splat-file.splat" :aspectRatio="aspectRatio" />
  </div>
</template>

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

  const aspectRatio = ref(16 / 9); // Default aspect ratio

  // Update aspect ratio based on window size
  const updateAspectRatio = () => {
    aspectRatio.value = window.innerWidth / window.innerHeight;
  };

  onMounted(() => {
    window.addEventListener("resize", updateAspectRatio);
    updateAspectRatio();
  });

  onUnmounted(() => {
    window.removeEventListener("resize", updateAspectRatio);
  });
</script>

<style>
  .responsive-container {
    width: 100%;
    height: 0;
    padding-bottom: 56.25%; /* For 16:9 aspect ratio */
    position: relative;
  }

  .responsive-container > * {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
  }
</style>

Mobile-Friendly Container

The component includes touch support and responsiveness for mobile devices:

<template>
  <div class="mobile-friendly-container">
    <GaussianSplat src="your-splat-file.splat" />
  </div>
</template>

<style>
  .mobile-friendly-container {
    width: 100%;
    height: 50vh; /* Take half the viewport height */
    max-height: 500px; /* But not more than 500px */
  }

  @media (max-width: 768px) {
    .mobile-friendly-container {
      height: 70vh; /* Larger on mobile */
    }
  }
</style>

Props

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

Events

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