curryer.spicierpy.ext¶

Extensions to SPICE and the wrapper SpiceyPy.

@author: Brandon Stone

Attributes¶

`logger`
`SPICE_ERROR_COVERAGE`
`SPICE_ERROR_MISSING_KERNEL`
`SPICE_ERROR_BAD_TIME`
`SPICE_ERROR_OTHER`
`POSITION_COLUMNS`
`VELOCITY_COLUMNS`

Classes¶

`load_kernel`	SPICE Kernel Context Manager.
`KernelType`	SPICE kernel-pool type categories, as used by `ktotal` / `kdata`.
`LoadedKernel`	A kernel currently furnished in the SPICE kernel pool.
`InstrumentFov`	An instrument's field-of-view definition, as declared in its instrument kernel (IK).
`SpiceErrorInfo`	A `SpiceyError` reduced to a user-facing cause.

Functions¶

`loaded_kernels`(→ list[LoadedKernel])	List the kernels currently furnished in the SPICE kernel pool.
`object_frame`(obj_name[, as_id])	Retrieve frame name/id associated with an object name or id.
`frame_class_id`(→ int)	Resolve a frame reference to the frame class ID used by binary PCKs.
`kernel_coverage`(→ numpy.ndarray)	Determine the coverage window for an entire kernel file.
`kernel_objects`(...)	Determine what objects (names or codes) are within a kernel file.
`infer_ids`(spacecraft_name, spacecraft_id[, ...])	Infer NAIF IDs based on the spacecraft ID.
`instrument_boresight`(instrument[, n_vectors, norm])	Retrieve an instrument's boresight vector from the kernel pool.
`instrument_fov`(instrument[, max_bounds])	Retrieve an instrument's field-of-view definition from the kernel pool.
`brief`(kernel_file[, bin_])	Brief summary of a kernel file.
`spice_error_to_val`([err_value, err_flag, pass_flag, ...])	Wrapper to catch spice errors and convert them to non-error values.
`classify_spice_error`(err)	Reduce a `SpiceyError` to a user-facing cause.
`spice_error_message`(err)	One-line, user-facing message for a caught `SpiceyError`.
`query_ephemeris`(ugps_times, target, observer[, ...])	Query SPICE ephemeris data from pre-loaded kernels.

Module Contents¶

curryer.spicierpy.ext.logger¶

class curryer.spicierpy.ext.load_kernel(kernels)¶

SPICE Kernel Context Manager.

property loaded¶: List of kernels that have been loaded.

load(kernel)¶: Load a kernel file.

unload(kernel=None, clear=False)¶: Unload a kernel file.

class curryer.spicierpy.ext.KernelType¶

Bases: str, enum.Enum

SPICE kernel-pool type categories, as used by ktotal / kdata.

These are the pool’s load-time categories, not file formats: SPICE collapses every text kernel (LSK, FK, IK, SCLK, text PCK, meta-kernel contents, …) into TEXT, so a text PCK is reported as TEXT, never PCK. PCK matches only binary PCKs.

Members are plain strings (KernelType.SPK == "SPK") and may be passed anywhere SPICE expects a kind string.

SPK = 'SPK'¶

CK = 'CK'¶

PCK = 'PCK'¶

DSK = 'DSK'¶

EK = 'EK'¶

TEXT = 'TEXT'¶

META = 'META'¶

ALL = 'ALL'¶

class curryer.spicierpy.ext.LoadedKernel¶

Bases: NamedTuple

A kernel currently furnished in the SPICE kernel pool.

file¶

Kernel file path, as it was furnished.

Type:: str

ktype¶

SPICE kernel type (e.g. "SPK", "CK", "PCK", "TEXT", "META").

Type:: str

source¶

Name of the source file that furnished this kernel (e.g. a meta-kernel), or an empty string if it was furnished directly.

Type:: str

handle¶

SPICE integer handle for binary kernels; 0 for text kernels.

Type:: int

file: str¶

ktype: str¶

source: str¶

handle: int¶

curryer.spicierpy.ext.loaded_kernels(kind: str | KernelType | Iterable[str | KernelType] = KernelType.ALL) → list[LoadedKernel]¶

