astroterm is a terminal-based celestial viewer written in C using ncurses. It displays the real-time positions of stars, planets, constellations, and more, all within your terminal—no telescope required! Configure sky views by date, time, and location with precise ASCII-rendered visuals. See usage for all supported options!
astroterm is constantly improving, and we'd love to hear your ideas! If you have a suggestion or find a bug, please open an issue and share your feedback.
Stars above Singapore on January 2, 2025
- 🔭 Customizable Sky View: Choose any date, time, and location to explore past, present, or future celestial events
- 📐 Accurate Rendering: Displays the moon, stars, and planets with as much precision as terminal graphics allow.
- 🌘 Moon Phases: Displays precise lunar phases in real-time
- 🌌 Constellation Figures: Renders detailed constellation shapes
- ⚡ Performance Optimized: Lightweight and fast ASCII rendering
Important
When building, you must install the development version of the runtime requirements, which provide the headers and libraries necessary for compiling and linking. These packages are typically marked with a -dev or -devel suffix.
- Unix-like environment (Linux, macOS, WSL, etc.)
- C compiler
meson1.4.0 or newer (installation via python is recommended)ninja1.8.2 or newerncurseslibraryargtable2/3- Some common CLI tools (these are checked for automatically during install)
Warning
ncurses and argtable detection is spotty on some systems, and you may need to install
pkg-config in order
for Meson to find them.
Tip
apt-packages.txt contains all apt packages needed for building and testing on a Debian based distribution. See ci.yml for how astroterm is built and tested on Ubuntu via GitHub Actions.
Clone the repository and enter the project directory:
git clone https://github.com/da-luce/astroterm && cd astrotermRun the install script:
sh install.shYou may now run the generated ./build/astroterm binary or add the astroterm command system-wide via meson install -C build. Pressing q or ESC will exit the display.
Example output:
The --help flag displays all supported options:
Usage: astroterm [OPTION]...
-a, --latitude=<degrees> Observer latitude [-90°, 90°] (default: 0.0)
-o, --longitude=<degrees> Observer longitude [-180°, 180°] (0.0)
-d, --datetime=<yyyy-mm-ddThh:mm:ss>
Observation datetime in UTC
-t, --threshold=<float> Only render stars brighter than this magnitude (def
ault: 5.0)
-l, --label-thresh=<float>
Label stars brighter than this magnitude (default:
0.25)
-f, --fps=<int> Frames per second (default: 24)
-s, --speed=<float> Animation speed multiplier (default: 1.0)
-c, --color Enable terminal colors
-C, --constellations Draw constellation stick figures. Note: a constella
tion is only drawn if all stars in the figure are o
ver the threshold
-g, --grid Draw an azimuthal grid
-A, --ascii Only use ASCII characters
-m, --metadata Display metadata
-r, --aspect-ratio=<float>
Override the calculated terminal cell aspect ratio.
Use this if your projection is not 'square.' A valu
e around 2.0 works well for most cases
-h, --help Print this help message
-i, --city=<city_name> Use the latitude and longitude of the provided city
. If the name contains multiple words, enclose the
name in single or double quotes. For a list of avai
lable cities, see: https://github.com/da-luce/astro
term/blob/main/data/cities100000.csv
Say we wanted to view the sky at 5:00 AM (Eastern) on July 16, 1969—the morning of the Apollo 11 launch at the Kennedy Space Center in Florida. We would run:
astroterm --latitude 28.573469 --longitude -80.651070 --datetime 1969-7-16T8:00:00Finding the precise coordinates can be cumbersome, so we could also use the nearest major city to achieve a similar result:
astroterm --city Orlando --datetime 1969-7-16T8:00:00 -mWhile we're still waiting for someone to invent time travel, we can cheat a little by using Stellarium to confirm that this aligns with reality.
If we then wanted to display constellations and add color, we would add --constellations --color as options.
If you simply want the current time, don't specify the --datetime option and
astroterm will use the system time. For your current location, you will still
have to specify the --lat and --long options, or provide the nearest city with the --city option.
For more options and help, run astroterm -h or astroterm --help.
Tip
Use a tool like LatLong to get your latitude and longitude.
Tip
Star magnitudes decrease as apparent brightness increases, i.e., to show more stars, increase the threshold.
Run meson test within the build directory. To get a coverage report, subsequently run ninja coverage.
Many thanks to the following resources, which were invaluable to the development of this project.
- 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
- 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
- A Fast Bresenham Type Algorithm For Drawing Ellipses
- Stars: Yale Bright Star Catalog
- Star names: IAU Star Names
- Constellation figures: Stellarium (Converted from Hipparchus to BSC5 indices using the HYG Database—see convert_constellations.py)
- Cities: GeoNames (Filtered and condensed using filter_cities.py)
- Planet orbital elements: NASA Jet Propulsion Laboratory
- Planet magnitudes: Computing Apparent Planetary Magnitudes for The Astronomical Almanac