Trailens : reconnect with the real world

What I Built
🌲 TrailLens: AI that helps you touch grass.
Most modern apps are engineered like digital slot machines: algorithms designed to monopolize attention, maximize daily active screen time, and keep human eyes glued to glowing glass. Even outdoor companion apps often clutter the experience with social feeds, notification pings, and gamified loops that pull you out of the moment.

TrailLens flips this paradigm on its head.

"The best TrailLens session is one where the user spends very little time looking at TrailLens."

text
GO OUTSIDE 🌿
↓
SEE / HEAR A BIRD 🐦
↓
CAPTURE / SELECT PHOTO 📷
↓
LOCAL AI IDENTIFICATION (<25ms, 0% Cloud) ⚡
↓
DISCOVER ONE FASCINATING FIELD MARK 💡
↓
EARN XP / STREAKS / BADGES 🎖️
↓
PUT PHONE AWAY (Touch Grass Mode) 🔒
↓
KEEP EXPLORING THE REAL WORLD 🌳
Who It's For & How It Works
TrailLens is built for hikers, weekend naturalists, birders, trail runners, and anyone feeling digital burnout who wants an excuse to explore outside:

Snap & Learn in Seconds: Capture or upload a bird photo from the trail. Within 22.4 milliseconds, local AI classifies the species across a curated 200-bird catalog.
Digest One Field Mark: Instead of dumping an overwhelming wall of text, TrailLens highlights one key distinguishing field mark (e.g., wing bars, beak curve, crest color) so you can look back up at the tree with newly trained eyes.
Calibrated Uncertainty (Honest AI): If a bird is backlit or distant, TrailLens doesn't hallucinate. It evaluates prediction entropy and says: "🤔 I'm not confident yet (38%). Look closer at the beak shape or listen for its call."
"Touch Grass" Lock Mode: After logging your observation, TrailLens activates an intentional tranquil exploration mode. It locks distracting UI elements, plays ambient nature tones generated via the Web Audio API, and runs a gentle breathing timer that tracks your outdoor exploration minutes—encouraging you to pocket your device and keep walking.
Authentic Streaks: Streaks and badges are awarded for actual outdoor exploration sessions, not hollow app opens.
Demo
Interactive Local Walkthrough & Demo: Run locally in 1 click via python run_app.py or inspect the pre-bundled test suites and mock samples in the repo.
Live UI Highlights:
Viewfinder & Local Inference Engine: Instant classification with visual confidence indicators and top-5 alternative candidates.
200-Species Field Guide: Silhouette collection vault that reveals species cards, rarity stars (1★ to 5★), and synthesized bird calls as you discover them in the wild.
Touch Grass HUD: Real-time session tracker comparing minutes spent outdoors against minutes on screen.
Developer Diagnostics Panel: Live telemetry displaying inference latency (ms), parameter footprint, memory consumption, and hardware execution context.
text
[ 🌲 TrailLens Field Console ]
├── Local AI Latency: 22.4 ms (Standard CPU)
├── Parameters: 1.32M (MobileNetV3-Small)
├── Model Binary Footprint: 5.45 MB
└── Cloud API Requests: 0 (100% Offline)
Code
The complete source code, dataset provenance licenses, test suites, and pre-trained weights are open-source on GitHub:

satyam-257 / TrailLens

🌲 TrailLens

AI that helps you touch grass.
Identify birds with private, offline AI. Discover one fascinating field mark. Put your phone away and keep exploring.

---

🧭 Product Vision & Core Philosophy

Most outdoor apps are designed like slot machines: they attempt to maximize daily screen time, bombard users with social feeds, and keep their eyes glued to glass.

TrailLens reverses this paradigm.

GO OUTSIDE 🌿
     ↓
SEE / HEAR A BIRD 🐦
     ↓
CAPTURE / SELECT PHOTO 📷
     ↓
LOCAL AI IDENTIFICATION (22ms, 0% Cloud) ⚡
     ↓
DISCOVER ONE FASCINATING FIELD MARK 💡
     ↓
EARN XP / STREAKS / BADGES 🎖️
     ↓
PUT PHONE AWAY (Touch Grass Mode) 🔒
     ↓
KEEP EXPLORING THE REAL WORLD 🌳

"The best TrailLens session is one where the user spends very little time looking at TrailLens."

---

📐 Architecture Diagram

                                TRAILLENS
                                    │
       ┌────────────────────────────┴────────────────────────────┐
       │                                                         │
   Web / Mobile UI (React + Tailwind)                      Local AI

…

View on GitHub

Repository: https://github.com/satyam-257/TrailLens
License: MIT

