astroterm README

项目的 README,来自 github.com/da-luce/astroterm。合并为一个 markdown 文件:README.md。

🌌 astroterm

Test Status codecov Latest release License: MIT

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 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. See CONTRIBUTING.md for guidelines on building, testing, and contributing to astroterm.

The night sky above Singapore on January 2, 2025

The night sky above Singapore on January 2, 2025
See usage on how to obtain this view

Table of Contents

Features

Stars above Syndey, AU on January 6, 2025

Stars over Sydney, Australia on January 6, 2025

Installation

Several installation methods are provided based on your platform. If none of these fit your needs, you can always build from source. Refer to troubleshooting for help resolving any issues.

Packaging status

Arch Linux

You can install astroterm from the extra repository using pacman:

pacman -S astroterm

Fedora

You can install astroterm directly from the Fedora package repository on Fedora 40+.

sudo dnf install astroterm

Homebrew

You can install astroterm from Homebrew via:

brew install astroterm

Nix

You can try the package in a temporary environment with the following command:

nix-shell -I nixpkgs=channel:nixpkgs-unstable -p astroterm --command astroterm

Argument flags are added by wrapping the command in quotes. For example:

nix-shell -I nixpkgs=channel:nixpkgs-unstable -p astroterm --command "astroterm -u -c"

To make astroterm available from your $PATH, add it to your configuration.nix:

environment.systemPackages = with pkgs; [
  ...
  astroterm
]

Guix

You can install astroterm directly from the Guix main channel starting from this commit.

guix time-machine --commit=4b5f0408e66392ab745dc0f7830732217d88f17d -- shell astroterm

Or after guix pull:

guix shell astroterm -- astroterm --help  # to try
guix package --install astroterm          # add to current profile

Prebuilt Executable

Unix

  1. Download the latest executable using wget

    wget -O astroterm "https://github.com/da-luce/astroterm/releases/latest/download/astroterm-<os>-<arch>"
    
    • Replace <os> with the appropriate platform:
      • Linux: linux
      • macOS: darwin
    • Replace <arch> with the appropriate architecture:
      • Linux: x86_64 (arm64 support to come after Ubuntu arm64 runners are available)
      • Apple Silicon (M-series): aarch64
      • Intel-based Macs: x86_64
    • To view all supported combinations, see the Releases page.
  2. Run the executable

    chmod +x ./astroterm
    ./astroterm
    

Windows

  1. Download the latest .exe file using PowerShell's Invoke-WebRequest:

    Invoke-WebRequest -Uri "https://github.com/da-luce/astroterm/releases/latest/download/astroterm-win-x86_64.exe" -OutFile "astroterm.exe"
    
  2. Run the .exe

    .\astroterm.exe
    

Building From Source

Usage

Options

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°] (default: 0.0)
  -d, --datetime=<yyyy-mm-ddThh:mm:ss>
                            Observation datetime in UTC
  -t, --threshold=<float>   Only render stars brighter than this magnitude
                            (default: 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
                            constellation is only drawn if all stars in the
                            figure are over the threshold
  -g, --grid                Draw an azimuthal grid
  -u, --unicode             Use unicode characters
  -b, --braille             Use braille characters for constellation lines
                            (requires Unicode)
  -q, --quit-on-any         Quit on any keypress (default is to quit on 'q' or
                            'ESC' only)
  -m, --metadata            Display metadata
  -r, --aspect-ratio=<float>
                            Override the calculated terminal cell aspect ratio.
                            Use this if your projection is not 'square.' A value
                            around 2.0 works well for most cases
  -h, --help                Print this help message
  -B, --bash-completions    Print bash completions
  -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
                            available cities, see:
                            https://github.com/da-luce/astroterm/blob/main/data/
                            cities.csv
  -v, --version             Display version info and exit

Shell Completions

To enable Tab completions in Bash, add the following line to your ~/.bashrc:

source <(astroterm --bash-completions)

Example 1

To achieve the "spinning globe" effect as shown in the README GIF, use the following flags:

astroterm --color --constellations --speed 10000 --fps 64 --city Singapore

or

astroterm -cC -s 10000 -f 64 -i Singapore

for short. In fact, any city 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.

Example 2

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:00

Finding 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 -m

While 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.

Troubleshooting

Release Won't Download via Curl

For some reason, curl does not follow the latest release redirect. Use wget to download the latest release or hardcode the tag in the link using curl. Or, just download via the releases page.

Broken Unicode on Linux

If Unicode characters do not display correctly in the terminal, you may need to configure your system's locale to support Unicode.

  1. Temporarily set the locale (add this to ~/.bashrc or equivalent to permanently enforce)
export LC_ALL="en_US.UTF-8"
export LC_CTYPE="en_US.UTF-8"
  1. Install and configure locales (example for Ubuntu/Debian)
sudo apt update
sudo apt install -y locales
sudo dpkg-reconfigure locales

During configuration, select en_US.UTF-8 as the default locale.

Citations

Many thanks to the following resources, which were invaluable to the development of this project.

Data Sources

astroterm (da-luce/astroterm)

正在搜索数据库…

这是什么?astroterm 是一个用 C 语言编写的终端天象仪,无需望远镜,就能在终端里以 ASCII 字符画的形式实时显示恒星、行星、星座和月相的位置。
这是图形界面的天象仪软件,还是所有内容都在终端里显示?它是纯命令行工具,没有图形界面;整个星空画面都直接用 ASCII 字符绘制在你的终端窗口中。
我要怎么安装 astroterm?你可以通过所用平台的包管理器安装:Arch Linux 的 extra 仓库中的 pacman、Fedora 40 及更高版本的软件包仓库、Homebrew、Nix 或 Guix;也可以从 Releases 页面下载适用于 Linux、macOS 或 Windows 的预编译可执行文件,直接运行即可。
运行时有什么常见的坑?除非系统区域设置(locale)配置为 UTF-8,否则 Linux 上的 Unicode 字符可能显示不正确;另外,下载二进制文件时,curl 有时无法跟随指向最新发布版本的重定向(使用 wget 效果更好)。
支持哪些平台?Linux、macOS(同时支持 Apple Silicon 和 Intel 芯片)和 Windows 都可以通过预编译可执行文件使用;Linux 用户还可以通过 Arch(pacman)、Fedora、Homebrew、Nix 和 Guix 获取原生软件包。
我该如何设置观测地点?你可以用 --lat 和 --long 指定精确的经纬度坐标,也可以直接用 --city 选择最近的主要城市;如果省略 --datetime,则默认使用当前系统时间。
星星和行星位置的数据来源是什么?恒星位置来自耶鲁明亮星表(Yale Bright Star Catalog),星名来自 IAU Star Names;星座图形由 Stellarium 数据转换而来,城市查询使用 GeoNames,行星轨道根数则来自 NASA JPL。
我能查看历史上的天象事件吗,比如阿波罗 11 号发射?可以。同时设置 --datetime 和 --lat/--long 或 --city,就能重现过去、现在或未来任意时刻的星空,例如 1969 年 7 月 16 日上午的肯尼迪航天中心。
它支持彩色输出和星座连线吗?支持。添加 --constellations 和 --color 参数后,可以在默认的 ASCII 星图上叠加星座图形,并启用彩色显示。
有哪些类似的项目?cbirds, nchat, FTXUI, vhs, hexyl, world.execute-me-ascii, ripgrep, fx
作者
da-luce
大小
93.6 MB
星标
2.6K
时长
3年
提交 · 90 天