HorizonPlot

Horizon plots show what the sky looks like from the horizon at a specific time and place. They can help illustrate answers to questions like "what stars will I see in the sky tonight at 9pm when I look directly West from my backyard?"

These plots use the Lambert azimuthal equal-area projection, with the horizon as the central altitude (0 degrees) and the central azimuth is determined by the azimuth range you define when creating the plot.

starplot.HorizonPlot

HorizonPlot(
    lat: float,
    lon: float,
    altitude: tuple[float, float],
    azimuth: tuple[float, float],
    dt: datetime = None,
    ephemeris: str = "de421_2001.bsp",
    style: PlotStyle = DEFAULT_HORIZON_STYLE,
    resolution: int = 4096,
    hide_colliding_labels: bool = True,
    scale: float = 1.0,
    autoscale: bool = False,
    suppress_warnings: bool = True,
    *args,
    **kwargs
)

Creates a new horizon plot.

Parameters:

lat (float) –

Latitude of observer's location
lon (float) –

Longitude of observer's location
altitude (tuple[float, float]) –

Tuple of altitude range to plot (min, max)
azimuth (tuple[float, float]) –

Tuple of azimuth range to plot (min, max)
dt (datetime, default: None ) –

Date/time of observation (must be timezone-aware). Default = current UTC time.
ephemeris (str, default: 'de421_2001.bsp' ) –

