v0.8.2 (#47)

* doc links

* comet example

* example

* info and format

* version

* readme

* hash

Author: steveberardi

.gitignore

@@ -17,6 +17,7 @@ constellationship.fab
 de421.bsp
 hip_main.dat
 hip8.dat
+CometEls.txt
 
 temp*
 raw/

README.md

@@ -67,6 +67,10 @@ For a demo of Starplot's zenith plots, check out:
 - adjustText
 
 ## Coming Soon
+- ⚙️ Callables for star sizes/colors/alpha
+- ✴️ Custom markers
+- 📐 Better DSO outlines
+- 🌐 More map projection options
 - ⚖️ Better auto font-size adjustment
 - ☄️ Better label collision detection and handling
 

docs/examples.md

@@ -5,9 +5,8 @@ This page has a few examples to get you familiar with Starplot and how it works.
 3. [Map of Orion](#map-of-orion)
 4. [Map of The Pleiades with a Scope Field of View](#map-of-the-pleiades-with-a-scope-field-of-view)
 5. [Optic plot of The Pleiades with a Refractor Telescope](#optic-plot-of-the-pleiades-with-a-refractor-telescope)
-6. [Map plot of The Big Dipper with Custom Markers](#map-of-the-big-dipper-with-custom-markers)
-
-
+6. [Map of The Big Dipper with Custom Markers](#map-of-the-big-dipper-with-custom-markers)
+7. [Map of Hale-Bopp in 1997](#map-of-hale-bopp-in-1997)
 
 ## Star Chart for Time/Location
 To create a star chart for the sky as seen from [Palomar Mountain](https://en.wikipedia.org/wiki/Palomar_Mountain) in California on July 13, 2023 at 10pm PT:
@@ -57,6 +56,8 @@ The result should look like this:
 
 ![map-pleiades-scope](images/example_04.png)
 
+_The solid black circle in this plot is the extent of the Pleiades as defined in [OpenNGC](https://github.com/mattiaverga/OpenNGC)._
+
 !!! tip "Binocular Field of View"
 
     You can also plot a circle showing the field of view of binoculars with the `plot_bino_fov` function:
@@ -89,7 +90,27 @@ Here's a fun one 😃 Let's create a small plot of the big dipper ([Ursa Major](
 
 The result should look like this:
 
-![stars-m45](images/example_06.png)
+![map-big-dipper](images/example_06.png)
+
+
+
+## Map of Hale-Bopp in 1997
+
+Here's an example that uses [Skyfield](https://rhodesmill.org/skyfield/) to get some data on the comet [Hale-Bopp](https://en.wikipedia.org/wiki/Comet_Hale%E2%80%93Bopp) ☄️ and then uses that data to plot the comet's location in the sky in March and April of 1997 (when the comet was at its brightest in the sky):
+
+!!! note
+
+    Skyfield is a required dependency of Starplot (and a very important one!), so if you have Starplot installed, then Skyfield should be installed too.
+
+
+```python
+--8<-- "examples/example_07.py"
+```
+
+The result should look like this:
+
+![map-hale-bopp](images/example_07.png)
+
 
 ---
 

docs/images/example_03.png

@@ -178,6 +178,9 @@ Starplot has a bunch of built-in style extensions (all imported from `starplot.s
     options:
         show_root_heading: true
         show_docstring_attributes: true
+        separate_signature: true
+        show_signature_annotations: true
+        signature_crossrefs: true
         members: true
 
 
@@ -187,7 +190,6 @@ Starplot has a bunch of built-in style extensions (all imported from `starplot.s
         show_root_heading: true
         show_docstring_attributes: true
 
-
 ::: starplot.styles.LineStyle
     options:
         show_root_heading: true

docs/images/example_04.png

@@ -0,0 +1,90 @@
+from skyfield.api import load
+from skyfield.data import mpc
+from skyfield.constants import GM_SUN_Pitjeva_2005_km3_s2 as GM_SUN
+
+from starplot import MapPlot, Projection, SkyObject
+from starplot.styles import PlotStyle, extensions
+
+# First, we use Skyfield to get comet data
+# Code adapted from: https://rhodesmill.org/skyfield/kepler-orbits.html#comets
+with load.open(mpc.COMET_URL) as f:
+    comets = mpc.load_comets_dataframe(f)
+
+# Keep only the most recent orbit for each comet,
+# and index by designation for fast lookup.
+comets = (
+    comets.sort_values("reference")
+    .groupby("designation", as_index=False)
+    .last()
+    .set_index("designation", drop=False)
+)
+
+# Find Hale-Bopp
+row = comets.loc["C/1995 O1 (Hale-Bopp)"]
+
+ts = load.timescale()
+eph = load("de421.bsp")
+sun, earth = eph["sun"], eph["earth"]
+comet = sun + mpc.comet_orbit(row, ts, GM_SUN)
+
+# Find the RA/DEC of comet for every 4 days starting on March 20, 1997
+radecs = []
+for day in range(0, 28, 4):
+    t = ts.utc(1997, 3, 20 + day)
+    ra, dec, distance = earth.at(t).observe(comet).radec()
+    radecs.append((t, ra.hours, dec.degrees))
+
+# Now let's plot the data on a map!
+style = PlotStyle().extend(
+    extensions.BLUE_LIGHT,
+    extensions.MAP,
+)
+style.legend.location = "lower right"
+style.legend.num_columns = 1
+
+p = MapPlot(
+    projection=Projection.STEREO_NORTH,
+    # to make plots that are centered around the 0h equinox, you can
+    # set the max RA to a number over 24 which will determine how
+    # far past 0h the plot will extend. For example, here we set
+    # the max RA to 28, so this plot will have an RA extent from 23h to 4h
+    ra_min=23,
+    ra_max=28,
+    dec_min=30,
+    dec_max=50,
+    limiting_magnitude=6.2,
+    style=style,
+    resolution=2000,
+)
+
+for t, ra, dec in radecs:
+    label = f"{t.utc.month}/{t.utc.day}/{t.utc.year % 100}"
+    p.plot_object(
+        SkyObject(
+            name=label,
+            legend_label="Hale-Bopp Comet",
+            ra=ra,
+            dec=dec,
+            style={
+                "marker": {
+                    "size": 12,
+                    "symbol": "o",
+                    "fill": "full",
+                    "color": "#ff6868",
+                    "alpha": 0.8,
+                    "zorder": 4096,
+                },
+                "label": {
+                    "font_size": 13,
+                    "font_weight": "bold",
+                    "font_color": "#3c6daa",
+                    "zorder": 4096,
+                },
+            },
+        )
+    )
+
+# refresh the legend so the Hale-Bopp marker is included
+p.refresh_legend()
+
+p.export("07_map_hale_bopp.png", padding=0.2)

docs/images/example_05.png

@@ -2,7 +2,7 @@
 
 import subprocess
 
-for n in range(1, 7):
+for n in range(1, 8):
     subprocess.call(f"python example_{n:02}.py", shell=True)
     subprocess.call(f"cp {n:02}*.png ../docs/images/example_{n:02}.png", shell=True)
 

docs/images/example_07.png

@@ -658,7 +658,7 @@ def test_ex():
     from starplot.styles import PlotStyle, extensions, MarkerSymbolEnum
 
     style = PlotStyle().extend(
-        extensions.MINIMAL,
+        # extensions.MINIMAL,
         extensions.GRAYSCALE,
         extensions.MAP,
     )
@@ -668,12 +668,12 @@ def test_ex():
     # Star sizes are calculated based on their magnitude first,
     # but then that result will be multiplied by the star's marker size in the PlotStyle
     # so, adjusting the star marker size is a way to make all stars bigger or smaller
-    style.star.marker.size = 50
+    style.star.marker.size = 20
 
     p = MapPlot(
         projection=Projection.STEREO_NORTH,
-        ra_min=10.8,
-        ra_max=14,
+        ra_min=10,
+        ra_max=18,
         dec_min=48,
         dec_max=64,
         limiting_magnitude=3.6,
@@ -699,8 +699,8 @@ def test_ex():
 # create_map_mercator()
 # create_map_stereo_north()
 # create_map_stereo_south()
-create_map_orion()
-create_map_scratch()
+# create_map_orion()
+# create_map_scratch()
 # create_map_sgr()
 test_ex()
 

docs/reference-styling.md

@@ -1,6 +1,6 @@
 """Star charts and maps"""
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"
 
 from .base import StarPlot  # noqa: F401
 from .zenith import ZenithPlot  # noqa: F401

examples/03_map_orion.png

@@ -158,7 +158,12 @@ def in_bounds(self, ra: float, dec: float) -> bool:
             True if the coordinate is in bounds, otherwise False
 
         """
-        return self.ra_min < ra < self.ra_max and self.dec_min < dec < self.dec_max
+        if self.ra_max < 24:
+            return self.ra_min < ra < self.ra_max and self.dec_min < dec < self.dec_max
+        else:
+            return (
+                ra > self.ra_min or ra < self.ra_max - 24
+            ) and self.dec_min < dec < self.dec_max
 
     def _latlon_bounds(self):
         # convert the RA/DEC bounds to lat/lon bounds

examples/04_map_m45_scope.png

@@ -226,7 +226,7 @@ def test_map_plot_wrapping():
         resolution=2000,
     ).export(filename, padding=0.3)
 
-    assert dhash(filename) == "1f1e8f4743211117"
+    assert dhash(filename) == "1f1e0f4743211117"
     assert colorhash(filename) == "07000000000"