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:

Hope
Top-front-right quadrant
Regret
Top-back-left quadrant
Advice
Middle band (wraps around)
Dream
Bottom-front-right
Gratitude
Bottom-back-left

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

Touch
  • • Pinch to zoom
  • • Drag to rotate
  • • Tap to select
Mouse
  • • Scroll to zoom
  • • Drag to rotate
  • • Click to select
Keyboard
  • • WASD to move
  • • Arrow keys rotate

Challenges & Solutions

Challenge 1: Sphere Scale & Visibility

Problem:

Initial 500-unit sphere radius made stars appear tiny or invisible from camera position.

Solution:

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

Problem:

Initial random distribution created visible clusters and gaps, breaking immersion.

Solution:

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

Problem:

Some users encountered WebGL context creation failures due to browser/GPU limitations.

Solution:

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

Problem:

Three.js Points geometry has poor raycasting, making stars difficult to click.

Solution:

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))
);