Plot API

Ticks API

date_ticks

ticks.date_ticks = <matplotlib.dates.ConciseDateFormatter object>

deg_ticks

ticks.deg_ticks = <UnitFormatter> Unit: `°` | Sep: `` | Scale: 1 | Offset: 0 | Format: `,g`

km_ticks

ticks.km_ticks = <UnitFormatter> Unit: `km` | Sep: ` ` | Scale: 1 | Offset: 0 | Format: `,.10g`

au_ticks

ticks.au_ticks = <UnitFormatter> Unit: `AU` | Sep: ` ` | Scale: 6.6845871222684464e-09 | Offset: 0 | Format: `,g`

km_s_ticks

ticks.km_s_ticks = <UnitFormatter> Unit: `km/s` | Sep: ` ` | Scale: 1 | Offset: 0 | Format: `,g`

m_s_ticks

ticks.m_s_ticks = <UnitFormatter> Unit: `m/s` | Sep: ` ` | Scale: 1000 | Offset: 0 | Format: `,g`

km_pix_ticks

ticks.km_pix_ticks = <UnitFormatter> Unit: `km/pix` | Sep: ` ` | Scale: 1 | Offset: 0 | Format: `,g`

m_pix_ticks

ticks.m_pix_ticks = <UnitFormatter> Unit: `m/pix` | Sep: ` ` | Scale: 1000 | Offset: 0 | Format: `,.0f`

hr_ticks

ticks.hr_ticks = <UnitFormatter> Unit: `h` | Sep: ` ` | Scale: 1 | Offset: 0 | Format: `,g`

lat_ticks

ticks.lat_ticks = <matplotlib.ticker.FuncFormatter object>

lon_e_ticks

ticks.lon_e_ticks = <matplotlib.ticker.FuncFormatter object>

lon_w_ticks

ticks.lon_w_ticks = <matplotlib.ticker.FuncFormatter object>

lon_west_ticks

ticks.lon_west_ticks = <matplotlib.ticker.FuncFormatter object>

UnitFormatter

class planetary_coverage.ticks.ticks.UnitFormatter(unit='', sep=' ', scale=1, offset=0, fmt=',g')

Bases: Formatter

Format numbers with a unit.

Parameters:

• unit (str, optional) – A string that will be appended to the label. It may be None or empty to indicate that no unit should be used. LaTeX special characters are escaped in unit whenever latex mode is enabled, unless is_latex is True.

• sep (str, optional) – Separator used between the value and the unit. Default is a space but it can be remove with empty value.

• scale (float, optional) – Scaling factor (default: 1).

• offset (float, optional) – Base offset (default: 0).

• fmt (str, optional) – Number formatter (default: ',g').

Astronomical unit AU in km

ticks.AU = 149597870.7

Planetary Maps API

MERCURY

maps.MERCURY = <Map> Mercury | Radius 2439.7 km

VENUS

maps.VENUS = <Map> Venus | Radius 6051.8 km

EARTH

maps.EARTH = <Map> Earth | Radius 6371.0 km

MOON

maps.MOON = <Map> Moon | Radius 1737.4 km

MARS

maps.MARS = <Map> Mars | Radius 3389.5 km

JUPITER

maps.JUPITER = <Map> Jupiter | Radius 69911.3 km

IO

maps.IO = <Map> Io | Radius 1821.5 km

EUROPA

maps.EUROPA = <Map> Europa | Radius 1560.8 km

GANYMEDE

maps.GANYMEDE = <Map> Ganymede | Radius 2631.2 km

CALLISTO

maps.CALLISTO = <Map> Callisto | Radius 2410.3 km

SATURN

maps.SATURN = <Map> Saturn | Radius 58232.0 km

ENCELADUS

maps.ENCELADUS = <Map> Enceladus | Radius 252.1 km

TITAN

maps.TITAN = <Map> Titan | Radius 2574.8 km

URANUS

maps.URANUS = <Map> Uranus | Radius 25362.2 km

NEPTUNE

maps.NEPTUNE = <Map> Neptune | Radius 24622.2 km

PLUTO

maps.PLUTO = <Map> Pluto | Radius 1195.0 km

