A Rust port of astroterm with some extra stuff. A terminal star map showing stars, planets, the Moon, and constellations,
[NOTE]
This code is ported from astroterm by
da-luce (Dalton Luce), and further work on it is inspired by the original project.
All credit for the original design, algorithms and data preparation goes there.
Pixel rendering with the AT-HYG catalog in Kitty.
| Half-block graphics | Unicode characters | Unicode, zoomed in |
|---|---|---|
 |
 |
 |
With Rust and Cargo installed, run these commands from the project folder:
cargo build --release
./target/release/astroterm -i Tokyo -cCu -mArrow keys look around, + / - zoom, Space pauses, and q quits.
The built-in Bright Star Catalog works offline without downloads. For about 2.5 million stars, use AT-HYG:
./target/release/astroterm -i Tokyo --dataset athyg -t 8 -cCu# Pixel graphics instead of characters
./target/release/astroterm -i Tokyo --renderer pixels -C -m
# Look north-northwest, 20° above the horizon
./target/release/astroterm -i Tokyo --facing NNW --tilt 20 --fov 120 -cCu
# Freeze the sky at a specific date and time (UTC)
./target/release/astroterm -i Tokyo -d 2025-03-01T11:00:00 -s 0 -cCu -m
# Use coordinates instead of a city: latitude, then longitude
./target/release/astroterm -a 1.29 -o 103.85 -cCuWithout --facing, the view is centered overhead. Looking around with the arrow keys switches to a facing view.
Pixel mode detects Kitty, Sixel or iTerm2 support and falls back to colored half-blocks when needed.
If graphics look wrong, try --graphics-protocol halfblocks. To choose a supported protocol yourself,
use --graphics-protocol kitty, sixel or iterm2.
Use --text-scale 0.7 for smaller pixel text or --text-scale 1.2 for larger text
(default: 0.85). This affects Kitty/Sixel/iTerm2 only; characters and half-blocks use your terminal's font size.
| Option | What it does |
|---|---|
-c, -u, -C |
Character colors, Unicode glyphs, constellation lines; combine as -cCu |
-m |
Show the date, location and simulation speed |
-s 100 |
Run time 100× faster; -s 0 starts paused |
-t 8 |
Show fainter stars; default is 5. Higher values show more stars and can be slower |
-l 2 |
Label more stars; default is 0.25 |
--fov 60 |
Zoom into a smaller patch of sky |
--fps 24 |
Set the frame-rate target; defaults are 24 for characters and 12 for pixels |
-R |
Include atmospheric refraction near the horizon |
For all options: ./target/release/astroterm --help.
Dates supplied with -d are UTC; the panel uses the observer's local time zone when available.
Dates use the Gregorian calendar throughout history, with year 0 meaning 1 BC and -1 meaning 2 BC.
A yellow warning marks dates outside tested accuracy ranges. Drawn object sizes are schematic.
| Key | Action |
|---|---|
Arrows or h j k l |
Look around |
+ / - |
Zoom in / out |
| Space | Pause / resume |
] / [ |
Speed up / slow down by 10× |
r |
Reverse time |
0 |
Reset the view |
q, Esc or Ctrl-C |
Quit |
The first run downloads about 200 MB; later runs reuse the file offline.
You can also supply a local AT-HYG CSV or compressed CSV: --dataset ./athyg_40.csv.gz.
On Linux, the default locations are:
- Download:
~/.local/share/astroterm/athyg_40.csv.gz - Prepared catalog cache:
~/.cache/astroterm/
XDG_DATA_HOME and XDG_CACHE_HOME override these locations. The cache can be deleted while the app is closed;
it will be rebuilt from the dataset.
Optional setup and diagnostics
Enable Bash completions for the current shell:
source <(./target/release/astroterm --bash-completions)--debug-frametimes: show the time spent calculating and drawing each frame.--debug-singleframe: display one frame, then exit and print a detailed timing report.--disable-cache: recalculate runtime results every frame; keeps downloaded files and the catalog cache.--cache-config <path>: use custom reuse settings; see examples/cache.toml.
This port adds pixel graphics, interactive pan/zoom/time controls, optional AT-HYG downloads, and extra labels when zoomed in. It also improves astronomical calculations, curved constellation lines, date handling and observer-local time display. Independent accuracy checks are documented in scripts/reference/README.md.
Credits, citations and data sources
Resources used by the original astroterm and this port:
- astroterm by Dalton Luce, the project this code is ported from
- Map Projections - A Working Manual by John P. Snyder
- Wikipedia
- Atractor
- Jon Voisey's Blog: Following Kepler
- Celestial Programming: Greg Miller's Astronomy Programming Page
- Practical Astronomy with your Calculator by Peter Duffett-Smith
- Astronomical Algorithms by Jean Meeus
- NASA Jet Propulsion Laboratory
- Paul Schlyter's "How to compute planetary positions"
- Dan Smith's "Meeus Solar Position Calculations"
- Bryan Weber's "Orbital Mechanics Notes"
- ASCOM
Additional accuracy-model sources:
- Bretagnon & Francou (1988), VSOP87, through the VSOP87E Rust implementation.
- Vondrák, Capitaine & Wallace (2011/2012), long-term precession.
- ERFA: long-term pole and IAU 2000B nutation coefficients; translated code is covered by LICENSE-ERFA, with its SOFA heritage acknowledged there.
- Espenak–Meeus ΔT polynomials.
- Jean Meeus, Astronomical Algorithms, second edition, chapters 22 and 47 (lunar tables 47.A/B).
- WGS84: equatorial radius 6378137 m, inverse flattening 298.257223563, height 0.
- JPL DE440/DE441 and Horizons for independent comparisons.
The files in data/ are taken from the original astroterm repository:
- Stars: Yale Bright Star Catalog
- Star names: IAU Star Names
- Constellation figures: Stellarium (converted from Hipparcos to BSC5 indices using the HYG Database, see astroterm's convert_constellations.py)
- Cities: GeoNames (filtered and condensed using astroterm's filter_cities.py)
- Time-zone boundaries: timezone-boundary-builder, derived from © OpenStreetMap contributors, distributed through tzf-dist under the ODbL 1.0.
- Planet orbital elements: NASA Jet Propulsion Laboratory
Optional, not distributed with this repository:
- Larger star dataset for
--dataset: AT-HYG (Augmented Tycho-HYG) by David Nash / astronexus, about 2.5 million stars from Tycho-2, Gaia DR3 and HYG, licensed CC BY-SA 4.0.--dataset athygdownloads the pinned v4.0 file from its Git LFS media URL into the per-user data folder. Manual copies can be placed anywhere, including the gitignoreddatasets/folder.
MIT, see LICENSE. The original copyright notice of astroterm is kept there.
The unmodified bundled DejaVu Sans Mono font is distributed under its Bitstream Vera/DejaVu license; its license notice is also embedded in the font file.