MapPlot

Map plots are general-purpose maps of the sky. They support a variety of projections (including a few perspective based projections that help show what the sky looks like at a particular time and place).

starplot.MapPlot

MapPlot(
    projection: Projection,
    ra_min: float = 0,
    ra_max: float = 24,
    dec_min: float = -90,
    dec_max: float = 90,
    lat: float = None,
    lon: float = None,
    dt: datetime = None,
    ephemeris: str = "de421_2001.bsp",
    style: PlotStyle = DEFAULT_MAP_STYLE,
    resolution: int = 2048,
    hide_colliding_labels: bool = True,
    *args,
    **kwargs
)

Creates a new map plot.

Note

lat, lon, and dt are required for perspective projections (Orthographic, Stereographic, and Zenith)

Parameters:

• projection (Projection) –

  Projection of the map

• ra_min (float, default: 0 ) –

  Minimum right ascension of the map's extent, in hours (0...24)

• ra_max (float, default: 24 ) –

  Maximum right ascension of the map's extent, in hours (0...24)

• dec_min (float, default: -90 ) –

  Minimum declination of the map's extent, in degrees (-90...90)

• dec_max (float, default: 90 ) –

  Maximum declination of the map's extent, in degrees (-90...90)

• lat (float, default: None ) –

  Latitude for perspective projections: Orthographic, Stereographic, and Zenith

• lon (float, default: None ) –

  Longitude for perspective projections: Orthographic, Stereographic, and Zenith

• dt (datetime, default: None ) –

  Date/time to use for star/planet positions, (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_MAP_STYLE ) –

  Styling for the plot (colors, sizes, fonts, etc)

• resolution (int, default: 2048 ) –

  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

Returns:

• MapPlot –

  A new instance of a MapPlot

adjust_text

adjust_text(
    ensure_inside_axes: bool = False, **kwargs
) -> None

Adjust all the labels to avoid overlapping. This function uses the adjustText library.

Parameters:

• ensure_inside_axes (bool, default: False ) –

  If True, then labels will be forced to stay within the axes

• **kwargs –

  Any keyword arguments to pass through to adjustText

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,
)

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

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

constellations

constellations(
    style: PathStyle = None,
    labels: dict[str, str] = CONSTELLATIONS_FULL_NAMES,
)

Plots the constellation lines and/or labels

Parameters:

• style (PathStyle, default: None ) –

  Styling of the constellations. 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 abbreviation, and the values are how the constellation will be labeled on the plot.

dsos

dsos(
    mag: float = 8.0,
    types: list[DsoType] = DEFAULT_DSO_TYPES,
    names: list[str] = None,
    null: bool = False,
    true_size: bool = True,
    labels: Mapping[str, str] = DSO_LABELS_DEFAULT,
    legend_labels: Mapping[
        DsoType, str
    ] = DSO_LEGEND_LABELS,
)

Plots Deep Sky Objects (DSOs), from OpenNGC

Parameters:

• mag (float, default: 8.0 ) –

  Limiting magnitude of DSOs to plot

• types (list[DsoType], default: DEFAULT_DSO_TYPES ) –

  List of DSO types to plot

• names (list[str], default: None ) –

  List of DSO names (as specified in OpenNGC) to filter by (case sensitive!). If None, then the DSOs will not be filtered by name.

• null (bool, default: False ) –

  If True, then DSOs without a defined magnitude will be plotted

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

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,
)

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

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: "png" 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

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

gridlines

gridlines(
    style: PathStyle = None,
    labels: bool = True,
    tick_marks: bool = False,
)

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

• labels (bool, default: True ) –

  If True, then labels for each gridline will be plotted.

• tick_marks (bool, default: False ) –

  If True, then minor tick marks will be plotted outside the axis between the major gridlines.

horizon

horizon(
    style: PolygonStyle = PolygonStyle(
        fill=False,
        edge_color="red",
        line_style="dashed",
        edge_width=4,
        zorder=1000,
    )
)

Draws a great circle representing the horizon for the given lat, lon at time dt (so you must define these when creating the plot to use this function)

Parameters:

• style (PolygonStyle, default: PolygonStyle(fill=False, edge_color='red', line_style='dashed', edge_width=4, zorder=1000) ) –

  Style of the polygon

in_bounds

in_bounds(ra: float, dec: float) -> bool

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

Parameters:

• ra (float) –

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

• dec (float) –

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

Returns:

• bool –

  True if the coordinate is in bounds, otherwise False

info