CHARON

maps.CHARON = <Map> Charon | Radius 605.0 km

MAPS

maps.MAPS = {'CALLISTO': <Map> Callisto | Radius 2410.3 km, 'CHARON': <Map> Charon | Radius 605.0 km, 'EARTH': <Map> Earth | Radius 6371.0 km, 'ENCELADUS': <Map> Enceladus | Radius 252.1 km, 'EUROPA': <Map> Europa | Radius 1560.8 km, 'GANYMEDE': <Map> Ganymede | Radius 2631.2 km, 'IO': <Map> Io | Radius 1821.5 km, 'JUPITER': <Map> Jupiter | Radius 69911.3 km, 'MARS': <Map> Mars | Radius 3389.5 km, 'MERCURY': <Map> Mercury | Radius 2439.7 km, 'MOON': <Map> Moon | Radius 1737.4 km, 'NEPTUNE': <Map> Neptune | Radius 24622.2 km, 'PLUTO': <Map> Pluto | Radius 1195.0 km, 'SATURN': <Map> Saturn | Radius 58232.0 km, 'TITAN': <Map> Titan | Radius 2574.8 km, 'URANUS': <Map> Uranus | Radius 25362.2 km, 'VENUS': <Map> Venus | Radius 6051.8 km}

Map

class planetary_coverage.maps.Map(fname, body=None, centered_0=False, size=None, radius=None)

Bases: object

Map object.

By default, the map must be in a equirectangular projection centered in longitude 180°. You can set centered_0=True to flip the image internally.

Parameters:

• fname (str or pathlib.Path) – Equirectangular map filename.

• body (str, optional) – Target body name.

• centered_0 (bool, optional) – Flip the image if the map is center on 0° (default: False).

• size (tuple, optional) – Optional (width, height) image size.

• radius (float, optional) – Optional body radius (km).

property fname: Path

Map filename.

property img

Map background map image.

map(fout=False)

Plot planetary map in Equirectangular projection.

Parameters:

fout (str or pathlib.Path, optional) – Save map as image (default False).

Returns:

Output save file or Matplotlib axe object.

Return type:

pathlib.Path or matplotlib.axes.Axes

property radius

Body radius (km).

Projections API

ProjAxes

class planetary_coverage.projections.axes.ProjAxes(*args, proj='equi', bg=None, bg_extent=False, target='', **kwargs)

Bases: Axes

An abstract base class for geographic projections.

clear()

Clear axes.

plot(*args, scalex=True, scaley=True, data=None, **kwargs)

Generic plot function with map projection.

Warning

If explicit X and Y values are provided, they will considered as East Longitude and Latitude angles (in degrees).

See also

matplotlib.pyplot.plot

scatter(*args, **kwargs)

Scatter plot with map projection.

See also

matplotlib.pyplot.scatter

plot_colorline(x, y, data, vmin=None, vmax=None, label=None, fmt=None, orientation='horizontal', cbar=True, **kwargs)

Plot a colored line with a colorbar.

Parameters:

• x (numpy.ndarray) – Projected x-coordinates.

• y (numpy.ndarray) – Projected y-coordinates.

• data (numpy.ndarray) – Value to use to color the line.

• cmap (str, optional) – Matplotlib colormap name (default: turbo_r)

• vmin (int or float) – Color scaling min value. If None is provided (default) the data are scaled to the lowest (not-NaN) value.

• vmax (int or float) – Color scaling max value. If None is provided (default) the data are scaled to the lowest (not-NaN) value.

• norm (matplotlib.colors.Normalize) – Normalization colors normalizer. By default the values will be normalized between vmin and vmax.

• label (str, optional) – Colorbar label.

• fmt (str, optional) – Colorbar ticks formatter.

• orientation (str, optional) – Colorbar orientation (default: horizontal).

• **kwargs – Keyword attributes for LineCollection.

Note

If the range provided (with vmin and vmax) is smaller than the range of the data, the colorbar will be extended with arrows.

text(x, y, s, fontdict=None, clip_on=True, **kwargs)

Add text to the axes.

Note

Set clip on to True by default.

