v0.8.0 (#45)

* new milky way outline

* docs

* dso sizing initial

* gallery about placeholders

* work in progress

* stash

* tycho geopack script

* ongc geopack script

* parse ongc csv

* some progress

* adjust

* ongc outlines

* return early if empty

* update hashes

* style adjustments and new example

* gallery

* version

* no zoom

* included by mistake

* handle wrapping

* mollweide

* handle dso wrapping

* handle wrapping in optic plots

* normalize legend marker size

* adjust right ascension

* format

* about page

Author: steveberardi

.gitignore

@@ -19,11 +19,12 @@ hip_main.dat
 hip8.dat
 
 temp*
+raw/
 
 *.prof
 
 # test-generated data
-tests/data/actual*.png
+tests/data/*.png
 
 # Distribution / packaging
 .Python

docs/about.md

@@ -0,0 +1,19 @@
+![Starplot](images/favicon.svg){ align=right width="200" }
+
+**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).
+
+---
+
+### _Note from the author..._
+
+Like many amateur astronomers, when I first started looking up at the sky through a scope I bought the wonderful book [_Turn Left at Orion_](https://www.amazon.com/Turn-Left-Orion-Hundreds-Telescope-dp-1108457568/dp/1108457568/), and it was such a useful book for learning how to find stuff in the sky. The thing that helped me the most were all the finder charts that show an object in various ways: first a general overview of where the object is in the sky (useful for finding the object with your naked eye), and then vector drawings of what the object looks like through a medium/high power scope (including any transformations to the image from mirrors in the scope). These really helped me confirm I found the object.
+
+After finding most of the sky objects in _Turn Left at Orion_, I tried finding another book or software that would create those finder charts in the book for any spot in the sky, but I couldn't find anything. That was my main motivation for creating Starplot.
+
+I also just really love any kind of map of the stars, including more abstract/artistic types of maps. So, one of my goals with Starplot is to make it customizable for many different purposes.
+
+Starplot is still very much a work in progress, so I appreciate any feedback! Please feel free to [contact me](https://steveberardi.com/contact/) or [open an issue](https://github.com/steveberardi/starplot/issues) on the GitHub repo.
+
+Thanks!
+
+[Steve Berardi](https://steveberardi.com)

docs/css/extra.css

@@ -101,4 +101,34 @@
 code.raw {
     display: block;
     white-space: pre-wrap   
-}
+}
+
+.cards ul li {
+    display: flex !important;
+    align-items: center;
+}
+.cards ul li img {
+    align-self: center;
+    /* object-fit: cover;
+    width: 360px;
+    height: 360px; */
+      
+}
+
+.cards figure {
+    display: flex !important;
+    justify-content:space-between;
+    flex-grow: 1;
+    flex-direction: column;
+    align-items: center;
+    border: 1px solid #c6c6c6;
+    margin-right: 1em;
+    padding: 0.6rem;
+}
+.cards figure p {
+    align-self: center;
+}
+
+.md-nav--integrated>.md-nav__list>.md-nav__item--active:not(.md-nav__item--nested) {
+    padding: 0 !important;
+}

docs/data-sources.md

