Documentation
Technical deep-dive into Echoes in Orbit: algorithms, challenges, and solutions.
Overview
Echoes in Orbit is a 3D interactive planetarium built with modern web technologies. Users can post confessions (echoes) that are mapped onto a spherical surface, creating an immersive cosmic experience.
Technology Stack
- •Next.js 16 - React framework with App Router
- •Three.js + React Three Fiber - 3D rendering
- •Supabase - PostgreSQL database and real-time subscriptions
- •Clerk - Authentication (optional anonymous posting)
- •TailwindCSS - Styling
Spherical Distribution Algorithm
The core challenge was distributing stars evenly across a sphere surface while maintaining category-based zones. We use a modified Fibonacci sphere algorithm.
Mathematical Foundation
Stars are positioned using spherical coordinates (θ, φ) and converted to Cartesian (x, y, z):
x = radius × sin(φ) × cos(θ) y = radius × cos(φ) z = radius × sin(φ) × sin(θ)
Where:
- • radius = 200 units (planetarium dome)
- • θ (theta) = azimuthal angle (0 to 2π)
- • φ (phi) = polar angle (0 to π)
Category Zones
Each category occupies a specific zone on the sphere:
Fibonacci Sphere Technique
To achieve even distribution within zones, we use the golden angle:
const goldenRatio = (1 + √5) / 2 const goldenAngle = 2π / goldenRatio² // Distribute using golden angle theta = zoneStart + (index × goldenAngle) % zoneRange phi = zoneStart + (index / totalStars) × zoneRange
This prevents clustering and creates natural-looking star fields.
Camera System
The camera is positioned at the center of the sphere, creating a true planetarium experience where users look outward at stars surrounding them.
Configuration
<Canvas
camera={{
position: [0, 0, 0], // Center of sphere
fov: 75 // Wide field of view
}}
/>- •Position (0,0,0): Camera at sphere center
- •FOV 75°: Wide angle for immersive view
- •OrbitControls: Rotate view with mouse/touch
Controls
- • Pinch to zoom
- • Drag to rotate
- • Tap to select
- • Scroll to zoom
- • Drag to rotate
- • Click to select
- • WASD to move
- • Arrow keys rotate
Challenges & Solutions
Challenge 1: Sphere Scale & Visibility
Initial 500-unit sphere radius made stars appear tiny or invisible from camera position.
Reduced sphere radius to 200 units and increased star sizes (30-45 units). Positioned camera at (0,0,0) for optimal viewing distance.
Challenge 2: Star Distribution Clustering
Initial random distribution created visible clusters and gaps, breaking immersion.
Implemented Fibonacci sphere algorithm using golden angle spacing. Added organic noise (±0.15-0.3 radians) for natural variation while maintaining even coverage.
Challenge 3: WebGL Context Errors
Some users encountered WebGL context creation failures due to browser/GPU limitations.
Added error boundary with WebGL detection. Shows helpful fallback UI with troubleshooting steps (enable hardware acceleration, update drivers, try different browser).
Challenge 4: Click Detection on Points
Three.js Points geometry has poor raycasting, making stars difficult to click.
Created invisible sphere meshes (radius 2) at each star position for click detection. Visual Points remain for glow effect, spheres handle interaction.
Visual Effects
Pulsing Stars
Custom shader with time-based sine wave creates subtle breathing effect. Amplitude: 10%, frequency: 0.5Hz.
Constellation Lines
Connects nearest neighbors within galaxies using THREE.Line. Toggleable, color-coded by category, 15% opacity.
Dome Grid
Spherical wireframe (200-unit radius) with 24 radial lines and 12 latitude rings. Subtle 5% opacity for spatial reference.
Cosmic Background
Layered nebula shader with noise functions. Creates depth and atmosphere without overwhelming foreground stars.
Database Schema
Messages Table
CREATE TABLE messages (
id UUID PRIMARY KEY,
content TEXT NOT NULL,
category TEXT NOT NULL,
position JSONB NOT NULL, -- {x, y, z}
is_locked BOOLEAN DEFAULT false,
unlock_at TIMESTAMPTZ,
user_id TEXT,
session_id TEXT,
likes INTEGER DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW()
);Comments & Likes
CREATE TABLE comments ( id UUID PRIMARY KEY, message_id UUID REFERENCES messages(id), user_id TEXT, session_id TEXT, content TEXT NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); CREATE TABLE likes ( message_id UUID REFERENCES messages(id), user_id TEXT, session_id TEXT, PRIMARY KEY (message_id, COALESCE(user_id, session_id)) );