SPICE API#

Time convertor API#

`datetime()`#

planetary_coverage.spice.datetime(string, *others)[source]#

Parse datetime with SPICE convention.

Parameters

string (str) –
Input datetime string. Many format are supported, see the NAIF docs:

https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/time.html#Input%20String%20Conversion

If the string starts with a @, this character will be discarded before being parsed.
*others (str, optional) – Addition input string(s) to parse.

Returns

Parsed string(s) as numpy datetime64 object(s).

Return type

numpy.datetime64 or [numpy.datetime64, …]

Raises

TypeError – If the input time a not a string.
ValueError – If the provided string is not recognized by SPICE.

Note

This routine is the simple parser and does not require any kernel to be loaded.

Warning

This routine does not implement time conversion from UTC to TDB or TDT. You need to load at least a leapsecond kernel to perform these conversions.

`sorted_datetimes()`#

planetary_coverage.spice.sorted_datetimes()[source]#

Sort a list of datetimes.

Parameters

times (list) – List of datetimes to sort.
index (int or tuple, optional) – Index (or indexes) to use when a list of tuple/list is provided (default: None).
reverse (bool, optional) – Sort the list in reverse order.

Returns

Sorted list of datetimes.

Return type

list

Raises

TypeError – If the provided index is not None, int, list or tuple.

Note

The input times don’t need to be pre-formatted.
The output list is only reordered, the input times are not post-formatted.

`iso()`#

planetary_coverage.spice.iso(time)[source]#: Reformat datetime to ISO format.

`mapps_datetime()`#

planetary_coverage.spice.mapps_datetime(time)[source]#

Reformat datetime in MAPPS format.

2001-JAN-01_12:34:56.789

Warning

MAPPS datetime is not natively compatible with the SPICE time patterns.

`et()`#

planetary_coverage.spice.et(utc, *times)[source]#

Convert utc time to ephemeris time.

Parameters

utc (any) –
Input UTC time. All SPICE time formats are accepted.

For example:
- YYYY-MM-DDThh:mm:ss[.ms][Z]
- YYYY-MON-DD hh:mm:ss
Multiple iterable input (slice, list, tuple, numpy.ndarray) are accepted as well.

If an int or float is provided, the value is considered to be in ET and is not not converted.
*times (str) – Addition input UTC time(s) to parse.

Caution

The value is rounded at 1e-3 precision to avoid conversion rounding error with datetime at ms precisions values.

`et_range()`#

planetary_coverage.spice.et_range(start, stop, step='1s', endpoint=True)[source]#

Ephemeris temporal range.

Parameters

start (str) – Initial start UTC time.
stop (str) – Stop UTC time.
step (int or str, optional) – Temporal step to apply between the start and stop UTC times (default: 1s). If the step provided is an int >= 2 it will correspond to the number of samples to generate.
endpoint (bool, optional) – If True, stop is the last sample. Otherwise, it is not included (default: True).

Raises

TypeError – If the provided step is invalid.

`et_ranges()`#

planetary_coverage.spice.et_ranges(*ranges)[source]#

Ephemeris times with a irregular sequence.

Parameters: *ranges (tuple(s), optional) – Sequence(s) of (start, stop, step) tuples.
Returns: Ephemeris times distribution.
Return type: [float, …]

Note

If a start time match the previous stop time, the two sequence will be merged.

See also

et_range

`et_ca_range()`#

planetary_coverage.spice.et_ca_range(t, *dt, et_min=None, et_max=None)[source]#

Ephemeris times around closest approach with a redefined sequence.

Parameters

t (str or numpy.datetime64) – Closest approach UTC time.
*dt (tuple(s), optional) –
Temporal sequence around closest approach:
```
(duration, numpy.datetime unit, step value and unit)
```
By default, the pattern is:
```
[
    (10, 'm', '1 sec'),
    (1, 'h', '10 sec'),
    (2, 'h', '1 min'),
    (12, 'h', '10 min'),
]
```
With will lead to the following sampling:
- 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.
et_min (float, optional) – Smallest valid value of ET (default: None).
et_max (float, optional) – Largest valid value of ET (default: None).

Returns

Ephemeris times distribution around CA.

Return type

[float, …]

Note

The distribution of ET is symmetrical around CA.

`utc()`#

planetary_coverage.spice.utc(et, *ets, unit='ms')[source]#

Convert ephemeris time to UTC time(s) in ISOC format.

Parameters

et (str) – Input Ephemeris time.
*ets (str) – Addition input ET time(s) to parse.
unit (str, optional) – Numpy datetime unit (default: ‘ms’).

Returns

Parsed time in ISOC format: YYYY-MM-DDThh:mm:ss.ms as numpy.datetime64 object.

Return type

numpy.datetime64 or [numpy.datetime64, …]

`tdb()`#

planetary_coverage.spice.tdb(et, *ets)[source]#

Convert ephemeris time to Barycentric Dynamical Time(s).

Parameters

et (str) – Input Ephemeris time.
*ets (str) – Addition input ET time(s) to parse.

Returns

Parsed time in TDB format: YYYY-MM-DD hh:mm:ss.ms TDB