List the kernels currently furnished in the SPICE kernel pool.

Queries the kernel pool itself (ktotal / kdata), so the result reflects every furnished kernel regardless of which component loaded it — unlike load_kernel.loaded, which tracks only the kernels loaded through that handle. Useful for verifying furnish state and for pool-wide diagnostics.

Parameters:: kind (str or KernelType or iterable of them, optional) – Kernel kind filter: one or more KernelType values (or their string equivalents), or a space-delimited combination string. Note that all text kernels report as TEXT (see KernelType). Default=``KernelType.ALL``.
Returns:: One record per furnished kernel, in load order.
Return type:: list of LoadedKernel

curryer.spicierpy.ext.object_frame(obj_name, as_id=False)¶

Retrieve frame name/id associated with an object name or id.

Parameters:

obj_name (str or int) – Object name or id to get the frame for.
as_id (bool, default=False) – If True, change return to be the frame id instead of the name.

Returns:

frame_name – Associated frame name, or id if as_id=True.

Return type:

str or int

curryer.spicierpy.ext.frame_class_id(frame: str | curryer.spicierpy.obj.Body | curryer.spicierpy.obj.Frame) → int¶

Resolve a frame reference to the frame class ID used by binary PCKs.

Binary-PCK data (e.g. high-precision Earth orientation, lunar libration) is keyed on the frame class ID (e.g. 3000 for ITRF93, 31006 for MOON_PA_DE421), not the frame ID (13000, 31000). Class-4 (fixed-offset, “TK”) frames that alias another frame — e.g. MOON_PA, which aliases MOON_PA_DE421 — are followed to the frame they alias. Non-built-in definitions require their frame kernel (FK) to be loaded.

Parameters:: frame (str or Body or Frame) – Frame name or object. Body objects (or body names) resolve via the body’s associated frame (e.g. "MOON" -> MOON_PA -> 31006).
Returns:: Frame class ID, as used by pckcov / pckfrm.
Return type:: int
Raises:: ValueError – If the reference does not resolve to a defined frame, or the frame (after following aliases) is not a class-2 (PCK) frame.

curryer.spicierpy.ext.kernel_coverage(filename: str | pathlib.Path, body: int | str | curryer.spicierpy.obj.Body | curryer.spicierpy.obj.Frame, as_segments: bool = False, to_fmt: str = 'ugps') → numpy.ndarray¶

Determine the coverage window for an entire kernel file.

Parameters:

filename (str or Path) – SPICE kernel file.
body (int or str or Body or Frame) – NAIF body code or name to check coverage of. A string is assumed to be a body name, while an int is assumed to be a body code. Note: Using a body name requires that the body definition is loaded into memory; integer codes will work regardless. For binary PCK kernels, coverage is keyed on the frame class ID (e.g., 3000 for the ITRF93 Earth-orientation kernels); pass the class ID as an integer, or a frame/body name or Frame/Body object to resolve it (see frame_class_id; requires the frame definitions to be loaded).
as_segments (bool) – Option to return the coverage of each segment.
to_fmt (str, optional) – Datetime format for the returned times. Default=’ugps’.

Returns:

Start and stop coverage times in to_fmt or GPS microseconds.

Return type:

tuple of two int or float or str

Notes

Kernel dependencies of filename should be loaded prior to the function call (i.e., the spacecraft clock kernel (SCLK) for an attitude kernel (CK)).

curryer.spicierpy.ext.kernel_objects(filename: str | pathlib.Path, as_id: bool = False) → tuple[curryer.spicierpy.obj.Body | curryer.spicierpy.obj.Frame | int, ...]¶

Determine what objects (names or codes) are within a kernel file.

Parameters:

filename (str or Path) – SPICE kernel file.
as_id (bool, optional) – If False (default) return the NAIF body names, otherwise return the body codes. Note: Using a body name requires that the body definition is loaded into memory; integer codes will work regardless.

Returns:

Collection of NAIF body names (default) or codes found within the kernel file (filename). Binary PCK kernels contain frame class IDs, which have no name lookup and require as_id=True.

Return type:

