SPICE API

Time convertor API

datetime()

planetary_coverage.spice.datetime(string, *others)

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(times, index=None, reverse=False)

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)

Reformat datetime to ISO format.

jdn_hms()

planetary_coverage.spice.jdn_hms(string)

Extract the julian day and the time from a string.

Parameters:

string (str) – Input string to parse.

Returns:

Julian date number, hours, minutes, seconds and milliseconds values.

Return type:

int, int, int, int, int

Raises:

ValueError – If the string can not be parsed as a SPICE time.

Note

The precision output time is rounded at 1 millisecond. The Julian Day Number is always defined with respect to the Gregorian calendar.

Warning

This definition of the Julian Date does not date into account leapseconds. Use Ephemeris Time (et) if you need a 1 second precision.

See also

ymd(), jd()

jd()

planetary_coverage.spice.jd(string)

Convert time from a string to decimal Julian Date.

Parameters:

string (str) – Input time string to convert.

Returns:

Julian day decimal value.

Return type:

float

Raises:

ValueError – If the string can not be parsed as a SPICE time.

Warning

This definition of the Julian Date does not date into account leapseconds. Use Ephemeris Time (et) if you need a 1 second precision.

See also

jdn_hms()

ymd()

planetary_coverage.spice.ymd(jdn)

SPICE conversion from Julian Day to the Gregorian Calendar.

Parameters:

jdn (int) – Julian Date Number (no decimal value).

Returns:

Parsed year, month and day in the Gregorian Calendar.

Return type:

int, int, int

Warning

The dates before October 15th, 1582 are still represented in the Gregorian calendar and not in the Julian calendar. This is not strictly correct but it does correspond to the default behavior of SPICE and Numpy:

>>> spiceypy.tparse('1582-10-14')
>>> numpy.datetime64('1582-10-14')

Don’t throw errors even if theses date don’t exists, although the day before 1582-10-15 should be 1582-10-04.

>>> numpy.datetime64('1582-10-15') - numpy.datetime64('1582-10-04') ==         numpy.timedelta64(1,'D')
False

mapps_datetime()

planetary_coverage.spice.mapps_datetime(time)

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)

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)

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

Returns:

List of ephemeris times.

Return type:

numpy.array

Raises:

• TypeError – If the provided step is invalid.

• ValueError – If the provided stop time is before the start time.

See also

et_range, et_ranges, et_ca_range, utc_range, utc_ranges, utc_ca_range

et_ranges()

planetary_coverage.spice.et_ranges(*ranges)

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, utc_ranges

et_ca_range()

planetary_coverage.spice.et_ca_range(t, *dt, et_min=None, et_max=None)

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.

See also

et_range, et_ranges, utc_ca_range

utc()

planetary_coverage.spice.utc(et, *ets, unit='ms')

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, …]

utc_range()

planetary_coverage.spice.utc_range(start, stop, step='1s', endpoint=True)

UTC 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).

Returns:

List of UTC times.

Return type:

numpy.array

Raises:

• TypeError – If the provided step is invalid.

• ValueError – If the provided stop time is before the start time.

See also

et_range

utc_ranges()

planetary_coverage.spice.utc_ranges(*ranges)

UTC times with a irregular sequence.

Parameters:

*ranges (tuple(s), optional) – Sequence(s) of (start, stop, step) tuples.

Returns:

UTC times distribution.

Return type:

[float, …]

Note

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

See also

et_ranges

utc_ca_range()

planetary_coverage.spice.utc_ca_range(t, *dt, utc_min=None, utc_max=None)

UTC 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 (see et_ca_range for details).

• utc_min (float, optional) – Smallest valid value in UTC (default: None).

• utc_max (float, optional) – Largest valid value in UTC (default: None).

Returns:

UTC times distribution around CA.

Return type:

[float, …]

Note

The distribution of ET is symmetrical around CA.

See also

et_ca_range

tdb()

planetary_coverage.spice.tdb(et, *ets)

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)

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)

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)

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.

get_summary()

planetary_coverage.spice.kernel.get_summary(kernels)

Get kernels summary description.

Parameters:

kernels ([str or pathlib.Path, ...]) – List of kernel file names.

Returns:

Summary of kernels count and sizes grouped by types.

Return type:

list

get_details()

planetary_coverage.spice.kernel.get_details(kernels)

Get kernels detailed description.

