v0.20

.gitignore

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

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: 

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

docs/changelog.md

@@ -1,4 +1,12 @@
+## 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`
+
+
 ## 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

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>

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/">

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"
+```
+
+

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

@@ -7,6 +7,7 @@ title: The Milky Way
 
 ![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"

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

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

docs/reference-collisions.md

@@ -1,6 +1,12 @@
 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 that'll be used when plotting text. But, you can also override this default on all functions that plot text (either directly or as a side effect). There's one exception to this though: since constellation labels are area-based labels they have their own default collision handler. 
+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._
 
@@ -10,6 +16,45 @@ _See the [Virgo Galaxy Cluster](/examples/map-virgo-cluster/) plot for an exampl
     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

docs/reference-galaxyplot.md

@@ -0,0 +1,20 @@
+**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
+

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

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.

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).

examples/map_canis_major.py

@@ -24,7 +24,7 @@
 )
 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)

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)

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 @@
 
 _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")