`planetmapper`

Hint

See also the page of examples of using the PlanetMapper Python package

PlanetMapper: A Python package for visualising, navigating and mapping Solar System observations.

The core logic of this code is based on conversion between different coordinate systems of interest. The xy and radec coordinate systems define positions from the point of view of the observer while the lonlat coordinate system defines locations on the surface of the target body:

xy: image pixel coordinates. These coordinates count the number of pixels in an observed image with the bottom left pixel defined as (0, 0), and the x and y coordinates defined as normal. Integer coordinates represent the middle of the corresponding pixel, so (0, 3) covers x values from -0.5 to 0.5 and y values from 2.5 to 3.5.

radec: observer frame RA/Dec sky coordinates. These are the right ascension and declination which define the position in the sky of a point from the point of view of the observer. These coordinates are expressed in degrees. See Wikipedia for more details.

lonlat: planetographic coordinates on target body. These are the planetographic longitude and latitude coordinates of a point on the surface of the target body. These coordinates are expressed in degrees. See Wikipedia and the SPICE documentation for more details. The surface altitude can also be customised with the alt parameter, for example, body.lonlat2radec(12, 34, alt=1000) will calculate the RA/Dec coordinates of the point at planetographic coordinates (12, 34) and with an altitude of 1000 km. If planetocentric coordinates are desired, then functions Body.graphic2centric_lonlat() and Body.centric2graphic_lonlat() can be used to convert between planetographic and planetocentric coordinates.

km: defines the distance in the image plane from the centre of the target body in km with the target’s north pole pointing up. This coordinate system is similar to the radec and xy coordinate systems, but has the image zoomed so that the planet’s radius is fixed and rotated so that the north pole points up. It can therefore be useful for comparing observations of the same target taken at different times.

angular: relative angular coordinates in arcseconds. By default, the angular coordinates are centred on the target body, with the same rotation as the radec coordinates, meaning the angular coordinates define the distance in arcseconds from the centre of the target body. However, the origin and rotation of the angular coordinates can also be customised to measure the angular distance in arcseconds relative to an arbitrary point in the sky. See Body.radec2angular() for more details on customising the angular coordinates. Similarly to the km coordinate system, this can be useful for comparing observations of the same target taken at different times. It also can be used to minimise the distortion present when plotting radec coordinates for targets located near the celestial pole.

Dimension	Unit
Angles (RA, Dec, longitude, latitude…)	degrees
Angles (relative angular coordinates, plate scale…)	arcseconds [1]
Distances	km
Time intervals	seconds
Speeds	km/s
Dates (timezone)	UTC

Note

By default, all angles should be degrees unless using a function/value explicitly named with _arcsec or _radians, or using the relative angular coordinate system. Note that angles in SPICE are radians, so extra care should be taken converting to/from SPICE values.

These additional coordinate systems are mainly used for internal calculations and to interface with SPICE:

targvec - target frame rectangular vector.
obsvec - observer frame (e.g. J2000) rectangular vector.
obsvec_norm - normalised observer frame rectangular vector.
rayvec - target frame rectangular vector from observer to point.

This code makes extensive use of the the spiceypy package which provides a Python wrapper around NASA’s cspice toolkit. See the spiceypy documentation and the SPICE documentation for more information.

If you use PlanetMapper in your research, please cite the following paper:

King et al., (2023). PlanetMapper: A Python package for visualising, navigating and mapping Solar System observations. Journal of Open Source Software, 8(90), 5728, https://doi.org/10.21105/joss.05728

Warning

This code is in active development, so may contain bugs! Any issues, bugs and suggestions can be reported on GitHub.

planetmapper.run_gui(path: str | os.PathLike | None = None) → None[source]

Launch the PlanetMapper Graphical User Interface (GUI) to fit observations.

This is the Python equivalent of running planetmapper from the command line. See the user interface documentation for more details about how to use the GUI.

See also ring_radec().

other_bodies_of_interest: list[Body | BasicBody]: List of other bodies of interest to mark when plotting. Add to this list using add_other_bodies_of_interest().

coordinates_of_interest_lonlat: list[tuple[float, float]]

List of (lon, lat) coordinates of interest on the surface of the target body to mark when plotting (points which are not visible will not be plotted). To add a new point of interest, simply append a coordinate pair to this list:

body.coordinates_of_interest_lonlat.append((0, -22))

coordinates_of_interest_radec: list[tuple[float, float]]

List of (ra, dec) sky coordinates of interest to mark when plotting (e.g. background stars). To add new point of interest, simply append a coordinate pair to this list:

body.coordinates_of_interest_radec.append((200, -45))

create_other_body(other_target: str | int, fallback_to_basic_body: Literal[False]) → Body[source]

create_other_body(other_target: str | int, fallback_to_basic_body: bool = True) → planetmapper.body.Body | planetmapper.basic_body.BasicBody

Create a Body instance using identical parameters but just with a different target. For example, the europa body created here will have identical parameters (see below) to the jupiter body, just with a different target.

jupiter = Body('Jupiter', '2000-01-01', observer='Moon')
europa = jupiter.create_other_body('Europa')

The parameters kept the same are utc, observer, observer_frame, illumination_source, aberration_correction, subpoint_method, and surface_method.