add_path(path, *args, **kwargs)

Draw path.

add_patch(p)

Draw patch.

add_collection(collection, autolim=True)

Draw patches collection.

legend(*args, **kwargs)

Add HandlerPolyCollection to handler_map for PatchCollection.

colorbar(vmin, vmax, cmap='turbo_r', orientation='horizontal', shrink=0.6, aspect=40, pad=0.075, **kwargs)

Add a standalone colorbar on the axis.

Parameters:

• vmin (int or float, optional) – Color scaling min value. If None is provided (default) the data are scaled to the lowest (not-NaN) value.

• vmax (int or float, optional) – Color scaling max value. If None is provided (default) the data are scaled to the lowest (not-NaN) value.

• cmap (str, optional) – Matplotlib colormap name (default: turbo_r)

• orientation (str, optional) – Colorbar orientation (default: horizontal).

• label (str, optional) – Colorbar label (shortcuts are available).

• **kwargs – Keyword attributes for Colorbar.

Returns:

Output colorbar.

Return type:

matplotlib.colorbar.Colorbar

twin_colorbar(label=None, format=None, offset=0.05, ticks=None, **kwargs)

Twin colorbar with a secondary axis.

Parameters:

• label (str, optional) – Twin colorbar label (no shortcut).

• format (matplotlib.ticker.Formatter, optional) – Optional ticks formatter.

• offset (float, optional) – Colorbar offset (default: 0.05).

• ticks (list, optional) – Custom list of ticks (default: None).

set_longitude_grid(degrees)

Set the number of degrees between each longitude grid.

set_latitude_grid(degrees)

Set the number of degrees between each longitude grid.

set_lon_ticks(key, secondary=False)

Toggle longitude ticks (East/West and top/bottom).

Parameters:

• key (str) – Longitude ticks format. Possible values: 'east' | '0 360' or 'west' | '360 0'

• secondary (bool, optional) – Display the ticks on top secondary axis (default: False)

Warning

The values provided in the plot are always in East longitude. Here, only the axis ticks are changed (the data are not re-projected).

set_lat_ticks(secondary=False)

Toggle latitude secondary ticks.

Parameters:

secondary (bool, optional) – Display the ticks on right secondary axis (default: False)

Warning

The values provided in the plot are always in East longitude. Here, only the axis ticks are changed (the data are not re-projected).

set_view(*args, margin=5)

Center view on object coordinates.

Parameters:

• *args ([float, float, float, float] or object) – East longitudes and latitudes to center the view on. It can be either: - lon_e_min, lon_e_max, lat_min, lat_max - [lon_e_min, lon_e_max], [lat_min, lat_max] - [lon_e_min, lon_e_max, lat_min, lat_max] - an object with lonlat property - an object with lons_e and lats properties

• margin (int or float) – Margin percentage fraction of the object to add to the sides. Default: 5%.

Raises:

ValueError – If the provided coordinates are invalid.

Note

The limits are clipped on the side of the projection extent.

set_xlim(left=None, right=None, emit=True, auto=False, **kwargs)

Rescale the x-map coordinate limits.

Note

If both sides are provided the ticks grid is readjusted.

set_ylim(bottom=None, top=None, emit=True, auto=False, **kwargs)

Rescale the y-map coordinate limits.

Note

If both sides are provided the ticks grid is readjusted.

set_background()

Set image basemap background.

