starplot 0.21.4__tar.gz → 0.23.0__tar.gz

{starplot-0.21.4 → starplot-0.23.0}/.github/workflows/test.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
     steps:
     - uses: actions/checkout@v6
     - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0

{starplot-0.21.4 → starplot-0.23.0}/CITATION.cff

@@ -20,5 +20,5 @@ keywords:
   - graphs
   - plotting
 license: MIT
-version: 0.21.4
-date-released: '2026-10-12'
+version: 0.23.0
+date-released: '2026-11-11'

{starplot-0.21.4 → starplot-0.23.0}/Makefile

@@ -101,11 +101,6 @@ dev: env db setup download-test-fonts
 # ------------------------------------------------------------------
 # Python version testing
 # ------------------------------------------------------------------
-test-3.10: PYTHON_VERSION=3.10.21
-test-3.10:
-	$(DOCKER_BUILD_PYTHON)
-	$(DOCKER_RUN_PYTHON_TEST)
-
 test-3.11: PYTHON_VERSION=3.11.16
 test-3.11:
 	$(DOCKER_BUILD_PYTHON)
@@ -168,7 +163,7 @@ list-fonts:
 
 clean:
 	rm -rf __pycache__
-	rm -rf venv
+	rm -rf .venv
 	rm -rf dist
 	rm -rf site
 	rm -rf htmlcov

{starplot-0.21.4 → starplot-0.23.0}/PKG-INFO

@@ -1,14 +1,13 @@
 Metadata-Version: 2.4
 Name: starplot
-Version: 0.21.4
+Version: 0.23.0
 Summary: Star charts and maps of the sky
 Keywords: astronomy,stars,charts,maps,constellations,sky,plotting
 Author-email: Steve Berardi <steve@starplot.dev>
-Requires-Python: >=3.10,<3.15
+Requires-Python: >=3.11,<3.15
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -27,7 +26,7 @@ Requires-Dist: pyarrow >= 14.0.2
 Requires-Dist: rtree >= 1.2.0
 Requires-Dist: pyqtree >= 1.0.0
 Requires-Dist: requests >= 2.31.0
-Requires-Dist: duckdb >= 1.4.4
+Requires-Dist: duckdb < 2.0.0
 Requires-Dist: sqlglot >= 28.9.0
 Requires-Dist: ibis-framework[duckdb, geospatial] >= 11
 Requires-Dist: astropy-healpix >= 1.1.2

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/de/constellation_names.csv

@@ -64,7 +64,9 @@ peg,Pegasus,Pegasus
 per,Perseus,Perseus
 phe,Phoenix,Phönix
 pic,Pictor,Maler
+psc,Pisces,Fische
 psa,Piscis Austrinus,Südlicher Fisch
+psc,Pisces,Fische
 pup,Puppis,Achterdeck des Schiffes
 pyx,Pyxis,Schiffskompass
 ret,Reticulum,Netz
@@ -86,4 +88,4 @@ umi,Ursa Minor,Kleiner Bär
 vel,Vela,Segel des Schiffes
 vir,Virgo,Jungfrau
 vol,Volans,Fliegender Fisch
-vul,Vulpecula,Fuchs
+vul,Vulpecula,Fuchs

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/de/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),E (Abkürzung für Osten)
 S (abbreviation for south),S (Abkürzung für Süden)
 W (abbreviation for west),W (Abkürzung für Westen)
 Milky Way,Milchstraße
+Horizon,Horizont

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/en-us/other_terms.csv

@@ -43,4 +43,5 @@ N (abbreviation for north),N (abbreviation for north)
 E (abbreviation for east),E (abbreviation for east)
 S (abbreviation for south),S (abbreviation for south)
 W (abbreviation for west),W (abbreviation for west)
-Milky Way,Milky Way
+Milky Way,Milky Way
+Horizon,horizon

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/es/other_terms.csv

