🔭 Earth

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

Companion Earth is deprecated. Its development moved to Companion Atlas, a 4D globe that renders your located Companion Memory events and lets you scrub through time. The Earth app is still in the Hub App Store and still works as described below, but it gets no new features. Atlas is not in the Hub App Store yet, so if you only want a globe to search and pin places on, Earth is the version you can install today.

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.


Hub App Store	Search Companion Earth (app id `ci-earth`) → Install
Port	`18813` in the store listing. The container listens on `5173`.
Requires	Companion Hub v0.2.27 or later
Architecture	`linux/amd64` and `linux/arm64` (multi-arch)

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 from the container served on your Hub and needs no account. Your browser makes outside requests for place searches (to OpenStreetMap’s Nominatim geocoder), for Google’s tiles when you build the image with a key, for located photos from your Companion Memory (see Current capabilities), and for font data that draws text in the 3D scene (from the jsDelivr content network, cdn.jsdelivr.net). 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. Your search text goes to OpenStreetMap’s Nominatim service, or to Mapbox if the image was built with a Mapbox key.
“Pin this location” to save the spot you’re viewing; pins persist in browser localStorage only. A Collections panel lists your pins and lets you fly to one or remove it.
Located photos from Companion Memory. When the app loads, it asks a Companion Memory GraphQL address for your 50 most recent located media events and shows the images as photo pins next to your own. The request is read-only and attaches no sign-in. The address is set when the image is built (VITE_CI_SERVER_GRAPHQL_URL), and the Hub App Store image uses the default, http://ci-server.localhost:8000/graphql. If nothing answers at that address from your browser, or your Memory requires sign-in, the request fails quietly and you see only your own pins.
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

Earth’s Companion Memory support is limited to the located photos described above. It does not import location history or show notes or conversations. The features below are on the roadmap, not in the shipped image.

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
Memory pins generated from your notes and conversations (only located photos are fetched today)
Location-history import (Google Timeline, iOS Significant Locations)
Companion Scan Place and scan 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

Everything runs in the browser from the container on your Hub. Outside requests go to Nominatim for place searches, to Google’s tile service if you built the image with a key, to the Companion Memory address for located photos, and to jsDelivr for font data:

flowchart TB
    E["Companion Earth (WebGL)"]
    E --> R["3D globe renderer<br/>Three.js + react-three-fiber"]
    E --> G["Google Photorealistic 3D Tiles<br/>only if VITE_GOOGLE_MAPS_API_KEY was baked at build"]
    E --> S["Geocoding search → camera fly-to"]
    E --> L["Sun-lighting (time-of-day) slider"]
    E --> P["Pin store<br/>browser localStorage, this device only"]
    E --> N["OpenStreetMap Nominatim<br/>place-search text"]
    E --> J["jsDelivr<br/>font data for scene text"]
    E --> M["Companion Memory GraphQL<br/>located photos, read-only, no sign-in"]
    E --> X["WebXR session<br/>@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

Install from Hub

Search for Companion Earth in the Hub App Store and install.

Open Earth

Use the address on the app’s card in the Hub dashboard. To see how Hub builds app addresses, see Finding your app’s URL.

Open Earth from its card on the Hub dashboard. The initial screen is the globe on a star field, with Search and Collections buttons at the top, a time-of-day slider at the bottom left, an Enter VR button at the bottom right, and the camera position along the bottom.

Companion Earth on first load: a blue globe on a star field, Search and Collections buttons at the top, a time-of-day slider at the bottom left showing 12:00 PM, an Enter VR button at the bottom right, and the camera position along the bottom — Earth on first load. Captured from a local build of the app's source with no map key, so the globe is the plain procedural sphere that the published image also draws.

(Optional) Enable photorealistic tiles

Rebuild the image with VITE_GOOGLE_MAPS_API_KEY set, as shown above, then install your custom build.

Usage

Navigating the Globe

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

The Search Locations panel open over the globe, with the text San Francisco entered and three example results listed below it — Search Locations with three example results. In this capture the geocoder's answer is a fixed example list, not a live search.

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. Open Collections to list your pins, fly to one, or remove it.

The My Collections panel open beside the globe, listing four example pins, San Francisco, Paris, Tokyo, and Cape Town, each with its coordinates, a fly-to button, and a remove button — My Collections with four example pins. They are sample data seeded for this capture.

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 / Companion Memory on the map Earth requests located photos from http://ci-server.localhost:8000/graphql without signing in. If that address doesn’t answer from your browser, or your Memory requires sign-in, no photos appear. Notes, conversations, and location-history import are not part of this release — see Planned / roadmap.