Return type

str or list

`sclk()`#

planetary_coverage.spice.times.sclk(sc, utc, *times)[source]#

Convert utc time to spacecraft.

Parameters

sc (int) – NAIF spacecraft ID code.
utc (str) –
Input UTC time. All SPICE time formats are accepted.

For example:
- YYYY-MM-DDThh:mm:ss[.ms][Z]
- YYYY-MON-DD hh:mm:ss
*times (str) – Addition input UTC time(s) to parse.

Kernel parser API#

`kernel_parser()`#

planetary_coverage.spice.kernel_parser(fname)[source]#

Kernel content and data parser.

Parameters: fname (str or pathlib.Path) – Kernel file name to parse.
Returns: Kernel whole content and parsed data.
Return type: str, dict

`format_data()`#

planetary_coverage.spice.format_data(indent=4, sep=', ', fmt=False, eq='=', **kwargs)[source]#

Format raw data into a text-kernel complaint string.

SPICE constrains:

All assignments, or portions of an assignment, occurring on a line must not exceed 132 characters, including the assignment operator and any leading or embedded white space.

Metakernel only:

When continuing the value field (a file name) over multiple lines, the continuation marker must be a single + character.
The maximum length of any file name, including any path specification, is 255 characters (not enforced here, see planetary_coverage.spice.Metakernel.check() for more details).

Parameters

indent (int, optional) – Number of indentation
sep (str, optional) – Separator character in vectors (default: ', ').
fmt (bool, optional) – Optional value formatter (e.g. .3E for 1.23E-3).
eq (str, optional) – Key-value equal sign (default: '=').
**kwargs (any) – Data keyword(s) and value(s) to format.

Returns

Formatted key and value.

Return type

str

Raises

KeyError – If a key length is larger than 32 characters.
ValueError – If a indentation will create a line larger than 132 characters.

`MetaKernel`#

class planetary_coverage.spice.MetaKernel(mk, download=False, remote=0, load_kernels=False, **kwargs)[source]#

Bases: planetary_coverage.spice._abc.ABCMetaKernel

Metakernel object.

Parameters

mk (str or pathlib.Path) – Metakernel file name.
download (bool, optional) – Download the missing kernels (default: False).
remote (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) – Load the kernels listed in the metakernel into the SPICE pool. If other kernels are present in the SPICE pool, they will be flushed.
**kwargs (dict, optional) – Path key(s) and value(s) to be substituted in KERNELS_TO_LOAD.

Raises

FileNotFoundError – If the metakernel file does not exists locally.
KeyError – If the file provided does not a KERNELS_TO_LOAD key. Or, if a keyword argument is provided but is neither PATH_SYMBOLS nor PATH_VALUES are present.
ValueError – If one of the provided key is not part of the available SYMBOLS.

property fname#: Metakernel filename.

property remote#: Kernel remote source.

load_mk()[source]#: Load kernel content and data.

update_path_values(download=False, **kwargs)[source]#

Update path values.

Parameters

download (bool, optional) – Download the missing kernels (default: False).
**kwargs (any) – Path symbol and value to edit in the file.

Raises

KeyError – If the file provided does not a PATH_VALUES or PATH_SYMBOLS keys.
ValueError – If the provided key was not part of the available SYMBOLS.

property content#: Metakernel content.

get_remote(i=0) → str[source]#

Get remote URL kernel source from the file content.

Raises: ValueError – If more than one remote was found in the content. An explicit remote can be supplied in __init__ to avoid this issue.

property kernels: list#: Kernels to load.

property urls: list#

Kernels urls based on the remote source.

If the remote was not provided either in __init__ nor in the file content, the urls will be empty.

check(download=False)[source]#

Check if all the kernels are locally available.

SPICE constrains:

The maximum length of any file name, including any path specification, is 255 characters.

Parameters

download (bool, str) – Download all the missing kernels.

Raises

BufferError – If the resulting kernel length is larger than the SPICE constrain of 255 characters.
FileNotFoundError – If the kernel is missing locally.

load_kernels()[source]#: Load the kernels listed in the metakernel into the SPICE pool.

Note

If the SPICE pool already contains these kernels, nothing will append. If not, the pool is flushed and only the metakernels kernels are reloaded.

SPICE objects API#

`SpicePool`#

class planetary_coverage.spice.SpicePool[source]#

Bases: object

Spice kernel pool singleton.

See: MetaSpicePool for details.

`MetaSpicePool`#

class planetary_coverage.spice.pool.MetaSpicePool[source]#

Bases: type

Meta Spice kernel pool object.

static count() → int[source]#: Count the number of kernels in the pool.

property kernels#: Return the list of kernels loaded in the pool.

hash(kernels) → int[source]#: Hash a (meta)kernel or a list of (meta)kernels.

contains(kernel)[source]#: Check if the kernel is in the pool.

add(kernel, purge=False)[source]#: Add a kernel to the pool.

remove(kernel)[source]#: Remove the kernel from the pool if present.

purge()[source]#: Purge the pool from all its content.

windows(*refs, fmt='UTC')[source]#