If a full Body instance cannot be created due to insufficient data in the SPICE kernel, a BasicBody instance will be created instead. This is useful for objects such as minor satellites which do not have known radius data.

See also SpiceBase.replace() for a similar method which can be used to create new Body instances with custom parameters replaced.

Parameters:

other_target – Name of the other target, passed to Body
fallback_to_basic_body – If a full Body instance cannot be created due to insufficient data in the SPICE kernel, attempt to create a BasicBody instance instead.

Returns:

Body or BasicBody instance which corresponds to other_target.

add_other_bodies_of_interest(*other_targets: str | int, only_visible: bool = False) → None[source]

Add targets to the list of other_bodies_of_interest of interest to mark when plotting. The other targets are created using create_other_body(). For example, to add the Galilean moons as other targets to a Jupiter body, use

body = planetmapper.Body('Jupiter')
body.add_other_bodies_of_interest('Io', 'Europa', 'Ganymede', 'Callisto')

Integer SPICE ID codes can also be provided, which can be used to simplify adding multiple satellites to plots.

body = planetmapper.Body('Uranus')
body.add_other_bodies_of_interest(*range(701, 711))
# Uranus' satellites have ID codes 701, 702, 703 etc, so this adds 10 moons
# with a single function call

Parameters:

*other_targets – Names of the other targets, passed to Body
only_visible – If True, other targets which are hidden behind the target will not be added to other_bodies_of_interest.

add_satellites_to_bodies_of_interest(skip_insufficient_data: bool = False, only_visible: bool = False) → None[source]

Automatically add all satellites in the target planetary system to other_bodies_of_interest.

This uses the NAIF ID codes to identify the satellites. For example, Uranus has an ID of 799, and its satellites have codes 701, 702, 703…, so any valid object with a code in the range 701 to 798 is added for Uranus.

Parameters:

skip_insufficient_data – If True, satellites with insufficient data in the SPICE kernel will be skipped. If False, an exception will be raised if a satellite (a) has a valid ID code (i.e. spice.bodc2s works for the satellite) and (b) it has insufficient data.
only_visible – If True, satellites which are hidden behind the target body will not be added.

ring_radii_from_name(name: str) → list[float][source]

Get list of ring radii in km for a named ring.

This is a convenience function to load data from named_ring_data.

Parameters:: name – Name of ring. This is case insensitive and, “ring” suffix is optional and non-ASCII versions are allowed. For example, 'liberte' will load the 'Liberté' ring radii for Uranus and 'amalthea' will load the 'Amalthea Ring' radii for Jupiter.
Raises:: ValueError – if no ring with the provided name is found.
Returns:: List of ring radii in km. If the length of this list is 2, then the values give the inner and outer radii of the ring respectively. Otherwise, the length should be 1, meaning the ring has a single radius.

add_named_rings(*names: str) → None[source]

Add named rings to ring_radii so that they appear when creating wireframe plots. If no arguments are provided (i.e. calling body.add_named_rings()), then all rings in named_ring_data are added to ring_radii.

This is a convenience function to add data from named_ring_data to ring_radii.

Parameters:: *names – Ring names which are passed to ring_radii_from_name(). If no names are provided then all rings in named_ring_data are added.

lonlat2radec(lon: FloatOrArray, lat: FloatOrArray, *, alt: float = 0.0, not_visible_nan: bool = False) → tuple[FloatOrArray, FloatOrArray][source]

Convert longitude/latitude coordinates on the target body to RA/Dec sky coordinates for the observer.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

lon – Longitude of point(s) on target body.
lat – Latitude of point(s) on target body.
alt – Altitude of point above the surface of the target body in km.
not_visible_nan – If True, then the returned RA/Dec values will be NaN if the point is not visible to the observer (e.g. it is on the far side of the target). If False (the default), then (ra, dec) coordinates will be returned, even if the point is not directly visible.

Returns:

(ra, dec) tuple containing the RA/Dec coordinates of the point(s).

radec2lonlat(ra: FloatOrArray, dec: FloatOrArray, *, not_found_nan: bool = True, alt: float = 0.0) → tuple[FloatOrArray, FloatOrArray][source]

Convert RA/Dec sky coordinates for the observer to longitude/latitude coordinates on the target body.

The provided RA/Dec will not necessarily correspond to any longitude/latitude coordinates, as they could be ‘missing’ the target and instead be observing the background sky. In this case, the returned longitude/latitude values will be NaN if not_found_nan is True (the default) or this function will raise an error if not_found_nan is False.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

ra – Right ascension of point(s) in the sky of the observer.
dec – Declination of point(s) in the sky of the observer.
not_found_nan – Controls behaviour when the input ra and dec coordinates are missing the target body.
alt – Altitude of returned (lon, lat) point above the surface of the target body in km.

Returns:

(lon, lat) tuple containing the longitude/latitude coordinates on the target body. If the provided RA/Dec coordinates are missing the target body and not_found_nan is True, then the lon and lat values will both be NaN.

Raises:

NotFoundError – If the provided RA/Dec coordinates are missing the target body and not_found_nan is False, then NotFoundError will be raised.

lonlat2targvec(lon: float, lat: float, *, alt: float = 0.0, not_visible_nan: bool = False) → ndarray[source]

