`Frame`#

class Frame(name: str)#

Bases: object

SPICE defined reference frame.

Parameters:: name (str) – SPICE recognised frame name (e.g. 'J2000', 'ITRF93', 'ECLIPJ2000').

See also

scarabaeus.ArrayWFrame

Notes

If SPICE has no record of the given name, the frame-id and class attributes are set to None rather than raising an error.

References

[1]

NAIF Frames Kernel Tutorial, https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Tutorials/pdf/individual_docs/21_fk.pdf

Examples

Create the J2000 frame and examine its properties:

>>> import scarabaeus as scb
>>> J2000 = scb.Frame('J2000')
>>> J2000.disp_properties()
========================================
Frame Properties
========================================
Frame Name:     J2000
Frame ID:       1
Origin Name:    SOLAR SYSTEM BARYCENTER
Origin ID:      0
Frame Class:    1
Class ID:       1
========================================

Attributes:

class_id: The class ID the SPICE frame (SPICE compatible).
frame_class: The class of the SPICE frame (SPICE compatible).
frame_id: The frame ID (SPICE compatible).
name: The name of the frame.
origin: The origin of the frame (SPICE compatible).
origin_name: The name of the origin of the frame (SPICE compatible).

Methods

`disp_properties`()	Displays the frame object properties.
`generate_common_frames`()	Gets a set of common frames.
`get_DCM`(source_frame, target_frame, epoch)	Gets the Direction Cosine Matrix (DCM) given the source and target frames at a given epoch.
`get_relative_pos`(source_frame, target_frame, ...)	Get the translation vector between origin of reference frames given the source and target frames at a given epoch.
`get_relative_vel`(source_frame, target_frame, ...)	Get the translation vector between origin of reference frames given the source and target frames at a given epoch.
`get_transformation`(source_frame, ...)	Get 4x4 transformation matrix that combine rotation and translation between source and target frames at a given epoch.
`write_ck_frame`(file_name, frame_name, ...)	Generate a CK SPICE frame [[1]].
`write_pck_frame`(file_name, frame_name, ...)	Generate a PCK SPICE frame [[1]].
`write_tk_frame`(file_name, frame_name, ...[, ...])	Generate a TK SPICE frame [[1]].

static generate_common_frames() → Tuple[Self]#

Gets a set of common frames. Generates four widely used frames:

J2000
ITRF93
ECLIPJ2000
IAUEARTH

Returns:: commmon_frames – A tuple of common frames.
Return type:: tuple[Frame]

Examples

>>> import scarabaeus as scb
>>> J2000, ITRF93, ECLIPJ2000, IAUEARTH = scb.Frame.generate_common_frames()

static get_DCM(source_frame: Self, target_frame: Self, epoch: EpochArray) → ndarray#

Gets the Direction Cosine Matrix (DCM) given the source and target frames at a given epoch.

Parameters:

source_frame (Frame) – The source frame which the DCM performs a transformation from.
target_frame (Frame) – The target frame which the DCM performs a transformation to.
epoch (EpochArray) – The ephemeris time at which the transformation holds.

Returns:

DCM – The requested DCM.

Return type:

numpy.ndarray

static get_relative_pos(source_frame: Self, target_frame: Self, epoch: EpochArray) → ArrayWUnits#

Get the translation vector between origin of reference frames given the source and target frames at a given epoch.

Parameters:

source_frame (Frame) – The source frame which the translation vector needs to be computed from.
target_frame (Frame) – The target frame which the translation vector needs to be computed to.
epoch (EpochArray) – The ephemeris time at which the transformation holds.

Returns:

vec – The requested translation vector between origins.

Return type:

ArrayWUnits

static get_relative_vel(source_frame: Self, target_frame: Self, epoch: EpochArray) → ArrayWUnits#

Get the translation vector between origin of reference frames given the source and target frames at a given epoch.

Parameters:

source_frame (Frame) – The source frame which the translation vector needs to be computed from.
target_frame (Frame) – The target frame which the translation vector needs to be computed to.
epoch (EpochArray) – The ephemeris time at which the transformation holds.

Returns:

vec – The requested translation vector between origins.

Return type:

ArrayWUnits

static get_transformation(source_frame: Self, target_frame: Self, epoch: EpochArray) → ArrayWUnits#

Get 4x4 transformation matrix that combine rotation and translation between source and target frames at a given epoch. :param source_frame: The source frame which the transformation matrix needs to be computed from. :type source_frame: Frame :param target_frame: The target frame which the transformation matrix needs to be computed to. :type target_frame: Frame :param epoch: The ephemeris time at which the transformation holds. :type epoch: EpochArray

Returns:: T – The requested (4x4) transformation matrix T.
Return type:: ArrayWUnits

