A high-performance Next.js application for viewing 3D Gaussian Splats (.splat) with real-time, webcam-based head tracking to create a window-like parallax effect.
- Gaussian Splat Rendering: Native support for
.splatfiles using standard@react-three/dreiloaders. - Head Tracking: Real-time face detection uses webcam input to shift the 3D camera, simulating a holographic display.
- Auto-Calibration: "Math Module" automatically measures the model's bounding box and centers it at world origin
(0,0,0). - Performance Mode: Optimized for constrained hardware (Intel Macs) with adaptive resolution and alpha culling.
- Debug Suite: Built-in FPS counter, bounding box visualizers, and scene controls via Leva.
This project uses a Clean Architecture approach to avoid "Frankenstein" conflicts between React and the GPU.
components/SpatialViewer.tsx: The main controller. Handles the Canvas, camera physics, and global optimization settings (DPR, ToneMapping).components/StandardSplat.tsx: A smart wrapper around the 3D model. It handles the "Auto-Center" math and performance culling (discarding invisible pixels).hooks/useHeadTracking.ts: The logic layer that interprets webcam data into X/Y coordinates.
- Node.js 18+
- npm
-
Clone the repository
git clone [https://github.com/max-sho/GSPortal.git](https://github.com/max-sho/GSPortal.git) cd GSPortal -
Install Dependencies
npm install --legacy-peer-deps
-
Run the Development Server
npm run dev
-
Open in Browser Navigate to
http://localhost:3000. Allow camera permissions when prompted to enable head tracking.
Place your .splat files inside the public/ folder.
Update the URL in components/SpatialViewer.tsx:
<StandardSplat url="/your-file.splat" ... />