Get kernels windows on a collection of bodies in the pool.

Parameters

refs (str, int or SpiceRef) – Body(ies) reference(s).
fmt (str, optional) –
Output format:
- UTC (default)
- TDB
- ET

Returns

Start and stop times windows in the requested format.

Return type

np.array([[float,float], …])

Raises

KeyError – If the requested reference does not have a specific coverage range in the pool.

coverage(*refs, fmt='UTC')[source]#

Get coverage for a collection of bodies in the pool.

Parameters

refs (str, int or SpiceRef) – Body(ies) reference(s).
fmt (str, optional) –
Output format:
- UTC (default)
- TDB
- ET

Returns

Start and stop times covered for the requested format.

Return type

[str, str] or [float, float]

Note

If multiple values are available, only the max(start) and min(stop) are kept.

Raises

TypeError – If the output format is invalid.
ValueError – If the start time is after the stop time

`SpiceRef`#

class planetary_coverage.spice.SpiceRef(ref)[source]#

Bases: planetary_coverage.spice.references.AbstractSpiceRef

SPICE reference generic helper.

Parameters: ref (str or int) – Reference name or code id.

property spacecraft#

Spacecraft SPICE reference.

Not implemented for a SpiceRef.

sclk(*time)[source]#

Continuous encoded parent spacecraft clock ticks.

Not implemented for a SpiceRef.

`SpiceBody`#

class planetary_coverage.spice.SpiceBody(ref)[source]#

Bases: planetary_coverage.spice.references.AbstractSpiceRef

SPICE planet/satellite body reference.

Parameters: name (str or int) – Body name or code id.

is_valid()[source]#

Check if the code is valid for a SPICE body.

Refer to the NAIF Integer ID codes in section Planets and Satellites for more details.

Returns: Valid bodies are 10 (SUN) and any value between 101 and 999.
Return type: bool

property is_planet#: Check if the body is a planet.

property parent#: [Cached] Parent body.

property barycenter#: [Cached] Body barycenter.

property radii#: [Cached] Body radii, if available (km).

property radius#: Body mean radius, if available (km).

property r#: Body mean radius alias.

property re#: Body equatorial radius, if available (km).

property rp#: Body polar radius, if available (km).

property f#: Body flattening coefficient, if available (km).

property mu#: [Cached] Gravitational parameter (GM, km³/sec²).

`SpiceObserver`#

class planetary_coverage.spice.SpiceObserver(ref)[source]#

Bases: planetary_coverage.spice.references.AbstractSpiceRef

SPICE observer reference.

Parameters: ref (str or int) – Reference name or code id.
Raises: KeyError – If the provided key is neither spacecraft nor an instrument.

`SpiceSpacecraft`#

class planetary_coverage.spice.SpiceSpacecraft(ref)[source]#

Bases: planetary_coverage.spice.references.SpiceObserver

SPICE spacecraft reference.

Parameters: name (str or int) – Spacecraft name or code id.

is_valid()[source]#

Check if the code is valid for a SPICE spacecraft.

Refer to the NAIF Integer ID codes in sections Spacecraft and Earth Orbiting Spacecraft for more details.

Interplanetary spacecraft is normally the negative of the code assigned to the same spacecraft by JPL’s Deep Space Network (DSN) as determined the NASA control authority at Goddard Space Flight Center.
Earth orbiting spacecraft are defined as: -100000 - NORAD ID code

Returns: Valid spacecraft ids are between -999 and -1 and between -119,999 and -100,001.
Return type: bool

property instruments#: [Cached] SPICE instruments in the pool associated with the spacecraft.

instr(name)[source]#: SPICE instrument from the spacecraft.

property spacecraft#: Spacecraft SPICE reference.

sclk(*time)[source]#

Continuous encoded spacecraft clock ticks.

Parameters: *time (float or str) – Ephemeris time (ET) or UTC time inputs.

property frame#: [Cached] Spacecraft frame (if available).

property boresight#

Spacecraft z-axis boresight.

For an orbiting spacecraft, the Z-axis points from the spacecraft to the closest point on the target body.

The component of inertially referenced spacecraft velocity vector orthogonal to Z is aligned with the -X axis.

The Y axis is the cross product of the Z axis and the X axis.

You can change the SpiceSpacecraft.BORESIGHT value manually.

`SpiceInstrument`#

class planetary_coverage.spice.SpiceInstrument(ref)[source]#

Bases: planetary_coverage.spice.references.SpiceObserver, planetary_coverage.spice.fov.SpiceFieldOfView

SPICE instrument reference.

Parameters: name (str or int) – Instrument name or code id.

is_valid()[source]#

Check if the code is valid for a SPICE instrument.

Refer to the NAIF Integer ID codes in section Instruments for more details.

NAIF instrument code = (s/c code)*(1000) - instrument number

Returns: Valid instrument ids is below -1,000 and have a valid field of view definition.
Return type: bool

Warning

Based on the SPICE documentation, the min value of the NAIF code should be -1,000,000. This rule is not enforced because some instrument of JUICE have value below -2,800,000 (cf. JUICE_PEP_JDC_PIXEL_000 (ID: -2_851_000) in juice_pep_v09.ti).