@@ -43,4 +43,5 @@ N (abbreviation for north),N (abreviatura para norte)
 E (abbreviation for east),E (abreviatura para este)
 S (abbreviation for south),S (abreviatura para sur)
 W (abbreviation for west),O (abreviatura para oeste)
-Milky Way,Vía Láctea
+Milky Way,Vía Láctea
+Horizon,horizonte

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/fa/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),ق
 S (abbreviation for south),ج
 W (abbreviation for west),غ
 Milky Way,کهکشان راه شیری
+Horizon,افق

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/fr/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),E
 S (abbreviation for south),S
 W (abbreviation for west),O
 Milky Way,Voie lactée
+Horizon,horizon

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/it/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),E
 S (abbreviation for south),S
 W (abbreviation for west),O
 Milky Way,Via Lattea
+Horizon,orizzonte

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/lt/constellation_names.csv

@@ -65,7 +65,7 @@ per,Perseus,Persėjas
 phe,Phoenix,Feniksas
 pic,Pictor,Dailidė
 psa,Piscis Austrinus,Pietų Žuvis
-psc,Pisces,Žuvys 
+psc,Pisces,Žuvys
 pup,Puppis,Laivagalis
 pyx,Pyxis,Kompasas
 ret,Reticulum,Tinklas

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/lt/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),R
 S (abbreviation for south),P
 W (abbreviation for west),V
 Milky Way,Paukščių Takas
+Horizon,horizontas

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/nl/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),O
 S (abbreviation for south),Z
 W (abbreviation for west),W
 Milky Way,Melkweg
+Horizon,horizon

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/readme.md