Convert longitude/latitude coordinates on the target body to rectangular vector centred in the target frame (e.g. for use as an input to a SPICE function).

Parameters:

lon – Longitude of point on target body.
lat – Latitude of point on target body.
alt – Altitude of point above the surface of the target body in km.
not_visible_nan – If True, then the returned RA/Dec values will be NaN if the point is not visible to the observer (e.g. it is on the far side of the target). If False (the default), then (ra, dec) coordinates will be returned, even if the point is not directly visible.

Returns:

Numpy array corresponding to the 3D rectangular vector describing the longitude/latitude point in the target frame of reference.

targvec2lonlat(targvec: ndarray, *, alt: float = 0.0) → tuple[float, float][source]

Convert rectangular vector centred in the target frame to longitude/latitude coordinates on the target body (e.g. to convert the output from a SPICE function).

Parameters:

targvec – 3D rectangular vector in the target frame of reference.
alt – Altitude of returned (lon, lat) point above the surface of the target body in km.

Returns:

(lon, lat) tuple containing the longitude and latitude corresponding to the input vector.

radec2angular(ra: FloatOrArray, dec: FloatOrArray, *, origin_ra: float | None = None, origin_dec: float | None = None, coordinate_rotation: float = 0.0) → tuple[FloatOrArray, FloatOrArray][source]

Convert RA/Dec sky coordinates for the observer to relative angular coordinates.

The origin and rotation of the relative angular coordinates can be customised using the origin_ra, origin_dec and coordinate_rotation arguments. If these are not provided, the origin will be the centre of the target body and the rotation will be the same as in RA/Dec coordinates.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

ra – Right ascension of point(s) in the sky of the observer.
dec – Declination of point(s) in the sky of the observer.
origin_ra – Right ascension (RA) of the origin of the relative angular coordinates. If None, the RA of the centre of the target body is used.
origin_dec – Declination (Dec) of the origin of the relative angular coordinates. If None, the Dec of the centre of the target body is used.
coordinate_rotation – Angle in degrees to rotate the relative angular coordinates around the origin, relative to the positive declination direction. The default coordinate_rotation is 0.0, so the target will have the same orientation as in RA/Dec coordinates.

Returns:

(angular_x, angular_y) tuple containing the relative angular coordinates of the point(s) in arcseconds.

angular2radec(angular_x: FloatOrArray, angular_y: FloatOrArray, **angular_kwargs: Unpack[AngularCoordinateKwargs]) → tuple[FloatOrArray, FloatOrArray][source]

Convert relative angular coordinates to RA/Dec sky coordinates for the observer.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

angular_x – Angular coordinate(s) in the x direction in arcseconds.
angular_y – Angular coordinate(s) in the y direction in arcseconds.
**angular_kwargs – Additional arguments are used to customise the origin and rotation of the relative angular coordinates. See radec2angular() for details.

Returns:

(ra, dec) tuple containing the RA/Dec coordinates of the point(s).

angular2lonlat(angular_x: FloatOrArray, angular_y: FloatOrArray, *, not_found_nan: bool = True, alt: float = 0.0, **angular_kwargs: Unpack[AngularCoordinateKwargs]) → tuple[FloatOrArray, FloatOrArray][source]

Convert relative angular coordinates to longitude/latitude coordinates on the target body.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

angular_x – Angular coordinate(s) in the x direction in arcseconds.
angular_y – Angular coordinate(s) in the y direction in arcseconds.
not_found_nan – Controls behaviour when the input angular_x and angular_y coordinates are missing the target body.
alt – Altitude of returned (lon, lat) point above the surface of the target body in km.
**angular_kwargs – Additional arguments are used to customise the origin and rotation of the relative angular coordinates. See radec2angular() for details.

Returns:

(lon, lat) tuple containing the longitude and latitude of the point(s). If the provided angular coordinates are missing the target body and not_found_nan is True, then the lon and lat values will both be NaN.

Raises:

NotFoundError – If the provided angular coordinates are missing the target body and not_found_nan is False, then NotFoundError will be raised.

lonlat2angular(lon: FloatOrArray, lat: FloatOrArray, *, alt: float = 0.0, not_visible_nan: bool = False, **angular_kwargs: Unpack[AngularCoordinateKwargs]) → tuple[FloatOrArray, FloatOrArray][source]

Convert longitude/latitude coordinates on the target body to relative angular coordinates.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

lon – Longitude of point(s) on target body.
lat – Latitude of point(s) on target body.
alt – Altitude of point above the surface of the target body in km.
not_visible_nan – If True, then the returned RA/Dec values will be NaN if the point is not visible to the observer (e.g. it is on the far side of the target). If False (the default), then (ra, dec) coordinates will be returned, even if the point is not directly visible.
**angular_kwargs – Additional arguments are used to customise the origin and rotation of the relative angular coordinates. See radec2angular() for details.

Returns:

(angular_x, angular_y) tuple containing the relative angular coordinates of the point(s) in arcseconds.

km2radec(km_x: FloatOrArray, km_y: FloatOrArray) → tuple[FloatOrArray, FloatOrArray][source]

Convert distance in target plane to RA/Dec sky coordinates for the observer.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

km_x – Distance(s) in target plane in km in the East-West direction.
km_y – Distance(s) in target plane in km in the North-South direction.