property spacecraft#: [Cached] Parent spacecraft.

Warning

The current definition of JUICE PEP instruments IDs (in juice_pep_v09.ti) are out-of-range NAIF code rules. This special case is expected to be an exception and manually fixed here with a DepreciationWarning. See issue #12 to get more details.

sclk(*time)[source]#

Continuous encoded parent spacecraft clock ticks.

Parameters: *time (float or str) – Ephemeris time (ET) or UTC time inputs.

property ns#: Instrument number of samples.

property nl#: Instrument number of lines.

property fov_along_track#: Instrument field of view along-track angle (radians).

property fov_cross_track#: Instrument field of view cross-track angle (radians).

property ifov#: Instrument instantaneous field of view angle (radians).

Danger

This calculation expect that the sample direction is aligned with the cross-track direction (ie. 1-line acquisition in push-broom mode should be in the direction of flight).

Warning

JUICE_JANUS instrument in v06 does not follow this convention. We manually manage this exception for the moment. See MR !27 for more details.

property ifov_along_track#: Instrument instantaneous along-track field of view angle (radians).

property ifov_cross_track#: Instrument instantaneous cross-track field of view angle (radians).

`SpiceFieldOfView`#

class planetary_coverage.spice.SpiceFieldOfView(code)[source]#

Bases: object

SPICE Instrument field of view object.

Parameters: code (int) – SPICE instrument code.

See also

spiceypy.spiceypy.getfov

property frame#: Field of view reference frame.

property m#: [Cached] Boresight rotation matrix.

to_boresight(*vec)[source]#

Rotate a vector in the plane orthogonal to the boresight.

The vector(s) is/are rotated to be in the plane orthogonal to the boresight with a unit length in the z-direction.

Parameters: *vec (tuple or numpy.ndarray) – Input vector(s) to rotate.

property corners#: [Cached] Boundaries corners in the plane orthogonal to the boresight.

property extent#: [Cached] Boundaries extent in the plane orthogonal to the boresight.

property xlim#: Boundary x-limits in the plane orthogonal to the boresight.

property ylim#: Boundary y-limits in the plane orthogonal to the boresight.

from_boresight(*xy)[source]#

Rotate a vector from the boresight plane to the instrument frame.

Parameters: *xy (tuple or numpy.ndarray) – Input boresight unitary boresight vector(s).

rays(npt=24)[source]#

Interpolated rays around the FOV in the instrument frame.

The points are interpolated in the plane orthogonal to the boresight at a unitary distance to the center and re-aligned with the boresight.

Parameters: npt (int, optional) – Number of points in the interpolated contour (default: 24).
Returns: Field of view contour rays, shape: (npt, 3).
Return type: numpy.ndarray

Note

The points will be distributed evenly and the final number of points may be slightly lower than the requested count.

contour(npt=25)[source]#

FOV footprint contour.

Parameters: npt (int, optional) – Number of points in the interpolated contour (default: 25). The minimum of points is 9.

patch(**kwargs)[source]#

FOV patch in the plane orthogonal to the boresight.

Parameters: **kwargs (any) – Matplotlib artist optional keywords.
Returns: Matplotlib Patch.
Return type: matplotlib.patches.Circle or matplotlib.patches.PathPatch

view(ax=None, fig=None, **kwargs)[source]#

2D display field of view in the plane perpendicular to the boresight.

Parameters

ax (matplotlib.axes.Axes, optional) – Axis to incrust the plot.
fig (matplotlib.figure.Figure, optional) – Main figure (if no ax is provided).
**kwargs (any) – Matplotlib keyword attributes pass to matplotlib.patches.Patch.

Returns

FOV view

Return type

matplotlib.axes

display(ax=None, fig=None, npt=25, show_bounds=False, **kwargs)[source]#

3D display field of view with its the boresight.

Parameters

ax (matplotlib.axes.Axes, optional) – Axis to incrust the plot.
fig (matplotlib.figure.Figure, optional) – Main figure (if no ax is provided).
npt (int, optional) – Number of points in the interpolated contour (default: 25).

Returns

FOV view

Return type

matplotlib.axes

`SpiceAbCorr`#

class planetary_coverage.spice.SpiceAbCorr(abcorr='NONE', restrict=None)[source]#

Bases: str

SPICE light time aberration correction checker.

Parameters

abcorr (str, optional) – SPICE Aberration correction flag (default: 'NONE').
restrict (tuple or list, optional) – List of the valid values.

Returns

Valid SPICE Aberration Correction string.

Return type

str

Raises

KeyError – If the provided key is invalid.

See also

SPICE aberration corrections required reading.

property reception#: Transmission case.

property transmission#: Transmission case.

property stellar#: Stellar aberration.

property oneway#: One-way light time correction / planetary aberration.

property converged#: Converged Newtonian correction.

lt_corr(ets, lt)[source]#

Apply light time correction.

Parameters

ets (float or [float, …]) – Input Ephemeris Time(s).
lt (float or [float, …]) – Light time correction to apply if the aberration is not NONE.