static write_ck_frame(file_name: str, frame_name: str, frame_id: int, center_id: int, sclk_id: int, spk_id: int) → None#

Generate a CK SPICE frame [[1]].

Time-dependent frames that represent the orientation of a spacecraft or a part of it (e.g., an instrument, a solar panel) as a function of time.

Parameters:

file_name (str) – The output file name (e.g., ‘MGS_EXAMPLE_FRAME.tf’).
frame_name (str) – The name of the frame (e.g., ‘MGS_SPACECRAFT’).
frame_id (int) – The unique frame ID (e.g., -94000).
center_id (int) – The body ID at the center of the frame (e.g., -94).
sclk_id (int) – The spacecraft clock ID associated with the frame (e.g., -94).
spk_id (int) – The SPK ID associated with the frame (e.g., -94).

Return type:

None

References

[1] (1,2)

Spice Reference Frames Required Reading, https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/frames.html

Examples

Create a CK for the mars global surveyor:

>>> import scarabaeus as scb
>>> from pathlib import Path
>>> mk_path = Path('path/to/example_mk.tm')
>>> scb.SpiceManager.load_kernel_from_mkfile(str(mk_path))  # furnish metakernel
>>> scb.Frame.write_ck_frame(
...     file_name  = 'MGS_EXAMPLE_FRAME.tf',
...     frame_name = 'MGS_SPACECRAFT',
...     frame_id   = -94000,
...     center_id  = -94,
...     sclk_id    = -94,
...     spk_id     = -94,
... )

static write_pck_frame(file_name: str, frame_name: str, frame_class: int, frame_id: int) → None#

Generate a PCK SPICE frame [[1]].

These frames are used to describe the orientation of natural celestial bodies (e.g., planets, moons, asteroids) in space.

Parameters:

file_name (str) – The name of the output file (e.g., ‘EROS_EXAMPLE_FRAME.pck’).
frame_name (str) – The name of the frame (e.g., ‘EROS_FIXED’).
frame_class (int) – The frame class (e.g., 2).
frame_id (int) – The frame ID (e.g., 2000433).

Return type:

None

References

[1] (1,2)

Spice Reference Frames Required Reading, https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/frames.html

Examples

Create a PCK frame for Eros:

>>> import scarabaeus as scb
>>> from pathlib import Path
>>> mk_path = Path('path/to/example_mk.tm')
>>> scb.SpiceManager.load_kernel_from_mkfile(str(mk_path))  # furnish metakernel
>>> scb.Frame.write_pck_frame(
...     file_name   = 'EROS_EXAMPLE_FRAME.pck',
...     frame_name  = 'EROS_FIXED',
...     frame_class = 2,
...     frame_id    = 2000433,
... )

static write_tk_frame(file_name: str, frame_name: str, frame_id: int, center_id: int, relative_frame: int, matrix: list = None) → None#

Generate a TK SPICE frame [[1]].

TK frames are user-defined or mission-specific frames that are statically defined. They are often used to define spacecraft-specific or instrument-specific frames.

Parameters:

file_name (str) – The output file name (e.g., ‘MARS_EXAMPLE_FRAME.tf’).
frame_name (str) – The name of the frame (e.g., ‘MARS_FIXED’).
frame_id (int) – The unique frame ID (e.g., 1400499).
center_id (int) – The body ID at the center of the frame (e.g., 499).
relative_frame (int) – The relative reference frame (e.g., ‘IAU_MARS’).
matrix (list, optional) – 3x3 transformation matrix. Defaults to the identity matrix. Defaults to None.

Return type:

None

References

[1] (1,2)

Spice Reference Frames Required Reading, https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/req/frames.html

Examples

Create a CK for the mars global surveyor:

>>> import scarabaeus as scb
>>> from pathlib import Path
>>> mk_path = Path('path/to/example_mk.tm')
>>> scb.SpiceManager.load_kernel_from_mkfile(str(mk_path))  # furnish metakernel
>>> scb.Frame.write_tk_frame(
...     file_name      = 'MARS_EXAMPLE_FRAME.tf',
...     frame_name     = 'MARS_FIXED',
...     frame_id       = 1400499,
...     center_id      = 499,
...     relative_frame = 'IAU_MARS,
...     matrix         = [[1, 0, 0], [0, 1, 0], [0, 0, 1]],
... )

disp_properties() → None#: Displays the frame object properties.

property class_id: int#: The class ID the SPICE frame (SPICE compatible).

property frame_class: int#: The class of the SPICE frame (SPICE compatible).

property frame_id: int#: The frame ID (SPICE compatible).

property name: str#: The name of the frame.

property origin: int#: The origin of the frame (SPICE compatible).

property origin_name: str#: The name of the origin of the frame (SPICE compatible).

Frame#

`Frame`#