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

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.set_kernel_path(path: str | None) → None[source]

Set the path of the directory containing SPICE kernels. See the kernel directory documentation for more detail.

Parameters:: path – Directory which PlanetMapper will search for SPICE kernels. If None, then the default value of '~/spice_kernels/' will be used.

planetmapper.get_kernel_path(return_source: bool = False) → str | tuple[str, str][source]

Get the path of the directory of SPICE kernels used in PlanetMapper.

If a kernel path has been manually set using set_kernel_path(), then this path is used.
Otherwise the value of the environment variable PLANETMAPPER_KERNEL_PATH is used.
If PLANETMAPPER_KERNEL_PATH is not set, then the default value, '~/spice_kernels/' is used.

Parameters:: return_source – If True, return a tuple of the kernel path and a string which indicates the source of the kernel path. If False (the default), return only the kernel path. The possible source strings are: 'set_kernel_path()', 'PLANETMAPPER_KERNEL_PATH', and 'default'.
Returns:: The path of the directory of SPICE kernels used in PlanetMapper. If return_source is True, then a tuple of the kernel path and a string indicating the source of the kernel path is returned.

class planetmapper.SpiceBase(show_progress: bool = False, optimize_speed: bool = True, auto_load_kernels: bool = True, kernel_path: str | None = None, manual_kernels: None | list[str] = None)[source]

Bases: object

Class containing methods to interface with spice and manipulate coordinates.

This is the base class for all the main classes used in planetmapper.

Parameters:

show_progress – Show progress bars for long running processes. This is mainly useful for complex functions in derived classes, such as backplane generation in BodyXY. These progress bars can be quite messy, but can be useful to keep track of very long operations.
optimize_speed – Toggle speed optimizations. For typical observations, the optimizations can make code significantly faster with no effect on accuracy, so should generally be left enabled.
auto_load_kernels – Toggle automatic kernel loading with load_spice_kernels().
kernel_path – Passed to load_spice_kernels() if load_kernels is True. It is recommended to use set_kernel_path() instead of passing this argument.
manual_kernels – Passed to load_spice_kernels() if load_kernels is True. It is recommended to use planetmapper.base.prevent_kernel_loading() then manually load kernels yourself instead of passing this argument.

copy() → Self[source]: Return a copy of this object.

standardise_body_name(name: str | int) → str[source]

Return a standardised version of the name of a SPICE body.

This converts the provided name into the SPICE ID code with spice.bods2c, then back into a string with spice.bodc2s. This standardises to the version of the name preferred by SPICE. For example, 'jupiter', 'JuPiTeR', ' Jupiter ', '599' and 599 are all standardised to 'JUPITER'

Parameters:: name – The name of a body (e.g. a planet). This can also be the numeric ID code of a body.
Returns:: Standardised version of the body’s name preferred by SPICE.
Raises:: NotFoundError – If SPICE does not recognise the provided name

et2dtm(et: float) → datetime[source]

Convert ephemeris time to a Python datetime object.

Parameters:: et – Ephemeris time in seconds past J2000.
Returns:: Timezone aware (UTC) datetime corresponding to et.

static mjd2dtm(mjd: float) → datetime[source]

Convert Modified Julian Date into a python datetime object.

Parameters:: mjd – Float representing MJD.
Returns:: Python datetime object corresponding to mjd. This datetime is timezone aware and set to the UTC timezone.

speed_of_light() → float[source]

Return the speed of light in km/s. This is a convenience function to call spice.clight().

Returns:: Speed of light in km/s.

calculate_doppler_factor(radial_velocity: Numeric) → Numeric[source]

Calculates the doppler factor caused by a target’s radial velocity relative to the observer. This doppler factor, $D$ can be used to calculate the doppler shift caused by this velocity as $\lambda_r = \lambda_e D$ where $\lambda_r$ is the wavelength received by the observer and $\lambda_e$ is the wavelength emitted at the target.

This doppler factor is calculated as $D = \sqrt{\frac{1 + v/c}{1 - v/c}}$ where $v$ is the input radial_velocity and $c$ is the speed of light.