Parameters:

kernels ([str or pathlib.Path, ...]) – List of kernel file names.

Returns:

Detailed list of kernels types and sizes.

Return type:

list

get_type()

planetary_coverage.spice.kernel.get_type(kernel, default_txt='UNKNOWN', default_icon='❓') → str

Get kernel type icon.

Parameters:

• kernel (str or pathlib.Path) – Kernel filename.

• default_txt (str, optional) – Optional default type if the extension is unknown.

• default_icon (str, optional) – Optional default type if the kernel type is unknown.

Returns:

Kernel icon based on it extension.

Return type:

str

MetaKernel

class planetary_coverage.spice.MetaKernel(mk, download=False, remote=0, load_kernels=False, n_threads=2, **kwargs)

Bases: 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.

• n_threads (int, optional) – Number of threads to open in parallel to download missing kernels. Default: DEFAULT_N_THREADS. On windows, multi-thread download is disable by default (see #80) but you can still specify explicitly the number of thread that you want to use.

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

Load kernel content and data.

update_path_values(download=False, **kwargs)

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

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)

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

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.

property title

Metakernel title.

property description

Metakernel description.

property summary

Metakernel kernels content summary.

property details

Metakernel kernels content details.

property html

HTML representation.

SPICE objects API

SpicePool

class planetary_coverage.spice.SpicePool

Bases: object

Spice kernel pool singleton.

See: MetaSpicePool for details.

MetaSpicePool

class planetary_coverage.spice.pool.MetaSpicePool

Bases: type

Meta Spice kernel pool object.

static count() → int

Count the number of kernels in the pool.

property kernels

Return the list of kernels loaded in the pool.

hash(kernels) → int

Hash a (meta)kernel or a list of (meta)kernels.

contains(kernel)

Check if the kernel is in the pool.

add(kernel, *, purge=False)

Add a kernel to the pool.

remove(kernel)

Remove the kernel from the pool if present.

purge()

Purge the pool from all its content.

property summary

Pool content summary.

property details

Pool content summary.

windows(*refs, fmt='UTC')

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

Based on CK, PCK and SPK files.

Parameters:

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

• fmt (str, optional) –

  Output time format:

  • UTC (default)

  • TDB

  • ET

Returns:

{SpiceRef – Start and stop times windows in the requested format.

Return type:

{str: numpy.ndarray([[float|str, float|str], …]), …}, …}

Raises:

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

See also

coverage, gaps, brief

coverage(*refs, fmt='UTC')

Get coverage for a collection of bodies in the pool.

Parameters:

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

• fmt (str, optional) –

  Output time 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 time format is invalid.

• ValueError – If the start time is after the stop time

See also

coverage, gaps

gaps(*refs, fmt='UTC')

Get coverage caps (if any) for a collection of bodies in the pool.

Parameters:

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

• fmt (str, optional) –

  Output time format:

  • UTC (default)

  • TDB

  • ET

Returns:

Start and stop times of coverage gaps intervals in the requested format.

Return type:

[[str, str], …] or [[float, float], …]

See also

windows, coverage, brief

brief(fmt='UTC')

Bodies temporal coverage from CK, PCK and SPK kernels.

Similar to NAIF brief -t -a method.

Parameters:

fmt (str, optional) –

Output time format:

• UTC (default)

• TDB

• ET

Returns:

{SpiceRef – Bodies reference dictionary of start and stop times covered for the requested format.

Return type:

(float|str, float|str)}

Raises:

TypeError – If the output time format is invalid.

See also

windows, coverage, gaps

SpiceRef

class planetary_coverage.spice.SpiceRef(ref)

Bases: 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)

Continuous encoded parent spacecraft clock ticks.

Not implemented for a SpiceRef.

SpiceBody

class planetary_coverage.spice.SpiceBody(ref)

Bases: AbstractSpiceRef

SPICE body reference.

It can be either:

• Sun

• Planet

• Satellite

• Comet (including fragments)

• Asteroid (permanently or provisional numbered)

Parameters:

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

is_valid()

Check if the code is valid for a SPICE body.

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

• Sun: 10

• Planets: N99

• Satellites: NMM with MM not 00 or 99 (*)

(*): No satellites for Mercury nor Venus, only the Moon (301) for the Earth and Phobos (401) and Deimos (402) for Mars.

• Commets: 1,000,000 + JPL's Solar System Dynamics Group number

