Metadata-Version: 2.4
Name: zstarview
Version: 1.0.6
Summary: Transparent desktop sky viewer with stars, planets, eclipses, and optional real-time satellite cloud overlay.
Project-URL: Homepage, https://github.com/tos-kamiya/zstarview
Project-URL: Documentation, https://github.com/tos-kamiya/zstarview#readme
Project-URL: Issues, https://github.com/tos-kamiya/zstarview/issues
Project-URL: Source, https://github.com/tos-kamiya/zstarview
Author-email: Toshihiro Kamiya <kamiya@mbj.nifty.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: astronomy,clouds,desktop,planetarium,pyside6,satellite,sky
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Requires-Dist: appdirs>=1.4.4
Requires-Dist: astropy<7,>=6.1; python_version < '3.11'
Requires-Dist: astropy<8,>=7; python_version >= '3.11'
Requires-Dist: boto3<2,>=1.42
Requires-Dist: botocore<2,>=1.42
Requires-Dist: h5netcdf<2,>=1.8
Requires-Dist: h5py<4,>=3.15
Requires-Dist: numpy<2.4,>=2.2
Requires-Dist: pillow<13,>=12
Requires-Dist: polars<2,>=1.38
Requires-Dist: pyproj<4,>=3.7
Requires-Dist: pyside6<7,>=6.10
Requires-Dist: rasterio>=1.4.4
Requires-Dist: satpy<0.60,>=0.59; python_version < '3.11'
Requires-Dist: satpy<0.61,>=0.60; python_version >= '3.11'
Requires-Dist: skyfield<2,>=1.54
Requires-Dist: xarray<2026.0,>=2025.6; python_version < '3.11'
Requires-Dist: xarray<2027.0,>=2026.0; python_version >= '3.11'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pyongc; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Description-Content-Type: text/markdown

# zstarview

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

<p align="center">
  <img src="https://raw.githubusercontent.com/tos-kamiya/zstarview/main/docs/images/screenshot1.png" width="49%" alt="zstarview screenshot 1">
  <img src="https://raw.githubusercontent.com/tos-kamiya/zstarview/main/docs/images/screenshot4.png" width="49%" alt="zstarview screenshot 4">
</p>

Urban outline examples from several cities worldwide:

<table>
  <tr>
    <td align="center" width="25%"><img src="https://raw.githubusercontent.com/tos-kamiya/zstarview/main/docs/images/screenshot-tokyotower.png" alt="Near Tokyo Tower, Tokyo" width="100%" /></td>
    <td align="center" width="25%"><img src="https://raw.githubusercontent.com/tos-kamiya/zstarview/main/docs/images/screenshot-downtowndubai.png" alt="Downtown Dubai" width="100%" /></td>
    <td align="center" width="25%"><img src="https://raw.githubusercontent.com/tos-kamiya/zstarview/main/docs/images/screenshot-marinabay.png" alt="Marina Bay, Singapore" width="100%" /></td>
    <td align="center" width="25%"><img src="https://raw.githubusercontent.com/tos-kamiya/zstarview/main/docs/images/screenshot-sydney.png" alt="Circular Quay, Sydney" width="100%" /></td>
  </tr>
  <tr>
    <td align="center"><sub>Near Tokyo Tower, Tokyo</sub></td>
    <td align="center"><sub>Downtown Dubai</sub></td>
    <td align="center"><sub>Marina Bay, Singapore</sub></td>
    <td align="center"><sub>Circular Quay, Sydney</sub></td>
  </tr>
</table>

## Install

Recommended:

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

Confirm it with:

```bash
overturemaps --help
```

```bash
pipx install zstarview
```

Or with pip:

```bash
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

```bash
zstarview [options] [location]
```

Examples:

```bash
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 for the current viewpoint. In some skyscraper-heavy cities, distant skyscrapers can also be added from within a 10km radius.
- 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
