mirror of
https://github.com/storytold/spark.git
synced 2026-10-09 00:09:53 +00:00
Diego Marcos Segura
211 lines
5.3 KiB
Markdown
211 lines
5.3 KiB
Markdown
<p align="center">
|
|
|
|
|
|
|
|
|
|
<h3 align="center">An advanced 3D Gaussian Splatting renderer for THREE.js</h3>
|
|
<div align="center">
|
|
|
|
[Features](#features) -
|
|
[Getting Started](#getting-started) -
|
|
<a href="https://www.forge.dev/">Documentation</a> -
|
|
<a href="https://www.forge.dev/">FAQ</a>
|
|
</div>
|
|
</p>
|
|
|
|
<div align="center">
|
|
|
|
[](https://github.com/forge-gfx/forge/blob/main/LICENSE)
|
|
[](https://www.npmjs.com/package/forge)
|
|
|
|
</div>
|
|
|
|
<p>
|
|
<a href="https://www.forge.dev" target="_blank">
|
|
<picture>
|
|
</picture>
|
|
</a>
|
|
|
|
## Features
|
|
|
|
- Load multiple splats files simultaneously ([demo]())
|
|
- Combine and composite splats with regular Meshes ([demo]())
|
|
- Animation ([demo]())
|
|
- Real Time Visual Effects ([demo]())
|
|
- Multiple Camera Views ([demo]())
|
|
- Procedurally generated splats ([demo]())
|
|
|
|
Check out all the [examples]()
|
|
|
|
## Getting Started
|
|
|
|
### Copy Code
|
|
(Note: CDN setup is work-in-progress -- for now, skip to the [Web Editor](#web-editor) or [Run Examples](#run-examples) section to get started.)
|
|
|
|
|
|
Copy the following code into an `index.html` file.
|
|
|
|
|
|
```html
|
|
<style> body {margin: 0;} </style>
|
|
<script type="importmap">
|
|
{
|
|
"imports": {
|
|
"three": "https://cdnjs.cloudflare.com/ajax/libs/three.js/0.174.0/three.module.js",
|
|
"@worldlabsai/forge": "https://forge.dev/releases/forge/0.1.0/forge.module.js"
|
|
}
|
|
}
|
|
</script>
|
|
<script type="module">
|
|
import * as THREE from "three";
|
|
import { SplatMesh } from "@worldlabsai/forge";
|
|
|
|
const scene = new THREE.Scene();
|
|
const camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 1000);
|
|
const renderer = new THREE.WebGLRenderer();
|
|
renderer.setSize(window.innerWidth, window.innerHeight);
|
|
document.body.appendChild(renderer.domElement)
|
|
|
|
const splatURL = "https://forge.dev/assets/splats/butterfly.spz";
|
|
const butterfly = new SplatMesh({ url: splatURL });
|
|
butterfly.quaternion.set(1, 0, 0, 0);
|
|
butterfly.position.set(0, 0, -3);
|
|
scene.add(butterfly);
|
|
|
|
renderer.setAnimationLoop(function animate(time) {
|
|
renderer.render(scene, camera);
|
|
butterfly.rotation.y += 0.01;
|
|
});
|
|
</script>
|
|
```
|
|
|
|
See the [Run Examples](#run-examples) section below to try out other examples.
|
|
|
|
### Web Editor
|
|
|
|
Remix the [glitch starter template](https://glitch.com/edit/#!/forge-dev)
|
|
|
|
### Usage from CDN
|
|
|
|
```html
|
|
<script type="importmap">
|
|
{
|
|
"imports": {
|
|
"three": "https://cdnjs.cloudflare.com/ajax/libs/three.js/0.174.0/three.module.js",
|
|
"forge": "https://forge.dev/releases/forge/0.1.0/forge.module.js"
|
|
}
|
|
}
|
|
</script>
|
|
```
|
|
|
|
### Install with NPM
|
|
|
|
```shell
|
|
npm install @forge-dev/forge
|
|
```
|
|
|
|
## Run Examples
|
|
|
|
Install [Rust](https://www.rust-lang.org/tools/install) if it's not already installed in your machine.
|
|
|
|
Next, build Forge by running:
|
|
```
|
|
npm install
|
|
npm run build
|
|
```
|
|
This will first build the Rust Wasm component (can be invoked via `npm run build:wasm`), then Forge itself (`npm run build`).
|
|
|
|
The examples fetch assets from a remote URL. This step is optional, but offline development and faster loading times are possible if you download and cache the assets files locally with the following command:
|
|
```
|
|
npm run assets:download
|
|
```
|
|
|
|
Once you've built Forge and optionally downloaded the assets, you can now run the examples:
|
|
```
|
|
npm start
|
|
```
|
|
This will run a dev server by default at [http://localhost:8080/](http://localhost:8080/). Check the console log output to see if yours is served on a different port.
|
|
|
|
|
|
## Develop and contribute to the project
|
|
Here are some additional development tips and instructions:
|
|
### Build troubleshooting
|
|
|
|
First try cleaning all the build files and re-building everything:
|
|
```
|
|
npm run clean
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
There's no versioning system for assets. If you need to re-download a specific file you can delete that asset file individually or download all assets from scratch:
|
|
|
|
```
|
|
npm run assets:clean
|
|
npm run assets:download
|
|
```
|
|
|
|
### Ignore dist directory during development
|
|
|
|
To ignore the dist directory and prevent accidental commits and merge conflicts
|
|
|
|
```
|
|
git update-index --assume-unchanged dist/*
|
|
```
|
|
|
|
To revert and be able to commit into to the dist directory again:
|
|
|
|
```
|
|
git update-index --no-assume-unchanged dist/*
|
|
```
|
|
|
|
To list ignored files in case of need to troubleshoot
|
|
|
|
```
|
|
git ls-files -v | grep '^[a-z]' | cut -c3-
|
|
```
|
|
|
|
### Build docs
|
|
|
|
Install [Mkdocs Material](https://squidfunk.github.io/mkdocs-material/)
|
|
|
|
```
|
|
pip install mkdocs-material
|
|
```
|
|
|
|
If you hit an `externally managed environment` error on macOS and if you installed python via `brew` try:
|
|
|
|
```
|
|
brew install mkdocs-material
|
|
```
|
|
|
|
Edit markdown in `/docs` directory
|
|
|
|
```
|
|
mkdocs serve
|
|
```
|
|
|
|
### Build Forge website
|
|
|
|
Build the static site and docs in a `site` directory.
|
|
|
|
```
|
|
npm run site:build
|
|
```
|
|
|
|
You can run any static server in the `site` directory but for convenience you can run
|
|
|
|
```
|
|
npm run site:serve
|
|
```
|
|
|
|
### Deploy Forge website
|
|
|
|
TO-DO
|
|
|
|
### Compress splats
|
|
|
|
To compress a splat to [spz](https://scaniverse.com/spz) run
|
|
|
|
`npm run assets:compress <file or URL to ply>`
|