Parameters:: radial_velocity – Radial velocity in km/s with positive values corresponding to motion away from the observer. This can be a single float value or a numpy array containing multiple velocity values.
Returns:: Doppler factor calculated from input radial velocity. If the input radial_velocity is a single value, then a float is returned. If the input radial_velocity is a numpy array, then a numpy array of doppler factors is returned.

static load_spice_kernels(kernel_path: str | None = None, manual_kernels: None | list[str] = None, only_if_needed: bool = True) → None[source]

Attempt to intelligently SPICE kernels using planetmapper.base.load_kernels().

If manual_kernels is None (the default), then all kernels in the directory given by kernel_path which match the following patterns are loaded:

**/*.bsp
**/*.tpc
**/*.tls

Note that these patterns match an arbitrary number of nested directories (within kernel_path). If more control is required, you can instead specify a list of specific kernels to load with manual_kernels.

Hint

See the SPICE kernel documentation for more detail about downloading SPICE kernels and the automatic kernel loading behaviour.

Parameters:

kernel_path – Path to directory where kernels are stored. If this is None (the default) then the result of get_kernel_path() is used. It is usually recommended to use one of the methods described in the kernel directory documentation rather than using this kernel_path argument.
manual_kernels – Optional manual list of paths to kernels to load instead of using kernel_path.
only_if_needed – If this is True, kernels will only be loaded once per session.

static close_loop(arr: ndarray) → ndarray[source]

Return copy of array with first element appended to the end.

This is useful for cases like plotting the limb of a planet where the array of values forms a loop with the first and last values in arr adjacent to each other.

Parameters:: arr – Array of values of length $n$.
Returns:: Array of values of length $n + 1$ where the final value is the same as the first value.

static unit_vector(v: ndarray) → ndarray[source]

Return normalised copy of a vector.

For an input vector $\vec{v}$, return the unit vector $\hat{v} = \frac{\vec{v}}{|\vec{v}|}$.

Parameters:: v – Input vector to normalise.
Returns:: Normalised vector which is parallel to v and has a magnitude of 1.

static vector_magnitude(v: ndarray) → float[source]

Return the magnitude of a vector.

For an input vector $\vec{v}$, return magnitude $|\vec{v}| = \sqrt{\sum{v_i^2}}$.

Parameters:: v – Input vector.
Returns:: Magnitude (length) of vector.

static angular_dist(ra1: float, dec1: float, ra2: float, dec2: float) → float[source]

Calculate the angular distance between two RA/Dec coordinate pairs.

Parameters:

ra1 – RA of first point.
dec1 – Dec of first point.
ra2 – RA of second point
dec2 – Dec of second point.

Returns:

Angular distance in degrees between the two points.

class planetmapper.Body(target: str | int, utc: str | datetime.datetime | float | None = None, observer: str | int = 'EARTH', *, aberration_correction: str = 'CN', observer_frame: str = 'J2000', illumination_source: str = 'SUN', subpoint_method: str = 'INTERCEPT/ELLIPSOID', surface_method: str = 'ELLIPSOID', **kwargs)[source]

Bases: BodyBase

Class representing an astronomical body observed at a specific time.

Generally only target, utc and observer need to be changed. The additional parameters allow customising the exact settings used in the internal SPICE functions. Similarly, some methods (e.g. terminator_radec()) have parameters that are passed to SPICE functions which can almost always be left as their default values. See the SPICE documentation for more details about possible parameter values.

The target and observer names are passed to SpiceBase.standardise_body_name(), so a variety of formats are acceptable. For example 'jupiter', 'JUPITER', ' Jupiter ', '599' and 599 will all resolve to 'JUPITER'.

Body instances are hashable, so can be used as dictionary keys.

This class inherits from SpiceBase so the methods described above are also available.

Parameters:

target – Name of target body.
utc – Time of observation. This can be provided in a variety of formats and is assumed to be UTC unless otherwise specified. The accepted formats are: any string datetime representation compatible with SPICE (e.g. '2000-12-31T23:59:59' - see the documentation of acceptable string formats), a Python datetime object, or a float representing the Modified Julian Date (MJD) of the observation. Alternatively, if utc is None (the default), then the current time is used.
observer – Name of observing body. Defaults to 'EARTH'.
aberration_correction – Aberration correction used to correct light travel time in SPICE. Defaults to 'CN'.
observer_frame – Observer reference frame. Defaults to 'J2000',
illumination_source – Illumination source. Defaults to 'SUN'.
subpoint_method – Method used to calculate the sub-observer point in SPICE. Defaults to 'INTERCEPT/ELLIPSOID'.
surface_method – Method used to calculate surface intercepts in SPICE. Defaults to 'ELLIPSOID'.
**kwargs – Additional arguments are passed to SpiceBase.

target: str: Name of the target body, as standardised by SpiceBase.standardise_body_name().

utc: str: String representation of the time of the observation in the format '2000-01-01T00:00:00.000000'. This time is in the UTC timezone.

observer: str: Name of the observer body, as standardised by SpiceBase.standardise_body_name().

aberration_correction: str: Aberration correction used to correct light travel time in SPICE.

observer_frame: str: Observer reference frame.

et: float: Ephemeris time of the observation corresponding to utc.

dtm: datetime.datetime: Python timezone aware datetime of the observation corresponding to utc.

target_body_id: int: SPICE numeric ID of the target body.

target_light_time: float: Light time from the target to the observer at the time of the observation.

target_distance: float: Distance from the target to the observer at the time of the observation.

target_ra: float: Right ascension (RA) of the target centre.

target_dec: float: Declination (Dec) of the target centre.

illumination_source: str: Illumination source.

subpoint_method: str: Method used to calculate the sub-observer point in SPICE.

surface_method: str: Method used to calculate surface intercepts in SPICE.

radii: np.ndarray: Array of radii of the target body along the x, y and z axes in km.

r_eq: float: Equatorial radius of the target body in km.

r_polar: float: Polar radius of the target body in km.

flattening: float: Flattening of target body, calculated as (r_eq - r_polar) / r_eq.

prograde: bool: Boolean indicating if the target’s spin sense is prograde or retrograde.

positive_longitude_direction: Literal['E', 'W']

Positive direction of planetographic longitudes. 'W' implies positive west planetographic longitudes and 'E' implies positive east longitudes.

This is determined from the target’s spin sense (i.e. from prograde), with positive west longitudes for prograde rotation and positive east for retrograde. The earth, moon and sun are exceptions to this and are defined to have positive east longitudes

For more details, see https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/pgrrec_c.html#Particulars

target_diameter_arcsec: float: Equatorial angular diameter of the target in arcseconds.

subpoint_distance: float: Distance from the observer to the sub-observer point on the target.

subpoint_lon: float: Longitude of the sub-observer point on the target.

subpoint_lat: float: Latitude of the sub-observer point on the target.

subsol_lon: float: Longitude of the sub-solar point on the target.

subsol_lat: float: Latitude of the sub-solar point on the target.

named_ring_data: dict[str, list[float]]

Dictionary of ring radii for the target from data_loader.get_ring_radii().

The dictionary keys are the names of the rings, and values are 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. These ring radii values are sourced from planetary factsheets. If no ring data is available for the target, this dictionary is empty.

Values from this dictionary can be easily accessed using the convenience function ring_radii_from_name().

ring_radii: set[float]

Set of ring radii in km to plot around the target body’s equator. Each radius is plotted as a single line, so for a wide ring you may want to add both the inner and outer edger of the ring. The radii are defined as the distance from the centre of the target body to the ring. For Saturn, the A, B and C rings from named_ring_data are included by default. For all other bodies, ring_radii is empty by default.

Ring radii data from the named_ring_data can easily be added to ring_radii using add_named_rings(). Example usage:

body.ring_radii.add(122340) # Add new ring radius to plot
body.ring_radii.add(136780) # Add new ring radius to plot
body.ring_radii.update([66900, 74510]) # Add multiple radii to plot at once

body.ring_radii.remove(122340) # Remove a ring radius
body.ring_radii.clear() # Remove all ring radii

# Add specific ring radii using data from planetary factsheets
body.add_named_rings('main', 'halo')

# Add all rings defined in the planetary factsheets
body.add_named_rings()

planetmapper

`planetmapper`