Skip to content

OpticPlot

Optic plots simulate what you'll see through an optic (e.g. binoculars, telescope, camera) at a specific time and location. The simulated view will show you the true field of view for the optic, and it will even orient the stars based on the location you specify and the most logical position of your optic.

These plots use an azimuthal equidistant projection, with the projection's center set to the target's position (in azimuth, altitude coordinates). This projection was chosen because it preserves the correct proportional distances from the center point.

starplot.OpticPlot

OpticPlot(
    optic: Optic,
    ra: float,
    dec: float,
    lat: float,
    lon: float,
    dt: datetime = None,
    ephemeris: str = "de421_2001.bsp",
    style: PlotStyle = DEFAULT_OPTIC_STYLE,
    resolution: int = 2048,
    hide_colliding_labels: bool = True,
    raise_on_below_horizon: bool = True,
    *args,
    **kwargs
)

Creates a new optic plot.

Parameters:

  • optic (Optic) –

    Optic instance that defines optical parameters

  • ra (float) –

    Right ascension of target center, in hours (0...24)

  • dec (float) –

    Declination of target center, in degrees (-90...90)

  • lat (float) –

    Latitude of observer's location

  • lon (float) –

    Longitude of observer's location

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

  • raise_on_below_horizon (bool, default: True ) –

    If True, then a ValueError will be raised if the target is below the horizon at the observing time/location

Returns:

  • OpticPlot

    A new instance of an OpticPlot

objects property

objects: ObjectList

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

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.

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

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

in_bounds

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

info

info(style: LabelStyle = None)

Plots a table with info about the plot, including:

  • Target's position (alt/az and ra/dec)
  • Observer's position (lat/lon and date/time)
  • Optic details (type, magnification, FOV)

Parameters:

  • style (LabelStyle, default: None ) –

    If None, then the plot's style for info text 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

line

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

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,
    label: str,
    style: Union[dict, ObjectStyle],
    legend_label: str = None,
    skip_bounds_check: bool = False,
) -> 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

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

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)

Plots a polygon.

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

Parameters:

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

  • 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,
    catalog: StarCatalog = StarCatalog.BIG_SKY_MAG11,
    style: ObjectStyle = None,
    rasterize: bool = False,
    size_fn: Callable[[Star], float] = callables.size_by_magnitude_for_optic,
    alpha_fn: Callable[[Star], float] = callables.alpha_by_magnitude,
    color_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,
    *args,
    **kwargs
)

Plots stars

Parameters:

  • mag (float, default: 6.0 ) –

    Limiting magnitude of stars to plot

  • catalog (StarCatalog, default: BIG_SKY_MAG11 ) –

    The catalog of stars to use

  • 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_for_optic ) –

    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.

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

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 and legend

text

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

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

starplot.optics.Optic

Abstract class for defining Optics.

starplot.optics.Binoculars

Binoculars(magnification: float, fov: float)

Creates a new Binoculars optic

Parameters:

  • magnification (float) –

    Magnification of the binoculars

  • fov (float) –

    Apparent field of view (FOV) of the binoculars in degrees. This isn't always easy to find for binoculars, so if you can't find it in your binocular's specs, then try using 60.

Returns:

  • Binoculars

    A new instance of a Binoculars optic

starplot.optics.Scope

Scope(focal_length: float, eyepiece_focal_length: float, eyepiece_fov: float)

Creates a new generic Scope optic.

Use this class to create custom scope optics or use it as a generic optic that does NOT apply any transforms to the view.

See subclasses of this optic for more specific use cases:

  • Refractor - automatically inverts the view (i.e. assumes a star diagonal is used)

  • Reflector - automatically rotates the view so it's upside-down

Parameters:

  • focal_length (float) –

    Focal length (mm) of the telescope

  • eyepiece_focal_length (float) –

    Focal length (mm) of the eyepiece

  • eyepiece_fov (float) –

    Field of view (degrees) of the eyepiece

Returns:

  • Scope

    A new instance of a Scope optic

starplot.optics.Refractor

Refractor(
    focal_length: float, eyepiece_focal_length: float, eyepiece_fov: float
)

Creates a new Refractor Telescope optic

Warning

This optic assumes a star diagonal is used, so it applies a transform that inverts the image.

If you don't want this transform applied, then use the generic Scope optic instead.

Parameters:

  • focal_length (float) –

    Focal length (mm) of the telescope

  • eyepiece_focal_length (float) –

    Focal length (mm) of the eyepiece

  • eyepiece_fov (float) –

    Field of view (degrees) of the eyepiece

Returns:

  • Refractor

    A new instance of a Refractor optic

starplot.optics.Reflector

Reflector(
    focal_length: float, eyepiece_focal_length: float, eyepiece_fov: float
)

Creates a new Reflector Telescope optic

Warning

This optic applies a transform that produces an "upside-down" image.

If you don't want this transform applied, then use the generic Scope optic instead.

Parameters:

  • focal_length (float) –

    Focal length (mm) of the telescope

  • eyepiece_focal_length (float) –

    Focal length (mm) of the eyepiece

  • eyepiece_fov (float) –

    Field of view (degrees) of the eyepiece

Returns:

  • Reflector

    A new instance of a Reflector optic

starplot.optics.Camera

Camera(
    sensor_height: float,
    sensor_width: float,
    lens_focal_length: float,
    rotation: float = 0,
)

Creates a new Camera optic

Note

Field of view for each dimension is calculated using the following formula:

TFOV = 2 * arctan( d / (2 * f) )

Where:

d = sensor size (height or width)

f = focal length of lens

Parameters:

  • sensor_height (float) –

    Height of camera sensor (mm)

  • sensor_width (float) –

    Width of camera sensor (mm)

  • lens_focal_length (float) –

    Focal length of camera lens (mm)

  • rotation (float, default: 0 ) –

    Angle (degrees) to rotate camera

Returns:

  • Camera

    A new instance of a Camera optic