GalaxyPlot

Galaxy plots will plot everything in galactic coordinates, using a Mollweide projection. These plots will always plot the entire galactic sphere, since that's how they're most commonly used.

Although they plot everything in galactic coordinates, all functions still expect equatorial coordinates (RA/DEC). This decision was made for two reasons: it seems most astronomical data is presented in equatorial coordinates, and creating a transformation framework in Starplot would be a pretty large project so it'll be reserved for a future version.

Stars on galaxy plots are plotted in their astrometric positions.

New Feature - Feedback wanted!

These plots are a newer feature of Starplot (introduced in version 0.20.0), and will continue to evolve in future versions. If you notice any unexpected behavior or you think there's a useful feature missing, please open an issue on GitHub.

starplot.GalaxyPlot

GalaxyPlot(
    center_lon: float = 0,
    observer: Observer = None,
    ephemeris: str = "de440s.bsp",
    style: PlotStyle = None,
    resolution: int = 4096,
    point_label_handler: CollisionHandler = None,
    area_label_handler: CollisionHandler = None,
    path_label_handler: CollisionHandler = None,
    scale: float = 0.8,
    autoscale: bool = False,
    suppress_warnings: bool = True,
    *args,
    **kwargs,
)

Creates a new galaxy plot.

Parameters:

