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,
clip_path: Polygon = None,
*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
-
clip_path
(Polygon
, default:None
) –An optional Shapely Polygon that specifies the clip path of the plot -- only objects inside the polygon will be plotted. If
None
(the default), then the clip path will be the extent of the map you specified with the RA/DEC parameters.
Returns:
-
MapPlot
–A new instance of a MapPlot
objects
property
objects: ObjectList
Returns an ObjectList
that contains various lists of sky objects that have been plotted.
adjust_text
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
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,
where: list = None,
)
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.
-
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 passmag
andwhere
thenmag
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 toNone
. -
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 thelabels
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
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
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
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,
ra_locations: list[float] = None,
dec_locations: list[float] = None,
ra_formatter_fn: Callable[[float], str] = None,
dec_formatter_fn: Callable[[float], str] = None,
tick_marks: bool = False,
ra_tick_locations: list[float] = None,
dec_tick_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
-
labels
(bool
, default:True
) –If True, then labels for each gridline will be plotted on the outside of the axes.
-
ra_locations
(list[float]
, default:None
) –List of Right Ascension locations for the gridlines (in hours, 0...24). Defaults to every 1 hour.
-
dec_locations
(list[float]
, default:None
) –List of Declination locations for the gridlines (in degrees, -90...90). Defaults to every 10 degrees.
-
ra_formatter_fn
(Callable[[float], str]
, default:None
) –Callable for creating labels of right ascension gridlines
-
dec_formatter_fn
(Callable[[float], str]
, default:None
) –Callable for creating labels of declination gridlines
-
tick_marks
(bool
, default:False
) –If True, then tick marks will be plotted outside the axis. Only supported for rectangular projections (e.g. Mercator, Miller)
-
ra_tick_locations
(list[float]
, default:None
) –List of Right Ascension locations for the tick marks (in hours, 0...24)
-
dec_tick_locations
(list[float]
, default:None
) –List of Declination locations for the tick marks (in degrees, -90...90)
horizon
horizon(style: PathStyle = None, labels: list = ['N', 'E', 'S', 'W'])
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
(PathStyle
, default:None
) –Style of the horizon path. If None, then the plot's style definition will be used.
-
labels
(list
, default:['N', 'E', 'S', 'W']
) –List of labels for cardinal directions. NOTE: labels should be in the order: North, East, South, West.
in_bounds
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
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
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'sedge_color
. -
label
(str
, default:'Moon'
) –How the Moon will be labeled on the plot and legend
nebula
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
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.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,
*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 passmag
andwhere
thenmag
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 thelabels
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. 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
zenith
zenith(
style: ObjectStyle = None, label: str = None, legend_label: str = "Zenith"
)
Plots a marker for the zenith (requires lat
, lon
, and dt
to be defined when creating the plot)
Parameters:
-
style
(ObjectStyle
, default:None
) –Style of the zenith marker. If None, then the plot's style definition will be used.
-
label
(str
, default:None
) –Label for the zenith
-
legend_label
(str
, default:'Zenith'
) –Label in the legend
Map Projections
starplot.Projection
Supported projections for MapPlots
LAMBERT_AZ_EQ_AREA
class-attribute
instance-attribute
Lambert Azimuthal Equal-Area projection - accurately shows area, but distorts angles.
MERCATOR
class-attribute
instance-attribute
Good for declinations between -70 and 70, but distorts objects near the poles
MILLER
class-attribute
instance-attribute
Similar to Mercator: good for declinations between -70 and 70, but distorts objects near the poles
MOLLWEIDE
class-attribute
instance-attribute
Good for showing the entire celestial sphere in one plot
ORTHOGRAPHIC
class-attribute
instance-attribute
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.
ROBINSON
class-attribute
instance-attribute
Good for showing the entire celestial sphere in one plot
STEREOGRAPHIC
class-attribute
instance-attribute
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
Good for objects near the north celestial pole, but distorts objects near the mid declinations
STEREO_SOUTH
class-attribute
instance-attribute
Good for objects near the south celestial pole, but distorts objects near the mid declinations
ZENITH
class-attribute
instance-attribute
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_color=None,
edge_color="red",
line_style="dashed",
edge_width=4,
zorder=1000,
)
Default style for plotting scope and bino field of view circles