star-chart-spherical-projection
Advanced tools
A Python package to generate circular astronomy star charts (past, present, and future) with spherical projection to correct for distortions with more than a hundred named stars accurate over 400,000 years with proper motion and precession of the equinoxes
A Python package to generate circular astronomy star charts (past, present, and future) with spherical projection to correct for distortions with all IAU named stars accurate over 400,000 years with proper motion and precession of the equinoxes
Plot stars in the Southern Hemisphere for the year 2024 (without stars labels)
import star_chart_spherical_projection as scsp
scsp.plotStereographicProjection(northOrSouth="South",
displayStarNamesLabels=False,
yearSince2000=24)
Plot a few built-in stars as well as two new user defined stars in the Northern Hemisphere for the year 1961 (2000-39) (with stars labels and in red). This uses both methods to define the proper motion for new stars: with a given proper motion and angle and with the proper motion speed in the declination and right ascension
import star_chart_spherical_projection as scsp
exalibur_star = scsp.newStar(starName="Exalibur",
ra="14.04.23",
dec=64.22,
properMotionSpeed=12.3,
properMotionAngle=83,
magnitudeVisual=1.2)
karaboudjan_star = scsp.newStar(starName="Karaboudjan",
ra="3.14.15",
dec=10.13,
properMotionSpeedRA=57.6,
properMotionSpeedDec=60.1,
magnitudeVisual=0.3)
scsp.plotStereographicProjection(northOrSouth="North",
builtInStars=["Vega", "Arcturus", "Altair"],
userDefinedStars=[exalibur_star, karaboudjan_star],
displayStarNamesLabels=True,
fig_plot_color="red",
yearSince2000=-39)
Return the final position of a Vega (can be a single star or a list of stars) after 11,500 years when Vega is the new North Pole Star (star closest to +90°)
import star_chart_spherical_projection as scsp
star_final_pos_dict = scsp.finalPositionOfStars(builtInStars=["Vega"],
yearSince2000=11500,
save_to_csv="final_star_positions.csv")
Returns a dictionary with a star and its declination and right ascension: {'Vega': {'Declination': 83.6899118156341, 'RA': '05.38.21'}}
The final position of the stars are saved in final_star_positions.csv with the headers ["Star Name", "Right Ascension (HH.MM.SS)", "Declination (DD.SS)"]
PyPi pip install at pypi.org/project/star-chart-spherical-projection/
pip install star-chart-spherical-projection
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 (matplotlib polar plot's theta value) and declination as the distance from the center of the circle (matplotlib polar plot's radius value). However, attempting to map the right ascension and declination directly will cause 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 due to this distortion. By accounting for the spherical transformation, the star chart can be corrected as seen on the right.
| Without Correction | With Correction |
|---|---|
 |  |
The sphere is projected from the South Pole (via Stereographic projection):
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 arbitrary 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. During the course of a full 24-hour day, 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 angular distortion 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 Hemisphere, projections are formed from the South Pole:
The star chart package comes with over a hundred of brightest stars as part of a built-in library. However, a new star can be easily added for plotting or calculations by creating a newStar object. The newStar object will require a few important features that plotStereographicProjection() and finalPositionOfStars() can now accept as an additional argument.
This allows for the creation of a new star in two ways:
1. With a Proper Motion Speed and a Proper Motion Angle
As seen in in-the-sky.org for Pollux
star_chart_spherical_projection.newStar(starName=None,
ra=None,
dec=None,
properMotionSpeed=None,
properMotionAngle=None,
magnitudeVisual=None)
With the Proper Motion speed along the Right Ascension and Declination
As seen in wikipeida.og for Pollux
star_chart_spherical_projection.newStar(starName=None,
ra=None,
dec=None,
properMotionSpeedRA=None,
properMotionSpeedDec=None,
magnitudeVisual=None)
Important Note: RA/Dec proper motion will be converted from speed along the right ascension and declination to a proper motion speed (properMotionSpeed) and an angle (properMotionAngle) for further calculations
plotStereographicProjection()
Plot stars on a Stereographic Polar Plot
plotStereographicProjection(northOrSouth=None,
builtInStars=[],
declination_min=None,
yearSince2000=0,
displayStarNamesLabels=True,
displayDeclinationNumbers=True,
incrementBy=10,
isPrecessionIncluded=True,
maxMagnitudeFilter=None,
userDefinedStars=[],
onlyDisplayUserStars=False,
showPlot=True,
fig_plot_title=None,
fig_plot_color="C0",
figsize_n=12,
figsize_dpi=100,
save_plot_name=None)
| northOrSouth="North" (-30° to 90°) (without star labels) | northOrSouth="South" (30° to -90°) (without star labels) |
|---|---|
 |  |