Returns:

(ra, dec) tuple containing the RA/Dec coordinates of the point(s).

radec2km(ra: FloatOrArray, dec: FloatOrArray) → tuple[FloatOrArray, FloatOrArray][source]

Convert RA/Dec sky coordinates for the observer to distances in the target plane.

The input coordinates can either be floats or NumPy arrays of values. If both

input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

ra – Right ascension of point(s) in the sky of the observer.
dec – Declination of point(s) in the sky of the observer.

Returns:

(km_x, km_y) tuple containing distances in km in the target plane in the East-West and North-South directions respectively.

km2lonlat(km_x: FloatOrArray, km_y: FloatOrArray, *, not_found_nan: bool = True, alt: float = 0.0) → tuple[FloatOrArray, FloatOrArray][source]

Convert distance in target plane to longitude/latitude coordinates on the target body.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

km_x – Distance(s) in target plane in km in the East-West direction.
km_y – Distance(s) in target plane in km in the North-South direction.
not_found_nan – Controls behaviour when the input km_x and km_y coordinates are missing the target body.
alt – Altitude of returned (lon, lat) point above the surface of the target body in km.

Returns:

(lon, lat) tuple containing the longitude and latitude of the point(s). If the provided km coordinates are missing the target body, then the lon and lat values will both be NaN if not_found_nan is True, otherwise a NotFoundError will be raised.

Raises:

NotFoundError – If the provided km coordinates are missing the target body
and not_found_nan is False, then NotFoundError will be raised. –

lonlat2km(lon: FloatOrArray, lat: FloatOrArray, *, alt: float = 0.0, not_visible_nan: bool = False) → tuple[FloatOrArray, FloatOrArray][source]

Convert longitude/latitude coordinates on the target body to distances in the target plane.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

lon – Longitude of point(s) on the target body.
lat – Latitude of point(s) on the target body.
alt – Altitude of point above the surface of the target body in km.
not_visible_nan – If True, then the returned RA/Dec values will be NaN if the point is not visible to the observer (e.g. it is on the far side of the target). If False (the default), then (ra, dec) coordinates will be returned, even if the point is not directly visible.

Returns:

(km_x, km_y) tuple containing distances in km in the target plane in the East-West and North-South directions respectively.

km2angular(km_x: FloatOrArray, km_y: FloatOrArray, **angular_kwargs: Unpack[AngularCoordinateKwargs]) → tuple[FloatOrArray, FloatOrArray][source]

Convert distance in target plane to relative angular coordinates.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

km_x – Distance(s) in target plane in km in the East-West direction.
km_y – Distance(s) in target plane in km in the North-South direction.
**angular_kwargs – Additional arguments are used to customise the origin and rotation of the relative angular coordinates. See radec2angular() for details.

Returns:

(angular_x, angular_y) tuple containing the relative angular coordinates of the point(s) in arcseconds.

angular2km(angular_x: FloatOrArray, angular_y: FloatOrArray, **angular_kwargs: Unpack[AngularCoordinateKwargs]) → tuple[FloatOrArray, FloatOrArray][source]

Convert relative angular coordinates to distances in the target plane.

The input coordinates can either be floats or NumPy arrays of values. If both input coordinates are floats, the output will be a tuple of floats. If either of the input coordinates are arrays, the inputs will be broadcast together and a tuple of NumPy arrays will be returned.

Parameters:

angular_x – Angular coordinate(s) in the x direction in arcseconds.
angular_y – Angular coordinate(s) in the y direction in arcseconds.
**angular_kwargs – Additional arguments are used to customise the origin and rotation of the relative angular coordinates. See radec2angular() for details.

Returns:

(km_x, km_y) tuple containing distances in km in the target plane in the East-West and North-South directions respectively.

limb_radec(*, alt: float = 0.0, **kwargs) → tuple[numpy.ndarray, numpy.ndarray][source]

Calculate the RA/Dec coordinates of the target body’s limb.

Parameters:

npts – Number of points in the generated limb.
alt – Altitude of the limb above the surface of the target body, in km.

Returns:

(ra, dec) tuple of coordinate arrays.

limb_radec_by_illumination(*, alt: float = 0.0, **kwargs) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Calculate RA/Dec coordinates of the dayside and nightside parts of the target body’s limb.

Output arrays are like the outputs of limb_radec(), but the dayside coordinate arrays have non-illuminated locations replaced with NaN and the nightside arrays have illuminated locations replaced with NaN.

Parameters:

npts – Number of points in the generated limbs.
alt – Altitude of the limbs above the surface of the target body, in km.

Returns:

(ra_day, dec_day, ra_night, dec_night) tuple of coordinate arrays of the dayside then nightside parts of the limb.

limb_lonlat(alt: float = 0.0, **kwargs) → tuple[numpy.ndarray, numpy.ndarray][source]

Calculate the Lon/Lat coordinates of the target body’s limb.

Parameters:

npts – Number of points in the generated limb.
alt – Altitude of the limb above the surface of the target body, in km.

Returns:

(lon, lat) tuple of coordinate arrays.

limb_coordinates_from_radec(ra: float, dec: float, *, alt: float = 0.0) → tuple[float, float, float][source]

