Trajectory API

Contents

Trajectory API#

TourConfig#

class planetary_coverage.trajectory.TourConfig(*, mk=None, kernels=None, spacecraft='JUICE', instrument='', target='Ganymede', version='latest', kernels_dir=None, download_kernels=False, remote_kernels=0, load_kernels=False, default_time_step='1 minute', abcorr='NONE', exclude=None)[source]#

Bases: object

Orbital tour configuration object.

Prepare the kernels configuration based on the selected spacecraft, target and metakernel setup. By default the SPICE kernel pool is purge and automatically loaded with the selected kernels.

Parameters:

  • mk (MetaKernel or str, optional) –

    Metakernel filename (*.tm) or ESA metakernel identifier key. You can provide your own or use the one provided by ESA based on the spacecraft selected (default: None).

    For example: '5.0' with the spacecraft JUICE will load juice_crema_5_0.tm metakernel.

  • kernels (str or pathlib.Path, optional) –

    Kernel filename or list of kernel filenames that will be loaded into the kernel pool.

    This could be use alone or complementary to a metakernel. If used with a metakernel, the kernels will be loaded at the end and will have the priority over the kernels in the metakernel.

  • spacecraft (str, optional) – Name of the spacecraft selected (default: JUICE).

  • instrument (str, optional) – Name of the instrument selected (default: None).

  • target (str or SpiceBody, optional) – Name of the target selected (default: Ganymede).

  • version (str, optional) – ESA metakernel SKD version / tag (default:latest). This parameter is only available for metakernel defined with a key/shortcut and available in ESA_MK.

  • kernels_dir (str or pathlib.Path, optional) –

    Kernels directory location.

    This parameter is only used to substitute the $KERNELS symbol value at runtime in the provided metakernel. This parameter has no effect on the kernels parameter.

    If no explicit value is provided (default), the tool will try to pull the kernel location from your environment variables configuration, i.e. it will use the KERNELS_XXXX env variable if you defined it on your system (with XXXX the name spacecraft).

  • download_kernels (bool, optional) – Try to download the missing kernels in the metakernel if they are missing (default: False). This parameter has no effect on the kernels parameter.

  • remote_kernels (str or int, optional) – Remote kernel source. If none is provided (default), the content of the file will be parsed to search for a remote base value (with ://). If multiple remotes are present, the first one will be used by default. You can provide an integer to choose which one you want to use. This value is not required if all the kernel are present locally (it is only used to download the missing kernels).

  • load_kernels (bool, optional) – Explicitly force the load to the kernels in the SPICE pool (default: False). If forced, the content of the SPICE pool is checked, flushed and reloaded if needed. This can also be achieved with the .load_kernels() function. Any SPICE related calculation (decorated with @check_kernels) will performed this check.

  • default_time_step (str, optional) – Default time step if a temporal slice is provided without a defined temporal step (default: 1 minute).

  • abcorr (str, optional) – Aberration corrections to be applied when computing the target’s position and orientation. Only the SPICE keys are accepted.

  • exclude (EventWindow, EventsDict or EventsList) – Event window, dict or list of events to exclude from the analysis.

Raises:

  • ValueError – If the metakernel is provided as a key/shortcut but the associated spacecraft is not available in ESA_MK.

  • KernelsDirectoryNotFoundError – If not kernels directory is supplied and the kernels were not found in the metakernel location.

  • KernelNotFoundError – If some kernels are missing and download_kernels is set to False.

  • KernelRemoteNotFoundError – If the source of the kernels in the metakernel is unknown.

  • KeyError – If the target name is unknown.

Tip

If you need to replace a custom PATH_SYMBOLS different from KERNELS you could provide a MetaKernel object with the substituted values in the initial call:

>>> TourConfig(mk=MetaKernel('foo.tm', custom_symbol='CUSTOM_VALUE'))
property mk: MetaKernel#

Selected metakernel.

property metakernel: Path#

Metakernel filename.

property skd_version: str#

ESA metakernel SKD version value.

property mk_identifier: str#

ESA metakernel ID identifier value.

load_kernels()[source]#

Load the required kernels into the SPICE pool.

Note

If the SPICE pool already contains the required kernels, nothing will append. If not, the pool is flushed and only the required kernels are loaded.

property coverage#

Observer and Target intersection coverage.

Overlapping windows of coverage from the observer and target data loaded in the SPICE pool.

gaps(*refs)[source]#

Get temporal coverage gaps intervals by reference(s).

Parameters:

refs (str, int or SpiceRef) – Body(ies) reference(s).

Returns:

Events list of gaps.

Return type:

EventsList

property phases#

[Cached] Mission phases events list.

The following properties needs to be present in the pool: - <SPACECRAFT>_MISSION_PHASE_NAME - <SPACECRAFT>_MISSION_PHASE_DESC - <SPACECRAFT>_MISSION_PHASE_STRT - <SPACECRAFT>_MISSION_PHASE_STOP

property timeline#

[Cached] Mission timeline events list.

The following properties needs to be present in the pool: - <SPACECRAFT>_TIMELINE_EVENT_TYPE - <SPACECRAFT>_TIMELINE_EVENT_NAME - <SPACECRAFT>_TIMELINE_EVENT_TIME

get_event(name)[source]#

Get event by name from mission phases or timeline.

Parameters:

name (str) – Event name.

Returns:

Queried event or event window from the mission phases or timeline, if present.

Return type:

Event or EventWindow

Raises:

KeyError – If the provided event name is invalid.

add_kernel(*kernels)[source]#

Create a new tour with additional kernels.

Parameters:

*kernels (str or pathlib.Path) – Kernel(s) to append.

Returns:

New tour configuration with a new set of kernels.

Return type:

TourConfig

new_tour(*, spacecraft=None, instrument=None, target=None)[source]#

Create a new tour configuration for a different set of target/observer.

You can provide either one or multiple parameters as once.

Parameters:
Returns:

New tour configuration with new parameters.

Return type:

TourConfig

Raises:

ValueError – If no new parameter is provided.

Note

If a spacecraft is provided without an instrument, the instrument will be reset to ''.

property flybys#

List of all the flybys on the target below 150,000 km.

See also

get_flybys()

get_flybys(event=None, alt_min=150000)[source]#

List of all the flybys on the target below a given altitude.

Parameters:

  • event (EventWindow, EventsDict or EventsList, optional) – Optional event. If none is provided (default), the full coverage window will be used with a time step of 30 minutes.

  • default_time_step (str, optional) – Default time step grid to search the location of the minimum of altitude in the flyby (default: '30 mins').

  • alt_min (float, optional) – Minimal altitude at closest approach (default: 150,000 km).

Returns:

List of flybys below the required altitude.

Return type:

[Flyby, …]

flyby(approx_ca_date, *dt, alt_min=150000)[source]#

Select a single flyby with an approximate date.

Parameters:

  • approx_ca_date (float, str or numpy.datetime64) – Approximate CA datetime (at day level). This value will be re-computed (at the second level). Event, EventWindow, EventsDict and EventsList can be used as well.

  • *dt (tuple(s), optional) –

    Temporal sequence around closest approach:

    (duration, numpy.datetime unit, step value and unit)

    See et_ca_range() for more details.

  • alt_min (float, optional) – Minimal altitude at closest approach (default: 150,000 km).

Returns:

Flyby trajectory.

Return type:

SpacecraftFlyby or InstrumentFlyby

Note

If an EventWindow, EventsDict or an EventsList is provided, the output will be a list of the flybys found in these intervals.

Trajectory#

class planetary_coverage.trajectory.Trajectory(kernels, observer, target, ets, abcorr='NONE', exclude=None)[source]#

Bases: object

Spacecraft trajectory object.

Parameters:

  • kernels (str or tuple) – List of kernels to be loaded in the SPICE pool.

  • observer (str or SpiceSpacecraft or SpiceInstrument) – Observer (spacecraft or instrument) SPICE reference.

  • target (str or SpiceBody) – Target SPICE reference.

  • ets (float or str or list) – Ephemeris time(s).

  • abcorr (str, optional) – Aberration corrections to be applied when computing the target’s position and orientation. Only the SPICE keys are accepted.

  • exclude (EventWindow, EventsDict or EventsList) – Event window, list or dict of events to exclude from the analysis.

Raises:

ValueError – If the provided observer is not a valid spacecraft or instrument.

load_kernels()[source]#

Load the required kernels into the SPICE pool.

Note

If the SPICE pool already contains the required kernels, nothing will append. If not, the pool is flushed and only the required kernels are loaded.

add_kernel(*kernels)[source]#

Create a new trajectory with additional kernels.

Parameters:

*kernels (str or pathlib.Path) – Kernel(s) to append.

Returns:

New trajectory with a new set of kernels.

Return type:

TourConfig

new_traj(*, spacecraft=None, instrument=None, target=None)[source]#

Create a new trajectory for a different set of target/observer.

You can provide either one or multiple parameters as once.

Parameters:
Returns:

New trajectory object with new parameters.

Return type:

Trajectory

Raises:

ValueError – If no new parameter is provided.

Note

  • The instrument name, can be either the instrument full name or just a suffix (ie. <SPACECRAFT>_<INSTRUMENT>).

  • If the original trajectory has a instrument selected , you can discard it selected either by providing the spacecraft parameter alone or with instrument='none' syntax.

property target#

Trajectory target.

property observer#

Trajectory observer.

property spacecraft#

Observer spacecraft SPICE reference.

property ets#

Ephemeris Times (ET).

property utc#

[Cached] UTC times.

property start#

[Cached] UTC start time.

property stop#

[Cached] UTC stop time.

property boresight#

Observer boresight pointing vector.

property inertial_frame#

Target parent inertial frame.

property sc_pts#

[Cached] Sub-spacecraft surface intersection vector.

Returns:

Spacecraft XYZ intersection on the target body fixed frame (expressed in km).

Return type:

numpy.ndarray

Note

Currently the intersection method is fixed internally as method='NEAR POINT/ELLIPSOID'.

property sc_rlonlat#

[Cached] Sub-spacecraft coordinates.

Returns:

Sub-spacecraft planetocentric coordinates: radii, east longitudes and latitudes.

Return type:

numpy.ndarray

Note

Currently the intersection method is fixed internally as method='NEAR POINT/ELLIPSOID'.

See also

sc_pts

property lonlat#

Groundtrack or surface intersect (not implemented here).

property boresight_pts#

[Cached] Boresight surface intersection vector.

Returns:

Boresight XYZ intersection on the target body fixed frame (expressed in km).

Return type:

numpy.ndarray

Note

Currently the intersection method is fixed internally as method='ELLIPSOID'.

property boresight_rlonlat#

[Cached] Boresight surface intersect coordinates.

Returns:

Boresight surface intersect planetocentric coordinates: radii, east longitudes and latitudes.

Return type:

numpy.ndarray

See also

boresight_pts

property surface#

Boolean array when the boresight intersect the target surface.

property limb#

Boolean array when the boresight is above the limb.

property sc_state#

[Cached] Spacecraft position and velocity.

In the target body fixed frame (km and km/s).

property sc_pos#

Spacecraft position in the target body fixed frame (km).

See also

sc_state

property sc_velocity#

Spacecraft velocity vector in the target body fixed frame (km/s).

See also

sc_speed

property sc_speed#

[Cached] Observer speed in the target body fixed frame (km/s).

See also

sc_velocity

property dist#

[Cached] Spacecraft distance to the body target center (km).

This distance is computed to the center of the targeted body.

See also

sc_state

property alt#

[Cached] Spacecraft altitude to the sub-spacecraft point (km).

The intersect on the surface is computed on the reference ellipsoid.

See also

sc_pts, sc_state

property target_size#

[Cached] Target angular size (degrees).

See also

angular_size

property ets_target_center#

[Cached] Ephemeris Time (ET) at the target center.

The light time correction is only apply if abcorr in not NONE.

See also

Trajectory.dist, SpiceAbCorr.dist_corr

property groundtrack_velocity#

[Cached] Spacecraft groundtrack velocity (km/s).

It correspond to the motion speed of the sub-spacecraft point on the surface.

See also

sc_state

property sc_attitude#

[Cached] [Depreciated] Spacecraft attitude c-matrix in J2000 frame.

Changed in version 1.1.0: Fix C-matrix definition. The previous version was incorrect and returned the transpose of the C-matrix and not the C-matrix. See issue #73 for details.

Deprecated since version 1.1.0: .sc_attitude is depreciated in favor of .attitude.

property attitude#

[Cached] Observer attitude c-matrix in J2000 frame.

property quaternions#

[Cached] Observer quaternions in J2000 frame.

property radec#

[Cached] Observer boresight RA/DEC pointing in J2000 frame.

property ra#

Boresight pointing right ascension angle (degree).

property dec#

Boresight pointing declination angle (degree).

property sun_pos#

[Cached] Sun position in the target body fixed frame (km).

Note

Currently the intersection method is fixed on a sphere.

See also

ets_target_center

property sun_rlonlat#

[Cached] Sub-solar coordinates.

Returns:

Sub-solar planetocentric coordinates: radii, east longitudes and longitudes.

Return type:

numpy.ndarray

See also

sun_pos

property sun_lon_e#

Sub-solar point east longitude (degree).

property sun_lat#

Sub-solar point latitude (degree).

property sun_lonlat#

Sub-solar point groundtrack (degree).

property ss#

Alias on the sub-solar point groundtrack (degree).

property solar_longitude#

[Cached] Target seasonal solar longitude (degrees).

Warning

The seasonal solar longitude is computed on the main parent body for the moons (spiceypy.lspcn on the moon will not return the correct expected value).

property true_anomaly#

[Cached] Target orbital true anomaly (degree).

position_of(target)[source]#

Position vector of target body in spacecraft frame (km).

Parameters:

target (str or SpiceRef) – Target body name.

Returns:

Target position in spacecraft frame in km.

Return type:

numpy.ndarray

distance_to(target)[source]#

Distance to a target body (km).

Parameters:

target (str or SpiceRef) – Target body name.

Returns:

Distance between the spacecraft and the provided target in km.

Return type:

numpy.ndarray

ets_at(target)[source]#

Ephemeris time at target location with light-time corrections.

Parameters:

target (str or SpiceBody) – Target body name.

Returns:

Light-time correction ephemeris time at the target location.

Return type:

numpy.ndarray

utc_at(target)[source]#

UTC time at target location with light-time corrections.

Parameters:

target (str or SpiceBody) – Target body name.

Returns:

Light-time correction UTC time at the target location.

Return type:

numpy.ndarray

angular_size(target)[source]#

Angle size of a given target (in degrees) seen from the spacecraft.

Parameters:

target (str or SpiceBody) – Second ray (see above).

Returns:

Angular separation between the targets in degrees.

Return type:

numpy.ndarray

See also

target_separation

angle_between(ray_1, ray_2)[source]#

Angle between 2 rays in spacecraft frame (degrees).

Parameters:

  • ray_1 (str or list or tuple) – First ray name ('+Z'), ray vector ((0, 0, 1)) or target name ('JUPITER').

  • ray_2 (str or list or tuple) – Second ray (see above).

Returns:

Angular separation between the targets in degrees.

Return type:

numpy.ndarray

See also

target_separation

target_separation(target_1, target_2=None, *, shape_1='POINT', shape_2='POINT')[source]#

Angular separation between two target bodies (degrees).

Parameters:

  • target_1 (str or SpiceBody) – First target body name.

  • target_2 (str or SpiceBody) – Second target body name. If none provided (default), the trajectory main target will be used as the first target and the target provided as the secondary target.

  • shape_1 (str, optional) – First target body shape model. Only 'POINT' and 'SPHERE' are accepted. If POINT selected (default) the target is considered to have no radius. If SPHERE selected the calculation will take into account the target radii (max value used).

  • shape_2 (str, optional) – Second target body shape model. See shape_1 for details.

Returns:

Angular separation between the targets in degrees.

Return type:

numpy.ndarray

See also

angle_between

station_azel(station, *, az_spice=False, el_spice=True)[source]#

Spacecraft azimuth and elevation seen from an earth-based tracking station.

Warning

It is highly recommended to use abcorr='CN+S' to perform this calculation.

Danger

If you apply light-time corrections (abcorr), you need to represent the result in the correct time reference. Here you should use Trajectory.utc_at('EARTH') instead of Trajectory.utc`.

Parameters:

  • station (str) – Name of the tracking station.

  • az_spice (bool, optional) – Use SPICE azimuth convention (counted counterclockwise). Default: False (counted clockwise).

  • el_spice (bool, optional) – Use SPICE elevation convention (counted positive above XY plane, toward +Z). Default: True. Otherwise, counted positive below XY plane, toward -Z.

Returns:

Azimuth and elevation angles of the spacecraft seen from the tracking station in degrees.

Return type:

numpy.ndarray, numpy.ndarray

mask(cond)[source]#

Create a masked trajectory only where the condition invalid.

where(cond)[source]#

Create a masked trajectory only where the condition is valid.

intersect(obj, outside=False)[source]#

Intersection mask between the trajectory and an object.

Parameters:

  • obj (any) – ROI-like object to intersect the trajectory.

  • outside (bool, optional) – Return the invert of the intersection (default: False).

Returns:

Mask to apply on the trajectory.

Return type:

numpy.ndarray

Raises:

AttributeError – If the comparison object doest have a contains() test function.

approx_ca_utc(alt_min)[source]#

List of approximate closest approach UTC times to the target.

Parameters:

alt_min (float) – Minimal altitude at closest approach [km].

Danger

These values may not be accurate depending on the Trajectory temporal resolution.

get_flybys(alt_min=150000)[source]#

List of all the flybys on the target below a given altitude.

Parameters:

alt_min (float, optional) – Minimal altitude at closest approach (default: 150,000 km).

Returns:

List of flybys below the required altitude.

Return type:

[Flyby, …]

property flybys#

Get all the flybys for this trajectory below 150,000 km.

See also

get_flybys()

SpacecraftTrajectory#

class planetary_coverage.trajectory.SpacecraftTrajectory(kernels, observer, target, ets, abcorr='NONE', exclude=None)[source]#

Bases: Trajectory

Spacecraft trajectory object.

property lon_e#

Sub-spacecraft east longitude (degree).

property lat#

Sub-spacecraft latitude (degree).

property lonlat#

Sub-spacecraft groundtrack east longitudes and latitudes (degree).

property slant#

Spacecraft line-of-sight distance to the sub-spacecraft point (km).

This is not the distance the distance to the target body center, but an alias of the altitude of the spacecraft.

See also

Trajectory.dist, Trajectory.alt

property ets_surface_intersect#

[Cached] Ephemeris Time (ET) at the surface intersect point.

The light time correction is only apply if abcorr in not NONE.

See also

Trajectory.alt, SpiceAbCorr.dist_corr

property local_time#

[Cached] Sub-spacecraft local time (decimal hours).

See also

sc_rlonlat, ets_surface_intersect

property illum_angles#

[Cached] Sub-spacecraft illumination angles (degree).

Incidence, emission and phase angles.

See also

sc_pts, ets_surface_intersect

property inc#

Sub-spacecraft incidence angle (degree).

property emi#

Sub-spacecraft emission angle (degree).

property phase#

Sub-spacecraft phase angle (degree).

property day#

[Cached] Day side, sub-spacecraft incidence lower than 90°.

property night#

[Cached] Night side, sub-spacecraft incidence larger than 90°.

property nadir#

[Cached] Nadir viewing, always True for the sub-spacecraft point.

property off_nadir#

[Cached] Off-nadir viewing, always False for the sub-spacecraft point.

property ell_norm#

[Cached] Sub-spacecraft local normal.

Unitary vector pointing upward from the surface of the ellipsoid.

See also

sc_pts

property solar_zenith_angle#

[Cached] Sub-spacecraft solar zenith angle (degree).

The angle is computed from the local normal on the ellipsoid. If the targeted body is a sphere, this value much be equal to the incidence angle.

See also

Trajectory.sun_pos, sc_pts, ell_norm

InstrumentTrajectory#

class planetary_coverage.trajectory.InstrumentTrajectory(kernels, observer, target, ets, abcorr='NONE', exclude=None)[source]#

Bases: Trajectory

Instrument trajectory object.

property lon_e#

Instrument surface intersect east longitude (degree).

property lat#

Instrument surface intersect latitude (degree).

property lonlat#

Instrument surface intersect east longitudes and latitudes (degree).

property slant#

[Cached] Line-of-sight distance to the boresight surface intersection (km).

See also

sc_pts, boresight_pts

property ets_surface_intersect#

[Cached] Ephemeris Time (ET) at the surface intersect point.

The light time correction is only apply if abcorr in not NONE.

See also

slant, SpiceAbCorr.dist_corr

property local_time#

[Cached] Instrument surface intersect local time (decimal hours).

property illum_angles#

[Cached] Instrument surface intersect illumination angles (degree).

Incidence, emission and phase angles.

See also

boresight_pts, ets_surface_intersect

property inc#

Instrument surface intersect incidence angle (degree).

property emi#

Instrument surface intersect emission angle (degree).

property phase#

Instrument surface intersect phase angle (degree).

property day#

[Cached] Day side, boresight intersection incidence lower than 90°.

property night#

[Cached] Night side, boresight intersection incidence larger than 90°.

property nadir#

[Cached] Nadir viewing, boresight intersection emission angle is lower than 1°.

property off_nadir#

[Cached] Off-nadir viewing, boresight intersection emission angle is larger than 1°.

property ell_norm#

[Cached] Instrument surface intersect local normal.

Unitary vector pointing upward from the surface of the ellipsoid.

See also

boresight_pts

property solar_zenith_angle#

[Cached] Instrument surface intersect solar zenith angle (degree).

The angle is computed from the local normal on the ellipsoid. If the targeted body is a sphere, this value much be equal to the incidence angle.

See also

Trajectory.sun_pos, boresight_pts, ell_norm

property pixel_scale#

[Cached] Instrument pixel scale (km/pix).

Cross-track iFOV projected on the target body.

See also

emi, Trajectory.dist

property fovs#

[Cached] Instrument field of views collection.

FovsCollection#

class planetary_coverage.trajectory.fovs.FovsCollection(traj, npts=25, limb_contour=True, limb=None)[source]#

Bases: object

Instrument field of views collection.

Parameters:

  • traj (InstrumentTrajectory) – Input instrument trajectory.

  • npts (int or tuple, optional) – Number of points in the FOV contour (default: 25). If the FOV has a RECTANGULAR and POLYGON shape, it is possible to provide a tuple that will correspond to the number of points per edges (excluding the corners). If the tuple size is smaller than the number of edges, its values will be cycled.

  • limb_contour (bool, optional) – Compute the intersection on the limb impact parameter if no intersection with the surface was found (default: True)

  • deprecated: (..) – 1.2.0: limb parameter was replaced with limb_contour.

property kernels#

Trajectory required kernels.

property observer#

Trajectory observer.

property target#

Trajectory target.

property npts#

Number of points in the FOV contour.

property limb_contour#

Is the FOV should include the intersection points above the limb.

property pts#

[Cached] Instrument FOV points.

Note

Currently the intersection method is fixed internally as method='ELLIPSOID'.

property rlonlat#

[Cached] Instrument FOV intersect coordinates.

Returns:

Boresight surface intersect planetocentric coordinates: radii, east longitudes and latitudes.

Return type:

np.ndarray

See also

pts

property surface#

Boolean array when the contour points intersect the target surface.

property surface_any#

Boolean array when at least one point intersects the target surface.

property surface_all#

Boolean array when at all points intersect the target surface.

property limb#

Boolean array when the contour points are above the limb.

property limb_any#

Boolean array when at least one point is above the limb.

property limb_all#

Boolean array when at all points are above the limb.

property paths#

[Cached] Instrument FOV surface paths.

Note

If all the points are above the limb the path is set to None.

See also

rlonlat

get_colors(attr, cmap='turbo_r', vmin=None, vmax=None)[source]#

Get colors for a given attribute and an optional range.

Parameters:

  • attr (str) – Attribute to color.

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

Returns:

  • str – If the attribute is not part of the trajectory (e.g. pure color string).

  • numpy.ndarray – Normalized RGB color array.

Raises:

ValueError – If the data to represent is not a 1D array.

isort(attr, reverse=None)[source]#

Get sorting indexes for a given attribute.

collection(edgecolors=None, facecolors='none', vmin=None, vmax=None, cmap='turbo_r', label=None, sort=None, reverse=None, **kwargs) → PathCollection[source]#

Instrument field of view paths collection.

Parameters:

  • edgecolors (str, optional) – Color of the patch contours. This could be a Trajectory property.

  • facecolors (str, optional) – Color of the patch face. This could be a Trajectory property.

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

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

  • label (str, optional) – Collection legend label (default: observer name).

  • sort (str, optional) – Patches sorting on display (default: utc).

  • reverse (bool, optional) – Reverse patches sorting (default: False).

  • **kwargs – Keyword attributes for matplotlib.collections.PathCollection.

get_paths()[source]#

Collection paths.

static get_alpha(default=None)[source]#

Default transparencies.

static get_facecolor(default='tab:orange')[source]#

Default facecolors.

static get_edgecolor(default=None)[source]#

Default edgecolors.

static get_linewidth(default=1.5)[source]#

Default linewidth.

static get_linestyle(default='solid')[source]#

Default linestyle.

static get_zorder(default=1)[source]#

Default zorder.

static get_label(default='')[source]#

Default label.

Flyby#

class planetary_coverage.trajectory.Flyby(kernels, observer, target, approx_ca_utc, *dt, abcorr='NONE', exclude=None, alt_min=150000)[source]#

Bases: Trajectory

Trajectory flyby object.

The location of the closest approach point is recomputed internally to ensure that the flyby is correctly center on its lowest altitude with a resolution of 1 sec.

To ensure better performances, the CA location is found in a 3 steps process:

  • 1st stage with a coarse resolution (20 min at CA ± 12h)

  • 2nd stage with a medium resolution (1 min at CA ± 30 min)

  • 3rd stage with a fine resolution (1 sec at CA ± 2 min)

By default the final sampling temporal steps are irregular with a high resolution only around CA:

  • 1 pt from CA -12 h to CA -2 h every 10 min

  • 1 pt from CA -2 h to CA -1 h every 1 min

  • 1 pt from CA -1 h to CA -10 m every 10 sec

  • 1 pt from CA -10 m to CA +10 m every 1 sec

  • 1 pt from CA +10 m to CA +1 h every 10 sec

  • 1 pt from CA +1 h to CA +2 h every 1 min

  • 1 pt from CA +2 h to CA +12 h every 10 min

= 2,041 points around the CA point.

Parameters:

  • kernels (str or tuple) – List of kernels to be loaded in the SPICE pool.

  • observer (str or spice.SpiceSpacecraft) – Observer SPICE reference.

  • target (str or spice.SpiceBody) – Target SPICE reference.

  • approx_ca_utc (float, string or numpy.datetime64) – Approximate CA datetime. This value will be re-computed.

  • *dt (tuple(s), optional) –

    Temporal sequence around closest approach:

    (duration, numpy.datetime unit, step value and unit)

    See et_ca_range() for more details.

  • abcorr (str, optional) – Aberration corrections to be applied when computing the target’s position and orientation. Only the SPICE keys are accepted.

  • exclude (EventWindow, EventsDict or EventsList) – Event window, dict or list of events to exclude from the analysis.

  • alt_min (float, optional) – Altitude minimal to a given target [km] (default: 150,000 km).

See also

Trajectory, et_ca_range

new_traj(*, spacecraft=None, instrument=None, target=None)[source]#

Create a new flyby for a different observer.

You can provide either one or multiple parameters as once.

Parameters:
Returns:

New trajectory object with new parameters.

Return type:

Trajectory

Raises:

ValueError – If a target name change is requested.

Note

  • The instrument name, can be either the instrument full name or just a suffix (ie. <SPACECRAFT>_<INSTRUMENT>).

  • If the original trajectory has a instrument selected , you can discard it selected either by providing the spacecraft parameter alone or with instrument='none' syntax.

property duration#

Flyby duration.

property et_ca#

Closest approach ET time.

property utc_ca#

Closest approach UTC time.

property date_ca#

Closest approach date.

property t_ca#

Time to closest approach.

property lon_e_ca#

Sub-spacecraft west longitude at closest approach.

property lat_ca#

Sub-spacecraft latitude at closest approach.

property alt_ca#

Altitude at closest approach (km).

property inc_ca#

Incidence angle at closest approach (degree).

property emi_ca#

Emission angle at closest approach (degree).

property phase_ca#

Phase angle at closest approach (degree).

property ca#

[Cached] Closest approach point.

property inbound#

Inbound part of the flyby, before CA.

property outbound#

Outbound part of the flyby, after CA.

alt_window(alt)[source]#

Interpolated altitude window during the flyby.

Parameters:

alt (float) – Altitude reach to start and stop the window (in km).

Returns:

UTC start, stop times and duration.

Return type:

numpy.datetime64, numpy.datetime64, numpy.timedelta64

Raises:

  • AltitudeTooLowError – If the altitude provided is lower than the CA altitude.

  • AltitudeTooHighError – If the altitude provided is higher than the max altitude of the flyby.

SpacecraftFlyby#

class planetary_coverage.trajectory.SpacecraftFlyby(kernels, observer, target, approx_ca_utc, *dt, abcorr='NONE', exclude=None, alt_min=150000)[source]#

Bases: Flyby, SpacecraftTrajectory

Spacecraft flyby object.

InstrumentFlyby#

class planetary_coverage.trajectory.InstrumentFlyby(kernels, observer, target, approx_ca_utc, *dt, abcorr='NONE', exclude=None, alt_min=150000)[source]#

Bases: Flyby, InstrumentTrajectory

Instrument flyby object.

property pixel_scale_ca#

Instrument pixel scale e at closest approach (km/pixel).

MaskedTrajectory#

class planetary_coverage.trajectory.mask_traj.MaskedTrajectory[source]#

Bases: object

Generic masked trajectory object.

MaskedSpacecraftTrajectory#

class planetary_coverage.trajectory.mask_traj.MaskedSpacecraftTrajectory(traj, mask)[source]#

Bases: MaskedTrajectory

Masked spacecraft trajectory object.

Parameters:

  • traj – Original trajectory.

  • mask (numpy.ndarray) – Bool list of the points to mask.

property nb_masked#

Number of point masked.

property nb_segments#

Number of segment(s).

property starts#

UTC start time segments.

property stops#

UTC stop time segments.

property start#

UTC start time of the initial segment.

property stop#

UTC stop time of the last segment.

property windows#

Segmented windows (UTC start and stop times).

property observer#

Observer SPICE reference for the trajectory.

property target#

Target SPICE reference for the trajectory.

property ets#

Masked ephemeris times.

property utc#

Masked UTC times.

property lon_e#

Masked sub-observer ground track east longitudes (degree).

property lat#

Masked sub-observer ground track east latitudes (degree).

property lonlat#

Masked sub-observer ground track east longitudes and latitudes (degree).

property local_time#

Masked sub-observer local time (decimal hours).

property inc#

Masked sub-observer incidence angle (degree).

property emi#

Masked sub-observer emission angle (degree).

property phase#

Masked sub-observer phase angle (degree).

property day#

Masked day side.

property night#

Masked night side.

property dist#

Masked spacecraft distance to target body center (km).

property alt#

Masked spacecraft altitude to the sub-observer point (km).

property target_size#

Masked target angular size (degrees).

property slant#

Masked spacecraft line-of-sight distance to the sub-observer point (km).

property quaternions#

Masked observer quaternions (degree).

property ra#

Masked boresight right ascension pointing (degree).

property dec#

Masked boresight declination pointing (degree).

property radec#

Masked boresight RA/DEC pointing (degree).

property sun_lonlat#

Masked sub-solar ground track coordinates (degree).

property solar_zenith_angle#

Masked sub-observer solar zenith angle (degree).

property solar_longitude#

Masked target seasonal solar longitude (degree).

property true_anomaly#

Masked target orbital true anomaly (degree).

property groundtrack_velocity#

Masked groundtrack velocity (km/s).

distance_to(*args, **kwargs)[source]#

Masked distance to a target body (km).

ets_at(*args, **kwargs)[source]#

Masked ephemeris time at target location with light-time corrections.

utc_at(*args, **kwargs)[source]#

Masked UTC time at target location with light-time corrections.

angular_size(*args, **kwargs)[source]#

Masked Angle size of a given target seen from the spacecraft (degrees).

angle_between(*args, **kwargs)[source]#

Masked angle between 2 rays in spacecraft frame (degrees).

station_azel(*args, **kwargs)[source]#

Masked spacecraft azimuth and elevation seen from a tracking station.

target_separation(*args, **kwargs)[source]#

Masked angular target separation (degrees).

MaskedInstrumentTrajectory#

class planetary_coverage.trajectory.mask_traj.MaskedInstrumentTrajectory(traj, mask)[source]#

Bases: MaskedSpacecraftTrajectory

Masked instrument trajectory.

property lon_e#

Masked instrument surface intersect east longitudes (degree).

property lat#

Masked instrument surface intersect east latitudes (degree).

property lonlat#

Masked instrument surface intersect east longitudes and latitudes (degree).

property local_time#

Masked instrument surface intersect local time (decimal hours).

property inc#

Masked instrument surface intersect incidence angle (degree).

property emi#

Masked instrument surface intersect emission angle (degree).

property phase#

Masked instrument surface intersect phase angle (degree).

property slant#

Masked line-of-sight distance to the boresight surface intersection (km).

property solar_zenith_angle#

Masked instrument surface intersect solar zenith angle (degree).

property pixel_scale#

Masked instrument pixel scale (km/pix).

property fovs#

[Cached] Masked instrument field of view paths collection.

MaskedFovsCollection#

class planetary_coverage.trajectory.fovs.MaskedFovsCollection(fovs, mask)[source]#

Bases: FovsCollection

Masked field of views collection.

property paths#

[Cached] Masked instrument FOV surface paths.

Note

If all the points are above the limb the path is set to None.

SegmentedTrajectory#

class planetary_coverage.trajectory.mask_traj.SegmentedTrajectory[source]#

Bases: object

Generic segmented trajectory object.

SegmentedSpacecraftTrajectory#

class planetary_coverage.trajectory.mask_traj.SegmentedSpacecraftTrajectory(traj, segment)[source]#

Bases: SegmentedTrajectory

Segmented spacecraft trajectory object.

Parameters:

  • traj – Original trajectory.

  • segment (slice) – Segment to extract.

property kernels#

Trajectory required kernels.

property observer#

Observer SPICE reference for the trajectory.

property target#

Target SPICE reference for the trajectory.

property abcorr#

Trajectory aberration correction.

property ets#

Segment Ephemeris Times.

property utc#

Segment UTC times.

property start#

Segment UTC start time.

property stop#

Segment UTC stop time.

property lon_e#

Segment sub-observer ground track east longitudes (degree).

property lat#

Segment sub-observer ground track east latitudes (degree).

property lonlat#

Segment sub-observer ground track coordinates (degree).

property local_time#

Segment sub-observer local time (decimal hours).

property inc#

Segment sub-observer incidence angle (degree).

property emi#

Segment sub-observer emission angle (degree).

property phase#

Segment sub-observer phase angle (degree).

property day#

Segment day side.

property night#

Segment night side.

property dist#

Segment spacecraft distance to target body center (km).

property alt#

Segment spacecraft altitude to the sub-observer point (km).

property target_size#

Segment target angular size (degrees).

property slant#

Segment spacecraft line-of-sight distance to the sub-observer point (km).

property quaternions#

Segment observer quaternions (degree).

property ra#

Segment boresight right ascension pointing (degree).

property dec#

Segment boresight declination pointing (degree).

property radec#

Segment boresight RA/DEC pointing (degree).

property sun_lonlat#

Segment sub-solar ground track coordinates (degree).

property solar_zenith_angle#

Segment sub-observer solar zenith angle (degree).

property solar_longitude#

Segment target seasonal solar longitude (degree).

property true_anomaly#

Segment target orbital true anomaly (degree).

property groundtrack_velocity#

Segment groundtrack velocity (km/s).

distance_to(*args, **kwargs)[source]#

Segment distance to a target body (km).

ets_at(*args, **kwargs)[source]#

Segment ephemeris time at target location with light-time corrections.

utc_at(*args, **kwargs)[source]#

Segment UTC time at target location with light-time corrections.

angular_size(*args, **kwargs)[source]#

Segment Angle size of a given target seen from the spacecraft (degrees).

angle_between(*args, **kwargs)[source]#

Segment angle between 2 rays in spacecraft frame (degrees).

station_azel(*args, **kwargs)[source]#

Segment spacecraft azimuth and elevation seen from a tracking station.

target_separation()[source]#

Segment angular target separation (degrees).

SegmentedInstrumentTrajectory#

class planetary_coverage.trajectory.mask_traj.SegmentedInstrumentTrajectory(traj, segment)[source]#

Bases: SegmentedSpacecraftTrajectory

Segmented instrument trajectory.

property lon_e#

Segment instrument surface intersect east longitudes (degree).

property lat#

Segment instrument surface intersect east latitudes (degree).

property lonlat#

Segment instrument surface intersect east longitudes and latitudes (degree).

property local_time#

Segment instrument surface intersect local time (decimal hours).

property inc#

Segment instrument surface intersect incidence angle (degree).

property emi#

Segment instrument surface intersect emission angle (degree).

property phase#

Segment instrument surface intersect phase angle (degree).

property slant#

Segment line-of-sight distance to the boresight surface intersection (km).

property solar_zenith_angle#

Segment instrument surface intersect solar zenith angle (degree).

property pixel_scale#

Segment instrument pixel scale (km/pix).

property fovs#

[Cached] Segment instrument field of view paths collection.

SegmentedFovsCollection#

class planetary_coverage.trajectory.fovs.SegmentedFovsCollection(traj, npts=25, limb_contour=True, limb=None)[source]#

Bases: FovsCollection

Segmented field of views collection.

Contents