SPICE API

spiceypy.spiceypy.reclat

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

`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

spiceypy.spiceypy.recpgr

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

`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

`azel()`#

planetary_coverage.spice.toolbox.azel(vec, az_spice=False, el_spice=True)[source]#

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

rlonlat, station_azel

See also

`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

spiceypy.spiceypy.subpnt

See also

`target_position()`#

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

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

`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

See also

target_position

`angular_size()`#

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

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

See also

target_position

`station_azel()`#

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

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

target_position, azel

See also

`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.attitude(time, observer, ref='J2000')[source]#

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)[source]#

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

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

Return type

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', corloc='TANGENT POINT', 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’)
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).

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

Return type

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')[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’),
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).

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

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')[source]#

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

spiceypy.spiceypy.trgsep

Note

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

See also

`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

spiceypy.spiceypy.et2lst

Raises

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

See also

`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

spiceypy.spiceypy.ilumin

Raises

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

See also

`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

spiceypy.spiceypy.lspcn

Note

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

See also

`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

`groundtrack_velocity()`#

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

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

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