| builtInStars=[] (Includes all stars, default) | builtInStars=["Vega", "Arcturus", "Enif", "Caph", "Mimosa"] |
|---|---|
 |  |
| declination_min=-30° (default) | declination_min=10° |
|---|---|
 |  |
| yearSince2000=0 (default) | yearSince2000=-3100 |
|---|---|
 |  |
| displayStarNamesLabels=True (default) | displayStarNamesLabels=False |
|---|---|
 |  |
| displayDeclinationNumbers=True (default) (without star labels) | displayDeclinationNumbers=False (without star labels) |
|---|---|
 |  |
| incrementBy=10 (default) (without star labels) | incrementBy=5 (without star labels) |
|---|---|
 |  |
| isPrecessionIncluded=True (default) (yearSince2000=11500) | isPrecessionIncluded=False (yearSince2000=11500) |
|---|---|
 |  |
| maxMagnitudeFilter=None (default) | maxMagnitudeFilter=1 |
|---|---|
 |  |
| userDefinedStars=[] (default) (with just "Vega") | userDefinedStars=[exalibur_star, karaboudjan_star] (from Quickstart with "Vega") |
|---|---|
 |  |
| onlyDisplayUserStars=False (default) with userDefinedStars | onlyDisplayUserStars=True with userDefinedStars=[exalibur_star, karaboudjan_star] (from Quickstart) |
|---|---|
 |  |
| fig_plot_title=(default) | fig_plot_title="This is a Example Title for a Star Chart" |
|---|---|
 |  |
| fig_plot_color="C0" (default) (without star labels) | fig_plot_color="darkorchid" (without star labels) |
|---|---|
 |  |
