README.md

metadata

title: Trailhead
emoji: 🌲
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.18.0
python_version: 3.1
app_file: app.py
pinned: false

🌲 Trailhead — Tactical Trail Computer & Route Planner

"Plan online at basecamp, trek offline on the trail."

Trailhead is an offline-first, mobile-friendly trail computer and navigation assistant designed for wilderness hiking and backpacking. It parses GPX files, calculates smoothed elevation profiles, generates interactive offline maps, and leverages an in-process Large Language Model (LLM) and Speech-to-Text (ASR) to guide you safely through the backcountry without relying on cellular connection.

---

🧭 System Architecture

graph TD
    A[Basecamp: Signal / Wifi] -->|Download Map Tiles & Route| B(GPX Upload / ORS Fetch)
    B --> C{Trailhead App}
    C --> D[Deterministic Engine]
    C --> E[AI Navigation Layer]
    C --> F[Offline Journaling]
    
    D -->|Naismith's Rule & Smoothing| G[Distance / Pace / smoothed Elevation / ETA]
    E -->|Gemma-4 GGUF via llama.cpp| H[Contextual Checkpoint Briefing & RAG First-Aid]
    F -->|whisper.cpp ASR| I[SQLite Database + Post-Trek Shareable Reports]
    
    G --> J[Tactical HUD UI]
    H --> J
    I --> J

---

✨ Key Features

1. Ingest, Planning & POI Fetching (Basecamp Mode)

• GPX Ingestion: Directly parse track files, extract metadata, and calculate cumulative distances/elevations.
• OSM Overpass API Integration: Pulls nearby Points of Interest (POIs) such as drinking water, alpine huts, campsites, viewpoints, and emergency phones directly from OpenStreetMap.
• Custom Buffer Filter: Filters POIs locally using the haversine formula to only retain those within a 150m buffer of the trail.
• Enhanced GPX Export: Saves fetched POIs into standard GPX <extensions> and <wpt> tags to be stored on disk and read offline.

2. Tactical HUD, Live GPS & Trek Simulation

• Live GPS Tracking: Uses client-side browser Geolocation API (getCurrentPosition & watchPosition) to plot real-time coordinates. Renders a pulsing blue Google Maps-style location marker with a shaded accuracy circle.
• Smart Auto-Zoom: Dynamically scales map zoom levels using Leaflet fitBounds to display both the predefined route path and the hiker's live position simultaneously.
• Unified Trek Controls: The ▶ START button serves a dual purpose: if GPS is enabled, it initiates live tracking and locks/centers position updates (throttled at 5 seconds to conserve battery); otherwise, it runs the time-lapse simulation. ⏸ PAUSE freezes updates, and 🔄 RESET clears status and restores initial layout.
• Flicker-Free Client-Side Map: Renders a native Leaflet canvas directly within the Gradio container. State synchronization from textboxes updates coordinates smoothly in real time without iframe refreshes.
• Color-Coded Vector Markers: Custom circle-markers are drawn for POIs (Blue = water, Green = huts, Orange = campsite, Purple = viewpoints, Red = emergency phone) to avoid external asset requests.
• Playback Simulation Player: Play, pause, speed slider, and reset state controller updates the hiker's current position along the trail when GPS is disabled.
• Live HUD Dashboard: Telemetry tracking route completion percentage, cumulative distance hiked, current altitude, and next-checkpoint ETA.
• Offline Proximity Alerts: Audio-visual indicators triggered automatically when the hiker is within 150m of any filtered POI.

3. Unified Wilderness Guide & First-Aid AI

• Unified Chatbot Interface: Merges the Wilderness Guide AI and Wilderness First-Aid manual query engine into a single chatbot interface.
• Emergency Quick-Lookup: Column layout integrates a sidebar with the offline Emergency Card and a Manual Quick Search accordion for instant access.
• Robust Local LLM Processing: Configured with a 120s timeout threshold to prevent premature mock fallback during heavy local prompt prefilling.
• Keyword RAG Search: Local keyword intersection retriever indexes the manual (first_aid_guide.json) and guides the local gemma-2b-it LLM model to return highly grounded first-aid instructions with manual citations.
• Proximity Checkpoint Narration: Delivers terrain updates, safety advice, and target destination briefings as hikers approach landmarks.