Ephemeris to use for calculating planet positions (see Skyfield's documentation for details)
style (PlotStyle, default: DEFAULT_HORIZON_STYLE ) –

Styling for the plot (colors, sizes, fonts, etc)
resolution (int, default: 4096 ) –

Size (in pixels) of largest dimension of the map
hide_colliding_labels (bool, default: True ) –

If True, then labels will not be plotted if they collide with another existing label
scale (float, default: 1.0 ) –

Scaling factor that will be applied to all relevant sizes in styles (e.g. font size, marker size, line widths, etc). For example, if you want to make everything 2x bigger, then set scale to 2.
autoscale (bool, default: False ) –

If True, then the scale will be automatically set based on resolution
suppress_warnings (bool, default: True ) –

If True (the default), then all warnings will be suppressed

Returns:

HorizonPlot –

A new instance of an HorizonPlot

objects `property`

objects: ObjectList

Returns an ObjectList that contains various lists of sky objects that have been plotted.

bino_fov

bino_fov(
    ra: float,
    dec: float,
    fov: float,
    magnification: float,
    style: PolygonStyle = DEFAULT_FOV_STYLE,
)

Draws a circle representing the field of view for binoculars.

Parameters:

ra (float) –

Right ascension of the center of view
dec (float) –

Declination of the center of view
fov (float) –

field of view (degrees) of the binoculars
magnification (float) –

magnification of the binoculars
style (PolygonStyle, default: DEFAULT_FOV_STYLE ) –

style of the polygon

celestial_equator

celestial_equator(style: PathStyle = None, label: str = 'CELESTIAL EQUATOR')

Plots the celestial equator

Parameters:

style (PathStyle, default: None ) –

Styling of the celestial equator. If None, then the plot's style will be used
label (str, default: 'CELESTIAL EQUATOR' ) –

How the celestial equator will be labeled on the plot

circle

circle(
    center: tuple,
    radius_degrees: float,
    style: PolygonStyle,
    num_pts: int = 100,
    legend_label: str = None,
    **kwargs
)

Plots a circle

Parameters:

center (tuple) –

Center of circle (ra, dec)
radius_degrees (float) –

Radius of circle (degrees)
style (PolygonStyle) –

Style of circle
num_pts (int, default: 100 ) –

Number of points to calculate for the circle polygon
legend_label (str, default: None ) –

Label for this object in the legend

close_fig

close_fig() -> None

Closes the underlying matplotlib figure.

constellation_borders

constellation_borders(style: LineStyle = None)

Plots the constellation borders

Parameters:

style (LineStyle, default: None ) –

Styling of the constellation borders. If None, then the plot's style (specified when creating the plot) will be used

constellation_labels

constellation_labels(
    style: LabelStyle = None,
    labels: dict[str, str] = CONSTELLATIONS_FULL_NAMES,
    auto_adjust: bool = True,
    auto_adjust_settings: dict = DEFAULT_AUTO_ADJUST_SETTINGS,
)

Plots 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.

Parameters:

style (LabelStyle, default: None ) –

Styling of the constellation labels. If None, then the plot's style (specified when creating the plot) will be used
labels (dict[str, str], default: CONSTELLATIONS_FULL_NAMES ) –

A dictionary where the keys are each constellation's 3-letter IAU abbreviation, and the values are how the constellation will be labeled on the plot.
auto_adjust (bool, default: True ) –

If True (the default), then labels will be automatically adjusted to avoid collisions with other labels and stars Important: you must plot stars and constellations first for this to work. This uses a fairly simple method: for each constellation it finds the centroid of all plotted constellation stars with lines and then generates random points in the constellation boundary starting at the centroid and then progressively increasing the distance from the centroid.
auto_adjust_settings (dict, default: DEFAULT_AUTO_ADJUST_SETTINGS ) –

Optional settings for the auto adjustment algorithm.

TODO

make this work without plotting constellations first

constellations

constellations(style: LineStyle = None, where: list = None)

Plots the constellation lines only. To plot constellation borders and/or labels, see separate functions for them.

Important: If you're plotting the constellation lines, then it's good to plot them first, because Starplot will use the constellation lines to determine where to place labels that are plotted afterwards (labels will look better if they're not crossing a constellation line).

Parameters:

style (LineStyle, default: None ) –

Styling of the constellations. If None, then the plot's style (specified when creating the plot) will be used
where (list, default: None ) –

A list of expressions that determine which constellations to plot. See Selecting Objects for details.

dsos

dsos(
    mag: float = 8.0,
    true_size: bool = True,
    labels: Mapping[str, str] = DSO_LABELS_DEFAULT,
    legend_labels: Mapping[DsoType, str] = DSO_LEGEND_LABELS,
    alpha_fn: Callable[[DSO], float] = None,
    label_fn: Callable[[DSO], str] = None,
    where: list = None,
    where_labels: list = None,
)

Plots Deep Sky Objects (DSOs), from OpenNGC

Parameters:

mag (float, default: 8.0 ) –

Limiting magnitude of DSOs to plot. For more control of what DSOs to plot, use the where kwarg. Note: if you pass mag and where then mag will be ignored
true_size (bool, default: True ) –

If True, then each DSO will be plotted as its true apparent size in the sky (note: this increases plotting time). If False, then the style's marker size will be used. Also, keep in mind not all DSOs have a defined size (according to OpenNGC) -- so these will use the style's marker size.
labels (Mapping[str, str], default: DSO_LABELS_DEFAULT ) –

A dictionary that maps DSO names (as specified in OpenNGC) to the label that'll be plotted for that object. By default, the DSO's name in OpenNGC will be used as the label. If you want to hide all labels, then set this arg to None.
legend_labels (Mapping[DsoType, str], default: DSO_LEGEND_LABELS ) –

A dictionary that maps a DsoType to the legend label that'll be plotted for that type of DSO. If you want to hide all DSO legend labels, then set this arg to None.
alpha_fn (Callable[[DSO], float], default: None ) –

Callable for calculating the alpha value (aka "opacity") of each DSO. If None, then the marker style's alpha will be used.
label_fn (Callable[[DSO], str], default: None ) –

Callable for determining the label of each DSO. If None, then the names in the labels kwarg will be used.
where (list, default: None ) –

A list of expressions that determine which DSOs to plot. See Selecting Objects for details.
where_labels (list, default: None ) –

A list of expressions that determine which DSOs are labeled on the plot. See Selecting Objects for details.

ecliptic

ecliptic(style: PathStyle = None, label: str = 'ECLIPTIC')

Plots the ecliptic

Parameters:

style (PathStyle, default: None ) –

Styling of the ecliptic. If None, then the plot's style will be used
label (str, default: 'ECLIPTIC' ) –

How the ecliptic will be labeled on the plot

ellipse

ellipse(
    center: tuple,
    height_degrees: float,
    width_degrees: float,
    style: PolygonStyle,
    angle: float = 0,
    num_pts: int = 100,
    start_angle: int = 0,
    end_angle: int = 360,
    legend_label: str = None,
    **kwargs
)

Plots an ellipse

Parameters:

center (tuple) –

Center of ellipse (ra, dec)
height_degrees (float) –

Height of ellipse (degrees)
width_degrees (float) –

Width of ellipse (degrees)
style (PolygonStyle) –

Style of ellipse
angle (float, default: 0 ) –

Angle of rotation clockwise (degrees)
num_pts (int, default: 100 ) –

Number of points to calculate for the ellipse polygon
start_angle (int, default: 0 ) –

Angle to start at
end_angle (int, default: 360 ) –

Angle to end at
legend_label (str, default: None ) –

Label for this object in the legend

export

export(filename: str, format: str = 'png', padding: float = 0, **kwargs)

Exports the plot to an image file.

Parameters:

filename (str) –

Filename of exported file
format (str, default: 'png' ) –

Format of file (options are "png", "jpeg", or "svg")
padding (float, default: 0 ) –

Padding (in inches) around the image
**kwargs –

Any keyword arguments to pass through to matplotlib's savefig method

galaxies

galaxies(*args, **kwargs)

Plots galaxy DSO types:

Galaxy
Galaxy Pair
Galaxy Triplet

This is just a small wrapper around the dsos() function, so any kwargs will be passed through.

globular_clusters

globular_clusters(*args, **kwargs)

Plots globular clusters

This is just a small wrapper around the dsos() function, so any kwargs will be passed through.

gridlines

gridlines(
    style: PathStyle = None,
    az_locations: list[float] = None,
    alt_locations: list[float] = None,
)

Plots gridlines

Parameters:

style (PathStyle, default: None ) –

Styling of the gridlines. If None, then the plot's style (specified when creating the plot) will be used
az_locations (list[float], default: None ) –

List of azimuth locations for the gridlines (in degrees, 0...360). Defaults to every 15 degrees
alt_locations (list[float], default: None ) –

List of altitude locations for the gridlines (in degrees, -90...90). Defaults to every 10 degrees.

horizon

horizon(
    style: PathStyle = None,
    labels: dict[int, str] = DEFAULT_HORIZON_LABELS,
    show_degree_labels: bool = True,
    degree_step: int = 15,
    show_ticks: bool = True,
    tick_step: int = 5,
)

Plots rectangle for horizon that shows cardinal directions and azimuth labels.

Parameters:

style (PathStyle, default: None ) –

Style of the horizon path. If None, then the plot's style definition will be used.
labels (dict[int, str], default: DEFAULT_HORIZON_LABELS ) –

Dictionary that maps azimuth values (0...360) to their cardinal direction labels (e.g. "N"). Default is to label each 45deg direction (e.g. "N", "NE", "E", etc)
show_degree_labels (bool, default: True ) –

If True, then azimuth degree labels will be plotted on the horizon path
degree_step (int, default: 15 ) –

Step size for degree labels
show_ticks (bool, default: True ) –

If True, then tick marks will be plotted on the horizon path for every tick_step degree that is not also a degree label
tick_step (int, default: 5 ) –

Step size for tick marks

in_bounds `cached`

in_bounds(ra, dec) -> bool

Determine if a coordinate is within the bounds of the plot.

Parameters:

ra –

Right ascension, in hours (0...24)
dec –

Declination, in degrees (-90...90)

Returns:

bool –

True if the coordinate is in bounds, otherwise False

in_bounds_altaz

in_bounds_altaz(alt, az, scale: float = 1) -> bool

Determine if a coordinate is within the bounds of the plot.

Parameters:

alt –

Altitude angle in degrees (0...90)
az –

Azimuth angle in degrees (0...360)

Returns:

bool –

True if the coordinate is in bounds, otherwise False

legend

legend(style: LegendStyle = None)

Plots the legend.

If the legend is already plotted, then it'll be removed first and then plotted again. So, it's safe to call this function multiple times if you need to 'refresh' the legend.

Parameters:

style (LegendStyle, default: None ) –

Styling of the legend. If None, then the plot's style (specified when creating the plot) will be used

line

line(coordinates: list[tuple[float, float]], style: LineStyle, **kwargs)

Plots a line

Parameters:

coordinates (list[tuple[float, float]]) –

List of coordinates, e.g. [(ra, dec), (ra, dec)]
style (LineStyle) –

Style of the line

marker

marker(
    ra: float,
    dec: float,
    style: Union[dict, ObjectStyle],
    label: Optional[str] = None,
    legend_label: str = None,
    skip_bounds_check: bool = False,
    **kwargs
) -> None

Plots a marker

Parameters:

ra (float) –

Right ascension of the marker
dec (float) –

Declination of the marker
label (Optional[str], default: None ) –

Label for the marker
style (Union[dict, ObjectStyle]) –

Styling for the marker
legend_label (str, default: None ) –

How to label the marker in the legend. If None, then the marker will not be added to the legend
skip_bounds_check (bool, default: False ) –

If True, then don't check the marker coordinates to ensure they're within the bounds of the plot. If you're plotting many markers, setting this to True can speed up plotting time.

messier

messier(*args, **kwargs)

Plots Messier objects

This is just a small wrapper around the dsos() function, so any kwargs will be passed through.

milky_way

milky_way(style: PolygonStyle = None)

Plots the Milky Way

Parameters:

style (PolygonStyle, default: None ) –

Styling of the Milky Way. If None, then the plot's style (specified when creating the plot) will be used

moon

moon(
    style: ObjectStyle = None,
    true_size: bool = False,
    show_phase: bool = False,
    label: str = "Moon",
    legend_label: str = "Moon",
) -> None

Plots the Moon.

If you specified a lat/lon when creating the plot (e.g. for perspective projections or optic plots), then the Moon's apparent RA/DEC will be calculated.

Parameters:

style (ObjectStyle, default: None ) –

Styling of the Moon. If None, then the plot's style (specified when creating the plot) will be used
true_size (bool, default: False ) –

If True, then the Moon's true apparent size in the sky will be plotted as a circle (the marker style's symbol will be ignored). If False, then the style's marker size will be used.
show_phase (bool, default: False ) –

If True, and if true_size = True, then the approximate phase of the moon will be illustrated. The dark side of the moon will be colored with the marker's edge_color.
label (str, default: 'Moon' ) –

How the Moon will be labeled on the plot and legend

nebula

nebula(*args, **kwargs)

Plots nebula DSO types:

Nebula
Planetary Nebula
Emission Nebula
Star Cluster Nebula
Reflection Nebula

This is just a small wrapper around the dsos() function, so any kwargs will be passed through.

open_clusters

open_clusters(*args, **kwargs)

Plots open clusters

This is just a small wrapper around the dsos() function, so any kwargs will be passed through.

planets

planets(
    style: ObjectStyle = None,
    true_size: bool = False,
    labels: Dict[PlanetName, str] = PLANET_LABELS_DEFAULT,
    legend_label: str = "Planet",
) -> None

Plots the planets.

If you specified a lat/lon when creating the plot (e.g. for perspective projections or optic plots), then the planet's apparent RA/DEC will be calculated.

Parameters:

style (ObjectStyle, default: None ) –

Styling of the planets. If None, then the plot's style (specified when creating the plot) will be used
true_size (bool, default: False ) –

If True, then each planet's true apparent size in the sky will be plotted. If False, then the style's marker size will be used.
labels (Dict[PlanetName, str], default: PLANET_LABELS_DEFAULT ) –

How the planets will be labeled on the plot and legend. If not specified, then the planet's name will be used (see [Planet][starplot.models.planet.PlanetName])
legend_label (str, default: 'Planet' ) –

How to label the planets in the legend. If None, then the planets will not be added to the legend

polygon

polygon(
    style: PolygonStyle,
    points: list = None,
    geometry: Polygon = None,
    legend_label: str = None,
    **kwargs
)

Plots a polygon.

Must pass in either points or geometry (but not both).

Parameters:

style (PolygonStyle) –

Style of polygon
points (list, default: None ) –

List of polygon points [(ra, dec), ...] - must be in counterclockwise order
geometry (Polygon, default: None ) –

A shapely Polygon. If this value is passed, then the points kwarg will be ignored.
legend_label (str, default: None ) –

Label for this object in the legend

rectangle

rectangle(
    center: tuple,
    height_degrees: float,
    width_degrees: float,
    style: PolygonStyle,
    angle: float = 0,
    legend_label: str = None,
    **kwargs
)

Plots a rectangle

Parameters:

center (tuple) –

Center of rectangle (ra, dec)
height_degrees (float) –

Height of rectangle (degrees)
width_degrees (float) –

Width of rectangle (degrees)
style (PolygonStyle) –

Style of rectangle
angle (float, default: 0 ) –

Angle of rotation clockwise (degrees)
legend_label (str, default: None ) –

Label for this object in the legend

scope_fov

scope_fov(
    ra: float,
    dec: float,
    scope_focal_length: float,
    eyepiece_focal_length: float,
    eyepiece_fov: float,
    style: PolygonStyle = DEFAULT_FOV_STYLE,
)

Draws a circle representing the field of view for a telescope and eyepiece.

Parameters:

ra (float) –

Right ascension of the center of view
dec (float) –

Declination of the center of view
scope_focal_length (float) –

focal length (mm) of the scope
eyepiece_focal_length (float) –

focal length (mm) of the eyepiece
eyepiece_fov (float) –

field of view (degrees) of the eyepiece
style (PolygonStyle, default: DEFAULT_FOV_STYLE ) –

style of the polygon

stars

stars(
    mag: float = 6.0,
    catalog: StarCatalog = StarCatalog.HIPPARCOS,
    style: ObjectStyle = None,
    rasterize: bool = False,
    size_fn: Callable[[Star], float] = callables.size_by_magnitude,
    alpha_fn: Callable[[Star], float] = callables.alpha_by_magnitude,
    color_fn: Callable[[Star], str] = None,
    label_fn: Callable[[Star], str] = None,
    where: list = None,
    where_labels: list = None,
    labels: Mapping[int, str] = STAR_NAMES,
    legend_label: str = "Star",
    bayer_labels: bool = False,
    flamsteed_labels: bool = False,
    *args,
    **kwargs
)

Plots stars

Parameters:

mag (float, default: 6.0 ) –

Limiting magnitude of stars to plot. For more control of what stars to plot, use the where kwarg. Note: if you pass mag and where then mag will be ignored
catalog (StarCatalog, default: HIPPARCOS ) –

The catalog of stars to use: "hipparcos", "big-sky-mag11", or "big-sky" -- see StarCatalog for details
style (ObjectStyle, default: None ) –

If None, then the plot's style for stars will be used
rasterize (bool, default: False ) –

If True, then the stars will be rasterized when plotted, which can speed up exporting to SVG and reduce the file size but with a loss of image quality
size_fn (Callable[[Star], float], default: size_by_magnitude ) –

Callable for calculating the marker size of each star. If None, then the marker style's size will be used.
alpha_fn (Callable[[Star], float], default: alpha_by_magnitude ) –

Callable for calculating the alpha value (aka "opacity") of each star. If None, then the marker style's alpha will be used.
color_fn (Callable[[Star], str], default: None ) –

Callable for calculating the color of each star. If None, then the marker style's color will be used.
label_fn (Callable[[Star], str], default: None ) –

Callable for determining the label of each star. If None, then the names in the labels kwarg will be used.
where (list, default: None ) –

A list of expressions that determine which stars to plot. See Selecting Objects for details.
where_labels (list, default: None ) –

A list of expressions that determine which stars are labeled on the plot. See Selecting Objects for details.
labels (Mapping[int, str], default: STAR_NAMES ) –

A dictionary that maps a star's HIP id to the label that'll be plotted for that star. If you want to hide name labels, then set this arg to None.
legend_label (str, default: 'Star' ) –

Label for stars in the legend. If None, then they will not be in the legend.
bayer_labels (bool, default: False ) –

If True, then Bayer labels for stars will be plotted.
flamsteed_labels (bool, default: False ) –

If True, then Flamsteed number labels for stars will be plotted.

sun

sun(
    style: ObjectStyle = None,
    true_size: bool = False,
    label: str = "Sun",
    legend_label: str = "Sun",
) -> None

Plots the Sun.

If you specified a lat/lon when creating the plot (e.g. for perspective projections or optic plots), then the Sun's apparent RA/DEC will be calculated.

Parameters:

style (ObjectStyle, default: None ) –

Styling of the Sun. If None, then the plot's style (specified when creating the plot) will be used
true_size (bool, default: False ) –

If True, then the Sun's true apparent size in the sky will be plotted as a circle (the marker style's symbol will be ignored). If False, then the style's marker size will be used.
label (str, default: 'Sun' ) –