Calculate the coordinates relative to the target body’s limb for a point in the sky.

The coordinates are calculated for the point on the ray (as defined by RA/Dec) which is closest to the target body’s limb.

Parameters:

ra – Right ascension of point in the sky of the observer.
dec – Declination of point in the sky of the observer.
alt – Altitude of the reference limb above the surface of the target body, in km.

Returns:

(lon, lat, dist) tuple of coordinates relative to the target body’s limb. lon and lat give the planetographic longitude and latitude of the point on the limb closest to the point defined by ra and dec. dist gives the distance from the point defined by ra and dec to the target’s limb. Positive values of dist mean that the point is above the limb and negative values mean that the point is below the limb (i.e. on the target body’s disc).

test_if_lonlat_visible(lon: float, lat: float, *, alt: float = 0.0) → bool[source]

Test if longitude/latitude coordinate on (or above) the target body is visible.

Parameters:

lon – Longitude of point on target body.
lat – Latitude of point on target body.
alt – Altitude of point above the surface of the target body in km.

Returns:

True if the point is visible from the observer, otherwise False.

other_body_los_intercept(other: str | int | planetmapper.body.Body | planetmapper.basic_body.BasicBody, *, alt: float = 0.0) → Union[None, Literal['transit', 'hidden', 'part transit', 'part hidden', 'same']][source]

Test for line-of-sight intercept between the target body and another body.

This can be used to test for if another body (e.g. a moon) is in front of or behind the target body (e.g. a planet).

Warning

This method does not perform any checks to ensure that any input Body or BasicBody instances have a consistent observer location and observation time as the target body.

Parameters:

other – Other body to test for intercept with. Can be a :class`Body` (or BasicBody) instance, or a string/integer NAIF ID code which is passed to create_other_body().
alt – Altitude adjustment to the surface of the target body in km.

Returns:

None if there is no intercept, otherwise a string indicating the type of intercept. For example, with jupiter.other_body_los_intercept('europa'), the possible return values mean:

None - there is no intercept, meaning that Europa and Jupiter do not overlap in the sky.

'hidden' - all of Europa’s disk is hidden behind Jupiter.

'part hidden' - part of Europa’s disk is hidden behind Jupiter and part is visible.

'transit' - all of Europa’s disk is in front of Jupiter.

'part transit' - part of Europa’s disk is in front of Jupiter.

The return value can also be 'same', which means that the other body is the same object as the target body (or has an identical location).

test_if_other_body_visible(other: str | int | planetmapper.body.Body | planetmapper.basic_body.BasicBody, **kwargs) → bool[source]

Test if another body is visible, or is hidden behind the target body.

This is a convenience method equivalent to:

body.other_body_los_intercept(other) != 'hidden'

Parameters:

other – Other body to test for visibility, passed to other_body_los_intercept().
**kwargs – Additional keyword arguments are passed to other_body_los_intercept().

Returns:

False if the other body is hidden behind the target body, otherwise True. If any part of the other body is visible, this method will return True.

illumination_angles_from_lonlat(lon: float, lat: float, *, alt: float = 0.0) → tuple[float, float, float][source]

Calculate the illumination angles of a longitude/latitude coordinate on the target body.

Parameters:

lon – Longitude of point on target body.
lat – Latitude of point on target body.
alt – Altitude of point above the surface of the target body in km.

Returns:

(phase, incidence, emission) tuple containing the illumination angles.

azimuth_angle_from_lonlat(lon: float, lat: float, *, alt: float = 0.0) → float[source]

Calculate the azimuth angle of a longitude/latitude coordinate on the target body.

Parameters:

lon – Longitude of point on target body.
lat – Latitude of point on target body.
alt – Altitude of point above the surface of the target body in km.

Returns:

Azimuth angle in degrees.

local_solar_time_from_lon(lon: float) → float[source]

Calculate the numerical local solar time for a longitude on the target body. For example, 0.0 corresponds to midnight and 12.5 corresponds to 12:30pm.

Note

A ‘local hour’ of solar time is a defined as 1/24th of the solar day on the target body, so will not correspond to a ‘normal’ hour as measured by a clock. See the SPICE documentation for more details.

Parameters:: lon – Longitude of point on target body.
Returns:: Numerical local solar time in ‘local hours’.

local_solar_time_string_from_lon(lon: float) → str[source]

Local solar time string representation for a longitude on the target body. For example, '00:00:00' corresponds to midnight and '12:30:00' corresponds to 12:30pm.

See local_solar_time_from_lon() for more details.

Parameters:: lon – Longitude of point on target body.
Returns:: String representation of local solar time.

terminator_radec(npts: int = 360, *, only_visible: bool = True, close_loop: bool = True, alt: float = 0.0, method: str = 'UMBRAL/TANGENT/ELLIPSOID', corloc: str = 'ELLIPSOID TERMINATOR') → tuple[numpy.ndarray, numpy.ndarray][source]

Calculate the RA/Dec coordinates of the terminator (line between day and night) on the target body. By default, only the visible part of the terminator is returned (this can be changed with only_visible).

Parameters:

npts – Number of points in generated terminator.
only_visible – Toggle only returning visible part of terminator.
alt – Altitude adjustment to the surface of the target body in km.
close_loop – If True, passes coordinate arrays through close_loop() (e.g. to enable nicer plotting).
method – Passed to SPICE function.
corloc – Passed to SPICE function.

