README.md

---
title: SparkSplat
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
app_port: 7860
---

# SparkSplat

SparkSplat is a fast, interactive, and professional multi-file 3D Gaussian Splatting viewer and sandbox environment. 

Unlike traditional static viewers, SparkSplat retains the power of a fully-fledged 3D engine right in your browser. Powered by the incredibly fast [Spark](https://github.com/sparkjsdev/spark) engine for high-performance WebGL Gaussian Splat rendering, it comes out-of-the-box with rigid body physics (`@react-three/rapier`), first-person character controllers, and a robust placement editor for creating dynamic and interactive 3D sandboxes.

## Features

- **Universal Format Support**: Natively supports uncompressed and compressed Gaussian Splat formats including `.ply`, `.spz`, `.splat`, `.ksplat`, and `.sog`.
- **External URL Loading (Cloud Ready)**: Pass any direct link to a model via the URL query parameter `?url=YOUR_SPLAT_LINK` (e.g., from Hugging Face Datasets or AWS S3). SparkSplat will instantly stream and render the remote model with a beautiful download progress UI, bypassing the need for local storage.
- **Drag-and-Drop Local Storage**: Simply drag your splat files directly into the window. SparkSplat will automatically save them to your local `models/` directory and load them instantly for fast iteration.
- **Interactive Sandbox**: Walk through your splats with a built-in character controller, place 3D objects (`.glb`, `.obj`), and edit the scene physics dynamically.
- **Standalone and Lightweight**: No heavy Python AI generation pipelines required. SparkSplat is fully decoupled and works universally with any valid Gaussian Splat file.

## Quickstart

1. Install dependencies:
   ```bash
   cd app
   npm install
   ```

2. Start the local development server:
   ```bash
   npm run dev
   ```

3. Open your browser to the local URL (typically `http://localhost:5173`).
4. **Usage Options**:
   - **Local**: Drag and drop any `.ply`, `.spz`, `.splat`, `.ksplat`, or `.sog` file into the window to begin exploring!
   - **Remote**: Just append `?model=[URL]` to load an external model:

```
https://huggingface.co/spaces/Junyueeeeee/SparkSplat-Viewer?model=https://huggingface.co/datasets/Junyueeeeee/SparkSplat_Model/resolve/main/my_model.ply
```

## License

This project is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for the project license, and [THIRDPARTY.md](THIRDPARTY.md) for third-party open source notices.