Repository Architecture
text
traillens/
├── ml/ # PyTorch vision training, evaluation & inference pipeline
│ ├── dataset.py # Outdoor affine & photometric augmentation pipeline
│ ├── model.py # MobileNetV3-Small & EfficientNet classifier heads
│ ├── inference.py # LocalVisionIdentifier with Shannon entropy thresholds
│ ├── train.py # Reproducible training with Cosine Annealing & Label Smoothing
│ └── export.py # TorchScript compilation for edge devices
├── server/
│ └── app.py # FastAPI backend with hardware telemetry (psutil)
├── frontend/ # React + Tailwind + Vite web client
│ ├── src/components/ # TouchGrassMode, FieldGuide, Viewfinder, DeveloperHUD
│ └── src/utils/audio.js # Procedural Web Audio API soundscape synthesizer
└── tests/ # 100% passing test suite across ML and API contracts
How I Built It

1. The Open-Weight AI Core TrailLens avoids multi-gigabyte closed multimodal APIs in favor of an ultra-compact, fine-grained computer vision architecture:

Base Architecture: Open-weight MobileNetV3-Small fine-tuned on North American avian taxonomy (derived from CUB-200-2011 and NABirds benchmarks).
Lightweight Footprint: Only 1,325,032 parameters compiling to an exportable 5.45 MB TorchScript binary.
Sub-25ms CPU Inference: Executes at 22.4 ms per inference on a standard consumer laptop CPU (equivalent to 45+ FPS)—no GPU or cloud cluster required.

1. Calibrated Uncertainty Engine (Entropy vs. Blind Guessing) Proprietary vision APIs frequently guess wrong with 99% false confidence when given blurry nature photos. TrailLens uses a rigorous uncertainty pipeline:

python

ml/inference.py snippet

probs = F.softmax(logits / self.temperature, dim=1)
entropy = -torch.sum(probs * torch.log(probs + 1e-12)).item()
is_uncertain = (
top1_conf < self.confidence_threshold or
entropy > self.uncertainty_entropy_threshold
)
When confidence dips below 60% or predictive entropy spikes, the system shifts into Field Observation Coaching, prompting the user to observe field marks with their own eyes rather than trusting a flawed prediction.

1. Pluggable BirdIdentifierBase The inference engine exposes an extensible abstract interface. Anyone can hot-swap the classifier backbone with ResNet, EfficientNet-B0, or a custom vision transformer in under 5 lines of code:

python
class BirdIdentifierBase(ABC):
@abstractmethod
def identify(self, image_input: Union[str, bytes, Image.Image], top_k: int = 5) -> Dict[str, Any]:
"""Runs identification and returns structured predictions with calibrated confidence."""
pass

1. Zero External Audio Assets (Web Audio API Synthesizer) To stay featherweight and offline, bird calls and ambient nature soundscapes are synthesized mathematically in the browser using the Web Audio API (frequency modulation and bandpass filters), requiring zero remote MP3 downloads.

Why Does Open Innovation Matter?

1. Wilderness Reality: Zero Cell Reception
   The best birding spots, old-growth forests, and mountain trails have zero cellular signal. Proprietary cloud APIs fail completely the moment you lose LTE. Open-weight models running on local silicon make AI a dependable wilderness tool, accessible everywhere on Earth without a satellite subscription.

2. Ethical Outdoor Privacy
   Nature observation shouldn't come at the cost of corporate data harvesting. Proprietary platforms often ingest user uploads and GPS coordinates to monetize training sets or feed location advertising. Open-source AI ensures that photos, journal notes, and location data never leave your local device.

3. Scientific Scrutiny & Attribution
   Bird conservation relies on open scientific data (e.g., Cornell Lab of Ornithology and Caltech-UCSD). Open-source AI respects this lineage: dataset provenance is documented (DATASET_LICENSES.md), model architectures are reproducible, and prediction uncertainty is mathematically transparent.

4. Anti-Addiction Alignment
   Commercial AI products are optimized for engagement metrics—keeping you scrolling and querying. Because TrailLens is open-source and free of ad-driven business models, its objective function can genuinely prioritize human well-being: using AI as a brief bridge to help you look up, put your phone in your pocket, and touch grass.

My Agent Session
TrailLens was architected and refined with Google Antigravity / Gemini 3.7, utilizing agentic workflows to build:

The PyTorch offline inference pipeline and TorchScript compilation script.
The uncertainty calibration math and unit test harness (tests/).
The nature-inspired UI with procedural audio synthesis and Touch Grass screen lock mechanisms.
Prize Categories
Overall Challenge (Hacktoberfest Week 1: Touch Grass)