finalPositionOfStars()
Returns a dictionary for the final positions of the stars for a specific year in the format: {'Star Name': {"Declination" : Declination (int), "RA": RA (str)}
finalPositionOfStars(builtInStars=[],
yearSince2000=0,
isPrecessionIncluded=True,
userDefinedStars=[],
onlyDisplayUserStars=False,
declination_min=None,
declination_max=None,
save_to_csv=None)
starPositionOverTime()
Returns a single star's position over time
starPositionOverTime(builtInStarName=None,
newStar=None,
startYearSince2000=None,
endYearSince2000=None,
incrementYear=5,
isPrecessionIncluded=True,
save_to_csv=None)
Vega5 yearspredictPoleStar
Return the North/South Pole star for a given year since 2000
predictPoleStar(yearSince2000=0, northOrSouth="North")
North = 90° and South = -90°, defaults to NorthplotStarPositionOverTime()
Plot a star's declination and right ascension position over time
plotStarPositionOverTime(builtInStarName=None,
newStar=None,
startYearSince2000=None,
endYearSince2000=None,
incrementYear=10,
isPrecessionIncluded=True,
DecOrRA="D",
showPlot=True,
showYearMarker=True,
fig_plot_title=None,
fig_plot_color="C0",
figsize_n=12,
figsize_dpi=100,
save_plot_name=None)
VegaD or Right Ascension RA, defaults to D10 years<STAR NAME> <DECLINATION/RA> (<With/Without> Precession) from <START BCE/CE> to <END BCE/CE>, every <YEAR INCREMENT> YearsC012100Declination with Precession:
star_chart_spherical_projection.plotStarPositionOverTime(builtInStarName="Vega",
newStar=None,
startYearSince2000=-15000,
endYearSince2000=15000,
isPrecessionIncluded=True,
incrementYear=5,
DecOrRA="D")
Declination without Precession:
star_chart_spherical_projection.plotStarPositionOverTime(builtInStarName="Vega",
newStar=None,
startYearSince2000=-15000,
endYearSince2000=15000,
isPrecessionIncluded=False,
incrementYear=5,
DecOrRA="D")
Right Ascension with Precession:
star_chart_spherical_projection.plotStarPositionOverTime(builtInStarName="Vega",
newStar=None,
startYearSince2000=-15000,
endYearSince2000=15000,
isPrecessionIncluded=True,
incrementYear=5,
DecOrRA="R")
Right Ascension without Precession:
star_chart_spherical_projection.plotStarPositionOverTime(builtInStarName="Vega",
newStar=None,
startYearSince2000=-15000,
endYearSince2000=15000,
isPrecessionIncluded=False,
incrementYear=5,
DecOrRA="R")
Star Chart in the Northern Hemisphere (centered on 90°) without Precession
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="North",
displayStarNamesLabels=False,
yearSince2000=11500,
isPrecessionIncluded=False,
fig_plot_color="red")
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="North",
displayStarNamesLabels=True,
yearSince2000=11500,
isPrecessionIncluded=False,
fig_plot_color="red")
Star Chart in the Northern Hemisphere (centered on 90°) with Precession
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="North",
displayStarNamesLabels=False,
yearSince2000=11500,
isPrecessionIncluded=True,
fig_plot_color="red")
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="North",
displayStarNamesLabels=True,
yearSince2000=11500,
isPrecessionIncluded=True,
fig_plot_color="red")
Star Chart in the Southern Hemisphere (centered on -90°) without Precession
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="South",
displayStarNamesLabels=False,
yearSince2000=11500,
isPrecessionIncluded=False,
fig_plot_color="cornflowerblue")
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="South",
displayStarNamesLabels=True,
yearSince2000=11500,
isPrecessionIncluded=False,
fig_plot_color="cornflowerblue")
Star Chart in the Southern Hemisphere (centered on -90°) with Precession
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="South",
displayStarNamesLabels=False,
yearSince2000=11500,
isPrecessionIncluded=True,
fig_plot_color="cornflowerblue")
star_chart_spherical_projection.plotStereographicProjection(northOrSouth="South",
displayStarNamesLabels=True,
yearSince2000=11500,
isPrecessionIncluded=True,
fig_plot_color="cornflowerblue")
To run or test against star-chart-spherical-projection github repo/fork, a development environment can be created via conda/miniconda
First, install Miniconda
Then, using the existing environment.yml, a new conda environment can be create to run/test scripts against
conda env create --file environment.yml
Once the environment has been built, activate the environment:
conda activate star_chart
To run existing and new tests from the root directory:
python -m pytest
Named stars specified by "IAU Catalog of Star Names" with the star position (right ascension and declination) as well as the angle and speed of proper motion from in-the-sky.org and Wikipedia where indicated
Precession model: Vondrák, J., et al. “New Precession Expressions, Valid for Long Time Intervals.” Astronomy & Astrophysics, vol. 534, 2011
Precession code adapted to Python 3+ from the Vondrak long term precession model Github repo 'vondrak')
Submit a bug fix, question, or feature request as a Github Issue or to cyschneck@gmail.com
FAQs
A Python package to generate circular astronomy star charts (past, present, and future) with spherical projection to correct for distortions with more than a hundred named stars accurate over 400,000 years with proper motion and precession of the equinoxes
We found that star-chart-spherical-projection demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A flawed sandbox in @nestjs/devtools-integration lets attackers run code on your machine via CSRF, leading to full Remote Code Execution (RCE).
Product
Customize license detection with Socket’s new license overlays: gain control, reduce noise, and handle edge cases with precision.
Product
Socket now supports Rust and Cargo, offering package search for all users and experimental SBOM generation for enterprise projects.