info(style: LabelStyle = None)

Plots info text in the lower left corner, including date/time and lat/lon.

Only available for ZENITH projections

Parameters:

• style (LabelStyle, default: None ) –

  Styling of the info text. If None, then the plot's style definition will be used.

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

marker

marker(
    ra: float,
    dec: float,
    label: str,
    style: Union[dict, ObjectStyle],
    legend_label: str = None,
) -> None

Plots a marker

Parameters:

• ra (float) –

  Right ascension of the marker

• dec (float) –

  Declination of the marker

• label (str) –

  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

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,
    label: str = "Moon",
    legend_label: str = "Moon",
) -> None

Plots the Moon

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. If False, then the style's marker size will be used.

• label (str, default: 'Moon' ) –

  How the Moon will be labeled on the plot and legend

nebula

nebula(*args, **kwargs)

Plots nebula DSO types

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[Planet, str] = PLANET_LABELS_DEFAULT,
    legend_label: str = "Planet",
) -> None

Plots the planets

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[Planet, 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)

• 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(points: list, style: PolygonStyle)

Plots a polygon of points

Parameters:

• points (list) –

  List of polygon points [(ra, dec), ...]

• style (PolygonStyle) –

  Style of polygon

rectangle

rectangle(
    center: tuple,
    height_degrees: float,
    width_degrees: float,
    style: PolygonStyle,
    angle: float = 0,
    *args,
    **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)

• angle (float, default: 0 ) –

  Angle of rotation clockwise (degrees)

• style (PolygonStyle) –

  Style of rectangle

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,
    mag_labels: 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,
    labels: Mapping[int, str] = STAR_NAMES,
    legend_label: str = "Star",
    bayer_labels: bool = False,
    *args,
    **kwargs
)

Plots stars

Parameters:

• mag (float, default: 6.0 ) –

  Limiting magnitude of stars to plot

• mag_labels (float, default: 6.0 ) –

  Limiting magnitude of stars to label on the plot

• catalog (StarCatalog, default: HIPPARCOS ) –

  The catalog of stars to use: "hipparcos" or "tycho-1" -- Hipparcos is the default and has about 10x less stars than Tycho-1 but will also plot much faster

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

• 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. Set this to False if you want to hide Bayer labels.

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

Map Projections

starplot.Projection

Supported projections for MapPlots

MERCATOR class-attribute instance-attribute

MERCATOR = 'mercator'

Good for declinations between -70 and 70, but distorts objects near the poles

MILLER class-attribute instance-attribute

MILLER = 'miller'

Similar to Mercator: good for declinations between -70 and 70, but distorts objects near the poles

MOLLWEIDE class-attribute instance-attribute

MOLLWEIDE = 'mollweide'

Good for showing the entire celestial sphere in one plot

ORTHOGRAPHIC class-attribute instance-attribute

ORTHOGRAPHIC = 'orthographic'

Shows the celestial sphere as a 3D-looking globe. Objects near the edges will be distorted.

This is a perspective projection, so it requires the following kwargs when creating the plot: lat, lon, and dt. The perspective of the globe will be based on these values.

STEREOGRAPHIC class-attribute instance-attribute

STEREOGRAPHIC = 'stereographic'

Similar to the North/South Stereographic projection, but this version is location-dependent.

This is a perspective projection, so it requires the following kwargs when creating the plot: lat, lon, and dt. The perspective of the map will be based on these values.

STEREO_NORTH class-attribute instance-attribute

STEREO_NORTH = 'stereo_north'

Good for objects near the north celestial pole, but distorts objects near the mid declinations

STEREO_SOUTH class-attribute instance-attribute

STEREO_SOUTH = 'stereo_south'

Good for objects near the south celestial pole, but distorts objects near the mid declinations

ZENITH class-attribute instance-attribute

ZENITH = 'zenith'

This is a perspective projection, so it requires the following kwargs when creating the plot: lat, lon, and dt. The perspective of the map will be based on these values.

The Zenith projection shows the whole sky as seen from a specific time and place. They're also sometimes called "star charts" but that name is used for many different types of star maps, so Starplot uses the more specific name "Zenith plot" (which reflects the fact that the zenith is in the center of the chart).

starplot.base.DEFAULT_FOV_STYLE module-attribute

DEFAULT_FOV_STYLE = PolygonStyle(
    fill=False,
    edge_color="red",
    line_style="dashed",
    edge_width=4,
    zorder=1000,
)

Default style for plotting scope and bino field of view circles