Name	Type	Description	Default
`center_lon`	`float`	Central galactic longitude of the Mollweide projection	`0`
`observer`	`Observer`	Observer instance which specifies a time and place. Defaults to an observer at epoch J2000	`None`
`ephemeris`	`str`	Ephemeris to use for calculating planet positions (see Skyfield's documentation for details)	`'de440s.bsp'`
`style`	`PlotStyle`	Styling for the plot (colors, sizes, fonts, etc). If `None`, it defaults to `PlotStyle()` with the MAP extension	`None`
`resolution`	`int`	Size (in pixels) of largest dimension of the map	`4096`
`point_label_handler`	`CollisionHandler`	Default CollisionHandler for point labels.	`None`
`area_label_handler`	`CollisionHandler`	Default CollisionHandler for area labels.	`None`
`path_label_handler`	`CollisionHandler`	Default CollisionHandler for path labels.	`None`
`scale`	`float`	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.	`0.8`
`autoscale`	`bool`	If True, then the scale will be automatically set based on resolution	`False`
`suppress_warnings`	`bool`	If True (the default), then all warnings will be suppressed	`True`

Returns:

Name	Type	Description
`GalaxyPlot`		A new instance of a GalaxyPlot

area_label_handler `instance-attribute`

area_label_handler = area_label_handler or CollisionHandler(
    allow_constellation_line_collisions=True
)

Default collision handler for area labels.

magnitude_range `property`

magnitude_range: tuple[float, float]

Range of magnitude for all plotted stars, as a tuple (min, max)

objects `property`

objects: ObjectList

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

path_label_handler `instance-attribute`

path_label_handler = path_label_handler or CollisionHandler(
    allow_constellation_line_collisions=True
)

Default collision handler for path labels.

point_label_handler `instance-attribute`

point_label_handler = point_label_handler or CollisionHandler(
    attempts=10,
    anchor_fallbacks=[
        AnchorPoint.BOTTOM_RIGHT,
        AnchorPoint.TOP_LEFT,
        AnchorPoint.TOP_RIGHT,
        AnchorPoint.BOTTOM_LEFT,
        AnchorPoint.BOTTOM_CENTER,
        AnchorPoint.TOP_CENTER,
        AnchorPoint.RIGHT_CENTER,
        AnchorPoint.LEFT_CENTER,
    ],
)

Default collision handler for point labels.

style `instance-attribute`

style = style or PlotStyle()

The plot's style.

arrow

arrow(
    origin: tuple[float, float] | None = None,
    target: tuple[float, float] | None = None,
    style: ArrowStyle = None,
    scale: float = 0.99,
    length: float = 5,
    max_attempts: int = 100,
    gid: str = "arrow",
)

Plots an arrow from one point to another if you specify both origin and target. If you only specify a target, then the arrow will serve as a "pointer" to that target.

Parameters:

Name	Type	Description	Default
`origin`	`tuple[float, float] \| None`	Starting point (ra, dec)	`None`
`target`	`tuple[float, float] \| None`	Target of the arrow (ra, dec)	`None`
`style`	`ArrowStyle`	Style of the arrow	`None`
`scale`	`float`	Scaling factor for the arrow, to make it offset from the origin/target	`0.99`
`length`	`float`	If you only specify a target, then this will be the length of the arrow (in degrees). This value is ignored if you're plotting an arrow from one point to another.	`5`
`max_attempts`	`int`	If you only specify a target, then this will be the max number of attempts for plotting the arrow without colliding with labels. Arrow will be plotted on the final attempt.	`100`
`gid`	`str`	Group id for this layer in the exported SVG	`'arrow'`

bright_nebula

bright_nebula(**kwargs)

Plots the following nebula DSO types:

Nebula
Emission Nebula
Star Cluster Nebula
Reflection Nebula
HII Ionized Regions

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

celestial_equator

celestial_equator(
    style: PathStyle = None,
    label: str = "CELESTIAL EQUATOR",
    num_labels: int = 2,
    collision_handler: CollisionHandler = None,
    gid: str = "celestial-equator",
)

Plots the celestial equator

Parameters:

Name	Type	Description	Default
`style`	`PathStyle`	Styling of the celestial equator. If None, then the plot's style will be used	`None`
`label`	`str`	How the celestial equator will be labeled on the plot	`'CELESTIAL EQUATOR'`
`num_labels`	`int`	Max number of labels to plot along the line	`2`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the plot's `path_label_handler` will be used.	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'celestial-equator'`

circle

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

Plots a circle

Parameters:

Name	Type	Description	Default
`center`	`tuple`	Center of circle (ra, dec)	required
`radius_degrees`	`float`	Radius of circle (degrees)	required
`style`	`PolygonStyle`	Style of circle	required
`num_pts`	`int`	Number of points to calculate for the circle polygon	`100`
`legend_label`	`str`	Label for this object in the legend	`None`

constellation_borders

constellation_borders(
    style: LineStyle = None,
    catalog: Catalog = CONSTELLATION_BORDERS,
    gid: str = "constellation-borders",
)

Plots the constellation borders

Parameters:

Name	Type	Description	Default
`style`	`LineStyle`	Styling of the constellation borders. If None, then the plot's style (specified when creating the plot) will be used	`None`
`catalog`	`Catalog`	Catalog to use for constellation borders	`CONSTELLATION_BORDERS`
`gid`	`str`	Group id for this layer in the exported SVG	`'constellation-borders'`

constellation_labels

constellation_labels(
    style: LabelStyle = None,
    label_fn: Callable[[Constellation], str] = get_label,
    collision_handler: CollisionHandler = None,
    gid: str = "constellations-labels",
)

Plots constellation labels for all constellations that have been plotted. This means you must plot the constellations before plotting their 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:

Name	Type	Description	Default
`style`	`LabelStyle`	Styling of the constellation labels. If None, then the plot's style (specified when creating the plot) will be used	`None`
`label_fn`	`Callable[[Constellation], str]`	Callable for determining the label for each constellation. The default function returns the constellation's name in uppercase.	`get_label`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on collisions with other labels, markers, etc. If `None`, then `CollisionHandler(allow_constellation_line_collisions=True)` will be used (Important: this function does NOT default to the plot's collision handler, since it's the only area-based label function and collisions should be handled differently).	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'constellations-labels'`

constellations

constellations(
    style: LineStyle = None,
    where: list | None = None,
    sql: str | None = None,
    catalog: Catalog = CONSTELLATIONS_IAU,
    gid: str = "constellations",
)

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:

Name	Type	Description	Default
`style`	`LineStyle`	Styling of the constellations. If None, then the plot's style (specified when creating the plot) will be used	`None`
`where`	`list \| None`	A list of expressions that determine which constellations to plot. See Selecting Objects for details.	`None`
`sql`	`str \| None`	SQL query for selecting constellations (table name is `_`). This query will be applied after any filters in the `where` kwarg.	`None`
`catalog`	`Catalog`	The catalog of constellations to use -- see catalogs overview for details	`CONSTELLATIONS_IAU`
`gid`	`str`	Group id for this layer in the exported SVG	`'constellations'`

dark_nebula

dark_nebula(**kwargs)

Plots dark nebula

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

dsos

dsos(
    where: list | bool | None = None,
    where_labels: list | bool | None = None,
    where_true_size: list | bool | None = None,
    legend_labels: Mapping[DsoType, str] = DSO_LEGEND_LABELS,
    opacity_fn: Callable[[DSO], float] | None = None,
    label_fn: Callable[[DSO], str] = get_label,
    sql: str | None = None,
    sql_labels: str | None = None,
    catalog: Catalog = OPEN_NGC,
    collision_handler: CollisionHandler = None,
    gids_markers: Mapping[DsoType, str] | None = None,
    gids_labels: Mapping[DsoType, str] | None = None,
)

Plots Deep Sky Objects (DSOs).

Parameters:

Name	Type	Description	Default
`where`	`list \| bool \| None`	A list of expressions that determine which DSOs to plot. See Selecting Objects for details.	`None`
`where_labels`	`list \| bool \| None`	A list of expressions that determine which DSOs are labeled on the plot. By default all DSOs are labeled. See Selecting Objects for details. Can also be a boolean: if `False` then no labels will be plotted.	`None`
`where_true_size`	`list \| bool \| None`	A list of expressions that determine which DSOs are plotted as their true apparent size in the sky. By default all DSOs are plotted as their true size. Can also be a boolean: if `False` then no DSOs will be plotted as their true size.	`None`
`legend_labels`	`Mapping[DsoType, str]`	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`.	`DSO_LEGEND_LABELS`
`opacity_fn`	`Callable[[DSO], float] \| None`	Callable for calculating the opacity value of each DSO. If `None`, then the marker style's opacity will be used.	`None`
`label_fn`	`Callable[[DSO], str]`	Callable for determining the label of each DSO.	`get_label`
`sql`	`str \| None`	SQL query for selecting DSOs (table name is `_`). This query will be applied after any filters in the `where` kwarg.	`None`
`sql_labels`	`str \| None`	SQL query for selecting DSOs that will be labeled (table name is `_`). Applied after any filters in the `where_labels` kwarg.	`None`
`catalog`	`Catalog`	The catalog of DSOs to use -- see catalogs overview for details	`OPEN_NGC`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the collision handler of the plot will be used.	`None`
`gids_markers`	`Mapping[DsoType, str] \| None`	A dictionary that maps a `DsoType` to the group id (gid) used for that type's markers in the exported SVG. If a type is not in the dict, then the default gid (`dso-{type}-markers`) is used.	`None`
`gids_labels`	`Mapping[DsoType, str] \| None`	A dictionary that maps a `DsoType` to the group id (gid) used for that type's labels in the exported SVG. If a type is not in the dict, then the default gid (`dso-{type}-labels`) is used.	`None`

ecliptic

ecliptic(
    style: PathStyle = None,
    label: str = "ECLIPTIC",
    num_labels: int = 2,
    collision_handler: CollisionHandler = None,
    gid: str = "ecliptic",
)

Plots the ecliptic

Parameters:

Name	Type	Description	Default
`style`	`PathStyle`	Styling of the ecliptic. If None, then the plot's style will be used	`None`
`label`	`str`	How the ecliptic will be labeled on the plot	`'ECLIPTIC'`
`num_labels`	`int`	Max number of labels to plot along the line	`2`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the plot's `path_label_handler` will be used.	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'ecliptic'`

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

Plots an ellipse

Parameters:

Name	Type	Description	Default
`center`	`tuple`	Center of ellipse (ra, dec)	required
`height_degrees`	`float`	Height of ellipse (degrees)	required
`width_degrees`	`float`	Width of ellipse (degrees)	required
`style`	`PolygonStyle`	Style of ellipse	required
`angle`	`float`	Angle of rotation clockwise (degrees)	`0`
`num_pts`	`int`	Number of points to calculate for the ellipse polygon	`100`
`start_angle`	`int`	Angle to start at	`0`
`end_angle`	`int`	Angle to end at	`360`
`legend_label`	`str`	Label for this object in the legend	`None`

export

export(filename: str, scale: float = 1)

Exports the plot to an image file (SVG or PNG)

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename of exported file (the format will be inferred from the extension)	required
`scale`	`float`	Scaling factor for PNG files (e.g. a value of `2` will make the PNG two times bigger than the resolution of the plot). Only applies to PNG files	`1`

galactic_equator

galactic_equator(
    style: PathStyle = None,
    label: str = "GALACTIC EQUATOR",
    num_labels: int = 1,
    collision_handler: CollisionHandler = None,
)

Plots the galactic equator

Parameters:

Name	Type	Description	Default
`style`	`PathStyle`	Styling of the galactic equator. If None, then the plot's style will be used	`None`
`label`	`str`	How the galactic equator will be labeled on the plot	`'GALACTIC EQUATOR'`
`num_labels`	`int`	Max number of labels to plot along the line	`1`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the plot's `path_label_handler` will be used.	`None`

galaxies

galaxies(**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(**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,
    labels: bool = True,
    lon_locations: list[float] = None,
    lat_locations: list[float] = None,
    lon_label_fn: Callable[[float], str] = rounded_degrees_label,
    lat_label_fn: Callable[[float], str] = rounded_degrees_label,
    lon_label_locations: list[str] = None,
    lat_label_locations: list[str] = None,
)

Plots gridlines

Parameters:

Name	Type	Description	Default
`style`	`PathStyle`	Styling of the gridlines. If None, then the plot's style (specified when creating the plot) will be used	`None`
`labels`	`bool`	If True, then labels for each gridline will be plotted on the outside of the axes.	`True`
`lon_locations`	`list[float]`	List of longitude locations for the gridlines (in degrees, 0...360). Defaults to every 15 degrees.	`None`
`lat_locations`	`list[float]`	List of latitude locations for the gridlines (in degrees, -90...90). Defaults to every 10 degrees.	`None`
`lon_label_fn`	`Callable[[float], str]`	Callable for creating labels of longitude gridlines.`	`rounded_degrees_label`
`lat_label_fn`	`Callable[[float], str]`	Callable for creating labels of latitude gridlines.`	`rounded_degrees_label`
`lon_label_locations`	`list[str]`	Locations where labels will be plotted (options: `top` and/or `bottom`). Defaults to `['top', 'bottom']`	`None`
`lat_label_locations`	`list[str]`	Locations where labels will be plotted (options: `left` and/or `right`). Defaults to `['left', 'right']`	`None`

in_bounds `cached`

in_bounds(ra, dec) -> bool

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

Parameters:

Name	Type	Description	Default
`ra`		Right ascension, in hours (0...24)	required
`dec`		Declination, in degrees (-90...90)	required

Returns:

Type	Description
`bool`	True if the coordinate is in bounds, otherwise False

in_bounds_lonlat

in_bounds_lonlat(lon, lat) -> bool

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

Parameters:

Name	Type	Description	Default
`lon`		Galactic longitude in degrees (0...360)	required
`lat`		Galactic latitude in degrees (-90...90)	required

Returns:

Type	Description
`bool`	True if the coordinate is in bounds, otherwise False

legend

legend(
    title: str = "Legend",
    style: LegendStyle = None,
    magnitude_scale: bool = False,
    magnitude_scale_title: str = "Star Magnitude",
    magnitude_start: float | None = None,
    magnitude_stop: float | None = None,
    magnitude_step: float = 1,
    magnitude_size_fn: Callable | None = None,
    magnitude_label_fn: Callable | None = None,
    gid: str = "legend",
)

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.

Star Magnitude Scale - Limitations

Only supports size functions that determine size based on magnitude
Does not automatically determine the magnitude range of the stars you already plotted

Parameters:

Name	Type	Description	Default
`title`	`str`	Title of the legend, which will be plotted at the top	`'Legend'`
`style`	`LegendStyle`	Styling of the legend. If None, then the plot's style (specified when creating the plot) will be used	`None`
`magnitude_scale`	`bool`	If True, a star magnitude scale will also be plotted	`False`
`magnitude_scale_title`	`str`	Title of the star magnitude section	`'Star Magnitude'`
`magnitude_start`	`float \| None`	Magnitude to start at in the magnitude scale	`None`
`magnitude_stop`	`float \| None`	Magnitude to stop at in the magnitude scale	`None`
`magnitude_step`	`float`	Step size for magnitudes in the scale	`1`
`magnitude_size_fn`	`Callable \| None`	Size function for the star magnitudes. Defaults to the last used size function when calling `stars()`	`None`
`magnitude_label_fn`	`Callable \| None`	Function for determining the label for each magnitude in the scale. The function should take a single parameter and return a string. Default is `lambda m: str(m)`	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'legend'`

line

line(
    coordinates: list[tuple[float, float]] = None,
    geometry: LineString = None,
    style: PathStyle = None,
    label: str = None,
    num_labels: int = 2,
    collision_handler: CollisionHandler = None,
    **kwargs,
)

Plots a line, with optional labels. Either coordinates OR geometry must be specified.

Parameters:

Name	Type	Description	Default
`coordinates`	`list[tuple[float, float]]`	List of coordinates, e.g. `[(ra, dec), (ra, dec)]`	`None`
`geometry`	`LineString`	A shapely LineString. If this value is passed, then the `coordinates` kwarg will be ignored.	`None`
`style`	`PathStyle`	Style of the line	`None`
`label`	`str`	Label for the line	`None`
`num_labels`	`int`	Number of labels to plot along the line	`2`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the plot's `path_label_handler` will be used.	`None`

marker

marker(
    ra: float,
    dec: float,
    style: dict | ObjectStyle,
    label: str | None = None,
    legend_label: str = None,
    skip_bounds_check: bool = False,
    collision_handler: CollisionHandler = None,
) -> None

Plots a marker

Parameters:

Name	Type	Description	Default
`ra`	`float`	Right ascension of the marker	required
`dec`	`float`	Declination of the marker	required
`label`	`str \| None`	Label for the marker	`None`
`style`	`dict \| ObjectStyle`	Styling for the marker	required
`legend_label`	`str`	How to label the marker in the legend. If `None`, then the marker will not be added to the legend	`None`
`skip_bounds_check`	`bool`	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.	`False`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the collision handler of the plot will be used.	`None`

messier

messier(**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,
    catalog: Catalog = MILKY_WAY,
    gid: str = "milky-way",
)

Plots the Milky Way

Parameters:

Name	Type	Description	Default
`style`	`PolygonStyle`	Styling of the Milky Way. If None, then the plot's style (specified when creating the plot) will be used	`None`
`catalog`	`Catalog`	Catalog to use for Milky Way polygons	`MILKY_WAY`
`gid`	`str`	Group id for this layer in the exported SVG	`'milky-way'`

moon

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

Plots the Moon, at its apparent RA/DEC (based on the observer you defined).

Parameters:

Name	Type	Description	Default
`style`	`ObjectStyle`	Styling of the Moon. If None, then the plot's style (specified when creating the plot) will be used	`None`
`true_size`	`bool`	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.	`False`
`show_phase`	`bool`	If True, and if `true_size = True`, then the phase of the moon will be illustrated. The dark side of the moon will be colored with the marker's `stroke`.	`False`
`label`	`str`	How the Moon will be labeled on the plot	`'Moon'`
`legend_label`	`str`	How the Moon will be labeled in the legend	`'Moon'`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the collision handler of the plot will be used.	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'moon'`

nebula

nebula(**kwargs)

Plots all nebula DSO types (except for dark nebulae):

Nebula
Emission Nebula
Star Cluster Nebula
Reflection Nebula
HII Ionized Regions
Planetary Nebula

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

open_clusters

open_clusters(**kwargs)

Plots open clusters

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

optic_fov

optic_fov(ra: float, dec: float, optic: Optic, style: PolygonStyle = None)

Draws a polygon representing the field of view for an optic, centered at a specific point.

Parameters:

Name	Type	Description	Default
`ra`	`float`	Right ascension of the center of view	required
`dec`	`float`	Declination of the center of view	required
`optic`	`Optic`	Instance of an [Optic][starplot.models.Optic]	required
`style`	`PolygonStyle`	style of the polygon	`None`

planetary_nebula

planetary_nebula(**kwargs)

Plots planetary nebula

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",
    collision_handler: CollisionHandler = None,
    gid: str = "planets",
) -> None

Plots the planets, at their apparent RA/DEC (based on the observer you defined).

Parameters:

Name	Type	Description	Default
`style`	`ObjectStyle`	Styling of the planets. If None, then the plot's style (specified when creating the plot) will be used	`None`
`true_size`	`bool`	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.	`False`
`labels`	`dict[PlanetName, str]`	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])	`PLANET_LABELS_DEFAULT`
`legend_label`	`str`	How to label the planets in the legend. If `None`, then the planets will not be added to the legend	`'Planet'`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the collision handler of the plot will be used.	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'planets'`

polygon

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

Plots a polygon.

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

Parameters:

Name	Type	Description	Default
`style`	`PolygonStyle`	Style of polygon	required
`points`	`list`	List of polygon points `[(ra, dec), ...]` - must be in counterclockwise order	`None`
`geometry`	`Polygon`	A shapely Polygon. If this value is passed, then the `points` kwarg will be ignored.	`None`
`legend_label`	`str`	Label for this object in the legend	`None`

rectangle

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

Plots a rectangle

Parameters:

Name	Type	Description	Default
`center`	`tuple`	Center of rectangle (ra, dec)	required
`height_degrees`	`float`	Height of rectangle (degrees)	required
`width_degrees`	`float`	Width of rectangle (degrees)	required
`style`	`PolygonStyle`	Style of rectangle	required
`angle`	`float`	Angle of rotation clockwise (degrees)	`0`
`legend_label`	`str`	Label for this object in the legend	`None`

stars

stars(
    where: list = None,
    where_labels: list = None,
    catalog: Catalog | Path | str = BIG_SKY_MAG11,
    style: ObjectStyle = None,
    size_fn: Callable[[Star], float] = size_by_magnitude_galaxy,
    opacity_fn: Callable[[Star], float] = None,
    color_fn: Callable[[Star], str] = None,
    label_fn: Callable[[Star], str] = get_label,
    legend_label: str = "Star",
    bayer_labels: bool = False,
    flamsteed_labels: bool = False,
    sql: str = None,
    sql_labels: str = None,
    collision_handler: CollisionHandler = None,
)

Plots stars

Parameters:

Name	Type	Description	Default
`where`	`list`	A list of expressions that determine which stars to plot. See Selecting Objects for details.	`None`
`where_labels`	`list`	A list of expressions that determine which stars are labeled on the plot (this includes all labels: name, Bayer, and Flamsteed). If you want to hide all labels, then set this arg to `[False]`. See Selecting Objects for details.	`None`
`catalog`	`Catalog \| Path \| str`	The catalog of stars to use -- see catalogs overview for details	`BIG_SKY_MAG11`
`style`	`ObjectStyle`	If `None`, then the plot's style for stars will be used	`None`
`size_fn`	`Callable[[Star], float]`	Callable for calculating the marker size of each star.	`size_by_magnitude_galaxy`
`opacity_fn`	`Callable[[Star], float]`	Callable for calculating the opacity value of each star. If `None`, then the marker style's opacity will be used.	`None`
`color_fn`	`Callable[[Star], str]`	Callable for calculating the color of each star. If `None`, then the marker style's color will be used.	`None`
`label_fn`	`Callable[[Star], str]`	Callable for determining the label of each star.	`get_label`
`legend_label`	`str`	Label for stars in the legend. If `None`, then they will not be in the legend.	`'Star'`
`bayer_labels`	`bool`	If True, then Bayer labels for stars will be plotted.	`False`
`flamsteed_labels`	`bool`	If True, then Flamsteed number labels for stars will be plotted.	`False`
`sql`	`str`	SQL query for selecting stars (table name is `_`). This query will be applied after any filters in the `where` kwarg.	`None`
`sql_labels`	`str`	SQL query for selecting stars that will be labeled (table name is `_`). Applied after any filters in the `where_labels` kwarg.	`None`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the collision handler of the plot will be used.	`None`

sun

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

Plots the Sun, at its apparent RA/DEC (based on the observer you defined).

Parameters:

Name	Type	Description	Default
`style`	`ObjectStyle`	Styling of the Sun. If None, then the plot's style (specified when creating the plot) will be used	`None`
`true_size`	`bool`	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.	`False`
`label`	`str`	How the Sun will be labeled on the plot	`'Sun'`
`legend_label`	`str`	How the sun will be labeled in the legend	`'Sun'`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on label collisions with other labels, markers, etc. If `None`, then the collision handler of the plot will be used.	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'sun'`