Returns

Corrected Ephemeris Time(s).

Return type

float or [float, …]

dist_corr(ets, dist)[source]#

Compute light time correction from source distance.

Parameters

ets (float or [float, …]) – Input ephemeris time(s).
lt (float or [float, …]) – Source distance (km).

Returns

Light time corrected values.

Return type

float or [float, …]

`AbstractSpiceRef`#

class planetary_coverage.spice.references.AbstractSpiceRef(ref)[source]#

Bases: object

SPICE reference helper.

Parameters: ref (str or int) – Reference name or code id.
Raises: KeyError – If this reference is not known in the kernel pool.

property code#: SPICE reference ID as string.

encode(encoding='utf-8')[source]#: Reference name encoded.

is_valid()[source]#

Generic SPICE reference.

Returns: Generic SPICE reference should always True.
Return type: bool

property frame#: [Cached] Reference frame.

SPICE toolbox API#

`deg()`#

planetary_coverage.spice.toolbox.deg(rad)[source]#: Convert radian angle in degrees.

`rlonlat()`#

planetary_coverage.spice.toolbox.rlonlat(pt)[source]#

Convert point location in planetocentric coordinates.

Parameters

pt (tuple) – Input XYZ cartesian coordinates.

Returns

Point radius (in km).
East planetocentric longitude (in degree).
North planetocentric latitude (in degree).

Return type

float, float, float

Note

If the X and Y components of pt are both zero, the longitude is set to zero.
If pt is the zero vector, longitude and latitude are both set to zero.

See also

spiceypy.spiceypy.reclat

`planetographic()`#

planetary_coverage.spice.toolbox.planetographic(body, xyz)[source]#

Convert point location in planetographic coordinates.

Parameters

body (str or SpiceBody) – SPICE reference name or object.
xyz (tuple) – Input XYZ cartesian coordinates, one or multiple point(s).

Returns

Point altitude (in km).
East or West planetographic longitude (in degree).
North planetographic latitude (in degree).

Return type

float, float, float

Raises

ValueError – If the shape of the point(s) provided is not (3,) or (N, 3).

Note

Planetographic longitude can be positive eastward or westward. For bodies having prograde (aka direct) rotation, the direction of increasing longitude is positive west: from the +X axis of the rectangular coordinate system toward the -Y axis. For bodies having retrograde rotation, the direction of increasing longitude is positive east: from the +X axis toward the +Y axis. The Earth, Moon, and Sun are exceptions: planetographic longitude is measured positive east for these bodies.
Planetographic latitude is defined for a point P on the reference spheroid, as the angle between the XY plane and the outward normal vector at P. For a point P not on the reference spheroid, the planetographic latitude is that of the closest point to P on the spheroid.
You may need a tpc kernel loaded in to the SPICE pool to perform this type of calculation.

See NAIF documentation for more details.

See also

spiceypy.spiceypy.recpgr

`ocentric2ographic()`#

planetary_coverage.spice.toolbox.ocentric2ographic(body, lon_e, lat)[source]#

Convert planetocentric to planetographic coordinates.

Parameters

body (str or SpiceBody) – SPICE reference name or object.
lon_e (float) – East planetocentric longitude.
lat (float) – North planetocentric latitude.

Returns

Planetographic longitude and latitude (in degrees)

Return type

float, float

Raises

ValueError – If the longitude and latitude inputs dimension are not the same.

Note

You may need a tpc kernel loaded in to the SPICE pool to perform this type of calculation.
By default we use the body mean radius (harmonic mean on the ellipsoid).

See also

SpiceBody.radius, planetographic

`radec()`#

planetary_coverage.spice.toolbox.radec(vec)[source]#

Convert vector on the sky J2000 to RA/DEC coordinates.

Parameters

vec (tuple) – Input XYZ cartesian vector coordinates in J200 frame.

Returns

Right-ascension (in degree).
Declination angle (in degree).

Return type

float or numpy.ndarray, float or numpy.ndarray

See also

rlonlat

`sub_obs_pt()`#

planetary_coverage.spice.toolbox.sub_obs_pt(time, observer, target, abcorr='NONE', method='NEAR POINT/ELLIPSOID')[source]#

Sub-observer point calculation.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the observer location.
observer (str) – Observer name.
target (str or SpiceBody) – Target body name.
abcorr (str, optional) – Aberration correction (default: ‘None’)
method (str, optional) –
Computation method to be used. Possible values:
- ’NEAR POINT/ELLIPSOID’ (default)
- ’INTERCEPT/ELLIPSOID’
- ’NADIR/DSK/UNPRIORITIZED[/SURFACES = <surface list>]’
- ’INTERCEPT/DSK/UNPRIORITIZED[/SURFACES = <surface list>]’
(See NAIF spiceypy.spiceypy.subpnt() for more details).

Returns

Sub-observer XYZ coordinates in the target body fixed frame (expressed in km).

If a list of time were provided, the results will be stored in a (3, N) array.

Return type

(float, float, float) or numpy.ndarray

See also

spiceypy.spiceypy.subpnt

