🔭 Earth

Explore the planet in 3D. A locally-hosted, interactive 3D globe you can search, fly across, and drop personal location pins onto.

Install & availability

Available now. Install from the Companion Hub App Store. Verified on the test fleet: the published image pulls, starts, serves its web UI, and survives a container restart.

Overview

Companion Earth is a locally-hosted, interactive 3D globe rendered in your browser. It is built on Three.js with react-three-fiber  and @react-three/xr , and renders Google’s Photorealistic 3D Tiles when an API key is supplied at build time. You search for a place, fly to it, and can save a personal “pin” for any location you visit.

Earth runs entirely from the container served on your Hub — no account, no cloud sync. Pins you save are stored in your browser’s localStorage on the device you used.

Current capabilities

What Earth does today, as shipped:

• 3D globe rendering with Three.js / react-three-fiber, optionally using Google Photorealistic 3D Tiles
• Geocoding search → fly-to navigation: type a place name and the camera animates to it
• “Pin this location” to save the spot you’re viewing; pins persist in browser localStorage only
• Time-of-day sun-lighting slider that changes the angle of the sunlight on the globe
• WebXR scaffolding via @react-three/xr for headset viewing

Planned / roadmap

These features are described in the product vision but are not present in the current release. Treat them as future work:

• Offline tile cache / local tile server for fully offline maps
• “Digital Memory” pins generated from your photos, notes, and conversations
• Location-history import (Google Timeline, iOS Significant Locations)
• Spatial Scan 3D overlays on the globe
• Rich memory cards, cluster view, and trip export / sharing
• A Settings panel for Offline Maps and Data Sources

Use Cases

• Search any place on Earth and fly to a photorealistic 3D view of it
• Bookmark locations you care about as local pins on your own device
• Adjust the sun angle to see a location under different lighting
• View the globe in a WebXR-capable headset

Architecture

Companion Earth (WebGL)
├── 3D Globe Renderer (Three.js + react-three-fiber)
├── Google Photorealistic 3D Tiles (if VITE_GOOGLE_MAPS_API_KEY baked at build)
├── Geocoding search → camera fly-to
├── Sun-lighting (time-of-day) slider
├── Pin store (browser localStorage)
└── WebXR session (@react-three/xr)

Photorealistic 3D Tiles

Earth can render Google’s Photorealistic 3D Tiles . This requires a Google Maps API key, which must be provided as VITE_GOOGLE_MAPS_API_KEY at build time — Vite bakes the value into the static bundle. The published image is built without a key, so to enable photorealistic tiles you must rebuild the image with your key:

docker build \
  --build-arg VITE_GOOGLE_MAPS_API_KEY=your_key_here \
  -t ci-earth:custom .

Without a key, the globe still renders, but Google’s photorealistic tiles are unavailable.

Setup

Usage

Navigating the Globe

Navigation is search-driven: type a place name (city, landmark, address) into the search bar and Earth geocodes it and flies the camera to that location. There are no free click-drag / scroll camera controls in this build.

Pinning a Location

Fly to a location you want to remember, then click Pin this location. The pin is saved to your browser’s localStorage on the current device. Pins do not sync between devices or to your Hub.

The Sun-Lighting Slider

The time-of-day slider adjusts the angle of the sunlight illuminating the globe — it is a lighting control, not a memory time scrubber.

Troubleshooting

Globe renders but isn’t photorealistic The image was built without a Google Maps API key. Rebuild with VITE_GOOGLE_MAPS_API_KEY set to enable Photorealistic 3D Tiles.

My pins disappeared Pins are stored in the browser’s localStorage. Clearing site data, switching browsers, or using a different device will not show pins saved elsewhere.

Looking for my photos / Digital Memory on the map Memory pins, location-history import, and Digital Memory integration are not part of this release — see Planned / roadmap.

Links

• Digital Memory Server
• Spatial Time Machine
• Photogram