• Asteroid original schema (7-digits):

  • Permanently numbered: 2,000,000 + Permanent Asteroid Number (2,000,001 to 2,999,999)

  • Provisional numbered: 3,000,000 + Provisional Asteroid Number (3,000,001 to 3,999,999)

• Asteroid extended schema (8 or 9-digits):

  • Permanently numbered: 20,000,000 + Permanent Asteroid Number (20,000,001 to 49,999,999)

  • Provisional numbered: 50,000,000 + Provisional Asteroid Number (20,000,001 to 49,999,999)

Warning

For asteroid systems with two or more bodies the 8-digit NAIF ID code represents the barycenter. Individual satellites have a prepended number 1 through 8, while the primary body uses the last available prefix 9, resulting in 9-digit NAIF ID codes. For example, asteroids Didymos (65,803) and its satellite Dimorphos can be accommodated only using the extended schema with IDs 920,065,803 and 120,065,803, and Didymos system barycenter with ID 20,065,803.

Note

Asteroid barycenter will not be considered as SpiceBody but as a regular SpiceRef.

Returns:

Valid body ids are listed above.

Return type:

bool

property is_planet

Check if the body is a planet.

property is_satellite

Check if the body is a planet, asteroid or commet’s satellite.

property is_comet

Check if the body is a comet.

property is_asteroid

Check if the body is an asteroid.

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)

Bases: 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)

Bases: SpiceObserver

SPICE spacecraft reference.

Parameters:

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

is_valid()

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)

SPICE instrument from the spacecraft.

property spacecraft

Spacecraft SPICE reference.

sclk(*time)

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)

Bases: SpiceObserver, SpiceFieldOfView

SPICE instrument reference.

Parameters:

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

is_valid()

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

This allows for 1000 instrument assignments on board a spacecraft.

Danger

Based on the SPICE documentation, and instrument should have a NAIF code between -1,000,000. For some mission (Juice, EnVision), this rule is not enforced because some instrument requires more ids. For examples:

• juice_pep_v15.ti has JUICE_PEP_JDC_PIXEL_000 (ID: -2_851_000)

• envision_vensar_v00.ti has ENVISION_VENSAR_SAR_20_220 (ID: -668_110_001)

Returns:

Valid instrument ids are below -1,000 and have a valid field of view definition.

Return type:

bool

property spacecraft

[Cached] Parent spacecraft.

Warning

Some mission don’t enforce NAIF rule on instrument id definition. Therefore, the preferred method to guess the parent of the spacecraft name is to extract the first part of the instrument name. If this method fails, the instrument id is divided by 1,000 to get the space id.

Raises:

ValueError – If the SpiceSpacecraft is not found.

sclk(*time)

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

SpiceFrame

class planetary_coverage.spice.SpiceFrame(ref)

Bases: AbstractSpiceRef

SPICE reference frame.

Parameters:

name (str or int) – Reference frame name or code id.

is_valid()

Check if the code is a frame code.

property class_type

Frame class type.

property center

Frame center reference.

property sclk

Frame SCLK reference.

property spk

Frame SPK reference.

property frame

[Cached] Reference frame.

Not implemented for a SpiceFrame.

SpiceFieldOfView

class planetary_coverage.spice.SpiceFieldOfView(code)

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)

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)

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)

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 or tuple, optional) –

Number of rays in the interpolated contour.

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.

Returns:

Field of view contour rays, shape: (npt, 3).

If npt is a tuple, you need to compute how many points were added per edge to get to total number of points in the contour.

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.

static rays_circle(r, npt)

Interpolated rays around a CIRCLE FOV.

Parameters:

• r (float, optional) – Circle radius.

• npt (int) – Number of points in the interpolated contour.

Returns:

Interpolated coordinates in the XY plane.

Return type:

numpy.ndarray

static rays_ellipse(a, b, npt)

Interpolated rays around a ELLIPSE FOV.

Parameters:

• a (float, optional) – Ellipse primary axis.

• b (float, optional) – Ellipse secondary axis.

• npt (int) – Number of points in the interpolated contour.

Returns:

Interpolated coordinates in the XY plane.

Return type:

numpy.ndarray

static rays_edges(corners, npt)

Interpolated rays around a RECTANGULAR or POLYGON FOV.

Parameters:

• corners (list) – List of FOV corners coordinates.

