v0.13.0 (#120)

.github/workflows/test.yml

@@ -49,3 +49,10 @@ jobs:
     - uses: actions/checkout@v4
     - name: Run Tests - Python 3.12
       run: make test-3.12 CI=true
+  # Python 3.13 not supported yet, needs investigation!
+  # test-python-3-13:
+  #   runs-on: ubuntu-22.04
+  #   steps:
+  #   - uses: actions/checkout@v4
+  #   - name: Run Tests - Python 3.13
+  #     run: make test-3.13 CI=true

.gitignore

@@ -20,6 +20,7 @@ hash_checks/results.html
 temp.py
 temp/
 raw/
+scripts/temp/
 
 # Documentation Generated Files
 examples/*.png

Dockerfile

@@ -1,17 +1,11 @@
-ARG PYTHON_VERSION=3.11.7
+ARG PYTHON_VERSION=3.11.11
 FROM python:${PYTHON_VERSION}-bookworm AS base
 
 WORKDIR /starplot
 
+# Install required system libraries (GEOS + GDAL)
 RUN apt-get clean && apt-get update -y && apt-get install -y libgeos-dev libgdal-dev
 
-# Install fonts
-# not required, but make the maps look better (especially greek letters)
-RUN mkdir -p /usr/share/fonts/truetype
-RUN wget https://github.com/google/fonts/raw/main/ofl/gfsdidot/GFSDidot-Regular.ttf -P /tmp/fonts
-RUN install -m644 /tmp/fonts/*.ttf /usr/share/fonts/truetype/
-RUN fc-cache -f
-
 # ---------------------------------------------------------------------
 FROM base as dev
 

Makefile

@@ -22,7 +22,7 @@ DOCKER_RUN_PYTHON_TEST=docker run --rm $(DR_ARGS) -v $(shell pwd):/starplot star
 export PYTHONPATH=./src/
 
 # ------------------------------------------------------------------
-build: PYTHON_VERSION=3.11.7
+build: PYTHON_VERSION=3.11.11
 build: DOCKER_BUILD_ARGS=-t starplot-dev
 build:
 	touch -a .env
@@ -82,26 +82,32 @@ version:
 # ------------------------------------------------------------------
 # Python version testing
 # ------------------------------------------------------------------
-test-3.9: PYTHON_VERSION=3.9.18
+test-3.9: PYTHON_VERSION=3.9.21
 test-3.9:
 	$(DOCKER_BUILD_PYTHON)
 	$(DOCKER_RUN_PYTHON_TEST)
 
-test-3.10: PYTHON_VERSION=3.10.13
+test-3.10: PYTHON_VERSION=3.10.16
 test-3.10:
 	$(DOCKER_BUILD_PYTHON)
 	$(DOCKER_RUN_PYTHON_TEST)
 
-test-3.11: PYTHON_VERSION=3.11.7
+test-3.11: PYTHON_VERSION=3.11.11
 test-3.11:
 	$(DOCKER_BUILD_PYTHON)
 	$(DOCKER_RUN_PYTHON_TEST)
 
-test-3.12: PYTHON_VERSION=3.12.1
+test-3.12: PYTHON_VERSION=3.12.8
 test-3.12:
 	$(DOCKER_BUILD_PYTHON)
 	$(DOCKER_RUN_PYTHON_TEST)
 
+# Python 3.13 not supported yet!
+test-3.13: PYTHON_VERSION=3.13.1
+test-3.13:
+	$(DOCKER_BUILD_PYTHON)
+	$(DOCKER_RUN_PYTHON_TEST)
+
 # ------------------------------------------------------------------
 # Docs
 docs-serve: DR_ARGS=-it -p 8000:8000
@@ -134,6 +140,9 @@ hip8:
 scripts:
 	$(DOCKER_RUN) "python ./scripts/$(SCRIPT).py"
 
+allsky:
+	$(DOCKER_RUN) "python ./scripts/temp/allsky.py"
+
 clean:
 	rm -rf __pycache__
 	rm -rf venv

README.md

@@ -6,7 +6,7 @@
 
 **Starplot** is a Python library for creating star charts and maps of the sky.
 
-- ⭐ **Zenith Plots** - showing the stars from a specific time/location
+- ⭐ **Zenith Plots** - showing the whole sky from a specific time/location
 - 🗺️ **Map Plots** - including many map projections
 - 🔭 **Optic Plots** - simulates what you'll see through an optic (e.g. binoculars, telescope) from a time/location
 - 🪐 **Planets and Deep Sky Objects (DSOs)**
@@ -21,7 +21,7 @@
 *Map around the constellation Orion:*
 ![map-orion](https://starplot.dev/images/examples/map_orion.png)
 
-*Optic plot of The Pleiades through a refractor as seen from a specific time/location:*
+*The Pleiades star cluster, as seen through a refractor telescope from a specific time and location:*
 ![optic-pleiades](https://starplot.dev/images/examples/optic_m45.png)
 
 ## Basic Usage
@@ -42,9 +42,9 @@ p = sp.MapPlot(
     dt=datetime.now(tz).replace(hour=22),
     style=sp.styles.PlotStyle().extend(
         sp.styles.extensions.BLUE_MEDIUM,
-        sp.styles.extensions.ZENITH,
     ),
-    resolution=2000,
+    resolution=3200,
+    autoscale=True,
 )
 p.constellations()
 p.stars(mag=4.6)
@@ -72,12 +72,11 @@ https://discord.gg/WewJJjshFu
 Contributing to Starplot is welcome and very much appreciated! Please see [here](CONTRIBUTING.md) for details.
 
 ## Coming Soon
+- 🌄 Horizon plots
 - 🌑 Planet moons
 - ✴️ Custom markers
-- 🚀 Plotting Optimizations
 - ☄️ Comet model
-- 🌄 Horizon plots
-- ⚖️ Better auto font-size adjustment
+- 💫 Better constellation label placement
 - 😄 🔭 Clear skies
 
 See more details on the [Public Roadmap](https://trello.com/b/sUksygn4/starplot-roadmap)

docs/about.md

@@ -1,6 +1,10 @@
 ![Starplot](images/favicon.svg){ align=right width="128" .off-glb }
 
-**Starplot** is a Python library for creating star charts and maps. It lets you create zenith plots that show the whole sky from a time/place, map plots that show more detail of an area, and optic plots that simulate the field of view from a particular optic (e.g. telescope, binoculars, or a camera).
+**Starplot** is a Python library for creating star charts and maps of the sky. It lets you create zenith plots that show the whole sky from a time/place, map plots that show more detail of an area, and optic plots that simulate the field of view from a particular optic (e.g. telescope, binoculars, or a camera).
+
+👷 **Work In Progress** 🚧 Starplot is still very much a work in progress, and under active development. We try to follow [semantic versioning](https://semver.org/), which means that [_anything_ can change between versions before `1.0.0`](https://semver.org/#spec-item-4).
+
+However, the Starplot API becomes more stable with each new version. We anticipate that version `1.0.0` is still at least a year away. The best way to help us get there faster is to [join as a contributor](https://github.com/steveberardi/starplot/blob/main/CONTRIBUTING.md) 😃 help is wanted and very much appreciated!
 
 Join other starplotters on [Discord :fontawesome-brands-discord:{ .fg-primary }](https://discord.gg/WewJJjshFu)
 

docs/changelog.md

@@ -1,4 +1,17 @@
+## v0.13.x
+
+- Adds a `scale` factor to control sizing of all objects/text
+- Adds an "auto" option for label offsets from markers
+- Adds constellation lines to label collision detection
+- Adds a `gid` to plotted objects to make exported SVGs easier to work with in external applications (e.g. Inkscape)
+- Adds Flamsteed numbers to stars
+- Adds all star names from IAU
+- Adds the standard symbol for planetary nebulae
+- Adds a border size/color property to label styles
+- Bundles fonts: Inter & GFS Didot
+
 ## v0.12.x
+[Documentation](https://archives.starplot.dev/0.12.5/)
 
 - Adds Shapely geometry to all sky object models, including support for `intersects` in `where` clauses
 - Adds kwarg to map plots to allow custom clip paths

docs/coming-soon.md

@@ -1,10 +1,9 @@
 
+- 🌄 Horizon plots
 - 🌑 Planet moons
 - ☄️ Comet model
-- 🌄 Horizon plots
 - ✴️ Custom markers
-- 🚀 Plotting Optimizations
-- ⚖️ Better auto font-size adjustment
+- 💫 Better constellation label placement
 - 😄 🔭 Clear skies
 
 <br/>

docs/examples/map-canis-major.md

@@ -7,6 +7,8 @@ title: Map of Canis Major
 
 ![map-canis-major](/images/examples/map_canis_major.png)
 
+In this example, we set the plot's `clip_path` to the boundary of Canis Major, so only objects in that constellation are plotted:
+
 ```python
 --8<-- "examples/map_canis_major.py"
 ```

docs/examples/map-orion.md

@@ -7,7 +7,7 @@ title: Map of Orion
 
 ![map-orion](/images/examples/map_orion.png)
 
-The following code will create a simple map plot that shows the area around the constellation Orion, including a legend and an ellipse around [Orion's Belt](https://en.wikipedia.org/wiki/Orion%27s_Belt):
+The following code will create a simple map plot that shows the area around the constellation [Orion](https://en.wikipedia.org/wiki/Orion_(constellation)):
 
 ```python
 --8<-- "examples/map_orion.py"

docs/index.md

@@ -28,6 +28,7 @@ Starplot is a Python library for creating star charts and maps of the sky.
 
 Join other starplotters on [Discord :fontawesome-brands-discord:{ .fg-primary }](https://discord.gg/WewJJjshFu)
 
+
 *Example charts and maps created with Starplot:*
 <!-- {.text-subtitle} -->
 
@@ -38,7 +39,7 @@ Join other starplotters on [Discord :fontawesome-brands-discord:{ .fg-primary }]
 
 <figure markdown>
   <img src="images/examples/map_orion.png" width="900">
-  <figcaption>Map around the constellation Orion, with an ellipse around Orion's Belt (<a href="/examples/map-orion/">source code</a>)</figcaption>
+  <figcaption>Map around the constellation Orion (<a href="/examples/map-orion/">source code</a>)</figcaption>
 </figure>
 
 

docs/installation.md

@@ -28,6 +28,19 @@ apt-get install libgeos-dev libgdal-dev
 pip install starplot
 ```
 
+## Docker
+
+Here's a basic Docker container definition that'll get you up and running:
+
+```docker
+FROM python:3.11.11-bookworm
+
+# Install required system libraries (GEOS + GDAL)
+RUN apt-get clean && apt-get update -y && apt-get install -y libgeos-dev libgdal-dev
+
+RUN pip install starplot
+```
+
 !!! star "What about Windows?"
 
     I haven't tried installing Starplot on Windows, but if you have and would like to share instructions, please feel free to [open a pull request on GitHub](https://github.com/steveberardi/starplot) with an update to this file (`docs/installation.md`). Thanks! :)

docs/reference-styling.md

@@ -83,7 +83,7 @@ from starplot import PlotStyle
 style = PlotStyle().extend(
     {
         "bayer_labels": {
-            "font_name": "GFS Didot",
+            "font_name": "Literata",
             "font_size": 10
         }
     }
@@ -92,7 +92,7 @@ style = PlotStyle().extend(
 Alternatively, you can do this:
 ```python
 style = PlotStyle()
-style.bayer_labels.font_name = "GFS Didot"
+style.bayer_labels.font_name = "Literata"
 style.bayer_labels.font_size = 10
 
 ```
@@ -152,8 +152,8 @@ Starplot has a bunch of built-in style extensions (all imported from `starplot.s
     - `GRAYSCALE` - Optimized for printing in grayscale ([details](#extensions-grayscale))
     - `GRAYSCALE_DARK` - Like `GRAYSCALE`, but inverted (white stars, black background) ([details](#extensions-grayscale-dark))
     - `BLUE_LIGHT` - Light and bright colors ([details](#extensions-blue-light))
-    - `BLUE_MEDIUM` - Medium brightness bluish gray colors ([details](#extensions-blue-medium))
-    - `BLUE_DARK` - Dark "Starplot blue" colors ([details](#extensions-blue-dark))
+    - `BLUE_MEDIUM` - Medium brightness blue colors ([details](#extensions-blue-medium))
+    - `BLUE_DARK` - Dark blue and contrasting colors ([details](#extensions-blue-dark))
     - `ANTIQUE` - Antique map inspired colors ([details](#extensions-antique))
     - `NORD` - Nord-inspired colors ([details](#extensions-nord))
 - **Plot types**

docs/tutorial.md

@@ -15,7 +15,7 @@ Here's an overview of what the tutorial covers:
 8. [Using callables](tutorial/08.md)
 9. [Where to go from here](tutorial/09.md)
 
-Estimated time to complete: 1 hour
+Estimated time to complete: 30 minutes
 
 <br/>
 

docs/tutorial/02.md

@@ -37,8 +37,9 @@ On line 8, we create a [`MapPlot`][starplot.MapPlot] instance that specifies a f
 - `lat`/`lon`: Observing location
 - `dt`: Observing date/time
 - `resolution`: Resolution (in pixels) of the widest dimension of the plot
+- `scale`: This controls the sizing of all text and markers. At scale `1.0` everything is optimized for a basic map of 1-3 constellations, so if you're plotting a larger area (or just want everything smaller), then it's a good idea to decrease the scale so the plot isn't too crowded.
 
-When you create a plot instance, initially it'll be empty (i.e. it won't have any stars). In Starplot, you have to explicitly plot all objects. So, on line 15 we plot the constellations, which includes lines and labels. Then, we plot stars with a limiting magnitude of 4.6.
+When you create a plot instance, initially it'll be empty (i.e. it won't have any stars). In Starplot, you have to explicitly plot all objects. So, on line 16 we plot the constellations, which includes lines and labels. Then, we plot stars with a limiting magnitude of 4.6.
 
 Finally, we export the plot to a PNG file.
 

docs/tutorial/05.md

@@ -22,15 +22,15 @@ For example, here's how you'd create an optic plot of the Beehive Star Cluster (
 
 The first 13 lines should look familiar from the other plots we've created in this tutorial.
 
-Line 15 is where we create the instance of an `OpticPlot`. Most of the kwargs are the same as the map plot's kwargs, except for the following: 
+Line 14 is where we create the instance of an `OpticPlot`. Most of the kwargs are the same as the map plot's kwargs, except for the following: 
 
 - `ra`: Right ascension of the target
 - `dec`: Declination of the target
 - `optic`: An instance of an [optic](/reference-opticplot/#starplot.optics.Optic). This example uses binoculars, but Starplot also supports refractor/reflector telescopes, generic scopes, and cameras.
 
 The `ra`/`dec` you specify for the target will be the center of the plot.
 
-On line 31, we plot stars down to magnitude 14, but we also specify the [star catalog](/reference-data/#starplot.data.stars.StarCatalog) to use. By default, Starplot uses the Hipparcos catalog, but it also has the [Big Sky Catalog](https://github.com/steveberardi/bigsky) built-in which has many more stars.
+On line 31, we plot stars down to magnitude 12, but we also specify the [star catalog](/reference-data/#starplot.data.stars.StarCatalog) to use. By default, Starplot uses the Hipparcos catalog, but it also has the [Big Sky Catalog](https://github.com/steveberardi/bigsky) built-in which has many more stars.
 
 *In the [next section](06.md), we'll learn how to be more selective of objects to plot...*
 

docs/tutorial/06.md

@@ -20,7 +20,7 @@ p.stars(
     ],
 )
 ```
-When passing the `where` kwarg, the `mag` kwarg will be ignored, and only the stars/DSOs that satisfy ALL the `where` conditions will be plotted. You can reference any field on the model in expressions, and there are also a few functions available for determining if a field is null or is in a list of values. For complete details about selecting objects, see the [reference page](/reference-selecting-objects/).
+When passing the `where` kwarg, the `mag` kwarg will be ignored, and only the stars/DSOs that satisfy ALL the `where` conditions will be plotted. You can reference any field on the [model](/reference-models/) in expressions, and there are also a few functions available for determining if a field is null or is in a list of values. For complete details about selecting objects, see the [reference page](/reference-selecting-objects/).
 
 Here's some code that uses the `where` kwarg extensively to produce the image above:
 <div class="tutorial" markdown>

docs/tutorial/08.md

@@ -11,7 +11,7 @@ title: 8 - Using Callables
 
 [Callables](/reference-callables/) allow you to define your own functions for calculating a few of the style properties for stars: size, alpha (opacity),  color, and their labels. DSOs support callables for alpha and labels only. Starplot has a few basic callables built-in, but you can also create your own.
 
-Here's an example that uses the built-in callable `color_by_bv` to create an optic plot of [Antares](https://en.wikipedia.org/wiki/Antares) that colorizes the stars based on their B-V index (Antares B-V is 1.83 so it appears red/orange in the sky):
+Here's an example that uses the built-in callable `color_by_bv` to create an optic plot of [Antares](https://en.wikipedia.org/wiki/Antares) that colorizes the stars based on their B-V index (Antares' B-V is 1.83 so it appears red/orange in the sky):
 <div class="tutorial" markdown>
 ```python linenums="1"
 --8<-- "tutorial/tutorial_08.py"

examples/examples.py

@@ -5,10 +5,15 @@
 import time
 
 from PIL import Image
-from multiprocessing import Pool, Process
+from multiprocessing import Pool
 
 start = time.time()
 
+skip = [
+    # "map_milky_way_stars.py",
+    # "stuff.py",
+]
+
 
 def thumbnail(filename, max_dimension=900):
     print(filename)
@@ -23,16 +28,17 @@ def get_example_names():
     for filename in glob.iglob("*.py"):
         if filename.endswith("examples.py"):
             continue
+
+        if filename in skip:
+            continue
+
         filenames.append(filename)
 
     return filenames
 
 
 def run_example(filename):
-    import subprocess
-
     print(f"Running {filename}")
-
     subprocess.call(["python", filename])
 
 
@@ -42,16 +48,6 @@ def run_example(filename):
 with Pool(5) as pool:
     pool.map(run_example, example_files)
 
-# Run all examples
-# for filename in glob.iglob("*.py"):
-#     if filename.endswith("examples.py"):
-#         continue
-
-#     # if filename != "map_lyra.py":
-#     #     continue
-#     print(f"Running {filename}")
-#     subprocess.call(f"python {filename}", shell=True)
-
 # Create thumbnail images for the examples list page
 image_files = glob.glob("*.png")
 pool = Pool(5)