text

text(
    text: str,
    ra: float,
    dec: float,
    style: LabelStyle = None,
    collision_handler: CollisionHandler = None,
    **kwargs,
)

Plots text

Parameters:

Name	Type	Description	Default
`text`	`str`	Text to plot	required
`ra`	`float`	Right ascension of text (0...360)	required
`dec`	`float`	Declination of text (-90...90)	required
`style`	`LabelStyle`	Styling of the text	`None`
`collision_handler`	`CollisionHandler`	An instance of CollisionHandler that describes what to do on collisions with other labels, markers, etc. If `None`, then the plot's `point_label_handler` will be used.	`None`

tissot

tissot(radius: int = 4, style: PolygonStyle = None, gid: str = 'tissot')

Draws a Tissot indicatrix, which helps illustrate the distortion of a projection.

Parameters:

Name	Type	Description	Default
`radius`	`int`	Radius of each circle, in degrees	`4`
`style`	`PolygonStyle`	Styling of the Tissot circles. If None, then the plot's style will be used	`None`
`gid`	`str`	Group id for this layer in the exported SVG	`'tissot'`

title

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

Plots a title at the top of the plot

Parameters:

Name	Type	Description	Default
`text`	`str`	Title text to plot	required
`style`	`TitleStyle`	Styling of the title. If None, then the plot's style (specified when creating the plot) will be used	`None`

GalaxyPlot

starplot.GalaxyPlot

area_label_handler instance-attribute

magnitude_range property

objects property

path_label_handler instance-attribute

point_label_handler instance-attribute

style instance-attribute

arrow

bright_nebula

celestial_equator

circle

constellation_borders

constellation_labels

constellations

dark_nebula

dsos

ecliptic

ellipse

export

galactic_equator

galaxies

globular_clusters

gridlines

in_bounds cached

in_bounds_lonlat

legend

line

marker

messier

milky_way

moon

nebula

open_clusters

optic_fov

planetary_nebula

planets

polygon

rectangle

stars

sun

text

tissot

title

area_label_handler `instance-attribute`

magnitude_range `property`

objects `property`

path_label_handler `instance-attribute`

point_label_handler `instance-attribute`

style `instance-attribute`

in_bounds `cached`