Introduction

Practicing Soil Science requires extensive observation in the field. This poses a challenge when training students, so multimedia representations are used to bridge the gap. This project aims to provide an example of teaching resources that leverage developments in accessible immersive media web standards as well as the performance benefits of 3D Gaussian splatting.

Primary Features

Virtual Soil is a web experience built around Virtual Soils: exploring 3D Gaussian splat (radiance field) models of soil and landscape sites. The main path is a Map view powered by Leaflet and OpenStreetMap. Locations appear as pins loaded from a signed /pins API, each with a title, coordinates, a link to splat data, description, thumbnail, and optional markers. The map can load on demand; popups let you open an embedded 3D viewer that sits over the map so you can move from map to scene and back.

The viewer uses Three.js and @mkkellogg/gaussian-splats-3d to show one scene at a time, with fly navigation, an HDR skybox, a loading state, and quality/perf controls plus basic on-screen feedback (e.g. FPS and movement). World-space markers (icons and labels) can be placed in the scene and interacted with. The same viewer is available as a standalone route with URL query parameters for the splat path and markers, so you can share direct links.

The home shell also has an Info tab with long-form About: why the project exists, what radiance fields and Gaussian splats are, and where the project is headed, with images and video aimed at soil science and education. A separate Editor route uses the same 3D stack so you can select a site from the pin list and place, edit, or remove markers in the scene; in the current design, those edits are for authoring workflow, while the Admin area is how stored site data (including markers) is maintained. Admin is gated by AWS Amplify (Cognito) and talks to a fields API for create/read/update/delete of locations and metadata, with the public pins shape feeding the map and editor; public requests use AWS request signing (aws4fetch) where configured.

The stack is React 19, TypeScript, Vite, React Router, plus the 3D and map libraries above and AWS for auth and API access.

First Time Setup Guide

Prerequisites: A current Node.js (LTS) and npm (the repo is a Vite + React + TypeScript app; no root .env.example is committed, so you will create env files yourself).

1. Install dependencies

From the project root: npm install.

2. Environment variables

The app expects a base API URL for data and admin:

Set VITE_API_URL to the origin of your deployed API (no trailing path segment issues; code uses `${VITE_API_URL}/pins`, etc.).
If it is missing at build/dev time, fetches can produce invalid URLs (e.g. undefined/pins), so the map and editor will not load locations until this is set correctly.

docs/PROJECT.md also documents optional VITE_AWS_ACCESS_KEY_ID, VITE_AWS_SECRET_ACCESS_KEY, and VITE_AWS_REGION for AWS request signing in setups that use aws4fetch / IAM signing. The map and editor paths in the current tree use plain fetch to `${VITE_API_URL}/pins`; whether your API requires SigV4 or CORS depends on the API Gateway / Lambda you point at, not on the Vite file alone.

3. Local API during development

vite.config.ts proxies /pins to http://localhost:3000. That only helps if the browser actually requests the dev server for /pins (e.g. VITE_API_URL set to your Vite dev origin such as http://localhost:5173, or a relative base that resolves there). If VITE_API_URL is a different host, traffic goes there directly and the proxy is unused; then either run your API on the URL you set or use a full URL to a deployed stage.

4. Start the app

npm run dev starts the Vite dev server (default port 5173 unless changed). Open the URL Vite prints in the browser.

Poster

File:W25 Virtual Soils Poster.pdf

Development Team

Kai Zhang - Developer

Riddhima Gupta - Developer

Kieren Stewart - Developer

Khushi Narang - Developer

Amy Yiqin Li - Designer

Dante Cerrone - Staff Developer

Bibliography

- https://github.com/mkkellogg/GaussianSplats3D

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Last edit: September 2025 EML

Permission is granted to copy, distribute and/or modify this document according to the terms in Creative Commons License, Attribution-ShareAlike 4.0. The full text of this license may be found here: CC by-sa 4.0