zstarview 1.0.4

Transparent desktop sky viewer with stars, planets, eclipses, and optional real-time satellite cloud overlay.

zstarview

Transparent desktop sky viewer with stars, planets, eclipses, optional real-time satellite cloud overlay, optional terrain horizon overlay, and optional urban outline overlay.

Urban outline examples from several cities worldwide:

Near Tokyo Tower, Tokyo	Downtown Dubai	Marina Bay, Singapore	Circular Quay, Sydney

Install

Recommended:

Prerequisite for the urban outline overlay: install the overturemaps CLI separately. Installation: https://pypi.org/project/overturemaps/

Confirm it with:

overturemaps --help

pipx install zstarview

Or with pip:

pip install zstarview

Note: Windows on Arm64 is currently not supported for installation. As of 2026-03-15, native dependencies such as shapely can fail there because they may require a source build.

Quick Start

zstarview [options] [location]

Examples:

zstarview Tokyo
zstarview "Tokyo Skytree"
zstarview "35.68;139.76"
zstarview --place "Matsue Station" --place-countrycode jp
zstarview -Z E -A 25 Tokyo

Highlights

• Deep-sky objects: named galaxies/open clusters/globular clusters are shown as soft blue extents.
• Asterism overlay: popular line patterns rather than formal IAU constellation boundaries are shown as dim ambient lines.
• Solar-system bodies: supports Sun, Moon, and major planets.
• Flexible location input: specify the observer location through the CLI argument using a city name, tower name, mountain name, direct latitude/longitude input, or online place/station search via Nominatim.
• Adjustable view center: adjust the view center with CLI options -A and -Z, or with the arrow keys.
• Satellite cloud imagery: real-time Himawari/GOES satellite data are downloaded and rendered as a stylized hatched overlay.
• Terrain horizon and ground fill: Copernicus DEM data can be downloaded to render the local terrain skyline and ground region below the horizon.
• Urban outline overlay: major rooflines are drawn as a white overlay using cached Overture building data; very narrow roof spans are simplified to thick horizontal strokes.
• Never-rises region: the celestial region that never rises above the horizon for the observer's latitude is shown in a red tint.
• Python support: routinely tested on CPython 3.10, 3.11, 3.12, and 3.13.

Common Options

• --place QUERY
• --place-countrycode CODE
• --place-lang LANG
• --cloud-opacity 0.0..1.0
• --terrain-horizon-opacity 0.0..1.0
• --urban-outline-opacity 0.0..1.0
• --observer-height-m METERS
• --datetime "YYYY-MM-DD HH[:MM[:SS]] [TZ]"

Notes:

• --place uses the public OpenStreetMap Nominatim search service and sends a single request with a User-Agent and Accept-Language.
• Satellite cloud rendering downloads Himawari/GOES data from public S3 buckets.
• Terrain horizon rendering downloads Copernicus DEM tiles on first use and reuses cached data later.

Code, Data Licenses, and Credits

• Code: MIT License. See LICENSE.
• Bundled and runtime-fetched data may be subject to their own licenses, attribution rules, or service terms.
• See the main project README for the full credits and third-party data notes.

Links

• Homepage: https://github.com/tos-kamiya/zstarview
• Documentation: https://github.com/tos-kamiya/zstarview#readme
• Issues: https://github.com/tos-kamiya/zstarview/issues