TerraExplorer

TerraExplorer is an interactive 3D globe application for exploring locations, discovering geographic information, and building journeys across the world.

Search for cities, landmarks, historical sites, and points of interest, explore locations on a 3D globe or street-level map, view AI-generated information and current news, listen to location narration, and use Trace Route to turn articles, URLs, or text into connected geographic journeys.

Features

• 3D Globe: Rotate, zoom, and explore the Earth from orbit to street level.
• Smart Search: Find locations using natural-language queries.
• AI Location Insights: Generate summaries, facts, population, climate, and other geographic information using Google Gemini or local LM Studio inference.
• Street Maps: Switch to detailed CARTO vector maps based on OpenStreetMap data.
• Documentary Mode: Experience cinematic camera transitions from the globe to selected locations.
• Location Narration: Listen to location titles and descriptions using System Voice, ultra-fast local Kokoro TTS, or local Orpheus TTS.
• Real-Time News: View current news relevant to selected locations.
• Trace Route: Extract locations from articles, URLs, or text and build connected journeys.
• Favorites & Notes: Save locations and attach personal notes.
• Visual Themes: Parchment, Modern, CRT Green, and CRT Amber.

Kokoro TTS

Kokoro is an optional local neural TTS provider for TRACE ROUTE narration, powered by Apple Silicon MLX (mlx-community/Kokoro-82M-bf16).

• Separate Local Service: Runs as an isolated Python service on http://127.0.0.1:8880.
• Model & Caching: The Kokoro model weights (~82M parameters) are downloaded from Hugging Face on first run and cached locally. The model weights and Python virtual environment are not committed to Git.
• Service Availability: The Kokoro service must be running locally before selecting or using Kokoro narration in TerraExplorer.

Setup

1. One-Time Environment Setup:

   ./scripts/setup-kokoro.sh

   This creates an isolated virtual environment at local-services/kokoro-tts/.venv/ (Python 3.11+) and installs the necessary dependencies without modifying TerraExplorer's global or Node environment.

2. Start the Service:

   ./scripts/start-kokoro.sh

   The service listens on:

   http://127.0.0.1:8880
   

   (To override the port, set KOKORO_PORT=8885 ./scripts/start-kokoro.sh)

Voice Options

The following six voices are available in the Settings Panel:

• Michael (American) — am_michael (Default)
• George (British) — bm_george
• Bella (American) — af_bella
• Sarah (American) — af_sarah
• Emma (British) — bf_emma
• Isabella (British) — bf_isabella

Repository Files

• local-services/kokoro-tts/: Contains the lightweight HTTP bridge server (server.py) and requirements (requirements.txt).
• scripts/setup-kokoro.sh: Automated setup script to configure the Python virtual environment.
• scripts/start-kokoro.sh: Startup script to run the Kokoro TTS bridge server.

Note: The Python virtual environment (.venv), model weight caches, and generated audio files are intentionally excluded from Git.

Local Orpheus TTS

TerraExplorer also supports local neural narration through Orpheus TTS and LM Studio.

See the Orpheus TTS setup guide for installation, configuration, and troubleshooting.

Setup

Environment Variables

Copy .env.example to .env and configure the services you want to use:

# AI
GEMINI_API_KEY=your_gemini_api_key

# Maps
VITE_CARTO_API_KEY=your_carto_api_key

# Optional news providers
VITE_NYT_API_KEY=your_nytimes_api_key
VITE_NEWS_API_KEY=your_newsapi_org_key
VITE_NEWS_DATA_API_KEY=your_newsdata_io_key

AI, local LM Studio, narration, and news settings can also be configured in the application.

Run

npm install
npm run dev

Build for production:

npm run build

Key Components

• Earth.tsx - 3D globe, lighting, atmosphere, and location markers.
• OSMMapLayer.tsx - CARTO/OpenStreetMap street-level map rendering.
• InfoPanel.tsx - Location information, news, notes, and related content.
• Controls.tsx - Search, navigation, Trace Route, themes, and settings.
• SettingsPanel.tsx - AI, map, news, narration, and Documentary Mode configuration.
• documentaryController.ts - Cinematic camera and narration orchestration.
• narrationService.ts - Browser speech synthesis.
• geminiService.ts - AI location intelligence and search classification.
• osmTileService.ts - CARTO map styles and geometry.
• routeExtractionService.ts - Location extraction and geographic resolution.

AI Development Context

Before making architectural changes, review docs/AI_CONTEXT.md.

It contains the project's architecture, conventions, data models, debugging history, and design decisions.