horizonchart 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- horizonchart-0.1.0/LICENSE +21 -0
- horizonchart-0.1.0/PKG-INFO +226 -0
- horizonchart-0.1.0/README.md +191 -0
- horizonchart-0.1.0/pyproject.toml +61 -0
- horizonchart-0.1.0/pyproject.toml.orig +54 -0
- horizonchart-0.1.0/src/horizonchart/__init__.py +32 -0
- horizonchart-0.1.0/src/horizonchart/cli.py +252 -0
- horizonchart-0.1.0/src/horizonchart/fonts/Inter.ttf +0 -0
- horizonchart-0.1.0/src/horizonchart/fonts/OFL.txt +93 -0
- horizonchart-0.1.0/src/horizonchart/skyview.py +1296 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 trice
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: horizonchart
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Clean horizon-view sky charts: finder charts for planets, the Moon and deep-sky objects, and twilight views
|
|
5
|
+
Keywords: astronomy,star chart,sky chart,planets,stargazing,starplot
|
|
6
|
+
Author: trice
|
|
7
|
+
Author-email: trice <rtphokie@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
License-File: src/horizonchart/fonts/OFL.txt
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Education
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Astronomy
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Visualization
|
|
22
|
+
Requires-Dist: geopy>=2.5.0
|
|
23
|
+
Requires-Dist: pillow>=10.1
|
|
24
|
+
Requires-Dist: platformdirs>=4.0
|
|
25
|
+
Requires-Dist: shapely>=2.0
|
|
26
|
+
Requires-Dist: skyfield>=1.49
|
|
27
|
+
Requires-Dist: starplot>=0.21.1,<0.22
|
|
28
|
+
Requires-Dist: timezonefinder>=9.0.0
|
|
29
|
+
Requires-Dist: tzdata ; sys_platform == 'win32'
|
|
30
|
+
Requires-Python: >=3.11
|
|
31
|
+
Project-URL: Homepage, https://github.com/rtphokie/horizonchart
|
|
32
|
+
Project-URL: Repository, https://github.com/rtphokie/horizonchart
|
|
33
|
+
Project-URL: Issues, https://github.com/rtphokie/horizonchart/issues
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
|
|
36
|
+
# horizonchart
|
|
37
|
+
|
|
38
|
+
Clean, 16:9 horizon-view sky charts built on [starplot](https://starplot.dev):
|
|
39
|
+
|
|
40
|
+
- **Finder charts** for planets, the Moon, stars or deep-sky objects at a given
|
|
41
|
+
place and time, showing just enough context (nearby constellations,
|
|
42
|
+
asterisms, bright stars) to find them.
|
|
43
|
+
- **Twilight views** for a date: the sky before sunrise and after sunset,
|
|
44
|
+
looking east or west, whichever has more to see.
|
|
45
|
+
|
|
46
|
+

|
|
47
|
+
|
|
48
|
+

|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
Requires Python 3.11+.
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
pip install horizonchart
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
or, from a checkout, with [uv](https://docs.astral.sh/uv/): `uv sync`.
|
|
59
|
+
|
|
60
|
+
### System requirement: Cairo
|
|
61
|
+
|
|
62
|
+
starplot renders PNGs with [CairoSVG](https://cairosvg.org), which needs the
|
|
63
|
+
Cairo graphics library installed on the system:
|
|
64
|
+
|
|
65
|
+
| Platform | Install |
|
|
66
|
+
|---|---|
|
|
67
|
+
| macOS | `brew install cairo` |
|
|
68
|
+
| Debian / Ubuntu | `sudo apt install libcairo2` |
|
|
69
|
+
| Fedora | `sudo dnf install cairo` |
|
|
70
|
+
| Windows | see [CairoSVG's notes](https://cairosvg.org/documentation/#installation) (a GTK runtime provides it) |
|
|
71
|
+
|
|
72
|
+
On macOS, Pythons that don't look in Homebrew's library folder (such as
|
|
73
|
+
uv-managed or python.org builds) may report `no library called "cairo" was
|
|
74
|
+
found`; point them at it with
|
|
75
|
+
`export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib`.
|
|
76
|
+
|
|
77
|
+
### Data files
|
|
78
|
+
|
|
79
|
+
The first run downloads star and deep-sky catalogs and planetary ephemerides
|
|
80
|
+
(~120 MB). They, and the place-name cache, are stored in the first of:
|
|
81
|
+
|
|
82
|
+
1. `$STARPLOT_DATA_PATH`, if set
|
|
83
|
+
2. `/var/data`, if it exists and is writable
|
|
84
|
+
3. the per-user cache folder for your platform (e.g.
|
|
85
|
+
`~/Library/Caches/horizonchart` on macOS, `~/.cache/horizonchart` on Linux,
|
|
86
|
+
`%LOCALAPPDATA%\horizonchart\Cache` on Windows)
|
|
87
|
+
|
|
88
|
+
## Command line
|
|
89
|
+
|
|
90
|
+
### Finder chart for specific objects
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
horizonchart target Saturn --location "Monkey's Eyebrow, KY" --time "2026-10-02 22:00"
|
|
94
|
+
# -> saturn_20261002T2200_35.78N_78.64W.png
|
|
95
|
+
|
|
96
|
+
horizonchart target Moon Pleiades -l "35.78N 78.64W" -t "2026-10-03 02:00"
|
|
97
|
+
|
|
98
|
+
# No --time: 2 hours after tonight's sunset
|
|
99
|
+
horizonchart target Saturn -l "35.78N 78.64W"
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Targets can be:
|
|
103
|
+
|
|
104
|
+
| Kind | Examples |
|
|
105
|
+
|---|---|
|
|
106
|
+
| Moon and planets | `Moon`, `Mars`, `Saturn`, `"saturn barycenter"` (BSP-style naming), `Pluto` |
|
|
107
|
+
| Messier / NGC / IC | `M31`, `M45`, `"NGC 1976"`, `"IC 2391"` |
|
|
108
|
+
| Deep-sky common names | `Pleiades`, `"Andromeda Galaxy"`, `Beehive` |
|
|
109
|
+
| Named stars | `Vega`, `Betelgeuse` |
|
|
110
|
+
|
|
111
|
+
`-t, --time` is local time at the location. By default it's 2 hours after
|
|
112
|
+
today's sunset there, rounded to the nearest half hour. Each target must be
|
|
113
|
+
above the horizon at that time.
|
|
114
|
+
|
|
115
|
+
### Twilight views for a date
|
|
116
|
+
|
|
117
|
+
```sh
|
|
118
|
+
horizonchart twilight --location "Ottawa, ON" --date 2026-10-02
|
|
119
|
+
# -> 20261002T0500_45.42N_75.69W_mor.png, 20261002T2030_45.42N_75.69W_eve.png
|
|
120
|
+
# (both moved to 2 hours from the Sun because planets were low at 1 hour)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
| Option | Meaning |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `-d, --date` | Date (default: today at the location) |
|
|
126
|
+
| `-m, --limiting-magnitude` | Faintest stars and deep-sky objects shown. Default 2.0 (suburban twilight); 4–6 for dark skies |
|
|
127
|
+
| `--no-title` | Leave off the title ("Looking east, 1 hour before sunrise") |
|
|
128
|
+
|
|
129
|
+
### Common options
|
|
130
|
+
|
|
131
|
+
| Option | Meaning |
|
|
132
|
+
|---|--------------------------------------------------------------------------------------------------------|
|
|
133
|
+
| `-l, --location` | Coordinates (`35.19,-88.99`, `47.99N 84.77W`) or a place name (`"Monkey's Eyebrow, NC"`, `"Wawa, ON"`) |
|
|
134
|
+
| `--tz` | Time zone name; by default it's looked up from the location |
|
|
135
|
+
| `-o, --output-dir` | Where to write PNGs (default: current directory) |
|
|
136
|
+
| `--no-timestamp` | Leave off the date, time and location in the lower right corner |
|
|
137
|
+
| `--no-labels` | Leave off all names: planets, the Moon, stars, deep-sky objects, asterisms and constellations |
|
|
138
|
+
|
|
139
|
+
Place names are looked up with OpenStreetMap's
|
|
140
|
+
[Nominatim](https://nominatim.org) service, at most one request per second,
|
|
141
|
+
and cached (`horizonchart-geocode.json` in the data folder), so each place is
|
|
142
|
+
looked up once. Coordinates never touch the network. Nominatim's
|
|
143
|
+
[usage policy](https://operations.osmfoundation.org/policies/nominatim/)
|
|
144
|
+
asks applications to identify themselves; set `HORIZONCHART_CONTACT` (e.g. to
|
|
145
|
+
your email address) to include a contact in the request's user agent.
|
|
146
|
+
|
|
147
|
+
## Python
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
from datetime import date, datetime
|
|
151
|
+
from zoneinfo import ZoneInfo
|
|
152
|
+
|
|
153
|
+
from horizonchart.skyview import plot_targets, plot_twilight_views
|
|
154
|
+
|
|
155
|
+
plot_targets(47.99, -84.77, ["Saturn"],
|
|
156
|
+
datetime(2026, 10, 2, 22, 0, tzinfo=ZoneInfo("America/New_York")))
|
|
157
|
+
|
|
158
|
+
plot_twilight_views(47.99, -84.77, date(2026, 10, 2))
|
|
159
|
+
# {"morning": Path(...), "evening": Path(...)}
|
|
160
|
+
|
|
161
|
+
# The command line's --no-title, --no-timestamp and --no-labels
|
|
162
|
+
plot_targets(..., timestamp=False, labels=False)
|
|
163
|
+
plot_twilight_views(..., title=False, timestamp=False, labels=False)
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## How charts are composed
|
|
167
|
+
|
|
168
|
+
**Both chart types**
|
|
169
|
+
|
|
170
|
+
- Planet and Moon markers are drawn in roughly their naked-eye colors.
|
|
171
|
+
Uranus, Neptune and Pluto are drawn smaller and semi-transparent.
|
|
172
|
+
- Asterisms (Great Square, Big Dipper, Summer Triangle, Orion's Belt, …) are
|
|
173
|
+
highlighted and labeled. When an asterism is essentially its whole
|
|
174
|
+
constellation (Cassiopeia's W, the Little Dipper), only the constellation is
|
|
175
|
+
named.
|
|
176
|
+
- Easily recognized constellations (Orion, Ursa Major and Minor, Cassiopeia,
|
|
177
|
+
Cygnus, Scorpius, Leo, Crux) are shown whenever most of the figure is in
|
|
178
|
+
view.
|
|
179
|
+
- At most five stars are labeled, chosen from a priority list of well-known
|
|
180
|
+
names (Polaris, Sirius, Betelgeuse, Vega, …). Other stars are unlabeled.
|
|
181
|
+
- The date, time and location are in small text in the lower right.
|
|
182
|
+
|
|
183
|
+
**Finder charts**
|
|
184
|
+
|
|
185
|
+
- Constellations are shown only if they contain a target, border it within
|
|
186
|
+
3°, or are home to a highlighted asterism.
|
|
187
|
+
- The view is framed automatically around the targets and asterisms.
|
|
188
|
+
|
|
189
|
+
**Twilight views**
|
|
190
|
+
|
|
191
|
+
- Each view is 1 hour before sunrise or after sunset, rounded to the half
|
|
192
|
+
hour. If planets or the Moon are low then, 2 hours is tried and used if it
|
|
193
|
+
shows more.
|
|
194
|
+
- Each view looks east or west, scored by what's in view (planets, the Moon,
|
|
195
|
+
deep-sky objects, asterisms, bright stars).
|
|
196
|
+
- The title, e.g. "Looking east, 1 hour before sunrise", is drawn on the
|
|
197
|
+
landscape.
|
|
198
|
+
|
|
199
|
+
Tuning constants (radii, magnitudes, font sizes, the asterism and
|
|
200
|
+
priority-star lists) are at the top of `src/horizonchart/skyview.py`.
|
|
201
|
+
|
|
202
|
+
## Compatibility with starplot
|
|
203
|
+
|
|
204
|
+
horizonchart draws its charts with starplot's public API, but a few features rely on starplot internals that have no public equivalent yet: keeping labels clear of highlighted asterism lines, detecting whether a label was placed, and converting coordinates for those checks. Because of this, the dependency is pinned to the tested starplot release series (`>=0.21.1,<0.22`). Update at your own risk.
|
|
205
|
+
|
|
206
|
+
## Tests
|
|
207
|
+
|
|
208
|
+
```sh
|
|
209
|
+
uv run pytest
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
The tests render real charts which require download of significant catalogs on first run and can take a few minutes to run as a result.
|
|
213
|
+
|
|
214
|
+
## Credits
|
|
215
|
+
|
|
216
|
+
- [starplot](https://starplot.dev) by Steve Berardi does the chart drawing, projections and catalogs (stars from Hipparcos/Tycho via its Big Sky catalog, deep-sky objects from [OpenNGC](https://github.com/mattiaverga/OpenNGC)). The horizon-view style follows its
|
|
217
|
+
[horizon gradient example](https://starplot.dev/examples/horizon-gradient/).
|
|
218
|
+
- [Skyfield](https://rhodesmill.org/skyfield/) by Brandon Rhodes computes sunrise and sunset, planetary magnitudes and alt/az positions, using JPL ephemerides.
|
|
219
|
+
- Place-name lookup uses [Nominatim](https://nominatim.org) through [geopy](https://geopy.readthedocs.io); geocoding data © [OpenStreetMap](https://www.openstreetmap.org/copyright) contributors.
|
|
220
|
+
- Time zones come from [timezonefinder](https://github.com/jannikmi/timezonefinder).
|
|
221
|
+
- Titles use the [Inter](https://rsms.me/inter/) typeface by Rasmus Andersson, bundled under the SIL Open Font License (`src/horizonchart/fonts/OFL.txt`).
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
MIT; see [LICENSE](https://github.com/rtphokie/horizonchart/blob/main/LICENSE). The bundled Inter font is under the SIL Open Font
|
|
226
|
+
License 1.1.
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# horizonchart
|
|
2
|
+
|
|
3
|
+
Clean, 16:9 horizon-view sky charts built on [starplot](https://starplot.dev):
|
|
4
|
+
|
|
5
|
+
- **Finder charts** for planets, the Moon, stars or deep-sky objects at a given
|
|
6
|
+
place and time, showing just enough context (nearby constellations,
|
|
7
|
+
asterisms, bright stars) to find them.
|
|
8
|
+
- **Twilight views** for a date: the sky before sunrise and after sunset,
|
|
9
|
+
looking east or west, whichever has more to see.
|
|
10
|
+
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+

|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
Requires Python 3.11+.
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
pip install horizonchart
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
or, from a checkout, with [uv](https://docs.astral.sh/uv/): `uv sync`.
|
|
24
|
+
|
|
25
|
+
### System requirement: Cairo
|
|
26
|
+
|
|
27
|
+
starplot renders PNGs with [CairoSVG](https://cairosvg.org), which needs the
|
|
28
|
+
Cairo graphics library installed on the system:
|
|
29
|
+
|
|
30
|
+
| Platform | Install |
|
|
31
|
+
|---|---|
|
|
32
|
+
| macOS | `brew install cairo` |
|
|
33
|
+
| Debian / Ubuntu | `sudo apt install libcairo2` |
|
|
34
|
+
| Fedora | `sudo dnf install cairo` |
|
|
35
|
+
| Windows | see [CairoSVG's notes](https://cairosvg.org/documentation/#installation) (a GTK runtime provides it) |
|
|
36
|
+
|
|
37
|
+
On macOS, Pythons that don't look in Homebrew's library folder (such as
|
|
38
|
+
uv-managed or python.org builds) may report `no library called "cairo" was
|
|
39
|
+
found`; point them at it with
|
|
40
|
+
`export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib`.
|
|
41
|
+
|
|
42
|
+
### Data files
|
|
43
|
+
|
|
44
|
+
The first run downloads star and deep-sky catalogs and planetary ephemerides
|
|
45
|
+
(~120 MB). They, and the place-name cache, are stored in the first of:
|
|
46
|
+
|
|
47
|
+
1. `$STARPLOT_DATA_PATH`, if set
|
|
48
|
+
2. `/var/data`, if it exists and is writable
|
|
49
|
+
3. the per-user cache folder for your platform (e.g.
|
|
50
|
+
`~/Library/Caches/horizonchart` on macOS, `~/.cache/horizonchart` on Linux,
|
|
51
|
+
`%LOCALAPPDATA%\horizonchart\Cache` on Windows)
|
|
52
|
+
|
|
53
|
+
## Command line
|
|
54
|
+
|
|
55
|
+
### Finder chart for specific objects
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
horizonchart target Saturn --location "Monkey's Eyebrow, KY" --time "2026-10-02 22:00"
|
|
59
|
+
# -> saturn_20261002T2200_35.78N_78.64W.png
|
|
60
|
+
|
|
61
|
+
horizonchart target Moon Pleiades -l "35.78N 78.64W" -t "2026-10-03 02:00"
|
|
62
|
+
|
|
63
|
+
# No --time: 2 hours after tonight's sunset
|
|
64
|
+
horizonchart target Saturn -l "35.78N 78.64W"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Targets can be:
|
|
68
|
+
|
|
69
|
+
| Kind | Examples |
|
|
70
|
+
|---|---|
|
|
71
|
+
| Moon and planets | `Moon`, `Mars`, `Saturn`, `"saturn barycenter"` (BSP-style naming), `Pluto` |
|
|
72
|
+
| Messier / NGC / IC | `M31`, `M45`, `"NGC 1976"`, `"IC 2391"` |
|
|
73
|
+
| Deep-sky common names | `Pleiades`, `"Andromeda Galaxy"`, `Beehive` |
|
|
74
|
+
| Named stars | `Vega`, `Betelgeuse` |
|
|
75
|
+
|
|
76
|
+
`-t, --time` is local time at the location. By default it's 2 hours after
|
|
77
|
+
today's sunset there, rounded to the nearest half hour. Each target must be
|
|
78
|
+
above the horizon at that time.
|
|
79
|
+
|
|
80
|
+
### Twilight views for a date
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
horizonchart twilight --location "Ottawa, ON" --date 2026-10-02
|
|
84
|
+
# -> 20261002T0500_45.42N_75.69W_mor.png, 20261002T2030_45.42N_75.69W_eve.png
|
|
85
|
+
# (both moved to 2 hours from the Sun because planets were low at 1 hour)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| Option | Meaning |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `-d, --date` | Date (default: today at the location) |
|
|
91
|
+
| `-m, --limiting-magnitude` | Faintest stars and deep-sky objects shown. Default 2.0 (suburban twilight); 4–6 for dark skies |
|
|
92
|
+
| `--no-title` | Leave off the title ("Looking east, 1 hour before sunrise") |
|
|
93
|
+
|
|
94
|
+
### Common options
|
|
95
|
+
|
|
96
|
+
| Option | Meaning |
|
|
97
|
+
|---|--------------------------------------------------------------------------------------------------------|
|
|
98
|
+
| `-l, --location` | Coordinates (`35.19,-88.99`, `47.99N 84.77W`) or a place name (`"Monkey's Eyebrow, NC"`, `"Wawa, ON"`) |
|
|
99
|
+
| `--tz` | Time zone name; by default it's looked up from the location |
|
|
100
|
+
| `-o, --output-dir` | Where to write PNGs (default: current directory) |
|
|
101
|
+
| `--no-timestamp` | Leave off the date, time and location in the lower right corner |
|
|
102
|
+
| `--no-labels` | Leave off all names: planets, the Moon, stars, deep-sky objects, asterisms and constellations |
|
|
103
|
+
|
|
104
|
+
Place names are looked up with OpenStreetMap's
|
|
105
|
+
[Nominatim](https://nominatim.org) service, at most one request per second,
|
|
106
|
+
and cached (`horizonchart-geocode.json` in the data folder), so each place is
|
|
107
|
+
looked up once. Coordinates never touch the network. Nominatim's
|
|
108
|
+
[usage policy](https://operations.osmfoundation.org/policies/nominatim/)
|
|
109
|
+
asks applications to identify themselves; set `HORIZONCHART_CONTACT` (e.g. to
|
|
110
|
+
your email address) to include a contact in the request's user agent.
|
|
111
|
+
|
|
112
|
+
## Python
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
from datetime import date, datetime
|
|
116
|
+
from zoneinfo import ZoneInfo
|
|
117
|
+
|
|
118
|
+
from horizonchart.skyview import plot_targets, plot_twilight_views
|
|
119
|
+
|
|
120
|
+
plot_targets(47.99, -84.77, ["Saturn"],
|
|
121
|
+
datetime(2026, 10, 2, 22, 0, tzinfo=ZoneInfo("America/New_York")))
|
|
122
|
+
|
|
123
|
+
plot_twilight_views(47.99, -84.77, date(2026, 10, 2))
|
|
124
|
+
# {"morning": Path(...), "evening": Path(...)}
|
|
125
|
+
|
|
126
|
+
# The command line's --no-title, --no-timestamp and --no-labels
|
|
127
|
+
plot_targets(..., timestamp=False, labels=False)
|
|
128
|
+
plot_twilight_views(..., title=False, timestamp=False, labels=False)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## How charts are composed
|
|
132
|
+
|
|
133
|
+
**Both chart types**
|
|
134
|
+
|
|
135
|
+
- Planet and Moon markers are drawn in roughly their naked-eye colors.
|
|
136
|
+
Uranus, Neptune and Pluto are drawn smaller and semi-transparent.
|
|
137
|
+
- Asterisms (Great Square, Big Dipper, Summer Triangle, Orion's Belt, …) are
|
|
138
|
+
highlighted and labeled. When an asterism is essentially its whole
|
|
139
|
+
constellation (Cassiopeia's W, the Little Dipper), only the constellation is
|
|
140
|
+
named.
|
|
141
|
+
- Easily recognized constellations (Orion, Ursa Major and Minor, Cassiopeia,
|
|
142
|
+
Cygnus, Scorpius, Leo, Crux) are shown whenever most of the figure is in
|
|
143
|
+
view.
|
|
144
|
+
- At most five stars are labeled, chosen from a priority list of well-known
|
|
145
|
+
names (Polaris, Sirius, Betelgeuse, Vega, …). Other stars are unlabeled.
|
|
146
|
+
- The date, time and location are in small text in the lower right.
|
|
147
|
+
|
|
148
|
+
**Finder charts**
|
|
149
|
+
|
|
150
|
+
- Constellations are shown only if they contain a target, border it within
|
|
151
|
+
3°, or are home to a highlighted asterism.
|
|
152
|
+
- The view is framed automatically around the targets and asterisms.
|
|
153
|
+
|
|
154
|
+
**Twilight views**
|
|
155
|
+
|
|
156
|
+
- Each view is 1 hour before sunrise or after sunset, rounded to the half
|
|
157
|
+
hour. If planets or the Moon are low then, 2 hours is tried and used if it
|
|
158
|
+
shows more.
|
|
159
|
+
- Each view looks east or west, scored by what's in view (planets, the Moon,
|
|
160
|
+
deep-sky objects, asterisms, bright stars).
|
|
161
|
+
- The title, e.g. "Looking east, 1 hour before sunrise", is drawn on the
|
|
162
|
+
landscape.
|
|
163
|
+
|
|
164
|
+
Tuning constants (radii, magnitudes, font sizes, the asterism and
|
|
165
|
+
priority-star lists) are at the top of `src/horizonchart/skyview.py`.
|
|
166
|
+
|
|
167
|
+
## Compatibility with starplot
|
|
168
|
+
|
|
169
|
+
horizonchart draws its charts with starplot's public API, but a few features rely on starplot internals that have no public equivalent yet: keeping labels clear of highlighted asterism lines, detecting whether a label was placed, and converting coordinates for those checks. Because of this, the dependency is pinned to the tested starplot release series (`>=0.21.1,<0.22`). Update at your own risk.
|
|
170
|
+
|
|
171
|
+
## Tests
|
|
172
|
+
|
|
173
|
+
```sh
|
|
174
|
+
uv run pytest
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
The tests render real charts which require download of significant catalogs on first run and can take a few minutes to run as a result.
|
|
178
|
+
|
|
179
|
+
## Credits
|
|
180
|
+
|
|
181
|
+
- [starplot](https://starplot.dev) by Steve Berardi does the chart drawing, projections and catalogs (stars from Hipparcos/Tycho via its Big Sky catalog, deep-sky objects from [OpenNGC](https://github.com/mattiaverga/OpenNGC)). The horizon-view style follows its
|
|
182
|
+
[horizon gradient example](https://starplot.dev/examples/horizon-gradient/).
|
|
183
|
+
- [Skyfield](https://rhodesmill.org/skyfield/) by Brandon Rhodes computes sunrise and sunset, planetary magnitudes and alt/az positions, using JPL ephemerides.
|
|
184
|
+
- Place-name lookup uses [Nominatim](https://nominatim.org) through [geopy](https://geopy.readthedocs.io); geocoding data © [OpenStreetMap](https://www.openstreetmap.org/copyright) contributors.
|
|
185
|
+
- Time zones come from [timezonefinder](https://github.com/jannikmi/timezonefinder).
|
|
186
|
+
- Titles use the [Inter](https://rsms.me/inter/) typeface by Rasmus Andersson, bundled under the SIL Open Font License (`src/horizonchart/fonts/OFL.txt`).
|
|
187
|
+
|
|
188
|
+
## License
|
|
189
|
+
|
|
190
|
+
MIT; see [LICENSE](https://github.com/rtphokie/horizonchart/blob/main/LICENSE). The bundled Inter font is under the SIL Open Font
|
|
191
|
+
License 1.1.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "horizonchart"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Clean horizon-view sky charts: finder charts for planets, the Moon and deep-sky objects, and twilight views"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = [
|
|
8
|
+
"LICENSE",
|
|
9
|
+
"src/horizonchart/fonts/OFL.txt",
|
|
10
|
+
]
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
keywords = [
|
|
13
|
+
"astronomy",
|
|
14
|
+
"star chart",
|
|
15
|
+
"sky chart",
|
|
16
|
+
"planets",
|
|
17
|
+
"stargazing",
|
|
18
|
+
"starplot",
|
|
19
|
+
]
|
|
20
|
+
classifiers = [
|
|
21
|
+
"Development Status :: 3 - Alpha",
|
|
22
|
+
"Environment :: Console",
|
|
23
|
+
"Intended Audience :: Education",
|
|
24
|
+
"Intended Audience :: Science/Research",
|
|
25
|
+
"Operating System :: OS Independent",
|
|
26
|
+
"Programming Language :: Python :: 3",
|
|
27
|
+
"Programming Language :: Python :: 3.11",
|
|
28
|
+
"Programming Language :: Python :: 3.12",
|
|
29
|
+
"Programming Language :: Python :: 3.13",
|
|
30
|
+
"Topic :: Scientific/Engineering :: Astronomy",
|
|
31
|
+
"Topic :: Scientific/Engineering :: Visualization",
|
|
32
|
+
]
|
|
33
|
+
dependencies = [
|
|
34
|
+
"geopy>=2.5.0",
|
|
35
|
+
"pillow>=10.1",
|
|
36
|
+
"platformdirs>=4.0",
|
|
37
|
+
"shapely>=2.0",
|
|
38
|
+
"skyfield>=1.49",
|
|
39
|
+
"starplot>=0.21.1,<0.22",
|
|
40
|
+
"timezonefinder>=9.0.0",
|
|
41
|
+
"tzdata; sys_platform == 'win32'",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[[project.authors]]
|
|
45
|
+
name = "trice"
|
|
46
|
+
email = "rtphokie@gmail.com"
|
|
47
|
+
|
|
48
|
+
[project.urls]
|
|
49
|
+
Homepage = "https://github.com/rtphokie/horizonchart"
|
|
50
|
+
Repository = "https://github.com/rtphokie/horizonchart"
|
|
51
|
+
Issues = "https://github.com/rtphokie/horizonchart/issues"
|
|
52
|
+
|
|
53
|
+
[project.scripts]
|
|
54
|
+
horizonchart = "horizonchart.cli:main"
|
|
55
|
+
|
|
56
|
+
[build-system]
|
|
57
|
+
requires = ["uv_build>=0.12.19,<0.13.0"]
|
|
58
|
+
build-backend = "uv_build"
|
|
59
|
+
|
|
60
|
+
[dependency-groups]
|
|
61
|
+
dev = ["pytest>=9.1.1"]
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "horizonchart"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Clean horizon-view sky charts: finder charts for planets, the Moon and deep-sky objects, and twilight views"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [
|
|
7
|
+
{ name = "trice", email = "rtphokie@gmail.com" }
|
|
8
|
+
]
|
|
9
|
+
license = "MIT"
|
|
10
|
+
license-files = ["LICENSE", "src/horizonchart/fonts/OFL.txt"]
|
|
11
|
+
requires-python = ">=3.11"
|
|
12
|
+
keywords = ["astronomy", "star chart", "sky chart", "planets", "stargazing", "starplot"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 3 - Alpha",
|
|
15
|
+
"Environment :: Console",
|
|
16
|
+
"Intended Audience :: Education",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Topic :: Scientific/Engineering :: Astronomy",
|
|
24
|
+
"Topic :: Scientific/Engineering :: Visualization",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"geopy>=2.5.0",
|
|
28
|
+
"pillow>=10.1",
|
|
29
|
+
"platformdirs>=4.0",
|
|
30
|
+
"shapely>=2.0",
|
|
31
|
+
"skyfield>=1.49",
|
|
32
|
+
# Uses some starplot internals (see README), so stay within the tested release
|
|
33
|
+
"starplot>=0.21.1,<0.22",
|
|
34
|
+
"timezonefinder>=9.0.0",
|
|
35
|
+
# zoneinfo needs an IANA time zone database, which Windows doesn't ship
|
|
36
|
+
"tzdata; sys_platform == 'win32'",
|
|
37
|
+
]
|
|
38
|
+
|
|
39
|
+
[project.urls]
|
|
40
|
+
Homepage = "https://github.com/rtphokie/horizonchart"
|
|
41
|
+
Repository = "https://github.com/rtphokie/horizonchart"
|
|
42
|
+
Issues = "https://github.com/rtphokie/horizonchart/issues"
|
|
43
|
+
|
|
44
|
+
[project.scripts]
|
|
45
|
+
horizonchart = "horizonchart.cli:main"
|
|
46
|
+
|
|
47
|
+
[build-system]
|
|
48
|
+
requires = ["uv_build>=0.12.19,<0.13.0"]
|
|
49
|
+
build-backend = "uv_build"
|
|
50
|
+
|
|
51
|
+
[dependency-groups]
|
|
52
|
+
dev = [
|
|
53
|
+
"pytest>=9.1.1",
|
|
54
|
+
]
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
"""Clean horizon-view sky charts built on starplot."""
|
|
2
|
+
|
|
3
|
+
import os
|
|
4
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
try:
|
|
8
|
+
__version__ = version("horizonchart")
|
|
9
|
+
except PackageNotFoundError: # running from a source tree without installing
|
|
10
|
+
__version__ = "0.0.0"
|
|
11
|
+
|
|
12
|
+
SHARED_DATA_PATH = Path("/var/data")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _data_path() -> Path:
|
|
16
|
+
"""Where catalogs, ephemerides and caches go: $STARPLOT_DATA_PATH if set,
|
|
17
|
+
else /var/data if it exists and is writable, else the per-user cache
|
|
18
|
+
folder for this platform."""
|
|
19
|
+
if os.environ.get("STARPLOT_DATA_PATH"):
|
|
20
|
+
return Path(os.environ["STARPLOT_DATA_PATH"])
|
|
21
|
+
if SHARED_DATA_PATH.is_dir() and os.access(SHARED_DATA_PATH, os.W_OK):
|
|
22
|
+
return SHARED_DATA_PATH
|
|
23
|
+
from platformdirs import user_cache_path
|
|
24
|
+
|
|
25
|
+
return user_cache_path("horizonchart", appauthor=False)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
DATA_PATH = _data_path()
|
|
29
|
+
DATA_PATH.mkdir(parents=True, exist_ok=True)
|
|
30
|
+
# Starplot fixes its data path when it's first imported, so this has to happen
|
|
31
|
+
# before anything imports starplot (importing horizonchart does it first)
|
|
32
|
+
os.environ["STARPLOT_DATA_PATH"] = str(DATA_PATH)
|