Returns:

(ra, dec) tuple of RA/Dec coordinate arrays.

terminator_lonlat(npts: int = 360, *, only_visible: bool = False, close_loop: bool = True, alt: float = 0.0, method: str = 'UMBRAL/TANGENT/ELLIPSOID', corloc: str = 'ELLIPSOID TERMINATOR') → tuple[numpy.ndarray, numpy.ndarray][source]

Calculate the Lon/Lat coordinates of the terminator (line between day and night) on the target body.

Parameters:

npts – Number of points in generated terminator.
only_visible – Toggle only returning visible part of terminator.
alt – Altitude adjustment to the surface of the target body in km.
close_loop – If True, passes coordinate arrays through close_loop() (e.g. to enable nicer plotting).
method – Passed to SPICE function.
corloc – Passed to SPICE function.

Returns:

(lon, lat) tuple of Lon/Lat coordinate arrays.

test_if_lonlat_illuminated(lon: float, lat: float, *, alt: float = 0.0) → bool[source]

Test if longitude/latitude coordinate on the surface of the target body is illuminated.

Parameters:

lon – Longitude of point on target body.
lat – Latitude of point on target body.
alt – Altitude of point above the surface of the target body in km.

Returns:

True if the point is illuminated, otherwise False.

ring_plane_coordinates(ra: float, dec: float, only_visible: bool = True) → tuple[float, float, float][source]

Calculate coordinates in the target body’s equatorial (ring) plane. This is mainly useful for calculating the coordinates in a body’s ring system at a given point in the sky.

To calculate the coordinates corresponding to a location on the target body, you can use

body.ring_plane_coordinates(*body.radec2lonlat(lon, lat))

This form can be useful to identify parts of a planet’s surface which are obscured by its rings

radius, _, _ = body.ring_plane_coordinates(*body.lonlat2radec(lon, lat))
ring_data = planetmapper.data_loader.get_ring_radii()['SATURN']
for name, radii in ring_data.items():
    if min(radii) < radius < max(radii):
        print(f'Point obscured by {name} ring')
        break
else:
    print('Point not obscured by rings')

Parameters:

ra – Right ascension of point in the sky of the observer.
dec – Declination of point in the sky of the observer.
only_visible – If True (the default), coordinates for parts of the equatorial plane hidden behind the target body are set to NaN.

Returns:

(ring_radius, ring_longitude, ring_distance) tuple for the point on the target body’s equatorial (ring) plane. ring_radius gives the distance of the point in km from the centre of the target body. ring_longitude gives the planetographic longitude of the point in degrees. ring_distance gives the distance from the observer to the point in km.

ring_radec(radius: float, npts: int = 360, only_visible: bool = True) → tuple[numpy.ndarray, numpy.ndarray][source]

Calculate RA/Dec coordinates of a ring around the target body.

The ring is assumed to be directly above the planet’s equator and has a constant radius for all longitudes. Use ring_radii to set the rings automatically plotted.

Parameters:

radius – Radius in km of the ring from the centre of the target body.
npts – Number of points in the generated ring.
only_visible – If True (default), the coordinates for the part of the ring hidden behind the target body are set to NaN. This routine will execute slightly faster with only_visible set to False.

Returns:

(ra, dec) tuple of coordinate arrays.

visible_lonlat_grid_radec(interval: float = 30, **kwargs: Unpack[LonLatGridKwargs]) → list[tuple[numpy.ndarray, numpy.ndarray]][source]

Convenience function to calculate a grid of equally spaced lines of constant longitude and latitude for use in plotting lon/lat grids.

This function effectively combines visible_lon_grid_radec() and visible_lat_grid_radec() to produce both longitude and latitude gridlines.

For example, to plot gridlines with a 45 degree interval, use:

lines = body.visible_lonlat_grid_radec(interval=45)
for ra, dec in lines:
    plt.plot(ra, dec)

Parameters:

interval – Spacing of gridlines. Generally, this should be an integer factor of 90 to produce nice looking plots (e.g. 10, 30, 45 etc).
**kwargs – Additional arguments are passed to visible_lon_grid_radec() and visible_lat_grid_radec().

Returns:

List of (ra, dec) tuples, each of which corresponds to a gridline. ra and dec are arrays of RA/Dec coordinate values for that gridline.

visible_lon_grid_radec(lons: Union[Sequence[float], ndarray], npts: int = 60, *, lat_limit: float = 90.0, alt: float = 0.0, planetocentric: bool = False) → list[tuple[numpy.ndarray, numpy.ndarray]][source]

Calculates the RA/Dec coordinates for visible lines of constant longitude.

For each longitude in lons, a (ra, dec) tuple is calculated which contains arrays of RA and Dec coordinates. Coordinates which correspond to points which are not visible are replaced with NaN.

See also get_backplane_img().

Returns:: Read-only array containing the planetographic longitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lon_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of planetographic longitude values.

get_lat_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the planetographic latitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lat_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of planetographic latitude values.

get_lon_centric_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the planetocentric longitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lon_centric_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of planetocentric longitude values.

