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.

Building on this goal, Virtual Soils is an immersive web experience that explores new ways of visualizing soil and environmental landscapes through 3D Gaussian splats (radiance fields). Combining interactive mapping, real-time rendering, and educational storytelling, the project allows users to move seamlessly between geographic locations and immersive 3D scenes directly in the browser.

Virtual Soils aims to make soil science more accessible and engaging through spatial exploration and interactive environmental visualization.

Primary Features

Interactive Geospatial Exploration

The experience is centered around a Leaflet and OpenStreetMap-powered interface where users can browse soil and landscape sites geographically. Site locations appear as dynamic pins loaded from a signed /pins API and include metadata such as:

titles and descriptions,
geographic coordinates,
thumbnails,
Gaussian splat scene links,
optional spatial markers and annotations.

Users can open immersive 3D scenes directly from map popups and transition smoothly between map-based exploration and scene viewing.

Immersive 3D Gaussian Splat Viewer

The platform includes a browser-based 3D viewer built with Three.js and @mkkellogg/gaussian-splats-3d for rendering radiance field reconstructions of soil and landscape environments.

Features include:

real-time Gaussian splat rendering,
fly-style navigation controls,
HDR skybox lighting,
loading and performance states,
FPS and movement feedback,
adjustable quality and performance settings.

The viewer is also available as a standalone sharable route using URL query parameters, allowing direct linking to specific scenes and marker configurations.

Spatial Annotation & Marker System

Virtual Soils supports world-space markers and annotations embedded directly into 3D environments. Markers can contain:

labels,
icons,
contextual environmental information,
interactive spatial references.

This system supports educational storytelling, guided exploration, and research workflows within immersive scenes.

Scene Authoring & Editing Workflow

A dedicated Editor environment allows contributors to select sites and place, modify, or remove markers directly within the 3D viewer. The editor shares the same rendering stack as the public experience and supports authoring workflows for environmental storytelling and spatial annotation.

Administrative management of site metadata and stored marker data is handled through a secure Admin interface connected to AWS-backed APIs.

Educational & Research Context

The project includes long-form informational content explaining:

the motivation behind Virtual Soils,
radiance fields and Gaussian splatting,
environmental and soil science concepts,
future directions for immersive scientific visualization.

Images and video content are integrated throughout the experience to support science communication and public engagement.

Cloud Infrastructure & Technology Stack

Virtual Soils is built using:

React 19,
TypeScript,
Vite,
React Router,
Three.js,
Leaflet,
OpenStreetMap,
AWS Amplify and Cognito.

The platform uses AWS-backed APIs for authentication and content management, with signed request workflows implemented through aws4fetch where configured.

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

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