tuple of str or tuple of ints

curryer.spicierpy.ext.infer_ids(spacecraft_name, spacecraft_id, instruments=None, from_dsn=False, from_norad=False)¶

Infer NAIF IDs based on the spacecraft ID.

Useful when planning out the necessary IDs; not meant to reverse existing IDs since the following rules are not strictly enforced.

Parameters:

spacecraft_name (str) – Spacecraft or mission name.
spacecraft_id (int) – Spacecraft ID; all other IDs are based on this. NOTE: It should be a negative number, unless from_dsn or from_norad is used.
instruments (str or list of str, optional) – One or more instrument names to create IDs for.
from_dsn (bool, optional) – Option to interpret spacecraft_id as a JPL Deep Space Network (DSN) ID. It will be converted to a SPICE-like spacecraft ID using the standard convention.
from_norad (bool, optional) – Option to interpret spacecraft_id as a NORAD tracking ID. It will be converted to a SPICE-like spacecraft ID using the standard convention.

Returns:

Collection of the mission name and IDs (spacecraft, clock, ephemeris, attitude), and instrument names and IDs.

Return type:

collections.dict

curryer.spicierpy.ext.instrument_boresight(instrument, n_vectors=1, norm=False)¶

Retrieve an instrument’s boresight vector from the kernel pool.

Parameters:

instrument (str or int or sds_spice.spicierypy.obj.Instrument) – The instrument ID, name or object to retrieve the boresight of.
n_vectors (int, optional) – Number of vectors to retrieve. Default=1
norm (bool, optional) – Option to return normalized vectors. Default=False

Return type:

numpy.ndarray

class curryer.spicierpy.ext.InstrumentFov¶

Bases: NamedTuple

An instrument’s field-of-view definition, as declared in its instrument kernel (IK).

shape: str¶

frame: str¶

boresight: numpy.ndarray¶

bounds: numpy.ndarray¶

ref_vector: numpy.ndarray | None = None¶

half_angle(degrees=False) → float¶

Half angle of the cone about the boresight that contains the field of view.

Parameters:: degrees (bool, optional) – If True, returns degrees, otherwise (default) radians.
Returns:: Angle from the boresight to the outermost FOV boundary vector. Exact for a “CIRCLE” FOV; for the other shapes this is the circumscribing cone, so it never understates the field of view.
Return type:: float

curryer.spicierpy.ext.instrument_fov(instrument, max_bounds=16)¶

Retrieve an instrument’s field-of-view definition from the kernel pool.

Parameters:

instrument (str or int or spicierpy.obj.Instrument) – The instrument ID, name or object to retrieve the FOV of.
max_bounds (int, optional) – Maximum number of FOV boundary vectors to read. Default=16

Returns:

The FOV shape, the name of the frame the boresight and boundary vectors are defined in, the boresight vector, the boundary vectors [N, 3], and the FOV reference vector if the IK declares one (None otherwise).

Return type:

InstrumentFov

Notes

Unlike instrument_boresight, this keeps the FOV frame and boundary vectors that getfov returns alongside the boresight. The frame matters because an IK may define the FOV in a frame other than the instrument’s own, and expressing a target direction in the FOV frame is what makes it directly comparable to the boresight.

getfov does not return INS<id>_FOV_REF_VECTOR, so it is read from the pool separately. It is a standard NAIF instrument-kernel keyword, required by the “ANGLES” FOV_CLASS_SPEC alongside FOV_REF_ANGLE and FOV_ANGLE_UNITS – an ANGLES FOV missing it makes getfov signal SPICE(REFVECTORMISSING). The “CORNERS” spec defines no such vector, so those FOVs give None. It is the IK’s own answer to which direction cross-boresight angles are measured from, which curryer.compute.spatial.boresight_offset_angles otherwise has to assume.

curryer.spicierpy.ext.brief(kernel_file, bin_=None)¶: Brief summary of a kernel file.

curryer.spicierpy.ext.spice_error_to_val(err_value=None, err_flag=None, pass_flag=None, disable=False)¶

Wrapper to catch spice errors and convert them to non-error values.

Parameters:

err_value (any) – Value to return when a SPICE error is encountered (e.g. nans).
err_flag (any) – Value to return with the err_value to indicate that an error had occurred. Can be a callable, excepting the error object.
pass_flag (any) – Value to return with the function’s return to indicate that no error had occurred. Can be a callable, excepting the output value.
disable (bool) – Option to disable to the error handling.

Returns:

any – Return from the wrapped function if no error was encountered, otherwise the err_value.
any – Flag indicating if an error occurred (err_flag) or not (pass_flag).

curryer.spicierpy.ext.SPICE_ERROR_COVERAGE = 'coverage'¶

curryer.spicierpy.ext.SPICE_ERROR_MISSING_KERNEL = 'missing_kernel'¶

curryer.spicierpy.ext.SPICE_ERROR_BAD_TIME = 'bad_time'¶

curryer.spicierpy.ext.SPICE_ERROR_OTHER = 'other'¶

class curryer.spicierpy.ext.SpiceErrorInfo¶

Bases: NamedTuple

A SpiceyError reduced to a user-facing cause.

category¶

One of SPICE_ERROR_COVERAGE, SPICE_ERROR_MISSING_KERNEL, SPICE_ERROR_BAD_TIME, or SPICE_ERROR_OTHER.

Type:: str

short¶

The NAIF short message (e.g. "SPICE(NOFRAMECONNECT)"), or "SPICE(UNKNOWN)" if the exception carried none.

Type:: str

summary¶

One-line, non-technical description of the likely cause.

Type:: str

detail¶

The NAIF long message, if any – the specifics behind summary.

Type:: str

routine¶

The SPICE call chain that failed (e.g. "pxform_c --> PXFORM").

Type:: str

category: str¶

short: str¶

summary: str¶

detail: str¶

routine: str¶

curryer.spicierpy.ext.classify_spice_error(err)¶

Reduce a SpiceyError to a user-facing cause.

SPICE surfaces failures as verbose, multi-line tracebacks whose actionable content is the NAIF short name (err.short). This maps that short name to a coarse operational category and a one-line summary, so callers can log or raise something a user can act on instead of the raw dump. Pairs with spice_error_to_val() – pass this (or spice_error_message()) as its err_flag.

Parameters:: err (spiceypy.utils.exceptions.SpiceyError) – The caught SPICE exception.
Returns:: The category, short name, summary, long detail, and failing routine.
Return type:: SpiceErrorInfo

curryer.spicierpy.ext.spice_error_message(err)¶

One-line, user-facing message for a caught SpiceyError.

Combines the plain-language cause from classify_spice_error() with the NAIF short name and failing routine for traceability, e.g. "The requested time or frame is outside the coverage of the loaded SPICE kernels. [SPICE(NOFRAMECONNECT) in pxform_c --> PXFORM]".

Parameters:: err (spiceypy.utils.exceptions.SpiceyError) – The caught SPICE exception.
Returns:: A message suitable for logging or re-raising to a user.
Return type:: str

curryer.spicierpy.ext.POSITION_COLUMNS = ('x', 'y', 'z')¶

curryer.spicierpy.ext.VELOCITY_COLUMNS = ('vx', 'vy', 'vz')¶

curryer.spicierpy.ext.query_ephemeris(ugps_times, target, observer, ref_frame='J2000', correction=None, velocity=False, allow_nans=False)¶

Query SPICE ephemeris data from pre-loaded kernels.

Parameters:

ugps_times (list of int) – One or more UGPS times to query data for.
target (str or int or Body) – Name or ID of the target object.
observer (str or int or Body) – Name or ID of the observing object.
ref_frame (str or Frame, optional) – Reference frame of the ephemeris data. Default=”J2000”
correction (str, optional) – SPICE correction to apply to the data (e.g., “LT”). Default=None
velocity (bool, optional) – Query position and velocity. Default is position only. Note that velocity requires angular velocity in all connected CK kernels.
allow_nans (bool, optional) – Allow setting NaNs for times when insufficient SPICE kernel data would otherwise raise an exception. Note: Setting this flag significantly impacts read performance. Default=False.

Return type:

pd.DataFrame