4. Live GPS Tracking & 1s Updates

• 1-Second Updates: Configured GPS tracking refresh interval to 1s, enabling high-resolution position updates on the trail.
• Active Proximity POI Highlights: Automatically detects and highlights close Points of Interest (POIs) near the hiker's current coordinates in the Active Proximity Alerts panel.

5. Offline Voice Journal & Post-Trek Reports

• ASR Voice Logs: Dictate logs hands-free in the cold using whisper.cpp tiny. Logs transcribing audio, time, and coordinates are saved directly to SQLite.
• Post-Trek Storyteller: Converts journal entries and raw GPS points into an engaging, non-technical first-person narrative (optimized for social media sharing) without listing raw coordinates.

---

🚀 Quick Start

Prerequisites

Make sure you have Python 3.11+ installed.

Installation

1. Clone the repository:

   git clone <your-github-repo-url>
   cd TrailHead
   

2. Create and activate a virtual environment:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # macOS/Linux:
   source .venv/bin/activate
   

3. Install dependencies: For local LLM inference on CPU, install llama-cpp-python first (using precompiled wheels is recommended for Windows):

   pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
   pip install -r requirements.txt
   

4. Run the Application:

   python app.py
   

   Open http://localhost:7860 in your web browser.

---

📱 Android Installation (Termux)

You can run Trailhead entirely offline on an Android device using Termux. This provides a portable trail computer right in your pocket.

1. Install Termux from F-Droid (do not use the Google Play Store version as it's deprecated).
2. Open Termux and install dependencies:

   pkg update && pkg upgrade -y
   pkg install python git clang libcrypt libffi -y
   

3. Clone and setup the project:

   git clone https://github.com/xandie985/TrailHead.git
   cd TrailHead
   python -m venv .venv
   source .venv/bin/activate
   

4. Install Python requirements:

   pip install -r requirements.txt
   

   (Note: For local LLM processing on Android, compiling llama-cpp-python might require additional CMake and build-essential packages. If you just need the map and GPS features, the base requirements are sufficient).
5. Run the App:

   python app.py
   

6. Open your mobile browser and navigate to http://127.0.0.1:7860.

---

🤗 Hugging Face Spaces Setup

This project is fully compatible with Hugging Face Spaces using the Gradio SDK.

Deploy to Hugging Face Spaces

1. Create a new Space on Hugging Face using the Gradio SDK.
2. Push the codebase directly to your Hugging Face Space repository.
3. The GGUF LLM and Whisper ASR models will download automatically upon first request at runtime and cache locally for offline use.

---

🛠️ Technical Details & Algorithms

Elevation Smoothing Filter

Raw GPX files suffer from GPS vertical drift, leading to massive over-reporting of elevation gain. Trailhead resolves this by:

1. Batch-querying missing elevations via the Open-Meteo API (when GPX coordinates lack altitude).
2. Applying a Moving Average window (size 5) to smooth out high-frequency noise.
3. Using a threshold delta (default 2.0 meters), only summing elevation changes that exceed the threshold: $$\Delta E = \sum |e_i - e_{i-1}| \quad \text{for} \quad |e_i - e_{i-1}| \ge 2.0\text{m}$$

Time Estimation (Naismith's Rule)

We estimate trail times dynamically using the classic Naismith's formula: $$\text{Time (hours)}=\frac{\text{Distance (km)}}{5.0}+\frac{\text{Elevation Gain (m)}}{600.0}\backslash text\{Time\; (hours)\}\; =\; \backslash frac\{\backslash text\{Distance\; (km)\}\}\{5.0\}\; +\; \backslash frac\{\backslash text\{Elevation\; Gain\; (m)\}\}\{600.0\}$$ This represents a conservative baseline for an average loaded hiker on established trails.

---

📄 License

This project is licensed under the MIT License. See LICENSE for details.