{"id":23524280,"url":"https://github.com/da-luce/astroterm","last_synced_at":"2025-05-14T20:10:46.991Z","repository":{"id":188304139,"uuid":"654385890","full_name":"da-luce/astroterm","owner":"da-luce","description":"A planetarium for your terminal! Explore stars, planets, constellations, and more, all rendered right in the command line—no telescope required. ✨🪐","archived":false,"fork":false,"pushed_at":"2025-02-22T19:02:28.000Z","size":95869,"stargazers_count":885,"open_issues_count":21,"forks_count":14,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-07T06:39:46.934Z","etag":null,"topics":["ascii","ascii-art","c","command-line","console","linux","linux-terminal","screencast","screensaver","space","terminal","tui","unix","unix-shell"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/da-luce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-16T02:43:30.000Z","updated_at":"2025-05-06T20:58:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"8f45df7f-fdac-407b-8973-f017347aa400","html_url":"https://github.com/da-luce/astroterm","commit_stats":null,"previous_names":["da-luce/starsaver","da-luce/astroterm"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fastroterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fastroterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fastroterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/da-luce%2Fastroterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/da-luce","download_url":"https://codeload.github.com/da-luce/astroterm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219374,"owners_count":22034397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascii","ascii-art","c","command-line","console","linux","linux-terminal","screencast","screensaver","space","terminal","tui","unix","unix-shell"],"created_at":"2024-12-25T18:15:25.830Z","updated_at":"2025-05-14T20:10:41.975Z","avatar_url":"https://github.com/da-luce.png","language":"C","readme":"# 🌌 astroterm\n\n[![Test Status](https://github.com/da-luce/astroterm/actions/workflows/ci.yml/badge.svg)](https://github.com/da-luce/astroterm/actions?query=branch%3Amain)\n[![codecov](https://codecov.io/gh/da-luce/astroterm/graph/badge.svg?token=80C0ZQBVTM)](https://codecov.io/gh/da-luce/astroterm)\n[![Latest release](https://img.shields.io/github/v/release/da-luce/astroterm?label=Latest%20Release\u0026cacheSeconds=3600)](https://github.com/da-luce/astroterm/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n`astroterm` is a terminal-based star map written in `C`. 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](#usage) for all supported options!\n\n`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.\n\n![The night sky above Singapore on January 2, 2025](./assets/SG_2025-01-02.gif)\n\n_\u003cp align=\"center\"\u003eThe night sky above Singapore on January 2, 2025\u003cbr\u003eSee \u003ca href=\"#example-1\"\u003eusage\u003c/a\u003e on how to obtain this view\u003c/p\u003e_\n\n\u003c!-- omit in toc --\u003e\n## Table of Contents\n\n- [🌌 astroterm](#-astroterm)\n  - [Features](#features)\n  - [Installation](#installation)\n    - [Arch Linux](#arch-linux)\n    - [Fedora](#fedora)\n    - [Homebrew](#homebrew)\n    - [Nix](#nix)\n    - [Prebuilt Executable](#prebuilt-executable)\n  - [Building from Source](#building-from-source)\n    - [Linux, macOS \\\u0026 WSL](#linux-macos--wsl)\n    - [Windows](#windows-1)\n  - [Usage](#usage)\n  - [Troubleshooting](#troubleshooting)\n  - [Citations](#citations)\n  - [Data Sources](#data-sources)\n\n## Features\n\n- 🔭 **Highly Customizable:** Choose any date, time, and location to explore past, present, or future celestial events\n- 📐 **Accurate Rendering:** View the moon, stars, and planets with as much precision as terminal graphics allow\n- 🌘 **Moon Phases:** Precise lunar phases in real-time\n- 🌌 **Constellation Figures:** Detailed constellation shapes\n- ⚡ **Performance Optimized:** Lightweight and fast ASCII rendering\n\n![Stars above Syndey, AU on January 6, 2025](./assets/SYD_2025-01-06.png)\n\n_\u003cp align=\"center\"\u003eStars over Sydney, Australia on January 6, 2025\u003c/p\u003e_\n\n## Installation\n\nSeveral installation methods are provided based on your platform. If none of these fit your needs, you can always [build from source](#building-from-source). Refer to [troubleshooting](#troubleshooting) for help resolving any issues.\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/astroterm.svg)](https://repology.org/project/astroterm/versions)\n\n### Arch Linux\n\nYou can install `astroterm` directly from the [AUR](https://aur.archlinux.org/packages/astroterm) using your favorite AUR helper:\n\n```sh\nparu -S astroterm\n```\n\n### Fedora\n\nYou can install `astroterm` directly from the [Fedora package repository](https://packages.fedoraproject.org/pkgs/astroterm/astroterm) on Fedora 40+.\n\n```sh\nsudo dnf install astroterm\n```\n\n### Homebrew\n\nYou can install `astroterm` from [Homebrew](https://formulae.brew.sh/formula/astroterm) via:\n\n```sh\nbrew install astroterm\n```\n\n### Nix\n\nYou can try the [package](https://search.nixos.org/packages?channel=unstable\u0026from=0\u0026size=50\u0026sort=relevance\u0026type=packages\u0026query=astroterm) in a temporary environment with the following command:\n\n```sh\nnix-shell -I nixpkgs=channel:nixpkgs-unstable -p astroterm --command astroterm\n```\n\nArgument flags are added by wrapping the command in quotes. For example:\n\n```sh\nnix-shell -I nixpkgs=channel:nixpkgs-unstable -p astroterm --command \"astroterm -u -c\"\n```\n\nTo make `astroterm` available from your `$PATH`, install it with:\n\n```sh\nnix-env -f channel:nixpkgs-unstable -iA astroterm\n```\n\n### Guix\n\nYou can install `astroterm` directly from the [Guix main\nchannel](https://hpc.guix.info/package/astroterm) starting from\n[this commit](https://data.guix.gnu.org/revision/4b5f0408e66392ab745dc0f7830732217d88f17d).\n\n```sh\nguix time-machine --commit=4b5f0408e66392ab745dc0f7830732217d88f17d -- shell astroterm\n```\n\nOr after `guix pull`:\n\n```sh\nguix shell astroterm -- astroterm --help  # to try\nguix package --install astroterm          # add to current profile\n```\n\n### Prebuilt Executable\n\n#### Unix\n\n1. Download the latest executable using `wget`\n\n    ```sh\n    wget -O astroterm \"https://github.com/da-luce/astroterm/releases/latest/download/astroterm-\u003cos\u003e-\u003carch\u003e\"\n    ```\n\n   - Replace `\u003cos\u003e` with the appropriate platform:\n     - **Linux:** `linux`\n     - **macOS:** `darwin`\n   - Replace `\u003carch\u003e` with the appropriate architecture:\n     - **Linux:** `x86_64` (arm64 support to come after [Ubuntu arm64 runners](https://github.blog/news-insights/product-news/arm64-on-github-actions-powering-faster-more-efficient-build-systems/) are avilable)\n     - **Apple Silicon (M-series):** `aarch64`\n     - **Intel-based Macs:** `x86_64`\n   - To view all supported combinations, see the [Releases](https://github.com/da-luce/astroterm/releases) page.\n\n2. Run the executable\n\n    ```sh\n    chmod +x ./astroterm\n    ./astroterm\n    ```\n\n#### Windows\n\n1. Download the latest `.exe` file using PowerShell's `Invoke-WebRequest`:\n\n    ```powershell\n    Invoke-WebRequest -Uri \"https://github.com/da-luce/astroterm/releases/latest/download/astroterm-win-x86_64.exe\" -OutFile \"astroterm.exe\"\n    ```\n\n2. Run the `.exe`\n\n    ```powershell\n    .\\astroterm.exe\n    ```\n\n## Building from Source\n\n### Linux, macOS \u0026 WSL\n\n#### Requirements\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n- Unix-like environment (Linux, macOS, WSL, etc.)\n- C compiler\n- [`meson`](https://github.com/mesonbuild/meson) 1.4.0 or newer ([installation via python](https://mesonbuild.com/Quick-guide.html#installation-using-python) is recommended)\n- [`ninja`](https://repology.org/project/ninja/versions) 1.8.2 or newer\n- [`ncurses`](https://repology.org/project/ncurses/versions) library\n- [`argtable2`](https://repology.org/project/argtable2/versions)\n- Some common CLI tools\n  - [`wget`](https://repology.org/project/wget/versions) or [`curl`](https://repology.org/project/curl/versions)\n  - [`xxd`](https://repology.org/project/xxd/versions) (is also commonly packaged with [`vim`](https://repology.org/project/vim/versions))\n\n\u003e [!WARNING]\n\u003e `ncurses` and `argtable` detection is spotty on some systems, and you may need to install\n\u003e [`pkg-config`](https://repology.org/project/pkg-config/versions) in order\n\u003e for Meson to find them.\n\n\u003e [!TIP]\n\u003e See [`ci.yml`](./.github/workflows/ci.yml) for how `astroterm` is built and tested on Ubuntu via GitHub Actions.\n\n#### Install\n\n1. Clone the repository and enter the project directory:\n\n  ```sh\n  git clone https://github.com/da-luce/astroterm \u0026\u0026 cd astroterm\n  ```\n\n2. Download star data:\n\n  ```sh\n  curl -L -o data/bsc5 https://web.archive.org/web/20231007085824if_/http://tdc-www.harvard.edu/catalogs/BSC5\n  ```\n\n3. Build:\n\n  ```sh\n  meson setup build\n  meson compile -C build\n  ```\n\nYou may now run the generated `./build/astroterm` binary or add the `astroterm` command system-wide via `meson install -C build`. Pressing \u003ckbd\u003eq\u003c/kbd\u003e or \u003ckbd\u003eESC\u003c/kbd\u003e will exit the display.\n\n### Windows\n\n\u003e [!WARNING]\n\u003e Building on Windows is more involved than other platforms.\n\n#### Requirements\n\n- [Microsoft Visual C++](https://visualstudio.microsoft.com/vs/features/cplusplus/) (Other C compilers currently don't work)\n- [`meson`](https://github.com/mesonbuild/meson) 1.4.0 or newer ([installation via python](https://mesonbuild.com/Quick-guide.html#installation-using-python) is recommended)\n- [`ninja`](https://repology.org/project/ninja/versions) 1.8.2 or newer\n- [`python`](https://www.python.org/downloads/) (for embedding data during build)\n- [`pdcurses`](https://github.com/wmcbrine/PDCurses/tree/master/wincon)*\n- [`argtable2`](https://github.com/jonathanmarvens/argtable2)*\n\n\u003e [!WARNING]\n\u003e *These libraries must be compiled locally and moved to where Meson expects them to be. See [`ci.yml`](./.github/workflows/ci.yml#L98) for how this is done.\n\u003e\n#### Install\n\n1. Clone the repository and enter the project directory:\n\n  ```sh\n  git clone https://github.com/da-luce/astroterm \u0026\u0026 cd astroterm\n  ```\n\n2. Download star data:\n\n  ```sh\n  curl -L -o data/bsc5 https://web.archive.org/web/20231007085824if_/http://tdc-www.harvard.edu/catalogs/BSC5\n  ```\n\n3. Build:\n\n  ```sh\n  meson setup build\n  meson compile -C build\n  ```\n\n\u003e [!TIP]\n\u003e Some steps must be done in the [Visual Studio Developer Command Prompt and Developer PowerShell](https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022), so it's best to just do everything there.\n\n## Usage\n\n\u003c!-- omit in toc --\u003e\n### Options\n\nThe `--help` flag displays all supported options:\n\n```text\nUsage: astroterm [OPTION]...\n\n  -a, --latitude=\u003cdegrees\u003e  Observer latitude [-90°, 90°] (default: 0.0)\n  -o, --longitude=\u003cdegrees\u003e Observer longitude [-180°, 180°] (default: 0.0)\n  -d, --datetime=\u003cyyyy-mm-ddThh:mm:ss\u003e\n                            Observation datetime in UTC\n  -t, --threshold=\u003cfloat\u003e   Only render stars brighter than this magnitude\n                            (default: 5.0)\n  -l, --label-thresh=\u003cfloat\u003e\n                            Label stars brighter than this magnitude (default:\n                            0.25)\n  -f, --fps=\u003cint\u003e           Frames per second (default: 24)\n  -s, --speed=\u003cfloat\u003e       Animation speed multiplier (default: 1.0)\n  -c, --color               Enable terminal colors\n  -C, --constellations      Draw constellation stick figures. Note: a\n                            constellation is only drawn if all stars in the\n                            figure are over the threshold\n  -g, --grid                Draw an azimuthal grid\n  -u, --unicode             Use unicode characters\n  -q, --quit-on-any         Quit on any keypress (default is to quit on 'q' or\n                            'ESC' only)\n  -m, --metadata            Display metadata\n  -r, --aspect-ratio=\u003cfloat\u003e\n                            Override the calculated terminal cell aspect ratio.\n                            Use this if your projection is not 'square.' A value\n                            around 2.0 works well for most cases\n  -h, --help                Print this help message\n  -i, --city=\u003ccity_name\u003e    Use the latitude and longitude of the provided city.\n                            If the name contains multiple words, enclose the\n                            name in single or double quotes. For a list of\n                            available cities, see:\n                            https://github.com/da-luce/astroterm/blob/main/data/\n                            cities.csv\n  -v, --version             Display version info and exit\n```\n\n\u003c!-- omit in toc --\u003e\n### Example 1\n\nTo achieve the \"spinning globe\" effect as shown in the [README GIF](./assets/SG_2025-01-02.gif), use the following flags:\n\n```sh\nastroterm --color --constellations --speed 10000 --fps 64 --city Singapore\n```\n\nor\n\n```sh\nastroterm -cC -s 10000 -f 64 -i Singapore\n```\n\nfor short. In fact, any [city](./data/cities.csv) around the equator will work. Locations closer to the poles will look different because the apparent motion of the stars is more circular around the celestial pole rather than sweeping across the sky.\n\n\u003c!-- omit in toc --\u003e\n### Example 2\n\nSay we wanted to view the sky at 5:00 AM (Eastern) on July 16, 1969—the morning\nof the Apollo 11 launch at the Kennedy Space Center in Florida. We would run:\n\n```sh\nastroterm --latitude 28.573469 --longitude -80.651070 --datetime 1969-7-16T8:00:00\n```\n\nFinding the precise coordinates can be cumbersome, so we could also use the nearest major city to achieve a similar result:\n\n```sh\nastroterm --city Orlando --datetime 1969-7-16T8:00:00 -m\n```\n\nWhile we're still waiting for someone to invent time travel, we can cheat a little by using [Stellarium](https://stellarium-web.org/skysource/UpsPeg?fov=185.00\u0026date=1969-07-19T09:00:00Z\u0026lat=28.47\u0026lng=-80.56\u0026elev=0) to confirm that this aligns with reality.\n\nIf we then wanted to display constellations and add color, we would add `--constellations --color` as options.\n\nIf you simply want the current time, don't specify the `--datetime` option and\n`astroterm` will use the system time. For your current location, you will still\nhave to specify the `--lat` and `--long` options, or provide the nearest city with the `--city` option.\n\nFor more options and help, run `astroterm -h` or `astroterm --help`.\n\n\u003e [!TIP]\n\u003e Use a tool like [LatLong](https://www.latlong.net/) to get your latitude and longitude.\n\n\u003e [!TIP]\n\u003e Star magnitudes decrease as apparent brightness increases, i.e., to show more stars, increase the threshold.\n\n## Troubleshooting\n\n\u003c!-- omit in toc --\u003e\n### Release Won't Download via Curl\n\nFor some reason, `curl` does not follow the latest release redirect. Use `wget`\nto download the latest release or hardcode the tag in the link using `curl`. Or,\njust download via the [releases page](https://github.com/da-luce/astroterm/releases).\n\n\u003c!-- omit in toc --\u003e\n### Broken Unicode on Linux\n\nIf Unicode characters do not display correctly in the terminal, you may need to configure your system's locale to support Unicode.\n\n1. Temporarily set the locale (add this to `.bashrc` or equivalent to permanently enforce)\n\n  ```bash\n  export LC_ALL=\"en_US.UTF-8\"\n  export LC_CTYPE=\"en_US.UTF-8\"\n  ```\n\n2. Install and configure locales (example for Ubuntu/Debian)\n\n  ```bash\n  sudo apt update\n  sudo apt install -y locales\n  sudo dpkg-reconfigure locales\n  ```\n\n  During configuration, select `en_US.UTF-8` as the default locale.\n\n\u003c!-- omit in toc --\u003e\n## Development\n\n\u003c!-- omit in toc --\u003e\n### ASCII BSC5\n\nYou can use the ASCII version of the BSC5 star catalog by downloading and extracting the [gzip-compressed file](https://web.archive.org/web/20250114171002if_/http://tdc-www.harvard.edu/catalogs/ybsc5.gz) to `data/ybsc5` instead of `data/bsc5`.\n\n\u003c!-- omit in toc --\u003e\n### Testing\n\nRun `meson test` within the build directory. To get a coverage report, subsequently run `ninja coverage`.\n\n## Citations\n\nMany thanks to the following resources, which were invaluable to the development of this project.\n\n- [Map Projections-A Working Manual by John P. Snyder](https://pubs.usgs.gov/pp/1395/report.pdf)\n- [Wikipedia](https://en.wikipedia.org)\n- [Atractor](https://www.atractor.pt/index-_en.html)\n- [Jon Voisey's Blog: Following Kepler](https://jonvoisey.net/blog/)\n- [Celestial Programming: Greg Miller's Astronomy Programming Page](https://astrogreg.com/convert_ra_dec_to_alt_az.html)\n- [Practical Astronomy with your Calculator by Peter Duffett-Smith](https://www.amazon.com/Practical-Astronomy-Calculator-Peter-Duffett-Smith/dp/0521356997)\n- [NASA Jet Propulsion Laboratory](https://ssd.jpl.nasa.gov/planets/approx_pos.html)\n- [Paul Schlyter's \"How to compute planetary positions\"](https://stjarnhimlen.se/comp/ppcomp.html)\n- [Dan Smith's \"Meeus Solar Position Calculations\"](https://observablehq.com/@danleesmith/meeus-solar-position-calculations)\n- [Bryan Weber's \"Orbital Mechanics Notes\"](https://github.com/bryanwweber/orbital-mechanics-notes)\n- [ASCOM](https://ascom-standards.org/Help/Developer/html/72A95B28-BBE2-4C7D-BC03-2D6AB324B6F7.htm)\n- [A Fast Bresenham Type Algorithm For Drawing Ellipses](https://dai.fmph.uniba.sk/upload/0/01/Ellipse.pdf)\n\n## Data Sources\n\n- Stars: [Yale Bright Star Catalog](http://tdc-www.harvard.edu/catalogs/bsc5.html)\n- Star names: [IAU Star Names](https://www.iau.org/public/themes/naming_stars/)\n- Constellation figures: [Stellarium](https://github.com/Stellarium/stellarium/blob/3c8d3c448f82848e9d8c1af307ec4cad20f2a9c0/skycultures/modern/constellationship.fab#L6) (Converted from [Hipparchus](https://heasarc.gsfc.nasa.gov/w3browse/all/hipparcos.html) to [BSC5](http://tdc-www.harvard.edu/catalogs/bsc5.html) indices using the [HYG Database](https://www.astronexus.com/projects/hyg)—see [convert_constellations.py](./scripts/convert_constellations.py))\n- Cities: [GeoNames](https://download.geonames.org/) (Filtered and condensed using [filter_cities.py](./scripts/filter_cities.py))\n- Planet orbital elements: [NASA Jet Propulsion Laboratory](https://ssd.jpl.nasa.gov/planets/approx_pos.html)\n- Planet magnitudes: [Computing Apparent Planetary Magnitudes for The Astronomical Almanac](https://arxiv.org/abs/1808.01973)\n","funding_links":[],"categories":["C","Utilities","Table of Contents","\u003ca name=\"graphics\"\u003e\u003c/a\u003eGraphics","ASCII UI/UX Apps"],"sub_categories":["Science"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fda-luce%2Fastroterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fda-luce%2Fastroterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fda-luce%2Fastroterm/lists"}