`sc_state()`#

planetary_coverage.spice.toolbox.sc_state(time, spacecraft, target, abcorr='NONE')[source]#

Spacecraft position and velocity relative to the target.

The position vector starts from the target body to the spacecraft:

target ------> spacecraft
        (km)

The velocity vector correspond to the spacecraft motion (in km/s).

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the spacecraft location.
spacecraft (str or SpiceSpacecraft) – Spacecraft name.
target (str or SpiceBody) – Target body name.
abcorr (str, optional) – Aberration correction (default: ‘None’)

Returns

Spacecraft XYZ position and velocity coordinates in the target body fixed frame (expressed in km and km/s).

If a list of time were provided, the results will be stored in a (6, N) array.

Return type

(float, float, float, float, float, float) or numpy.ndarray

See also

spiceypy.spiceypy.spkezr

`attitude()`#

planetary_coverage.spice.toolbox.attitude(time, observer, ref='J2000')[source]#

C-matrix attitude.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the observer location.
observer (str or SpiceSpacecraft or SpiceInstrument) – Spacecraft or instrument name.
ref (str, optional) – Reference for the return pointing.

Returns

C-matrix relative to the reference frame.

If a list of time were provided, the results will be stored in a (3, 3, N) array.

Return type

numpy.ndarray

Raises

ValueError – If the observer provided is not a Spacecraft or an instrument.

See also

spiceypy.spiceypy.pxform

`intersect_pt()`#

planetary_coverage.spice.toolbox.intersect_pt(time, observer, target, frame, ray, limb=False, abcorr='NONE', method='ELLIPSOID')[source]#

Intersection point on a target from a ray at the observer position.

The intersection is primarily computed with the target surface. If no intersection was found and the limb flag is set to TRUE, the intersection will be search on the target limb (defined as the impact parameter). When no value was find, a NaN array will be return.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the observer location.
observer (str or SpiceSpacecraft or SpiceInstrument) – Spacecraft of instrument observer name.
target (str or SpiceBody) – Target body name.
frame (str) – Reference frame relative to which the ray’s direction vector is expressed.
ray (tuple or list of tuple) – Ray direction vector emanating from the observer. The intercept with the target body’s surface of the ray defined by the observer and ray is sought.
limb (bool, optional) – Compute the intersection on the limb impact parameter if no intersection with the surface was found.
abcorr (str, optional) – Aberration correction (default: ‘None’)
method (str, optional) – Computation method to be used. (See NAIF spiceypy.spiceypy.sincpt() for more details).

Returns

Surface/limb intersection XYZ position on the target body fixed frame (expressed in km).

If a list of time/ray were provided, the results will be stored in a (3, N) array.

Return type

(float, float, float) or numpy.ndarray

Warning

Currently the limb intersection parameter is only available for abcorr='NONE' (an NotImplementedError will be raised).

`boresight_pt()`#

planetary_coverage.spice.toolbox.boresight_pt(time, observer, target, limb=False, abcorr='NONE', method='ELLIPSOID')[source]#

Surface intersection on a target from an instrument/spacecraft boresight.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the observer location.
observer (str or SpiceSpacecraft or SpiceInstrument) – Spacecraft or instrument name.
target (str or SpiceBody) – Target body name.
limb (bool, optional) – Compute the intersection on the limb impact parameter if no intersection with the surface was found.
abcorr (str, optional) – Aberration correction (default: ‘None’)
method (str, optional) – Computation method to be used. (See NAIF spiceypy.spiceypy.sincpt() for more details).

Returns

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

If a list of time were provided, the results will be stored in a (3, N) array.

Return type

(float, float, float) or numpy.ndarray

See also

intersect_pt

`fov_pts()`#

planetary_coverage.spice.toolbox.fov_pts(time, inst, target, limb=False, npt=24, abcorr='NONE', method='ELLIPSOID')[source]#

Surface intersection on a target from an instrument FOV rays.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the observer location.
inst (str or SpiceInstrument) – Instrument name.
target (str or SpiceBody) – Target body name.
limb (bool, optional) – Compute the intersection on the limb impact parameter if no intersection with the surface was found.
npt (int, optional) – Number of points in the field of view contour (default: 24).
abcorr (str, optional) – Aberration correction (default: ‘None’),
method (str, optional) – Computation method to be used. (See NAIF spiceypy.spiceypy.sincpt() for more details).

Returns

Field of View intersection XYZ positions on the target surface body fixed frame (expressed in km).

If a list of time were provided, the results will be stored in a (3, N, M) array. M being the number of bound in the FOV.

Return type

(float, float, float) or numpy.ndarray

See also

intersect_pt

Note

In the general case, the last point should be different from the 1st one. You need to add the 1st point to the end of the list if you want to close the polygon of the footprint.

`local_time()`#

planetary_coverage.spice.toolbox.local_time(time, lon, target, lon_type='PLANETOCENTRIC')[source]#

Local solar time.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the target surface point location.
lon (float or list or tuple) – Longitude of surface point (degree).
target (str) – Target body name.
lon_type (str, optional) –
Form of longitude supplied by the variable lon. Possible values:
- PLANETOCENTRIC (default)
- PLANETOGRAPHIC
(See NAIF spiceypy.spiceypy.et2lst() for more details).