• npt (int or tuple) –

  Number of points around the contour including the corners. If npt <= len(corners), no interpolation will be performed. If npt > len(corners), they will be evenly distributed on each edge, then the final number of points on the contour may be smaller than npt.

  If npt is provided as a tuple, it will correspond to the number of interpolation points to be added on each edges between the corners. If len(npt) < len(corners) it will be cycled though each edges.

Returns:

Interpolated coordinates in the XY plane.

Return type:

numpy.ndarray

contour(npt=25)

FOV footprint contour.

Parameters:

npt (int or tuple, optional) –

Number of points in the interpolated contour (default: 25). The minimum of points is 9 to properly represent the CIRCLE and ELLIPSE shapes.

If tuple is provided, it will be used to split the edges recursively.

See also

rays

patch(**kwargs)

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)

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)

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)

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)

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)

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)

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

Reference name encoded.

is_valid()

Generic SPICE reference.

Returns:

Generic SPICE reference should always True.

Return type:

bool

property frame

[Cached] Reference frame.

SpiceRefRegex

class planetary_coverage.spice.references.SpiceRefRegex(re_exp)

Bases: object

SPICE regular expression for references.

Tip

To check the pattern you need to use the in keyword:

>>> 399 in SpiceRefRegex(r'[1-9]99')
True

Warning

The match is only performed on the whole pattern, and the regular expression pattern is always prefixed with ^ and suffixed by $ internally (if not already present).

Note

SpiceRefRegex patterns can be concatenated with the OR operator (|):

>>> INNER_MOONS = SpiceRefRegex(r'301|401|402')
>>> OUTER_MOONS = SpiceRefRegex(r'[5-9](?!00|99)\d{2}')
>>> 501 in INNER_MOONS | OUTER_MOONS
True

SPICE toolbox API

deg()

planetary_coverage.spice.toolbox.deg(rad)

Convert radian angle in degrees.

rlonlat()

planetary_coverage.spice.toolbox.rlonlat(pt)

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)

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)

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)

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

azel()

planetary_coverage.spice.toolbox.azel(vec, az_spice=False, el_spice=True)

Convert vector in a reference frame into azimuth and elevation.

Parameters:

• vec (tuple) – Input XYZ cartesian vector coordinates in the reference frame.

• 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 angle from +X in XY plane (in degree).

• Elevation angle above or below the XY plane (in degree).

Return type:

float, float, float

See also

rlonlat, station_azel

sub_obs_pt()

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

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

target_position()

planetary_coverage.spice.toolbox.target_position(time, observer, target, *, abcorr='NONE')

Sun position relative to the target.

The vector starts from the observer to the target body:

observer ------> target
          (km)

Parameters:

• time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the observer’s center location.

• observer (str or SpiceRef) – Observer body name.

• target (str or SpiceRef) – Target body name.

• abcorr (str, optional) – Aberration correction (default: ‘NONE’)

Returns:

Target 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, sun_pos, ang_size, station_azel

sun_pos()

planetary_coverage.spice.toolbox.sun_pos(time, target, *, abcorr='NONE')

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

target_position

angular_size()

planetary_coverage.spice.toolbox.angular_size(time, observer, target, *, abcorr='NONE')

Angular size of a target as seen from an observer.

Parameters:

• time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the observer’s center location.

• observer (str or SpiceBody) – Observer body name.

• target (str or SpiceBody) – Target body name.

• abcorr (str, optional) – Aberration correction (default: ‘NONE’)

Returns:

Target angular size seen from the observer (in degree).

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

Return type:

float or numpy.ndarray

See also

target_position

station_azel()

planetary_coverage.spice.toolbox.station_azel(time, target, station, *, abcorr='CN+S', az_spice=False, el_spice=True)

Compute azimuth and elevation of target seen from a station on Earth.

station ------> target

Parameters:

• time (float or list or tuple) – Ephemeris Time or UTC time input(s). It refers to time at the station location.

• target (str or SpiceBody) – Target body name.

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

• abcorr (str, optional) – Aberration correction (default: ‘NONE’)

• 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 angle from +X in XY plane (in degree).

• Elevation angle above or below the XY plane (in degree).

Return type:

float, float, float

See also

target_position, azel

sc_state()

planetary_coverage.spice.toolbox.sc_state(time, spacecraft, target, abcorr='NONE')

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.attitude(time, observer, ref='J2000')