set(*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, facecolor=<UNSET>, forward_navigation_events=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, lat_ticks=<UNSET>, latitude_grid=<UNSET>, lon_ticks=<UNSET>, longitude_grid=<UNSET>, mouseover=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, subplotspec=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, view=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:

adjustable: {‘box’, ‘datalim’} agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: float or None anchor: (float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …} animated: bool aspect: {‘auto’, ‘equal’} or float autoscale_on: bool autoscalex_on: unknown autoscaley_on: unknown axes_locator: Callable[[Axes, Renderer], Bbox] axisbelow: bool or ‘line’ box_aspect: float or None clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None facecolor or fc: color figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure forward_navigation_events: bool or “auto” frame_on: bool gid: str in_layout: bool label: object lat_ticks: unknown latitude_grid: unknown lon_ticks: unknown longitude_grid: unknown mouseover: bool navigate: bool navigate_mode: unknown path_effects: list of .AbstractPathEffect picker: None or bool or float or callable position: [left, bottom, width, height] or ~matplotlib.transforms.Bbox prop_cycle: ~cycler.Cycler rasterization_zorder: float or None rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None subplotspec: unknown title: str transform: ~matplotlib.transforms.Transform url: str view: unknown visible: bool xbound: (lower: float, upper: float) xlabel: str xlim: unknown xmargin: float greater than -0.5 xscale: unknown xticklabels: unknown xticks: unknown ybound: (lower: float, upper: float) ylabel: str ylim: unknown ymargin: float greater than -0.5 yscale: unknown yticklabels: unknown yticks: unknown zorder: float

Equirectangular

class planetary_coverage.projections.Equirectangular(lon_e_0=180, lat_0=0, lat_ts=0, x_0=None, y_0=0, target=None, radius=None)

Bases: GroundProjection

Equirectangular projection object.

a.k.a. Plate Carrée and Equidistant Cylindrical.

Sources:

• https://proj.org/operations/projections/eqc.html

• proj4js/proj4js

Parameters:

• lon_e_0 (float, optional) – Center east longitude.

• lat_0 (float, optional) – Center latitude (North Pole by default).

• lat_ts (float, optional) – Latitude of true scale.

• x_0 (float, optional) – False easting (default: r * lambda_0). See note below.

• y_0 (float, optional) – False northing (default: 0).

• target (str) – Planet name.

• radius (float, optional) – Planet radius [km]. Use the target mean radius if the target is a Planet object.

Note

Here, by default the longitudes are defined eastward in [0°, 360°], The false easting x_0, if not provided, is automatically adjusted to make projected coordinates and real coordinates consistent. You can fall back to the Earth convention (±180°) with lon_e_0=0 attribute.

property lat_ts

Latitude of true scale [degree].

property rc

Cosine of latitude of origin.

property xc

Projected x crossing meridian value.

property yc

Projected y pole value.

property extent

Projection extent.

property proj4

Proj4 definition.

property wkt

WKT definition.

xy(lon_e, lat, value=None)

Convert latitude/longitude coordinates in map coordinates.

Parameters:

• lon_e (float or array) – East longitude [degree].

• lat (float or array) – Latitude [degree].

• value (float or array) – Value associated with the point.

Returns:

X-Y map coordinates.

Return type:

float or array, float or array

Note

The right side edge is kept during the warp of the longitudes.

lonlat(x, y)

Convert map coordinates in latitude/longitude coordinates.

Parameters:

• x (float or array) – X-coordinate on the map [m].

• y (float or array) – Y-coordinate on the map [m].

Returns:

East longitude and latitude [degree].

Return type:

float or array, float or array

xy_plot(lons_e, lats, values=None)

Plot latitude/longitude coordinates in a map.

Parameters:

• lons_e (float or array) – East longitude [degree].

• lats (float or array) – Latitude [degree].

• values (float or array) – Values associated with the points.

Returns:

X-Y map coordinates.

Return type:

float or array, float or array

xy_path(path)

Convert path vertices in map coordinates.

Parameters:

path (matplotlib.path.Path) – Matplotlib path in east-longitude and latitude coordinates.

Returns:

Path in map coordinates.

Return type:

matplotlib.path.Path

Raises:

ValueError – If the polygon cross more than 2 times the anti-meridian.

Note

Bézier curves control points are replaced by regular polygons.

EquirectangularGC

planetary_coverage.projections.EquirectangularGC

alias of Equirectangular

class planetary_coverage.projections.equi_gc.Equirectangular(lon_e_0=180, lat_0=0, lat_ts=0, x_0=None, y_0=0, target=None, radius=None, npt_gc=8)

Bases: Equirectangular

Equirectangular projection with great circle object.

a.k.a. Plate Carrée and Equidistant Cylindrical.

Parameters:

• lon_e_0 (float, optional) – Center east longitude.

• lat_0 (float, optional) – Center latitude (North Pole by default).

• lat_ts (float, optional) – Latitude of true scale.

• x_0 (float, optional) – False easting (default: r * lambda_0). See note below.

• y_0 (float, optional) – False northing (default: 0).

• target (str) – Planet name.

• radius (float, optional) – Planet radius [km]. Use the target mean radius if the target is a Planet object.

See also

planetary_coverage.projections.equi.Equirectangular, planetary_coverage.projections.proj.GroundProjection

vc(path)

Get projected vertices and codes (and close the polygon if needed).

Add new intermediate points along great circles to get defined the shape of the polygons.

Parameters:

path (matplotlib.path.Path) – Matplotlib path in east-longitude and latitude coordinates.

Returns:

X and Y vertices and path code.

Return type:

[float], [float], [int]

GroundProjection

class planetary_coverage.projections.proj.GroundProjection(lon_e_0=0, lat_0=0, target=None, radius=None)

Bases: Projection

Abstract ground projection object.

Parameters:

• lon_e_0 (float, optional) – Center east longitude.

• lat_0 (float, optional) – Center latitude.

• target (str) – Body name.

• radius (float, optional) – Body radius [km].

property lat_0

Latitude of origin [degree].

property clat0

Cosine of latitude of origin.

property slat0

Sine of latitude of origin.

property lon_e_0

East central meridian [degree].

property clon0_e

Cosine of west central meridian.

property slon0_e

Sine of west central meridian.

property target

Body target.

property radius

Target body radius [km].

property r

Target body radius [m].

property proj4

Proj4 definition.

property wkt

WKT definition.

Projection

class planetary_coverage.projections.proj.Projection

Bases: object

Abstract ground projection object.

property extent

Projection extent.

xy(lon_e, lat, value=None)

Convert latitude/longitude coordinates in map coordinates.

Parameters:

• lon_e (float or array) – East longitude [degree].

• lat (float or array) – Latitude [degree].

• value (float or array) – Value associated with the point.

Returns:

X-Y map coordinates.

Return type:

float or array, float or array

lonlat(x, y)

Convert map coordinates in latitude/longitude coordinates.

Parameters:

• x (float or array) – X-coordinate on the map [m].

• y (float or array) – Y-coordinate on the map [m].

Returns:

East longitude and latitude [degree].

Return type:

float or array, float or array

xy_plot(lons_e, lats, values=None)

Plot latitude/longitude coordinates in a map.

Parameters:

• lons_e (float or array) – East longitude [degree].

• lats (float or array) – Latitude [degree].

• values (float or array) – Values associated with the points.

Returns:

X-Y map coordinates.

Return type:

float or array, float or array

vc(path)

Get projected vertices and codes (and close the polygon if needed).

Parameters:

path (matplotlib.path.Path) – Matplotlib path in east-longitude and latitude coordinates.

Returns:

X and Y vertices and path code.

Return type:

[float], [float], [int]

xy_path(path)

Convert path vertices in map coordinates.

Parameters:

path (matplotlib.path.Path) – Matplotlib path in east-longitude and latitude coordinates.

Returns:

Path in map coordinates.

Return type:

matplotlib.path.Path

xy_patch(patch)

Convert patch vertices in map coordinates.

Parameters:

patch (matplotlib.patches.Patch) – Matplotlib patch in east-longitude and latitude coordinates.

Returns:

Patch in map coordinates.

Return type:

matplotlib.patches.Patch

Note

Only face and edge colors are preserved.

xy_collection(collection)

Convert collection vertices in map coordinates.

Parameters:

collection (matplotlib.collections.PatchCollection or matplotlib.collections.PathCollection) – Matplotlib collection in west-longitude and latitude coordinates.

Returns:

Collection in map coordinates.

Return type:

PatchCollection or PathCollection

meridians(lons_e=None, exclude=None, lon_e_min=0, lon_e_max=360, dlon_e=30, lat_min=-80, lat_max=80, nlat=65)

Projected meridians grid.

parallels(lats=None, exclude=None, lat_min=-80, lat_max=80, dlat=10, lon_e_min=0, lon_e_max=360, nlon_e=73)

Projected parallels grid.