Returns

Local solar time (expressed in decimal hours).

If a list of time or lon were provided, the results will be stored in an array.

Return type

float or numpy.ndarray

Raises

ValueError – If the time and lon are both arrays but their size don’t match.

See also

spiceypy.spiceypy.et2lst

`illum_angles()`#

planetary_coverage.spice.toolbox.illum_angles(time, spacecraft, target, pt, abcorr='NONE', method='ELLIPSOID')[source]#

Illumination angles.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the target surface point location.
spacecraft (str) – Spacecraft name.
target (str) – Target body name.
pt (numpy.ndarray) – Surface point (XYZ coordinates).
abcorr (str, optional) – Aberration correction (default: ‘None’)
method (str, optional) –
Form of longitude supplied by the variable lon. Possible values:
- ELLIPSOID (default)
- DSK/UNPRIORITIZED[/SURFACES = <surface list>]
(See NAIF spiceypy.spiceypy.ilumin() for more details).

Returns

Solar incidence, emission and phase angles at the surface point (degrees).

If a list of time were provided, the results will be stored in a (3, N) array.

Return type

float or numpy.ndarray

Raises

ValueError – If the time and lon are both arrays but their size don’t match.

See also

spiceypy.spiceypy.ilumin

`sun_pos()`#

planetary_coverage.spice.toolbox.sun_pos(time, target, abcorr='NONE')[source]#

Sun position relative to the target.

The vector starts from the target body to the Sun:

target ------> Sun
        (km)

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the target’s center location.
target (str) – Target body name.
abcorr (str, optional) – Aberration correction (default: ‘None’)

Returns

Sun XYZ coordinates in the target body fixed frame (expressed in km).

If a list of time were provided, the results will be stored in a (3, N) array.

Return type

(float, float, float) or numpy.ndarray

See also

spiceypy.spiceypy.spkpos

`solar_longitude()`#

planetary_coverage.spice.toolbox.solar_longitude(time, target, abcorr='NONE')[source]#

Seasonal solar longitude (degrees).

Compute the angle from the vernal equinox of the main parent body.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the target’s center location.
target (str) – Target body name.
abcorr (str, optional) – Aberration correction (default: ‘None’)

Returns

Solar longitude angle(s) (degrees).

If a list of time were provided, the results will be stored in an array.

Return type

float or numpy.ndarray

Note

If the target parent is not the SUN the target will be change for its own parent.

See also

spiceypy.spiceypy.lspcn

`true_anomaly()`#

planetary_coverage.spice.toolbox.true_anomaly(time, target, abcorr='NONE', frame='ECLIPJ2000')[source]#

Target orbital true anomaly (degrees).

The angular position of the target in its orbit compare to its periapsis.

Parameters

time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the target’s center location.
target (str) – Target body name.
abcorr (str, optional) – Aberration correction (default: ‘None’)
frame (str, optional) – Inertial frame to compute the state vector (default: ECLIPJ2000).

Returns

True anomaly angle (degrees).

If a list of time were provided, the results will be stored in an array.

Return type

float or numpy.ndarray

`groundtrack_velocity()`#

planetary_coverage.spice.toolbox.groundtrack_velocity(target, state)[source]#

Ground track velocity (km/s).

Speed motion of the sub-observer point along the groundtrack.

Caution

This speed does not correspond to the norm of the rejection of the velocity vector of the observer in the target fixed frame.

Warning

This formula is only valid for a spheroid elongated along the axis of rotation (c). It is not correct for a generic ellipsoid.

No aberration correction is applied.

Parameters

target (str) – Target body name.
state (str) – Target -> observer state position and velocity vectors. Computed at the observer time.

Returns

Ground track velocity (km/s).

If a list of state is provided, the results will be stored in an array.

Return type

float or numpy.ndarray

Raises

ValueError – If the state arrays doesn’t have the good shape.

Note

The tangential speed is obtained as product of the local radius of the observed body with the tangential angular speed:

latitudinal
component
    ^   x
    |  /
    | / <- tangential component
    |/
    o----> longitudinal component

        (the cos is to compensate the 'shrinking' of
         longitude increasing the latitude)

`pixel_scale()`#

planetary_coverage.spice.toolbox.pixel_scale(inst, target, emi, dist)[source]#

Instrument pixel resolution (km/pixel).

Only the cross-track iFOV is used and projected on the target body in spherical geometry (corrected from the local emission angle).

Parameters

target (str or SpiceBody) – Target body name.
inst (str or SpiceInstrument) – Instrument name.
emi (float, list or numpy.ndarray) – Local emission angle (in degrees).
dist (float, list or numpy.ndarray) – Distance from the observer to the target body center (in km).

Returns

Local instrument pixel resolution (km/pix).

Return type

float or numpy.ndarray

`limb_ip_pt()`#

planetary_coverage.spice.limb.limb_ip_pt(et_obs, observer_id, target_id, obs_frame, obs_ray, target_frame, abcorr='NONE')[source]#

