2 - Creating a Basic Star Chart

Let's begin our starplotting journey by creating a basic star chart that shows the entire sky at a specific time and place, like the chart above. Starplot calls these "Zenith" projections because the zenith is in the center of the chart.

Here's a look at the code to create the zenith chart above, which shows the sky as seen from Palomar Mountain in California on July 13, 2023 at 10pm PT:

from datetime import datetime
from pytz import timezone
from starplot import MapPlot, Projection

tz = timezone("America/Los_Angeles")
dt = datetime(2023, 7, 13, 22, 0, tzinfo=tz)  # July 13, 2023 at 10pm PT

p = MapPlot(
    projection=Projection.ZENITH,
    lat=33.363484,
    lon=-116.836394,
    dt=dt,
    resolution=4000,
    scale=0.9,
)
p.constellations()  # Plot the constellation lines first
p.stars(mag=4.6)
p.horizon()
p.constellation_labels()  # Plot the constellation labels last to avoid collisions

p.export("tutorial_02.png", transparent=True)

In the first few lines, we just import all the stuff we need. pytz is a required dependency of Starplot, so it should've been installed when you installed Starplot.

Next, we create a datetime for our plot, including the timezone. All datetime values in Starplot need to be timezone-aware. An exception will be raised if you try to pass a naive datetime.

On line 8, we create a MapPlot instance that specifies a few properties for the map:

projection: Method to use for transforming the curved shape of the three-dimensional sky to a flat two-dimensional map. In this example, we use a ZENITH projection, but Starplot supports many types of projections.
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 or constellations). In Starplot, you have to explicitly plot all objects.

So, on line 16 we start by plotting the constellation lines. We plot these first, because Starplot can use the constellation lines to automatically find good places to plot object labels.

Next, we plot stars with a limiting magnitude of 4.6. Notice how none of the star names in the plot cross over a constellation line? That's because we plotted the constellation lines before plotting the stars.

After the stars, we plot the horizon, which is the border around the plot with the cardinal direction labels.

Lastly, we plot the constellation labels. It's good to plot these last because they're area-based labels (vs point-based, like for star names), and area-based labels have more freedom to move around. If you plot area-based labels first, then it would limit the available space for point-based labels.

Once we're done plotting, we export the plot to a PNG file.

In the next section, we'll learn how to add some styles and other objects to the plot...