get_lat_centric_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the planetocentric latitude value of each pixel in the image. Points off the disc have a value of NaN.

get_lat_centric_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of planetocentric latitude values.

get_ra_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the right ascension (RA) value of each pixel in the image.

get_ra_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of right ascension values as viewed by the observer. Locations which are not visible have a value of NaN.

get_dec_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the declination (Dec) value of each pixel in the image.

get_dec_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of declination values as viewed by the observer. Locations which are not visible have a value of NaN.

get_x_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the x pixel coordinate value of each pixel in the image.

get_x_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the x pixel coordinates each location corresponds to in the observation. Locations which are not visible or are not in the image frame have a value of NaN.

get_y_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the y pixel coordinate value of each pixel in the image.

get_y_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the y pixel coordinates each location corresponds to in the observation. Locations which are not visible or are not in the image frame have a value of NaN.

get_km_x_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the distance in target plane in km in the East-West direction.

get_km_x_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the distance in target plane in km in the East-West direction. Locations which are not visible have a value of NaN.

get_km_y_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the distance in target plane in km in the North-South direction.

get_km_y_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the distance in target plane in km in the North-South direction. Locations which are not visible have a value of NaN.

get_phase_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the phase angle value of each pixel in the image. Points off the disc have a value of NaN.

get_phase_angle_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the phase angle value at each point on the target’s surface.

get_incidence_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the incidence angle value of each pixel in the image. Points off the disc have a value of NaN.

get_incidence_angle_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the incidence angle value at each point on the target’s surface.

get_emission_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the emission angle value of each pixel in the image. Points off the disc have a value of NaN.

get_emission_angle_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the emission angle value at each point on the target’s surface.

get_azimuth_angle_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the azimuth angle value of each pixel in the image. Points off the disc have a value of NaN.

get_azimuth_angle_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the azimuth angle value at each point on the target’s surface.

get_local_solar_time_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the local solar time value of each pixel in the image, as calculated by Body.local_solar_time_from_lon(). Points off the disc have a value of NaN.

get_local_solar_time_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the local solar time at each point on the target’s surface, as calculated by Body.local_solar_time_from_lon().

get_distance_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the observer-target distance in km of each pixel in the image. Points off the disc have a value of NaN.

get_distance_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the observer-target distance in km of each point on the target’s surface.

get_radial_velocity_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the observer-target radial velocity in km/s of each pixel in the image. Velocities towards the observer are negative. Points off the disc have a value of NaN.

get_radial_velocity_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the observer-target radial velocity in km/s of each point on the target’s surface.

get_doppler_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the doppler factor for each pixel in the image, calculated using SpiceBase.calculate_doppler_factor() on velocities from get_radial_velocity_img(). Points off the disc have a value of NaN.

get_doppler_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the doppler factor of each point on the target’s surface. This is calculated using SpiceBase.calculate_doppler_factor() on velocities from get_radial_velocity_map().

get_limb_lon_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the planetographic longitude of the point on the target’s limb that is closest to each pixel. See Body.limb_coordinates_from_radec() for more detail.

get_limb_lon_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the planetographic longitude of the point on the target’s limb that is closest to each point on the target’s surface (for the observer). See Body.limb_coordinates_from_radec() for more detail.

get_limb_lat_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the planetographic latitude of the point on the target’s limb that is closest to each pixel. See Body.limb_coordinates_from_radec() for more detail.

get_limb_lat_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the planetographic latitude of the point on the target’s limb that is closest to each point on the target’s surface (for the observer). See Body.limb_coordinates_from_radec() for more detail.

get_limb_distance_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the distance in km above the target’s limb for each pixel. See Body.limb_coordinates_from_radec() for more detail.

get_limb_distance_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the distance in km above the target’s limb for each point on the target’s surface (for the observer). See Body.limb_coordinates_from_radec() for more detail.

get_ring_plane_radius_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the ring plane radius in km for each pixel in the image, calculated using Body.ring_plane_coordinates(). Points of the ring plane obscured by the target body have a value of NaN.

get_ring_plane_radius_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the ring plane radius in km obscuring each point on the target’s surface, calculated using Body.ring_plane_coordinates(). Points where the target body is unobscured by the ring plane have a value of NaN.

get_ring_plane_longitude_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the ring plane planetographic longitude in degrees for each pixel in the image, calculated using Body.ring_plane_coordinates(). Points of the ring plane obscured by the target body have a value of NaN.

get_ring_plane_longitude_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the ring plane planetographic longitude in degrees obscuring each point on the target’s surface, calculated using Body.ring_plane_coordinates(). Points where the target body is unobscured by the ring plane have a value of NaN.

get_ring_plane_distance_img() → ndarray[source]

See also get_backplane_img().

Returns:: Read-only array containing the ring plane distance from the observer in km for each pixel in the image, calculated using Body.ring_plane_coordinates(). Points of the ring plane obscured by the target body have a value of NaN.

get_ring_plane_distance_map(**map_kwargs: Unpack[MapKwargs]) → ndarray[source]

See generate_map_coordinates() for accepted arguments. See also get_backplane_map().

Returns:: Read-only array containing map of the ring plane distance from the observer in km obscuring each point on the target’s surface, calculated using Body.ring_plane_coordinates(). Points where the target body is unobscured by the ring plane have a value of NaN.