Limb impact parameter point on a target from a ray at the observer position.

Impact parameter vector based on the ray emerging form the observer. No check is performed to know it the surface of the target is intersected.

· target
| ∖
|   ·
|     ∖  <- Target -> Impact parameter vector
|       ·  Impact parameter point ( ip vector ⟂ ray)
|     ⋰
|   ·
| /  <- Observer emerging Ray
· Observer

Parameters

time (float) – Observer Ephemeris Time.
observer_id (int) – Observer id code.
target_id (int) – Target body id code.
obs_frame (str) – Observer reference frame relative to which the ray’s direction vector is expressed.
obs_ray (tuple or list of tuple) – Ray direction vector emanating from the observer.
target_frame (str) – Target reference frame relative to impact parameter vector is expressed (from the target center).
abcorr (str, optional) – Aberration correction (default: ‘None’). See Danger section below.

Returns

Limb impact parameter XYZ coordinates in the target body fixed frame (expressed in km).

If a list of time were provided, the results will be stored in a (3, N) array.

Return type

(float, float, float) or np.ndarray

Raises

NotImplementedError – If a light time correction is required.

Danger

No implementation of the limb impact parameter is directly available in the NAIF SPICE routines. In this function we tried to implement our own but support for light aberration correction is not implemented yet. Use it at your own risks.

See also

spiceypy.spiceypy.spkezp

SPICE CLI#

`kernel-download`#

planetary_coverage.cli.cli_kernel_download(argv=None)[source]#

CLI to download kernel(s) from a kernel registry.

The user can provide an agency + mission argument (eg. –esa JUICE) to point to the known kernel registry or provide directly the URL (-r/–remote). If none is provided, the cli will attempt to download it from NAIF generic kernels.

Note: only one remote is accepted. Otherwise an ERROR is raised.

The user can also specify where to store the kernels (with -o/–kernels-dir).

If the requested kernel is already present locally, the cli will raise an ERROR, unless the user provide a -f/–force flag (to overwrite it) or -s/–skip flag (to continue).

Hint: the user can provide a list a kernels to download them in a batch.

Tip: if no kernels is provided, the cli will return the remote location url.

`metakernel-download`#

planetary_coverage.cli.cli_metakernel_download(argv=None)[source]#

CLI to download the missing kernel in a metakernel.

If a remote location is provided in the file header it will be used by default, unless if the user provide a custom -r/–remote location.

By default, the kernels will be stored at the location defined in the metakernel. This parameter can be override with -o/–kernels-dir.

SPICE Decorator#

`@check_kernels`#

@planetary_coverage.spice.check_kernels[source]#

Spice Pool kernels checker decorator.

The parent object must implement a __hash__() function and have a kernels attribute.

Planetary coverage documentation

SPICE API

Contents

SPICE API#

Time convertor API#

datetime()#

sorted_datetimes()#

iso()#

mapps_datetime()#

et()#

et_range()#

et_ranges()#

et_ca_range()#

utc()#

tdb()#

sclk()#

Kernel parser API#

kernel_parser()#

format_data()#

MetaKernel#

SPICE objects API#

SpicePool#

MetaSpicePool#

SpiceRef#

SpiceBody#

SpiceObserver#

SpiceSpacecraft#

SpiceInstrument#

SpiceFieldOfView#

SpiceAbCorr#

AbstractSpiceRef#

SPICE toolbox API#

deg()#

rlonlat()#

planetographic()#

ocentric2ographic()#

radec()#

sub_obs_pt()#

sc_state()#

attitude()#

intersect_pt()#

boresight_pt()#

fov_pts()#

local_time()#

illum_angles()#

sun_pos()#

solar_longitude()#

true_anomaly()#

groundtrack_velocity()#

pixel_scale()#

limb_ip_pt()#

SPICE CLI#

kernel-download#

metakernel-download#

SPICE Decorator#

@check_kernels#

`datetime()`#

`sorted_datetimes()`#

`iso()`#

`mapps_datetime()`#

`et()`#

`et_range()`#

`et_ranges()`#

`et_ca_range()`#

`utc()`#

`tdb()`#

`sclk()`#

`kernel_parser()`#

`format_data()`#

`MetaKernel`#

`SpicePool`#

`MetaSpicePool`#

`SpiceRef`#

`SpiceBody`#

`SpiceObserver`#

`SpiceSpacecraft`#

`SpiceInstrument`#

`SpiceFieldOfView`#

`SpiceAbCorr`#

`AbstractSpiceRef`#

`deg()`#

`rlonlat()`#

`planetographic()`#

`ocentric2ographic()`#

`radec()`#

`sub_obs_pt()`#

`sc_state()`#

`attitude()`#

`intersect_pt()`#

`boresight_pt()`#

`fov_pts()`#

`local_time()`#

`illum_angles()`#

`sun_pos()`#

`solar_longitude()`#

`true_anomaly()`#

`groundtrack_velocity()`#

`pixel_scale()`#

`limb_ip_pt()`#

`kernel-download`#

`metakernel-download`#

`@check_kernels`#