C-matrix attitude.

Based on SPICE documentation C-matrix (camera matrix) transforms the coordinates of a point in a reference frame (like J2000) into the instrument fixed coordinates:

[ x_inst]     [          ] [ x_J2000 ]
| y_inst|  =  | C-matrix | | y_J2000 |
[ z_inst]     [          ] [ z_J2000 ]

The transpose of a C-matrix rotates vectors from the instrument-fixed frame to the base frame:

[ x_J2000]     [          ]T [ x_inst ]
| y_J2000|  =  | C-matrix |  | y_inst |
[ z_J2000]     [          ]  [ z_inst ]

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.

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

quaternions()

planetary_coverage.spice.quaternions(attitude_matrix)

Compute the SPICE rotation quaternions.

Parameters:

attitude_matrix (numpy.ndarray) – Attitude rotation matrix

Returns:

SPICE quaternions equivalent to the provided rotation matrix.

If a list of attitude matrix was provided, the results will be stored in a (4, N) array.

Return type:

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

Raises:

ValueError – If the attitude matrix shape is not (3, 3) or (3, 3, N).

See also

attitude, spiceypy.spiceypy.pxform

intersect_pt()

planetary_coverage.spice.toolbox.intersect_pt(time, observer, target, frame, ray, limb=False, abcorr='NONE', corloc='TANGENT POINT', method='ELLIPSOID')

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’).

• corloc (str, optional) – Aberration correction locus (default: ‘TANGENT POINT’). Used only if limb=True.

• 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), plus a surface intersection flag.

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

Return type:

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

Warning

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

See also

spiceypy.spiceypy.sincpt, spiceypy.spiceypy.tangpt

boresight_pt()

planetary_coverage.spice.toolbox.boresight_pt(time, observer, target, limb=False, abcorr='NONE', corloc='TANGENT POINT', method='ELLIPSOID')

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

• corloc (str, optional) – Aberration correction locus (default: ‘TANGENT POINT’). Used only if limb=True.

• 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), plus a surface intersection flag.

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

Return type:

(float, 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', corloc='TANGENT POINT', method='ELLIPSOID')

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 or tuple, optional) – Number of points in the field of view contour (default: 24). Usually, this does not include the last point to close the polygon (to avoid to compute it twice). 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.

• abcorr (str, optional) – Aberration correction (default: ‘NONE’),

• corloc (str, optional) – Aberration correction locus (default: ‘TANGENT POINT’). Used only if limb=True.

• 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), plus a surface intersection flag.

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

Return type:

(float, 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.

target_separation()

planetary_coverage.spice.toolbox.target_separation(time, observer, target_1, target_2, *, shape_1='POINT', shape_2='POINT', abcorr='NONE')

Angular target separation between two bodies seen from an observer.

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_1 (str or SpiceBody) – First target body name.

• target_2 (str or SpiceBody) – Second target body name.

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

• target_2 – Second target body name.

• abcorr (str, optional) – Aberration correction (default: ‘NONE’),

Returns:

Angular separation between the two targets (in degrees).

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

Return type:

float or numpy.ndarray

Note

At the moment (N0067), DSK shape are not supported and frame_1 and frame_2 are always set to 'NULL'.

See also

spiceypy.spiceypy.trgsep

local_time()

planetary_coverage.spice.toolbox.local_time(time, lon, target, lon_type='PLANETOCENTRIC')

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

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

solar_longitude()

planetary_coverage.spice.toolbox.solar_longitude(time, target, abcorr='NONE')

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

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

See also

spiceypy.spiceypy.spkezr, spiceypy.spiceypy.oscltx

groundtrack_velocity()

planetary_coverage.spice.toolbox.groundtrack_velocity(target, state)

Groundtrack velocity (km/s).

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

Changed in version 1.1.0: Fix the formula. The previous one was incorrect. See issue #35 for details.

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)

See also

spiceypy.spiceypy.recgeo, spiceypy.spiceypy.dgeodr, spiceypy.spiceypy.mxv

pixel_scale()

planetary_coverage.spice.toolbox.pixel_scale(inst, target, emi, dist)

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

See also

planetary_coverage.math.sphere.sph_pixel_scale

SPICE CLI

kernel-download

planetary_coverage.cli.cli_kernel_download(argv=None)

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)

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

Spice Pool kernels checker decorator.

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