Skip to main content

A Python package to generate an astronomy star chart based on spherical projection that corrects for distortions with stereographic projection

Project description


PyPi license

A Python package to generate an astronomy star chart based on spherical projection with +90/-90° in the center (orignally based on this Astrolabe work) based on a star's position (declination and right ascension): past, present, and future (proper motion and *precession)

The first step to plot the celestial sphere onto a 2D plot is to map the star's right ascension as hours along the plot (polar plot's theta value) and declination as the distance from the center of the circle (polar plot's radius value). However, attempting to map the right ascension and declination directly will cause a distinct amount of distortion since the angles between the stars along the declination are no longer conserved. On the left, the constellation of the Big Dipper is stretched into an unfamiliar shape. By accounting for the spherical transformation, the star chart can be corrected as seen on the right.

Without Correction With Correction
without_correction with_correction

The sphere is projected from the South Pole (via Sterographic projection):

Example outputs:

Star Chart in the Northern Hemisphere (centered on 90°) without Precession north_star_chart_without_labels_without_precession+png north_star_chart_with_labels_without_precession+png north_star_chart_without_labels_with_precession+png north_star_chart_with_labels_with_precession+png

Star Chart in the Southern Hemisphere (centered on -90°) without Precession south_star_chart_without_labels_without_precession+png south_star_chart_with_labels_without_precession+png south_star_chart_without_labels_with_precession+png south_star_chart_with_labels_with_precession+png


From the perspective of an observer on the Earth's surface, the stars appear to sit along the surface of the celestial sphere--an imaginary sphere of arbitery radius with the Earth at its center. All objects in the sky will appear projected on the celestial sphere regardless of their true distance from Earth. Each star's position is given by two values. Declination is the angular distance from the celestial equator and right ascension is the distance from the position of the vernal equinox. The stars will appear to rotate across the sky as a result of the Earth's rotation, but their position is fixed. A star’s actual position does change over time as the combined result of the star’s small movement (proper motion) as well as the changing rotational axis of the Earth (precession).

Spherical projection can overcome this difficulty by converting the position of the declination to:

# Projected from South Pole (Northern Hemisphere)
north_hemisphere_declination = tan(45° + (original_declination / 2))

# Projected from North Pole (Southern Hemisphere)
south_hemisphere_declination = tan(45° - (original_declination / 2))

Where in the Northern Hemsiphere, projections are formed from the South Pole: morrisons_astrolabe


  • [REQUIRED] northOrSouth: (string) map for either the "North" or "South" hemisphere
  • [OPTIONAL] userListOfStar: (list) a list of star names to include, by default = [] includes all stars (in star_data.csv). Example: ["Vega", "Merak", "Dubhe"]
  • [OPTIONAL] declination_min: (int) outer declination value, defaults to -30° in Northern hemisphere and 30° in Southern hemisphere
  • [OPTIONAL] yearSince2000: (float) years since 2000 (-50 = 1950 and +50 = 2050) to calculate proper motion and precession, defaults = 0 years
  • [OPTIONAL] displayStarNamesLabels: (boolean) display the star name labels, defaults to True
  • [OPTIONAL] displayDeclinationNumbers: (boolean) display declination values, defaults to True
  • [OPTIONAL] incrementBy: (int) increment values for declination (either 1, 5, 10), defaults to 10
  • [OPTIONAL] isPrecessionIncluded: (boolean) when calculating star positions include predictions for precession, defaults to True
  • [OPTIONAL] showPlot: (boolean) show plot (triggers when finished running, defaults to True
  • [OPTIONAL] fig_plot_title: (string) figure title, defaults to "<North/South>ern Hemisphere [ Years Since 2000 (YYYY)]: +/-90° to °"
  • [OPTIONAL] fig_plot_color: (string) scatter plot star color, defaults to C0
  • [OPTIONAL] figsize_n: (int) figure size, default to 12
  • [OPTIONAL] figsize_dpi: (int) figure DPI, default to 100
  • [OPTIONAL] save_plot_name: (string) save plot with a string name, defaults to not saving

Current list of stars (to access via userListOfStar): ['Acamar', 'Achernar', 'Acrux', 'Aldebaran', 'Algol', 'Alhena', 'Alioth', 'Alkaid', 'Alnilam', 'Alnitak', 'Alphard', 'Alphecca', 'Alpheratz', 'Altair', 'Ankaa', 'Antares', 'Arcturus', 'Atria', 'Avior', 'Bellatrix', 'Beta Hydri', 'Beta Phoenicis', 'Betelgeuse', 'Canopus', 'Capella', 'Caph', 'Castor', 'Celaeno', 'Chara', 'Cor-Caroli', 'Delta Crucis', 'Deneb', 'Denebola', 'Diphda', 'Dubhe', 'Elnath', 'Formalhaut', 'Gacrux', 'Gamma Phoenicis', 'Hadar', 'Hamal', 'Megrez', 'Meissa', 'Menkalinan', 'Merak', 'Mimosa', 'Mintaka', 'Mirfak', 'Mirzam', 'Mizar', 'Muphrid', 'Navi', 'Phecda', 'Polaris', 'Pollux', 'Procyon', 'Rasalhague', 'Regulus', 'Rigel', 'Ruchbah', 'Saiph', 'Schedar', 'Segin', 'Seginus', 'Sirius', 'Spica', 'Vega', 'Wezen', 'Zubeneschamali']


Python 3.7

pip3 install -r requirements.txt


PyPi pip install at

pip install star-chart-spherical-projection


import star_chart_spherical_projection




Star position (right ascension and declination) as well as the angle and speed of proper motion taken from

Precession model: Vondrák, J., et al. “New Precession Expressions, Valid for Long Time Intervals.” Astronomy & Astrophysics, vol. 534, 2011,

Precession model code adapted to Python3 from


Add README badges: tests

Pypi tests

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

star-chart-spherical-projection-1.2.4.tar.gz (23.3 kB view hashes)

Uploaded Source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page