@@ -29,7 +29,7 @@ Please follow these steps in a pull request to submit a new translation:
     - `star_names.csv`
 3. Add the ISO-639-1 code to:
     - `LANGUAGES` list [here](https://github.com/steveberardi/starplot/blob/main/src/starplot/data/translations.py)
-    - Doc-string for `Settings.language` [here](https://github.com/steveberardi/starplot/blob/main/src/starplot/config.py)
+    - Doc-string for `Settings.language` [here](https://github.com/steveberardi/starplot/blob/main/src/starplot/settings.py)
 4. Copy the values from `other_terms.csv` to the `LABELS` dictionary [here](https://github.com/steveberardi/starplot/blob/main/src/starplot/data/translations.py)
 5. Include a `readme.md` file in the data folder that explains the source of the translation (e.g. a well known astronomy book in the language, astronomical society, etc) - [see example here](https://github.com/steveberardi/starplot/blob/main/data/raw/translations/it/readme.md)
 6. Add test cases for the translation in [test_languages.py](https://github.com/steveberardi/starplot/blob/main/tests/test_languages.py)

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/zh-cn/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),东
 S (abbreviation for south),南
 W (abbreviation for west),西
 Milky Way,银河
+Horizon,地平线

{starplot-0.21.4 → starplot-0.23.0}/data/raw/translations/zh-tw/other_terms.csv

@@ -44,3 +44,4 @@ E (abbreviation for east),東
 S (abbreviation for south),南
 W (abbreviation for west),西
 Milky Way,銀河
+Horizon,地平線

{starplot-0.21.4 → starplot-0.23.0}/docs/changelog.md

@@ -1,5 +1,33 @@
+## v0.23.x
+[Documentation](https://archives.starplot.dev/0.23.0/)
+
+- Adds an `image` overlay plotting function to map, horizon, and optic plots
+- Normalizes sizing of circle-based markers
+- Adds support for defining `where_*` kwargs as string SQL `WHERE` clauses
+- Improved smoothing in the `ellipse` function
+- Updates default DSO catalog to fix a bug with galaxy geometries
+- **Breaking:** Restructures some `PlotStyle` fields:
+    - `bayer_labels` and `flamsteed_labels` are now `star.bayer_label` and `star.flamsteed_label`
+    - `constellation_lines`, `constellation_labels`, and `constellation_borders` are now `constellation.line`, `constellation.label`, and `constellation.border`
+    - `planets` is now `planet`
+
+---
+
+## v0.22.x
+[Documentation](https://archives.starplot.dev/0.22.0/)
+
+- Adds support for "naked eye" optic plots, increasing FOV limit to 60 degrees
+- Adds support for plotting constellations, gridlines, and horizon on optic plots
+- Updates default catalog for Milky Way
+- Adds missing German translation for Pisces
+- Fixes bug with grouping star label SVG elements
+- Adds a double border circle marker
+- Drops official support for Python 3.10 (EOL)
+
+---
+
 ## v0.21.x
-[Migration Guide](migration-guides/0.21.0.md)
+[Documentation](https://archives.starplot.dev/0.21.4/) | [Migration Guide](migration-guides/0.21.0.md)
 
 - Replaces the plotting backend (matplotlib + cartopy) with an SVG-first backend
 - Adds support for gradient backgrounds on markers, polygons, and the figure background

{starplot-0.21.4 → starplot-0.23.0}/docs/coming-soon.md

@@ -8,18 +8,19 @@
 
 <table class="table-coming-soon">
     <tr>
-        <td>v0.22</td>
+        <td>v0.24</td>
         <td>
             <h4>⭐ Next Release ⭐</h4>
             <ul>
                 <li>Plot definition files</li>
                 <li>CLI for creating plots</li>
+                <li>Improved labeling pipeline</li>
             </ul>
         </td>
         <td></td>
     </tr>
     <tr>
-        <td>v0.23+</td>
+        <td>v0.25+</td>
         <td>
             <ul>
                 <li>Planet moons</li>

starplot-0.23.0/docs/examples/optic-image-overlay.md

@@ -0,0 +1,14 @@
+---
+title: Image Overlay on an Optic Plot
+---
+[:octicons-arrow-left-24: Back to Examples](../examples.md)
+
+# Image Overlay on an Optic Plot {.example-header}
+
+![optic-image-overlay](../images/examples/optic_image_overlay.png)
+
+Here's an example of plotting an image of the Andromeda Galaxy (M31) on an optic plot. The image is aligned to the sky using control points, which map pixel positions in the image with the known RA/DEC of the stars at those positions. You can use a plate solver like [tetra3rs](https://tetra3rs.dev/) to find these control points automatically.
+
+```python
+--8<-- "examples/optic_image_overlay.py"
+```

{starplot-0.21.4 → starplot-0.23.0}/docs/examples.md

@@ -68,15 +68,15 @@
         </a>
     </li>
     <li>
-        <a href="examples/map-milky-way-stars/">
-            <img src="images/examples/map_milky_way_stars-sm.png" alt="Stars of the Milky Way" class="off-glb">
-            <p class="example-card-title">The Milky Way</p>
+        <a href="examples/optic-image-overlay/">
+            <img src="images/examples/optic_image_overlay-sm.png" alt="Image Overlay on an Optic Plot of the Andromeda Galaxy" class="off-glb" loading="lazy"/>
+            <p class="example-card-title">Image Overlay on an Optic Plot</p>
         </a>
     </li>
     <li>
-        <a href="examples/map-big-dipper/">
-            <img src="images/examples/map_big_dipper-sm.png" alt="Map of the Big Dipper" class="off-glb" loading="lazy"/>
-            <p class="example-card-title">The Big Dipper</p>
+        <a href="examples/map-milky-way-stars/">
+            <img src="images/examples/map_milky_way_stars-sm.png" alt="Stars of the Milky Way" class="off-glb">
+            <p class="example-card-title">The Milky Way</p>
         </a>
     </li>
     <li>
@@ -103,6 +103,12 @@
             <p class="example-card-title">Orthographic Map</p>
         </a>
     </li>
+    <li>
+        <a href="examples/map-big-dipper/">
+            <img src="images/examples/map_big_dipper-sm.png" alt="Map of the Big Dipper" class="off-glb" loading="lazy"/>
+            <p class="example-card-title">The Big Dipper</p>
+        </a>
+    </li>
     <li>
         <a href="examples/map-canis-major/">
             <img src="images/examples/map_canis_major-sm.png" alt="Map of the Constellation Canis Major" class="off-glb" loading="lazy"/>

{starplot-0.21.4 → starplot-0.23.0}/docs/index.md

@@ -12,7 +12,7 @@ Starplot is a Python library for creating star charts and maps of the sky
 - <img src="images/examples/map_orion.png" width="600"> <h3>__Maps__</h3> shows an area that you define in one of many available map projections
 - <img src="images/examples/horizon_gradient.png" width="600"> <h3>Horizon Charts</h3> shows the horizon at a specific time and place
 - <img src="images/examples/star_chart_basic.png" height="600" width="600"> <h3>Zenith Charts</h3> shows the entire sky at a specific time and place
-- <img src="images/examples/optic_m45.png" width="600"> <h3>Optic Charts</h3> shows what you'll see through an optic (e.g. telescope) at a specific time and place
+- <img src="images/examples/optic_image_overlay.png" width="600"> <h3>Optic Charts</h3> shows what you'll see through an optic (e.g. telescope) at a specific time and place
 - <img src="images/examples/galaxy.png" height="600" width="600"> <h3>Galaxy Charts</h3> shows the entire sky in galactic coordinates
 
 - <a href="examples/">
@@ -33,7 +33,8 @@ Starplot is a Python library for creating star charts and maps of the sky
     <li><strong>Planets and Deep Sky Objects (DSOs)</strong> - with support for plotting their true extent</li>
     <li><strong>Comets and Satellites</strong> - easy trajectory plotting</li>
     <li><strong>Custom Styles</strong> - for all objects and with 8+ built-in themes</li>
-    <li><strong>Export to SVG or PNG</strong></li>
+    <li><strong>Export to SVG or PNG</strong> - with easy scaling for png exports</li>
+    <li><strong>Image overlays</strong> - given a set of control points</li>
     <li><strong>Data Backend</strong> - powered by DuckDB + Ibis for fast object lookup</li>
     <li><strong>Custom Data Catalogs</strong> - with helpers for building and optimizing</li>
     <li><strong>Label Collision Avoidance</strong> - ensuring all labels are readable</li>

{starplot-0.21.4 → starplot-0.23.0}/docs/installation.md

@@ -2,7 +2,7 @@
 
 Starplot is available on [PyPI](https://pypi.org/project/starplot/) and [Conda](https://anaconda.org/channels/conda-forge/packages/starplot/overview), and its dependencies have binary wheels for most operating systems, so installation should be easy. See below for details.
 
-Supported Python versions: 3.10 / 3.11 / 3.12 / 3.13 / 3.14
+Supported Python versions: 3.11 / 3.12 / 3.13 / 3.14
 
 <h3>1. Install Dependencies</h3>
 

{starplot-0.21.4 → starplot-0.23.0}/docs/models/index.md

@@ -49,6 +49,7 @@ Starplot has models to represent an observer and some of the objects you can plo
 ### :material-telescope: Optics
 
 - [Binoculars](optics.md#starplot.models.Binoculars)
+- [NakedEye](optics.md#starplot.models.NakedEye)
 - [Scope](optics.md#starplot.models.Scope)
 - [Refractor](optics.md#starplot.models.Refractor)
 - [Reflector](optics.md#starplot.models.Reflector)

{starplot-0.21.4 → starplot-0.23.0}/docs/models/optics.md

@@ -10,6 +10,14 @@ Optics are another set of models you instantiate directly when creating [OpticPl
         show_root_heading: true
         heading_level: 2
 
+::: starplot.models.NakedEye
+    options:
+        inherited_members: true
+        show_docstring_attributes: true
+        merge_init_into_class: true
+        show_root_heading: true
+        heading_level: 2
+
 ::: starplot.models.Scope
     options:
         inherited_members: true

{starplot-0.21.4 → starplot-0.23.0}/docs/reference-settings.md

@@ -29,6 +29,20 @@ STARPLOT_LANGUAGE=fr
 ```
 </div>
 
+## Temporary overrides
+
+To change settings for just part of your code, call `settings` in a `with` block. The previous values are restored when the block exits:
+
+```python
+from starplot import settings
+
+with settings(language="de", svg_text_type="path"):
+    # Plots created here will use German labels and SVG text as paths
+    ...
+
+# Back to the previous settings here
+```
+
 ---
 
 ## `data_path`
@@ -93,7 +107,7 @@ Number of decimal places to round coordinates and dimensions to when rendering S
 
 
 <!-- 
-::: starplot.config.Settings
+::: starplot.settings.Settings
     options:
         show_docstring_attributes: true
         separate_signature: true

{starplot-0.21.4 → starplot-0.23.0}/docs/scripts/markers.py

@@ -8,6 +8,7 @@ from typing import get_args
 from starplot import MapPlot, Miller
 from starplot.styles import MarkerStyle, ObjectStyle, PlotStyle, extensions
 from starplot.styles.types import MarkerSymbol
+from starplot.svg import symbols
 
 OUTPUT_DIR = Path(__file__).resolve().parent.parent / "images" / "reference"
 OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
@@ -50,15 +51,18 @@ marker_styles = {
     "star_4": default_style,
     "star_8": default_style,
     "triangle": default_style,
+    "circle_double_border": default_style,
 }
 
 
 for symbol_str in get_args(MarkerSymbol):
     marker_style = default_style
-    marker_style.size = 64
     marker_style.symbol = symbol_str
     marker_style.stroke_width = default_style.stroke_width
 
+    # size is the diameter of the circle for circle-based symbols, so scale it down
+    # to fit the whole symbol in the same box as all the others
+    marker_style.size = 64 / max(symbols.extent(symbol_str, 1))
 
     object_style = ObjectStyle(marker=marker_style)
 

{starplot-0.21.4 → starplot-0.23.0}/docs/scripts/style_explorer.py

@@ -29,8 +29,8 @@ OUTPUT_PATH = REPO_ROOT / "docs" / "images" / "reference" / "style_explorer.html
 # Groups of PlotStyle's own properties, in the order they should appear.
 GROUPS = [
     ("Layout", ["base", "axes", "figure", "title", "table", "legend"]),
-    ("Stars", ["star", "bayer_labels", "flamsteed_labels"]),
-    ("Solar System", ["planets", "moon", "sun"]),
+    ("Stars", ["star"]),
+    ("Solar System", ["planet", "moon", "sun"]),
     (
         "Deep Sky Objects",
         [
@@ -49,10 +49,7 @@ GROUPS = [
             "dso_duplicate",
         ],
     ),
-    (
-        "Constellations",
-        ["constellation_lines", "constellation_borders", "constellation_labels"],
-    ),
+    ("Constellations", ["constellation"]),
     (
         "Sky Features",
         [
@@ -69,8 +66,17 @@ GROUPS = [
         ],
     ),
     (
-        "Generic Shapes",
-        ["line", "polygon", "circle", "ellipse", "rectangle", "marker", "text"],
+        "Plotting Functions",
+        [
+            "line",
+            "polygon",
+            "circle",
+            "ellipse",
+            "rectangle",
+            "marker",
+            "text",
+            "image",
+        ],
     ),
 ]
 

{starplot-0.21.4 → starplot-0.23.0}/docs/styling/index.md

@@ -84,9 +84,11 @@ from starplot import PlotStyle
 
 style = PlotStyle().extend(
     {
-        "bayer_labels": {
-            "font_name": "Literata",
-            "font_size": 10
+        "star": {
+            "bayer_label": {
+                "font_name": "Literata",
+                "font_size": 10
+            }
         }
     }
 )
@@ -94,8 +96,8 @@ style = PlotStyle().extend(
 Alternatively, you can do this:
 ```python
 style = PlotStyle()
-style.bayer_labels.font_name = "Literata"
-style.bayer_labels.font_size = 10
+style.star.bayer_label.font_name = "Literata"
+style.star.bayer_label.font_size = 10
 
 ```
 

{starplot-0.21.4 → starplot-0.23.0}/docs/styling/markers.md

@@ -2,6 +2,8 @@
 
 Below are previews of all marker symbols available in Starplot. Many aspects of the symbol can be customized through its style, including fill color, edge color, edge thickness, edge style (solid, dotted, dashed, etc), opacity, and much more. See [`MarkerStyle`][starplot.MarkerStyle] for details.
 
+Most symbols fit inside a square with sides equal to the marker's `size`. The exceptions are `circle_line`, `circle_crosshair`, and `circle_double_border`: for these symbols, `size` is the diameter of the circle, so they're the same size as a `circle` marker with the same `size` (and the rest of the symbol extends outside of that circle).
+
 <div class="marker-symbol-grid" markdown>
 
 <div class="marker-symbol-card" markdown>
@@ -88,6 +90,12 @@ Below are previews of all marker symbols available in Starplot. Many aspects of
 `satellite`{: .marker-symbol-name}
 </div>
 
+<div class="marker-symbol-card" markdown>
+![Circle Double Border](../images/reference/marker_circle_double_border.svg){ loading=lazy .marker-symbol-img}
+
+`circle_double_border`{: .marker-symbol-name}
+</div>
+
 </div>
 
 

{starplot-0.21.4 → starplot-0.23.0}/docs/styling/reference.md

@@ -34,6 +34,16 @@
         show_root_heading: true
         show_docstring_attributes: true
 
+::: starplot.styles.StarStyle
+    options:
+        show_root_heading: true
+        show_docstring_attributes: true
+
+::: starplot.styles.ConstellationStyle
+    options:
+        show_root_heading: true
+        show_docstring_attributes: true
+
 ::: starplot.styles.PathStyle
     options:
         show_root_heading: true
@@ -70,6 +80,11 @@
         show_docstring_attributes: true
         inherited_members: true
 
+::: starplot.styles.ImageStyle
+    options:
+        show_root_heading: true
+        show_docstring_attributes: true
+
 ::: starplot.styles.TitleStyle
     options:
         show_root_heading: true

{starplot-0.21.4 → starplot-0.23.0}/examples/examples.py

@@ -31,7 +31,7 @@ def get_example_names():
     filenames = []
 
     for filename in glob.iglob("*.py"):
-        # if filename not in ["map_virgo_cluster.py"]:
+        # if filename not in ["optic_image_overlay.py"]:
         #     continue
 
         if filename.endswith("examples.py"):

{starplot-0.21.4 → starplot-0.23.0}/examples/horizon_gradient.py

@@ -10,7 +10,7 @@ style = PlotStyle().extend(
     extensions.GRADIENT_PRE_DAWN,
 )
 style.figure.padding = 40
-style.constellation_lines.width = 4
+style.constellation.line.width = 4
 style.star.marker.stroke_width = 0
 
 dt = datetime(2025, 8, 20, 21, 0, 0, 0, tzinfo=ZoneInfo("Pacific/Honolulu"))

{starplot-0.21.4 → starplot-0.23.0}/examples/map_canis_major.py

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

starplot-0.23.0/examples/optic_image_overlay.py

@@ -0,0 +1,97 @@
+from datetime import datetime
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from starplot import DSO, Observer, OpticPlot, Scope, callables, _
+from starplot.styles import PlotStyle, extensions
+
+
+IMAGE = Path(__file__).parent / "andromeda.jpeg"
+IMAGE_SIZE = (1200, 1200)
+
+# Control points that match a pixel position in the image with
+# its sky position: ((x, y), (ra, dec)) in degrees.
+CONTROL_POINTS = [
+    ((231.9, 870.0), (10.5060, 40.6883)),  # HIP 3293
+    ((113.8, 533.3), (11.1549, 40.6794)),  # HIP 3494
+    ((141.9, 316.8), (11.5135, 40.8089)),  # HIP 3597
+    ((132.2, 576.7), (11.0697, 40.6852)),  # HIP 3461
+    ((751.0, 404.0), (11.0162, 41.5709)),  # HIP 3447
+    ((421.1, 281.7), (11.4187, 41.1902)),  # TYC 2801-1743-1
+    ((543.3, 368.3), (11.1977, 41.3136)),  # TYC 2805-117-1
+    ((400.3, 638.7), (10.8089, 41.0094)),  # TYC 2801-2078-1
+    ((426.8, 41.7), (11.8345, 41.2989)),  # TYC 2805-39-1
+    ((1083.7, 503.7), (10.6477, 41.9630)),  # TYC 2805-695-1
+    ((1073.0, 280.3), (11.0473, 42.0458)),  # TYC 2805-1072-1
+    ((392.6, 744.0), (10.6292, 40.9537)),  # HIP 3333
+    ((993.9, 765.0), (10.2416, 41.7309)),  # HIP 3223
+    ((900.8, 560.2), (10.6563, 41.6994)),  # TYC 2805-789-1
+    ((1130.1, 761.1), (10.1676, 41.9105)),  # TYC 2805-1240-1
+    ((643.1, 152.1), (11.5197, 41.5368)),  # TYC 2805-700-1
+]
+
+# custom gradient background
+NIGHT_SUBTLE = (
+    (0.0, "hsl(240, 14%, 10%)"),
+    (0.25, "hsl(240, 14%, 5%)"),
+    (0.6, "hsl(240, 14%, 2%)"),
+    (1.0, "#000000"),
+)
+
+m31 = DSO.get(m="31")
+
+observer = Observer(
+    dt=datetime(2026, 10, 13, 21, 0, 0, tzinfo=ZoneInfo("US/Pacific")),
+    lat=33.363484,
+    lon=-116.836394,
+)
+
+style = PlotStyle().extend(
+    extensions.GRAYSCALE_DARK,
+    extensions.OPTIC,
+    {
+        "axes": {
+            "background": {"fill": {"stops": NIGHT_SUBTLE, "type": "radial"}},
+            "border": {
+                "stroke": "#3A3A3A",
+                "width": 32,
+            },
+        }
+    },
+    extensions.FIGURE_TRANSPARENT,
+)
+
+# outline the galaxies instead of filling them, so the photo shows through
+style.dso_galaxy.marker.fill = None
+style.dso_galaxy.marker.stroke = "#86c7f2"
+style.dso_galaxy.marker.stroke_width = 5
+style.dso_galaxy.marker.opacity = 1
+
+style.dso_galaxy.label.font_size = 72
+style.dso_galaxy.label.font_weight = 700
+
+p = OpticPlot(
+    ra=m31.ra,
+    dec=m31.dec,
+    optic=Scope(focal_length=714, eyepiece_focal_length=28, eyepiece_fov=82),
+    observer=observer,
+    resolution=2800,
+    scale=0.9,
+    style=style,
+)
+
+p.image(IMAGE, CONTROL_POINTS)
+
+p.stars(
+    where=[_.magnitude < 12],
+    color_fn=callables.color_by_bv_gradient,
+    style__marker__stroke=None,
+)
+
+# plot Andromeda (M31) and its satellite galaxies (M32, M110)
+p.dsos(
+    where=[_.m.isin([31, 32, 110])],
+    where_true_size=True,
+)
+
+p.export("optic_image_overlay.png")