starplot 0.19.6__tar.gz → 0.20.1__tar.gz

{starplot-0.19.6 → starplot-0.20.1}/.gitignore

@@ -29,6 +29,7 @@ bigsky*.parquet
 hash_checks/data/*.png
 hash_checks/results.html
 
+.tmp/
 temp*
 temp.py
 temp/

{starplot-0.19.6 → starplot-0.20.1}/CITATION.cff

@@ -20,5 +20,5 @@ keywords:
   - graphs
   - plotting
 license: MIT
-version: 0.19.6
-date-released: '2026-02-15'
+version: 0.20.1
+date-released: '2026-03-10'

{starplot-0.19.6 → starplot-0.20.1}/Makefile

@@ -35,7 +35,7 @@ format:
 	$(DOCKER_RUN) "python -m black src/ tests/ scripts/ examples/ hash_checks/ tutorial/ data/ $(ARGS)"
 
 test:
-	$(DOCKER_RUN) "python -m pytest --cov=src/ --cov-report=term --cov-report=html ."
+	$(DOCKER_RUN) "python -m pytest $(ARGS) --cov=src/ --cov-report=term --cov-report=html ."
 
 check-hashes:
 	$(DOCKER_RUN) "python hash_checks/hashio.py check"
@@ -65,10 +65,10 @@ examples:
 tutorial:
 	$(DOCKER_RUN) "cd tutorial && python build.py"
 
-profile: DR_ARGS=-it -p 8080:8080
+profile: DR_ARGS=-it -p 8081:8081
 profile:
 	$(DOCKER_RUN) "python -m cProfile -o temp/results.prof scripts/scratchpad.py && \
-	snakeviz -s -p 8080 -H 0.0.0.0 temp/results.prof"
+	snakeviz -s -p 8081 -H 0.0.0.0 temp/results.prof"
 
 # builds ALL data files and then database:
 db: 

{starplot-0.19.6 → starplot-0.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starplot
-Version: 0.19.6
+Version: 0.20.1
 Summary: Star charts and maps of the sky
 Keywords: astronomy,stars,charts,maps,constellations,sky,plotting
 Author-email: Steve Berardi <hello@steveberardi.com>
@@ -45,8 +45,9 @@ Project-URL: Source, https://github.com/steveberardi/starplot
 
 - 🗺️ **Maps** - including 10+ customizable projections
 - ⭐ **Zenith Charts** - shows the entire sky at a specific time and place
-- 🌃 **Horizon Charts** - shows the horizon at a specific time and place
+- 🌅 **Horizon Charts** - shows the horizon at a specific time and place
 - 🔭 **Optic Simulations** - shows what you'll see through an optic (e.g. telescope) at a specific time and place
+- 🌌 **Galactic Charts** - shows a Mollweide projection in galactic coordinates
 - 🪐 **Planets and Deep Sky Objects (DSOs)** - with support for plotting their true extent
 - ☄️ **Comets and Satellites** - easy trajectory plotting
 - 🎨 **Custom Styles** - for all objects and with 8+ built-in themes

{starplot-0.19.6 → starplot-0.20.1}/README.md

@@ -8,8 +8,9 @@
 
 - 🗺️ **Maps** - including 10+ customizable projections
 - ⭐ **Zenith Charts** - shows the entire sky at a specific time and place
-- 🌃 **Horizon Charts** - shows the horizon at a specific time and place
+- 🌅 **Horizon Charts** - shows the horizon at a specific time and place
 - 🔭 **Optic Simulations** - shows what you'll see through an optic (e.g. telescope) at a specific time and place
+- 🌌 **Galactic Charts** - shows a Mollweide projection in galactic coordinates
 - 🪐 **Planets and Deep Sky Objects (DSOs)** - with support for plotting their true extent
 - ☄️ **Comets and Satellites** - easy trajectory plotting
 - 🎨 **Custom Styles** - for all objects and with 8+ built-in themes

{starplot-0.19.6 → starplot-0.20.1}/docs/changelog.md

@@ -1,4 +1,20 @@
+## v0.20.x
+
+- Adds a `GalaxyPlot` for plotting in galactic coordinates
+- Adds label support to lines with automatic angle adjustment
+- Plots the Moon's precise phase / illumination when `show_phase=True`
+- Separate collision handlers for points, areas, and paths
+- Refactored some models to expect an observer instance instead of lat/lon/dt
+- Adds the PlateCarree projection
+- Adds effect of atmospheric refraction to horizon and optic plots
+- Fixes a bug with calculating apparent positions of solar system objects in horizon/optic plots
+- [**v0.20.1**]
+    - Optimizes coordinate conversions
+    - Makes constellation lines straight
+
+
 ## v0.19.x
+[Documentation](https://archives.starplot.dev/0.19.6/)
 
 - Adds a `CollisionHandler` for defining what to do when labels collide with something
 - Introduces catalogs for the Milky Way and constellation borders

{starplot-0.19.6 → starplot-0.20.1}/docs/coming-soon.md

@@ -1,16 +1,17 @@
 <table class="table-coming-soon">
     <tr>
-        <td>v0.20</td>
+        <td>v0.21</td>
         <td>
             <h4>⭐ Next Release ⭐</h4>
             <ul>
-                <li>Support for more coordinate systems</li>
+                <li>Plot definition files</li>
+                <li>CLI for creating plots</li>
             </ul>
         </td>
         <td></td>
     </tr>
     <tr>
-        <td>v0.21</td>
+        <td>v0.22</td>
         <td>
             <ul>
                 <li>TBD</li>
@@ -19,12 +20,11 @@
         <td></td>
     </tr>
     <tr>
-        <td>v0.22+</td>
+        <td>v0.23+</td>
         <td>
             <ul>
                 <li>Planet moons</li>
                 <li>Area-based labeling</li>
-                <li>Improved line labeling</li>
                 <li>Optimized vector graphics backend</li>
             </ul>
         </td>

starplot-0.20.1/docs/examples/map-galaxy.md

@@ -0,0 +1,14 @@
+---
+title: Galaxy Plot
+---
+[:octicons-arrow-left-24: Back to Examples](/examples)
+
+# Galaxy Plot {.example-header}
+
+![map-galaxy](/images/examples/map_galaxy.png)
+
+```python
+--8<-- "examples/map_galaxy.py"
+```
+
+

starplot-0.20.1/docs/examples/map-milky-way-stars.md

@@ -0,0 +1,16 @@
+---
+title: The Milky Way
+---
+[:octicons-arrow-left-24: Back to Examples](/examples)
+
+# The Milky Way {.example-header}
+
+![map-milky-way-stars](/images/examples/map_milky_way_stars.png)
+
+In this example, we first plot all stars with a limiting magnitude of 11, which clearly shows the Milky Way. And then we use [Pillow](https://pillow.readthedocs.io/en/latest/index.html) to apply a median filter, which helps make the Milky Way stand out more in the image.
+
+```python
+--8<-- "examples/map_milky_way_stars.py"
+```
+
+

{starplot-0.19.6 → starplot-0.20.1}/docs/examples/map-virgo-cluster.md

@@ -7,7 +7,7 @@ title: Map of the Virgo Galaxy Cluster
 
 ![map-virgo-galaxy-cluster](/images/examples/map_virgo_cluster.png)
 
-In this example, we create a custom [CollisionHandler](/reference-collisions/) to ensure _all_ labels are plotted in the very busy area of the Virgo Galaxy Cluster:
+In this example, we create a custom [CollisionHandler](/reference-collisions/) for points to ensure _all_ labels are plotted in the very busy area of the Virgo Galaxy Cluster:
 
 <div class="tutorial">
 ```python

{starplot-0.19.6 → starplot-0.20.1}/docs/examples.md

@@ -90,11 +90,17 @@
             <p class="example-card-title">The Big Dipper</p>
         </a>
     </li>
-    <li>
+    <!-- <li>
         <a href="/examples/map-sagittarius/">
             <img src="/images/examples/map_sagittarius-sm.png" alt="Map of Sagittarius" class="off-glb" loading="lazy"/>
             <p class="example-card-title">Map of Sagittarius</p>
         </a>
+    </li> -->
+    <li>
+        <a href="/examples/map-galaxy/">
+            <img src="/images/examples/map_galaxy-sm.png" alt="Open Clusters around the Milky Way" class="off-glb" loading="lazy"/>
+            <p class="example-card-title">Galaxy Plot</p>
+        </a>
     </li>
     <li>
         <a href="/examples/map-canis-major/">

{starplot-0.19.6 → starplot-0.20.1}/docs/index.md

@@ -16,10 +16,12 @@ Starplot is a Python library for creating star charts and maps of the sky
 
 - ⭐ **Zenith Charts** - shows the entire sky at a specific time and place
 
-- 🌃 **Horizon Charts** - shows the horizon at a specific time and place
+- 🌅 **Horizon Charts** - shows the horizon at a specific time and place
 
 - 🔭 **Optic Simulations** - shows what you'll see through an optic (e.g. telescope) at a specific time and place
 
+- 🌌 **Galactic Charts** - shows a Mollweide projection in galactic coordinates
+
 - 🪐 **Planets and Deep Sky Objects (DSOs)** - with support for plotting their true extent
 
 - ☄️ **Comets and Satellites** - easy trajectory plotting

starplot-0.20.1/docs/reference-collisions.md

@@ -0,0 +1,63 @@
+One of the biggest contributors to the visual quality of a map is labeling, which includes choosing carefully _what_ to label and also choosing good _positions_ for those labels. Obviously, you don't want labels to collide with each other, but there's also a few more subtle things to consider when labeling points and areas on a map. Starplot has a `CollisionHandler` to control some of these things.
+
+When you create a plot, you can specify the default collision handler for three different types of labels:
+
+- **Points** (`point_label_handler`) - stars, DSOs, etc
+- **Areas** (`area_label_handler`) - constellations
+- **Paths** (`path_label_handler`) - ecliptic, celestial equator, etc
+
+You can also override these defaults on all functions that plot text. There are three distinct types of collision handlers because it's very common to want different rules for different types of labels. For example, the default area collision handler allows collisions with constellation lines, but the point handler does not.
+
+_See the [Virgo Galaxy Cluster](/examples/map-virgo-cluster/) plot for an example of using a custom collision handler._
+
+
+!!! tip "New Feature"
+
+    The collision handler is a newer feature of Starplot (introduced in version 0.19.0), and will continue to evolve in future versions. As always, if you notice any unexpected behavior with it, please [open an issue on GitHub](https://github.com/steveberardi/starplot/issues).
+
+
+## Defaults
+
+Below are the defaults for each type of collision handler. These are the defaults for _all_ plot types.
+
+### Points
+
+```python
+CollisionHandler(
+    attempts=10,
+    anchor_fallbacks=[
+        AnchorPointEnum.BOTTOM_RIGHT,
+        AnchorPointEnum.TOP_LEFT,
+        AnchorPointEnum.TOP_RIGHT,
+        AnchorPointEnum.BOTTOM_LEFT,
+        AnchorPointEnum.BOTTOM_CENTER,
+        AnchorPointEnum.TOP_CENTER,
+        AnchorPointEnum.RIGHT_CENTER,
+        AnchorPointEnum.LEFT_CENTER,
+    ]
+)
+```
+
+### Areas
+
+```python
+CollisionHandler(
+    allow_constellation_line_collisions=True
+)
+```
+
+### Paths
+
+```python
+CollisionHandler(
+    allow_constellation_line_collisions=True
+)
+```
+
+
+::: starplot.CollisionHandler
+    options:
+        members_order: source
+        inherited_members: true
+        merge_init_into_class: true
+        show_root_heading: true

starplot-0.20.1/docs/reference-galaxyplot.md

@@ -0,0 +1,18 @@
+**Galaxy plots will plot everything in galactic coordinates, using a Mollweide projection**. These plots will always plot the entire galactic sphere, since that's how they're most commonly used.
+
+Although they plot everything in galactic coordinates, all functions still expect equatorial coordinates (RA/DEC). This decision was made for two reasons: it seems most astronomical data is presented in equatorial coordinates, and creating a transformation framework in Starplot would be a pretty large project so it'll be reserved for a future version.
+
+Stars on galaxy plots are plotted in their [_astrometric_ positions](reference-positions.md).
+
+!!! tip "New Feature - Feedback wanted!"
+
+    These plots are a newer feature of Starplot (introduced in version 0.20.0), and will continue to evolve in future versions. If you notice any unexpected behavior or you think there's a useful feature missing, please [open an issue on GitHub](https://github.com/steveberardi/starplot/issues).
+    
+
+::: starplot.GalaxyPlot
+    options:
+        inherited_members: true
+        merge_init_into_class: true
+        show_root_heading: true
+        docstring_section_style: list
+

{starplot-0.19.6 → starplot-0.20.1}/docs/reference-positions.md

@@ -12,6 +12,7 @@ Plots that use astrometric positions:
 
 - [MapPlot](reference-mapplot.md)
 - [ZenithPlot](reference-zenithplot.md)
+- [GalaxyPlot](reference-galaxyplot.md)
 
 
 ### Apparent Position

{starplot-0.19.6 → starplot-0.20.1}/docs/tutorial/04.md

@@ -14,7 +14,7 @@ title: 4 - Creating a Basic Map | Tutorial
 # 4 - Creating a Basic Map
 
 <figure markdown="span">
-  ![Tutorial - Map Plot](/images/tutorial/tutorial_04.png){ width="900" }
+  ![Tutorial - Map Plot](/images/tutorial/tutorial_04.png)
 </figure>
 
 The zenith plot is known as a [perspective projection](https://en.wikipedia.org/wiki/Perspective_(graphical)), which means it depends on a time and place. They're useful for many things in astronomy, but Starplot also lets you create general-purpose maps of the sky that are independent of location.

{starplot-0.19.6 → starplot-0.20.1}/docs/tutorial/06.md

@@ -14,7 +14,7 @@ title: 6 - Selecting Objects to Plot | Tutorial
 # 6 - Selecting Objects to Plot
 
 <figure markdown="span">
-  ![Tutorial - Selecting Objects](/images/tutorial/tutorial_06.png){ width="700" }
+  ![Tutorial - Selecting Objects](/images/tutorial/tutorial_06.png)
 </figure>
 
 When plotting stars, constellations, or deep sky objects (DSOs), you may want to limit the plotted objects by more than just a limiting magnitude. Starplot provides a way to [filter objects by using expressions](/reference-selecting-objects/). This allows you to be very specific about which objects to plot, and it also gives you a way to style objects differently (e.g. if you want to style very bright stars differently than dim stars).

{starplot-0.19.6 → starplot-0.20.1}/docs/tutorial/07.md

@@ -19,7 +19,7 @@ title: 7 - Object Lookup | Tutorial
 
 Starplot has [models](/reference-models/) for most objects you can plot, including stars, DSOs, planets, moons, and the Sun. These models also have properties relevant to each object (e.g. magnitude, ra, dec, etc). Sometimes you may want to create a plot directly from an object, so Starplot has a way to lookup objects by using each model's `get()` or `find()` functions.
 
-For example, here's a way to get Jupiter's position for tonight's sky and then create an optic plot directly from the Planet instance:
+For example, here's a way to get Jupiter's position for a specific date/time and then create an optic plot directly from the Planet instance:
 <div class="tutorial" markdown>
 ```python linenums="1"
 --8<-- "tutorial/tutorial_07.py"

{starplot-0.19.6 → starplot-0.20.1}/examples/map_big_dipper.py

@@ -2,7 +2,7 @@ from starplot import MapPlot, StereoNorth, _
 from starplot.styles import PlotStyle, extensions
 
 style = PlotStyle().extend(
-    extensions.BLUE_DARK, extensions.MAP, {"background_color": "#2C3F62"}
+    extensions.BLUE_DARK, extensions.MAP, {"background_color": "#193561"}
 )
 
 p = MapPlot(
@@ -22,7 +22,7 @@ p.stars(
     ],
     size_fn=lambda s: 2600,  # make stars a constant size
     style__marker__symbol="star",
-    style__marker__color="#ffff6c",
+    style__marker__color="hsl(59, 100%, 53%)",
     style__label__font_size=14,
     style__label__font_weight=400,
 )

{starplot-0.19.6 → starplot-0.20.1}/examples/map_canis_major.py

@@ -24,7 +24,7 @@ p.constellations(
 )
 p.line(
     geometry=canis_major.border,
-    style=p.style.constellation_borders,
+    style__line=p.style.constellation_borders,
 )
 p.open_clusters(where=[_.magnitude < 9], where_true_size=[False])
 p.stars(where=[_.magnitude < 9], where_labels=[_.magnitude < 4], bayer_labels=True)

starplot-0.20.1/examples/map_galaxy.py

@@ -0,0 +1,65 @@
+from starplot import _, GalaxyPlot, DSO
+from starplot.styles import PlotStyle, extensions
+from starplot.callables import size_by_magnitude_factory
+
+_sizer = size_by_magnitude_factory(6, 0.03, 12)
+
+style = PlotStyle().extend(
+    extensions.BLUE_NIGHT,
+    extensions.MAP,
+)
+
+p = GalaxyPlot(
+    style=style,
+    resolution=5000,
+    scale=0.83,
+)
+p.gridlines()
+
+p.galactic_equator(num_labels=2)
+p.celestial_equator(num_labels=2)
+p.ecliptic(num_labels=2)
+
+p.milky_way()
+
+p.stars(
+    where=[_.magnitude < 7],
+    where_labels=[False],
+    size_fn=_sizer,
+    style__marker__edge_color="#c5c5c5",
+)
+
+lmc = DSO.get(name="ESO056-115")
+smc = DSO.get(name="NGC0292")
+mc_style = {
+    "font_color": "#acc2e0",
+    "font_size": 42,
+    "font_weight": 700,
+    "border_width": 8,
+    "border_color": "#1e232a",
+}
+
+p.text(
+    "LMC",
+    ra=lmc.ra,
+    dec=lmc.dec,
+    style=mc_style,
+)
+
+p.text(
+    "SMC",
+    ra=smc.ra,
+    dec=smc.dec,
+    style=mc_style,
+)
+
+p.open_clusters(
+    where=[(_.magnitude < 16) | (_.magnitude.isnull())],
+    where_labels=[False],
+    where_true_size=[False],
+)
+p.legend()
+
+p.title("Open Clusters Around the Milky Way", style__font_size=86)
+
+p.export("map_galaxy.png", padding=1)

{starplot-0.19.6 → starplot-0.20.1}/examples/map_milky_way_stars.py

@@ -1,3 +1,5 @@
+from PIL import Image, ImageFilter
+
 from starplot import MapPlot, Mollweide, _
 from starplot.data.catalogs import BIG_SKY
 from starplot.styles import PlotStyle, extensions
@@ -10,38 +12,23 @@ style = PlotStyle().extend(
 
 _sizer = size_by_magnitude_factory(6, 0.02, 7)
 
-
-def alpha(s):
-    if s.magnitude > 9:
-        return 0.5
-    else:
-        return 0.9
-
-
 p = MapPlot(
     projection=Mollweide(),
     style=style,
     resolution=4800,
 )
-
 p.stars(
     where=[_.magnitude < 11],
     where_labels=[False],
     size_fn=_sizer,
-    alpha_fn=alpha,
-    color_fn=color_by_bv,
-    catalog=BIG_SKY,
-    style__marker__edge_color="#c5c5c5",
-)
-p.stars(
-    where=[_.magnitude < 6],
-    where_labels=[False],
-    size_fn=lambda s: _sizer(s) * 1.5,
-    alpha_fn=lambda s: 0.4,
+    alpha_fn=lambda s: 0.95 if s.magnitude < 9 else 0.6,
     color_fn=color_by_bv,
     catalog=BIG_SKY,
-    style__marker__symbol="star_8",
-    style__marker__edge_color=None,
+    style__marker__edge_color="#fff",
 )
-
 p.export("map_milky_way_stars.png", padding=0.1, transparent=True)
+
+# apply a median filter to increase contrast
+with Image.open("map_milky_way_stars.png") as img:
+    filtered = img.filter(ImageFilter.MedianFilter(size=5))
+    filtered.save("map_milky_way_stars.png")

{starplot-0.19.6 → starplot-0.20.1}/examples/map_orthographic.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from pytz import timezone
+from zoneinfo import ZoneInfo
 
 from starplot import MapPlot, Orthographic, Observer, _
 from starplot.styles import PlotStyle, extensions
@@ -10,7 +10,7 @@ style = PlotStyle().extend(
     extensions.MAP,
 )
 
-tz = timezone("America/Los_Angeles")
+tz = ZoneInfo("America/Los_Angeles")
 dt = datetime(2024, 10, 19, 21, 00, tzinfo=tz)
 
 observer = Observer(

{starplot-0.19.6 → starplot-0.20.1}/examples/map_virgo_cluster.py

@@ -33,7 +33,7 @@ p = MapPlot(
     style=style,
     resolution=3000,
     scale=1,
-    collision_handler=collision_handler,
+    point_label_handler=collision_handler,
 )
 p.title("Virgo Cluster", style__font_color="hsl(330, 44%, 92%)")
 p.stars(where=[_.magnitude < 12], where_labels=[False])

{starplot-0.19.6 → starplot-0.20.1}/examples/optic_iss_transit.py

@@ -19,7 +19,7 @@ observer = Observer(
     lon=-116.507025,
 )
 
-moon = Moon.get(dt=observer.dt, lat=observer.lat, lon=observer.lon)
+moon = Moon.get(observer)
 
 p = OpticPlot(
     ra=moon.ra,
@@ -39,8 +39,7 @@ iss = Satellite.from_tle(
     name="ISS (ZARYA)",
     line1="1 25544U 98067A   25312.42041502  .00013418  00000+0  24734-3 0  9990",
     line2="2 25544  51.6332 312.3676 0004093  47.8963 312.2373 15.49452868537539",
-    lat=observer.lat,
-    lon=observer.lon,
+    observer=observer,
 )
 
 dt_start = observer.dt - timedelta(minutes=1)
@@ -77,7 +76,7 @@ for sat in iss.trajectory(dt_start, dt_end, step=timedelta(seconds=1)):
                 "zorder": 5_000,
             },
         },
-        label=sat.dt.strftime("%-H:%M:%S"),
+        label=sat.observer.dt.strftime("%-H:%M:%S"),
     )
 
 p.export("optic_iss_transit.png", padding=0.1, transparent=True)

{starplot-0.19.6 → starplot-0.20.1}/examples/optic_moon_saturn.py

@@ -12,7 +12,7 @@ observer = Observer(
     lon=-116.585556,
 )
 
-m = Moon.get(dt=observer.dt, lat=observer.lat, lon=observer.lon)
+m = Moon.get(observer)
 
 op = m.create_optic(
     observer=observer,

{starplot-0.19.6 → starplot-0.20.1}/examples/optic_solar_eclipse.py

@@ -14,7 +14,7 @@ observer = Observer(
     lon=-81.669722,
 )
 
-m = Moon.get(dt=observer.dt, lat=observer.lat, lon=observer.lon)
+m = Moon.get(observer)
 
 op = m.create_optic(
     observer=observer,

{starplot-0.19.6 → starplot-0.20.1}/hash_checks/hashio.py

@@ -23,7 +23,7 @@ HERE = Path(__file__).resolve().parent
 
 RESULTS_PATH = HERE / "results.html"
 
-NUM_WORKERS = 10
+NUM_WORKERS = 12
 
 console = Console()