How the Sun will be labeled on the plot
legend_label (str, default: 'Sun' ) –

How the sun will be labeled in the legend

text

text(
    text: str,
    ra: float,
    dec: float,
    style: LabelStyle = None,
    hide_on_collision: bool = True,
    **kwargs
)

Plots text

Parameters:

text (str) –

Text to plot
ra (float) –

Right ascension of text (0...24)
dec (float) –

Declination of text (-90...90)
style (LabelStyle, default: None ) –

Styling of the text
hide_on_collision (bool, default: True ) –

If True, then the text will not be plotted if it collides with another label

title

title(text: str, style: LabelStyle = None)

Plots a title at the top of the plot

Parameters:

text (str) –

Title text to plot
style (LabelStyle, default: None ) –

Styling of the title. If None, then the plot's style (specified when creating the plot) will be used

HorizonPlot

starplot.HorizonPlot

objects property

bino_fov

celestial_equator

circle

close_fig

constellation_borders

constellation_labels

constellations

dsos

ecliptic

ellipse

export

galaxies

globular_clusters

gridlines

horizon

in_bounds cached

in_bounds_altaz

legend

line

marker

messier

milky_way

moon

nebula

open_clusters

planets

polygon

rectangle

scope_fov

stars

sun

text

title

objects `property`

in_bounds `cached`