class planetmapper.Observation(path: str | os.PathLike | None = None, *, data: numpy.ndarray | None = None, header: astropy.io.fits.header.Header | None = None, **kwargs)[source]

Bases: BodyXY

Class representing an actual observation of an astronomical body at a specific time.

This is a subclass of BodyXY, with additional methods to interact with the observed data, such as by saving a FITS file containing calculated backplane data. All methods described in BodyXY, Body and SpiceBase are therefore available in instances of this class.

This class can be created by either providing a path to a data file to be loaded, or by directly providing the data itself (and optionally a FITS header). The nx and ny values for BodyXY will automatically be calculated from the input data.

If the input data is a FITS file (or a header is specified), then this class will attempt to generate appropriate parameters (e.g. target, utc) by using the values in the header. This allows an instance of this class to be created with a single argument specifying the path to the FITS file e.g. Observation('path/to/file.fits'). Manually specified parameters will take precedence, so Observation('path/to/file.fits', target='JUPITER') will have Jupiter as a target, regardless of any values saying otherwise in the FITS header.

If a FITS header is not provided (e.g. if the input path corresponds to an image file), then at least the target and utc parameters need to be specified.

When an Observation object is created, the disc parameters (x0, y0, r0, rotation) initialised to the most useful values possible:

If the input file has previously been fit by PlanetMapper, the previous parameter values saved in the FITS header are loaded using disc_from_header().
Otherwise, if there is WCS information in the FITS header, this is loaded with disc_from_wcs().
Finally, if there is no useful information in the FITS header (or no header is provided), the disc parameters are initialised using centre_disc().

Parameters:

path – Path to data file to load. If this is None then data must be specified instead. Any user (~) and shell variables (e.g. $var) in the path are automatically expanded if possible.
data – Array containing observation data to use instead of loading the data from path. This should only be provided if path is None.
header – FITS header which corresponds to the provided data. This is optional and should only be provided if path is None.
target – Name of target body, passed to Body. If this is unspecified, then the target will be derived from the values in the FITS header.
utc – Time of observation, passed to Body. If this is unspecified, then the time will be derived from the values in the FITS header.
**kwargs – Additional parameters are passed to BodyXY. These can be used to specify additional parameters such as`observer`. The image size is automatically determined from the data, so passing nx, ny or sz as arguments when creating an Observation object will raise a TypeError.

FITS_FILE_EXTENSIONS = ('.fits', '.fits.gz'): File extensions which will be read as FITS files. All other file extensions will be assumed to be images.

FITS_KEYWORD = 'PLANMAP': FITS keyword used in metadata added to header of output FITS files.

path: str | None: Path of input data file, or None if no file was provided.

data: np.ndarray: Observed data.

header: fits.Header: FITS header containing data about the observation. If this is not provided, then a basic header will be produced containing data derived from the target and utc parameters.

to_body_xy() → BodyXY[source]

Create a BodyXY object with the same parameters and data as this observation.

Returns:: BodyXY object with the same disc parameters as this Observation instance.

get_wavelengths_from_header(*, check_ctype: bool = True) → ndarray[source]

Generate a wavelength array for a spectral cube, using metadata in the observation’s FITS Header.

This uses the NAXIS3, CRVAL3, CDELT3 (or CD3_3) and CRPIX3 keywords to generate the wavelengths. If check_ctype is True, then the CTYPE3 keyword is also checked to ensure it is 'WAVE'. If the Header does not contain the necessary information to construct a wavelength array, then a planetmapper.utils.GetWavelengthsError is raised.

See planetmapper.utils.generate_wavelengths_from_header() for more information.

Parameters:: check_ctype – Check that the CTYPE3 keyword is 'WAVE'.
Returns:: Wavelength array for the spectral cube. This will have the same length as the third axis of the data cube.
Raises:: GetWavelengthsError – if the Header does not contain the necessary information to construct a wavelength array.

disc_from_header() → None[source]

Sets the target’s planetary disc data in the FITS header generated by previous runs of planetmapper.

This uses values such as HIERARCH PLANMAP DISC X0 to set the disc location to be the same as the previous run.

Raises:: ValueError – if the header does not contain appropriate metadata values. This is likely because the file was not created by planetmapper.

disc_from_wcs(suppress_warnings: bool = False, validate: bool = True, use_header_offsets: bool = True) → None[source]

Set disc parameters using WCS information in the observation’s FITS header.

Note

There may be very slight differences between the coordinates converted directly from the WCS information and the coordinates converted by PlanetMapper.

Parameters:

suppress_warnings – Hide warnings produced by astropy when calculating WCS conversions.
validate – Run checks to ensure the WCS conversion has appropriate RA/Dec coordinate dimensions.
use_header_offsets – If present, use the HIERARCH NAV RA_OFFSET and HIERARCH NAV DEC_OFFSET values from the FITS headerr to adjust the target’s disc location by the specified arcsecond offsets. If these keywords are not present or use_header_offsets is False, no adjustment is made.

Raises:

ValueError – if no WCS information is found in the FITS header, or validation fails.

position_from_wcs(*args, **kwargs) → None[source]

Set disc position (x0, y0) using WCS information in the observation’s FITS header.

planetmapper

`planetmapper`