a-shygun / Terrascope

# Terrascope
`terrascope` is an interactive world map for the terminal. It renders countries,
place names, live aircraft, city weather, a radar overlay, earthquakes, and
day/night bands with `curses`, Unicode Braille cells, and terminal colors.
The app is intentionally lightweight at install time. Large map data is
downloaded into a user cache the first time it is needed, then reused on later
runs.
Country names and abbreviations, plus airport names and locations, are bundled
from Natural Earth so they are available offline without a first-run download.
## Status
This project is early-stage software. The core map, tabs, keyboard/mouse
navigation, live layers, and cache handling are implemented, but APIs and visual
details may still change.
## Requirements
- Python 3.10 or newer on macOS or Linux/Unix
- A UTF-8 terminal
- A terminal with 256-color or true-color support for the best appearance
- Network access for first-run map downloads and live data layers (optional)
Python dependencies are declared in `pyproject.toml`:
- `numpy`
- `Pillow`
- `PyYAML`
- `pyshp`
## Installation
For the latest published release:
 [code] 
### Package managers
Homebrew can install the latest tagged release or the latest code on `main`:
 [code] 
PyPI and Homebrew's default install use tagged releases. Their version comes
from `pyproject.toml`; the Homebrew formula reads it directly. Homebrew's
`--HEAD` option, the pipx VCS install, and the Nix checkout recipe use the
current `main` source. The Arch VCS recipe also tracks `main`, but remains a
draft and has not been submitted to the AUR.
For local development:
 [code] 
You can also run it from a checkout without installing the console script:
 [code] 
## First Run and Cache
On first launch, `terrascope` downloads Natural Earth GeoJSON files into:
 [code] 
If `XDG_CACHE_HOME` is not set, the default is:
 [code] 
Useful cache commands:
 [code] 
## Common Options
 [code] 
CLI flags override configuration for the current run. `--set` overrides flags;
see `terrascope --help` for the full precedence order and every available
option.
During first-run downloads the terminal UI shows a loading message before the
map appears. Errors and background warnings are written to the log file shown by
`terrascope --show-paths`, so stray output does not corrupt the curses screen.
## Controls
| Input | Action |
| --- | --- |
| `1`-`9` | Switch tabs |
| `WASD` or arrow keys | Pan |
| `+` / `-` | Zoom in / out |
| `0` | Reset view |
| Mouse drag | Pan |
| Mouse wheel | Zoom |
| Mouse click | Select a marker or map label |
| ` ` | Step through overlapping selections |
| `/` | Search |
| `O` | Open filter prompt |
| `H` | Show or hide the panel |
| `?` | Open the welcome/help modal |
| `Esc` | Close prompts or clear selection/filter state |
| `Q` | Quit |
Click `[+]` beside the clock to expand the top controls, then click the panel
placement label (`BOTTOM` or `LEFT`) to switch the panel between
the horizontal bottom row and vertical left side