@@ -16,4 +16,4 @@
 - [OpenNGC](https://github.com/mattiaverga/OpenNGC)
 
 ### **Milky Way Outline**
-- Milky Way Outline Catalog, Jose R. Vieira (via [d3-celestial](https://github.com/ofrohn/d3-celestial))
+- Created by Steve Berardi with QGIS + GDAL from NASA's [Deep Star Maps](https://svs.gsfc.nasa.gov/4851)

docs/examples.md

@@ -5,14 +5,15 @@ 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-plot-of-the-big-dipper-with-custom-markers)
 
 
 
 ## 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:
 
 ```python
-{% include 'examples/example_01.py' %}
+--8<-- "examples/example_01.py"
 ```
 
 The created file should look like this:
@@ -25,7 +26,7 @@ The created file should look like this:
 Building on the first example, you can also plot additional objects and even customize their style. Here's an example that plots the [Coma Star Cluster](https://en.wikipedia.org/wiki/Coma_Star_Cluster) (Melotte 111) as a red star and also changes the plot style to `GRAYSCALE`:
 
 ```python
-{% include 'examples/example_02.py' %}
+--8<-- "examples/example_02.py"
 ```
 
 ![zenith-coma](images/example_02.png)
@@ -36,7 +37,7 @@ Building on the first example, you can also plot additional objects and even cus
 The following code will create a simple map plot that shows the area around the constellation Orion, including a legend and an extra marker for M42 - [The Great Orion Nebula](https://en.wikipedia.org/wiki/Orion_Nebula):
 
 ```python
-{% include 'examples/example_03.py' %}
+--8<-- "examples/example_03.py"
 ```
 
 The result should look like this:
@@ -49,7 +50,7 @@ The result should look like this:
 The following code will create a minimal map plot that shows the field of view (red dashed circle) of [The Pleiades (M45)](https://en.wikipedia.org/wiki/Pleiades) when looking through a [Tele Vue 85](https://www.televue.com/engine/TV3b_page.asp?id=26) telescope with a 14mm eyepiece that has a 82 degree FOV:
 
 ```python
-{% include 'examples/example_04.py' %}
+--8<-- "examples/example_04.py"
 ```
 
 The result should look like this:
@@ -65,19 +66,30 @@ The result should look like this:
     ```
 
 
-## Optic plot of The Pleiades with a Refractor Telescope
+## Optic Plot of The Pleiades with a Refractor Telescope
 
 The following code will create an optic plot that shows what The Pleiades looked like through a refractor telescope on December 16, 2023 at 9pm PT from Palomar Mountain in California.
 
 ```python
-{% include 'examples/example_05.py' %}
+--8<-- "examples/example_05.py"
 ```
 
 The result should look like this:
 
 ![optic-m45](images/example_05.png)
 
 
+## Map of The Big Dipper with Custom Markers
+
+Here's a fun one 😃 Let's create a small plot of the big dipper ([Ursa Major](https://en.wikipedia.org/wiki/Ursa_Major)), but with custom star-shaped markers:
+
+```python
+--8<-- "examples/example_06.py"
+```
+
+The result should look like this:
+
+![stars-m45](images/example_06.png)
 
 ---
 

docs/gallery.md

@@ -0,0 +1,12 @@
+<div class="grid cards" markdown>
+
+- ![starchart-blue](images/example_01.png)
+- ![map-orion](images/map-orion.png)
+- ![map-sgr](images/map-sgr.png)
+- ![optic-p2](images/optic-p2.png)
+- ![map-lyra](images/map-lyra.png)
+- ![big-dipper](images/example_06.png)
+- ![map-mollweide](images/map-mollweide.png)
+- ![scope-fov](images/example_04.png)
+
+</div>

docs/images/example_01.png

@@ -5,3 +5,14 @@
         show_root_heading: true
         show_docstring_attributes: true
 
+
+::: starplot.data.dsos.DsoType
+    options:
+        show_root_heading: true
+        show_docstring_attributes: true
+        members: true
+
+::: starplot.data.dsos.DEFAULT_DSO_TYPES
+    options:
+        show_root_heading: true
+        show_docstring_attributes: true

docs/images/example_02.png

@@ -1,6 +1,11 @@
 **Map plots are general purpose maps of the sky.** They're not dependent on an observer's location, but they are dependent on time if you want to include the planets and/or the moon in the plot.
 
-There are three supported projections for map plots: mercator (the default), stereographic north, and stereographic south.
+There are four supported projections for map plots: 
+
+- Mercator (the default)
+- Stereographic North
+- Stereographic South
+- Mollweide
 
 ::: starplot.MapPlot
     options:

docs/images/example_03.png

@@ -286,9 +286,8 @@ Starplot has a bunch of built-in style extensions (all imported from `starplot.s
 <div class="indent" markdown>
 Optimized for printing in grayscale
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/grayscale.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/grayscale.yml"
 ```
 </div>
 
@@ -298,9 +297,8 @@ Optimized for printing in grayscale
 <div class="indent" markdown>
 Like `GRAYSCALE`, but inverted (white stars, black background)
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/grayscale_dark.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/grayscale_dark.yml"
 ```
 </div>
 
@@ -310,9 +308,8 @@ Like `GRAYSCALE`, but inverted (white stars, black background)
 <div class="indent" markdown>
 Light and bright colors
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/blue_light.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/blue_light.yml"
 ```
 </div>
 
@@ -322,9 +319,8 @@ Light and bright colors
 <div class="indent" markdown>
 Medium brightness bluish gray colors
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/blue_medium.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/blue_medium.yml"
 ```
 </div>
 
@@ -334,9 +330,8 @@ Medium brightness bluish gray colors
 <div class="indent" markdown>
 Dark bluish gray colors
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/blue_dark.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/blue_dark.yml"
 ```
 </div>
 
@@ -346,9 +341,8 @@ Dark bluish gray colors
 <div class="indent" markdown>
 Basic styling tailored for optic plots
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/optic.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/optic.yml"
 ```
 </div>
 
@@ -358,9 +352,8 @@ Basic styling tailored for optic plots
 <div class="indent" markdown>
 Basic styling tailored for map plots
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/map.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/map.yml"
 ```
 </div>
 
@@ -370,9 +363,8 @@ Basic styling tailored for map plots
 <div class="indent" markdown>
 Basic styling tailored for zenith plots
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/zenith.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/zenith.yml"
 ```
 </div>
 
@@ -382,9 +374,8 @@ Basic styling tailored for zenith plots
 <div class="indent" markdown>
 Hides all the labels
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/hide_labels.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/hide_labels.yml"
 ```
 </div>
 
@@ -395,8 +386,7 @@ Hides all the labels
 <div class="indent" markdown>
 Hides everything except stars and DSOs. Good for plotting scope fields of view.
 
-**Source**
-```yaml
-{% include 'src/starplot/styles/ext/minimal.yml' %}
+```yaml title="Source"
+--8<-- "src/starplot/styles/ext/minimal.yml"
 ```
 </div>

docs/images/example_04.png

@@ -1,10 +1,11 @@
 
 <!-- Here are some planned features coming soon to Starplot: -->
 
-- 🚀 Faster plotting and exporting
-- 📷 Rotation angles for camera optic plots
+- ⚙️ 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
-- 🌌 More accurate DSO outlines
 
 ✨ Clear Skies! ✨

docs/images/example_05.png

@@ -19,8 +19,8 @@
     star_catalog="tycho-1",
 )
 p.plot_scope_fov(
-    ra=3.7836111111,
-    dec=24.1166666667,
+    ra=3.7912777778,
+    dec=24.1052777778,
     scope_focal_length=600,
     eyepiece_focal_length=14,
     eyepiece_fov=82,

docs/images/example_06.png

@@ -14,8 +14,8 @@
 
 p = OpticPlot(
     # M45
-    ra=3.783611,
-    dec=24.11667,
+    ra=3.7912777778,
+    dec=24.1052777778,
     lat=33.363484,
     lon=-116.836394,
     # Refractor Telescope

docs/images/example_4.png

@@ -0,0 +1,29 @@
+from starplot import MapPlot, Projection
+from starplot.styles import PlotStyle, extensions, MarkerSymbolEnum
+
+style = PlotStyle().extend(
+    extensions.MINIMAL,
+    extensions.GRAYSCALE,
+    extensions.MAP,
+)
+
+style.star.marker.symbol = MarkerSymbolEnum.STAR
+
+# 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
+
+p = MapPlot(
+    projection=Projection.STEREO_NORTH,
+    ra_min=10.8,
+    ra_max=14,
+    dec_min=48,
+    dec_max=64,
+    limiting_magnitude=3.6,
+    style=style,
+    resolution=1400,
+    dso_types=[],  # this is one way to hide all deep sky objects
+)
+
+p.export("06_big_dipper_stars.png", padding=0.2)

docs/images/map-lyra.png

@@ -2,7 +2,7 @@
 
 import subprocess
 
-for n in range(1, 6):
+for n in range(1, 7):
     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)