orbital

A real-time satellite tracker for the terminal. Renders Earth as a 3D ASCII globe and tracks satellites using SGP4 orbital mechanics from live TLE data.

Features a rotating 3D Earth with continent geography, day/night cycle, city lights, aurora borealis, starfield with shooting stars, chase camera, and a real-time HUD — all in your terminal.

Demo

ISS Tracking	Satellite Search

Contents

• Installation
• Usage
• Features
• Controls
• License

Installation

Build from Source

You need Rust installed.

git clone https://github.com/zidankazi/orbital.git
cd orbital
cargo install --path .

Or run directly:

cargo run --release

Usage

Track the ISS (default):

orbital

CLI Options

Track any satellite by name or NORAD ID:

# Track the Hubble Space Telescope
orbital --satellite hubble

# Track by NORAD Catalog Number
orbital --id 20580

# Use imperial units (miles, mph)
orbital --imperial

# Set your location manually
orbital --location "40.7,-74.0"

# Set a custom frame rate
orbital --fps 30

# Combine flags
orbital --satellite tiangong --imperial --fps 30

Features

🌍 3D Earth Rendering

Ray-cast 3D globe with realistic continent outlines, elevation data, ocean/land differentiation, and biome-based coloring — all rendered in ASCII.

🌗 Day/Night Cycle

Real-time sun position drives a smooth day/night terminator. The night side shows city lights as warm amber dots and aurora borealis shimmering near the poles.

🛰️ Satellite Tracking

Live TLE data from CelesTrak with SGP4 orbital propagation. Tracks any satellite — ISS gets a detailed solar-panel sprite, others get a compact icon. Fading orbital trail shows the flight path.

📡 Real-Time HUD

Box-drawn heads-up display showing latitude, longitude, altitude, speed, distance from your location, camera mode, zoom level, and both UTC/local time.

⭐ Starfield

Multi-layered starfield with twinkling stars, a Milky Way band, and occasional shooting stars streaking across the sky.

🎥 Chase Camera

Auto-follow camera that keeps the satellite centered while Earth rotates beneath. Supports manual pan, zoom, and tilt with smooth damping.

Controls

Key	Action
← → ↑ ↓	Pan camera
Space	Toggle auto-follow
+ / -	Zoom in / out
R	Reset camera
Q / Ctrl+C	Quit

Data Sources

• TLE Data: CelesTrak for orbital elements
• Orbital Mechanics: SGP4 propagation via the sgp4 crate
• Geography: Built-in coastline and elevation dataset
• User Location: IP geolocation via ipinfo.io (optional)

License

MIT