Skip to content

Frame Graph

ReferenceFrame, the unified frame identity spanning celestial, orbit-relative, and body frames, and BodyFrame, the object-local body/sensor/actuator frame kind it wraps.

Note

For conceptual explanations and examples, see Frame Graph in the Learn section.

ReferenceFrame

ReferenceFrame 

ReferenceFrame()

Unified frame identity spanning celestial, orbit-relative, and body frames.

Covers three kinds of frame: a CelestialFrame (see ReferenceFrame.celestial to wrap one and the celestial_frame attribute to read one back), a local orbital frame of a specific object (RTN, LVLH, ...), and an object-local body/sensor frame (SC_BODY, CSS, ...). Orbit-relative and body frames carry an optional bound object: a frame constructed through one of the family staticmethods below (ReferenceFrame.RTN("SC")) is always bound; ReferenceFrame.body with object=None and ReferenceFrame.orbit_relative with object=None construct an unbound label.

Example 
1
2
3
4
5
import brahe as bh

rtn = bh.ReferenceFrame.RTN("SC")
css = bh.ReferenceFrame.CSS("SC", "1")
print(rtn.is_bound(), rtn.object())

Initialize instance.

celestial_frame property 

celestial_frame: Optional[CelestialFrame]

The wrapped CelestialFrame when this is a celestial frame.

This is the Python spelling of matching on the Celestial arm in Rust, and is how a caller reaches CelestialFrame.axes and CelestialFrame.center from a frame handed back by a trajectory or a message.

Returns:

Type Description
Optional[CelestialFrame]

Optional[CelestialFrame]: The celestial frame, or None for orbit-relative and body frames
Example 
1
2
3
4
5
import brahe as bh

frame = bh.ReferenceFrame.celestial(bh.CelestialFrame.MCI)
print(frame.celestial_frame.axes, frame.celestial_frame.center)
print(bh.ReferenceFrame.RTN("SC").celestial_frame)

ACC staticmethod 

ACC(object: str, designator: str) -> ReferenceFrame

Bound accelerometer frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound ACC_<designator> body frame

ACTUATOR staticmethod 

ACTUATOR(object: str, designator: str) -> ReferenceFrame

Bound actuator frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Actuator instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound ACTUATOR_<designator> body frame

AST staticmethod 

AST(object: str, designator: str) -> ReferenceFrame

Bound autonomous star tracker frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound AST_<designator> body frame

CSS staticmethod 

CSS(object: str, designator: str) -> ReferenceFrame

Bound coarse sun sensor frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound CSS_<designator> body frame

DSS staticmethod 

DSS(object: str, designator: str) -> ReferenceFrame

Bound digital sun sensor frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound DSS_<designator> body frame

EQW staticmethod 

EQW(object: str) -> ReferenceFrame

Bound Equinoctial orbit-relative frame (inertial-snapshot variant; EQW is SANA-registered only as inertial).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound EQW (inertial) orbit-relative frame

ESA staticmethod 

ESA(object: str, designator: str) -> ReferenceFrame

Bound Earth sensor assembly frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound ESA_<designator> body frame

GYRO_FRAME staticmethod 

GYRO_FRAME(object: str, designator: str) -> ReferenceFrame

Bound gyroscope frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound GYRO_FRAME_<designator> body frame

IMU_FRAME staticmethod 

IMU_FRAME(object: str, designator: str) -> ReferenceFrame

Bound inertial measurement unit frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound IMU_FRAME_<designator> body frame

INSTRUMENT staticmethod 

INSTRUMENT(object: str, designator: str) -> ReferenceFrame

Bound instrument frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Instrument instance designator (e.g. "A")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound INSTRUMENT_<designator> body frame

LVLH staticmethod 

LVLH(object: str) -> ReferenceFrame

Bound Local-Vertical Local-Horizontal orbit-relative frame (rotating variant).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound LVLH (rotating) orbit-relative frame

MTA staticmethod 

MTA(object: str, designator: str) -> ReferenceFrame

Bound magnetic torque assembly frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Actuator instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound MTA_<designator> body frame

NSW staticmethod 

NSW(object: str) -> ReferenceFrame

Bound Nadir/Sun/Normal orbit-relative frame (rotating variant).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound NSW (rotating) orbit-relative frame

NTW staticmethod 

NTW(object: str) -> ReferenceFrame

Bound Normal/Tangential/cross-track orbit-relative frame (rotating variant).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound NTW (rotating) orbit-relative frame

PQW staticmethod 

PQW(object: str) -> ReferenceFrame

Bound Perifocal orbit-relative frame (inertial-snapshot variant; PQW is SANA-registered only as inertial).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound PQW (inertial) orbit-relative frame

RTN staticmethod 

RTN(object: str) -> ReferenceFrame

Bound Radial/Transverse/Normal orbit-relative frame (rotating variant). SANA: RSW.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound RTN (rotating) orbit-relative frame

RW staticmethod 

RW(object: str, designator: str) -> ReferenceFrame

Bound reaction wheel frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Actuator instance designator (e.g. "4")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound RW_<designator> body frame

SA staticmethod 

SA(object: str, designator: str) -> ReferenceFrame

Bound solar array frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Array instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound SA_<designator> body frame

SC_BODY staticmethod 

SC_BODY(object: str) -> ReferenceFrame

Bound spacecraft body frame (no instance designator).

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound SC_BODY body frame

SENSOR staticmethod 

SENSOR(object: str, designator: str) -> ReferenceFrame

Bound generic sensor frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "10")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound SENSOR_<designator> body frame

SEZ staticmethod 

SEZ(object: str) -> ReferenceFrame

Bound topocentric South/East/Zenith orbit-relative frame (rotating variant).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound SEZ (rotating) orbit-relative frame

STARTRACKER staticmethod 

STARTRACKER(object: str, designator: str) -> ReferenceFrame

Bound star tracker frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "2")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound STARTRACKER_<designator> body frame

TAM staticmethod 

TAM(object: str, designator: str) -> ReferenceFrame

Bound three-axis magnetometer frame.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required
designator str

Sensor instance designator (e.g. "1")

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound TAM_<designator> body frame

TNW staticmethod 

TNW(object: str) -> ReferenceFrame

Bound Tangential/Normal/cross-track orbit-relative frame (rotating variant).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound TNW (rotating) orbit-relative frame

VNC staticmethod 

VNC(object: str) -> ReferenceFrame

Bound Velocity/Normal/Co-normal orbit-relative frame (rotating variant).

Among the orbit-relative kinds only RTN has an axes derivation today, so this frame is constructible but every transform through it raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The bound VNC (rotating) orbit-relative frame

body staticmethod 

body(object: str, body_frame: BodyFrame) -> ReferenceFrame

Constructs a body frame, general form. Covers designator-less and non-standard BodyFrame cases beyond the family-specific staticmethods (e.g. ReferenceFrame.CSS, ReferenceFrame.RW).

Parameters:

Name Type Description Default
object str

The object the frame is defined relative to. None constructs an unbound label frame.

 required
body_frame BodyFrame

The body frame kind and optional instance designator

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The body frame, bound to object if given
Example 
1
2
3
import brahe as bh

frame = bh.ReferenceFrame.body("SC", bh.BodyFrame.SC_BODY())

celestial staticmethod 

celestial(frame: CelestialFrame) -> ReferenceFrame

Wraps a CelestialFrame as a ReferenceFrame. Mirrors Rust's From<CelestialFrame> for ReferenceFrame.

Parameters:

Name Type Description Default
frame CelestialFrame

The celestial frame to wrap

 required

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The wrapped celestial frame
Example 
1
2
3
import brahe as bh

gcrf = bh.ReferenceFrame.celestial(bh.CelestialFrame.GCRF)

is_bound method descriptor 

is_bound() -> bool

Whether the frame is evaluable: a celestial frame, or an orbit-relative/body frame with a bound object.

Returns:

Name Type Description
bool bool

True if the frame is bound (celestial frames are always bound)

object method descriptor 

object() -> Optional[str]

The bound object, if any.

Returns:

Type Description
Optional[str]

Optional[str]: The bound object, or None for a celestial frame or an unbound orbit-relative/body frame

orbit_relative staticmethod 

orbit_relative(kind: OrbitRelativeFrameKind, variant: OrbitRelativeFrameVariant, object: str = None) -> ReferenceFrame

Constructs an orbit-relative frame, validating the kind/variant combination. General form of the family staticmethods (ReferenceFrame.RTN, ...), for callers that hold a runtime kind/variant pair and an optional, not-yet-bound object.

Among the orbit-relative kinds only RTN has an axes derivation today; the others construct successfully but every transform through them raises until issue #452 adds the remaining derivations.

Parameters:

Name Type Description Default
kind OrbitRelativeFrameKind

Frame construction (axes definition)

 required
variant OrbitRelativeFrameVariant

Rotating (true local orbital frame) or inertial (quasi-inertial snapshot)

 required
object str

The bound object, or None for an unbound label

 None

Returns:

Name Type Description
ReferenceFrame ReferenceFrame

The orbit-relative frame

Raises:

Type Description
ValueError

If kind is OrbitRelativeFrameKind.PQW/OrbitRelativeFrameKind.EQW and variant is OrbitRelativeFrameVariant.ROTATING

BodyFrame

BodyFrame 

BodyFrame()

An object-local spacecraft body frame (spacecraft body, sensor, or actuator), with an optional instance designator (e.g. CSS("1")).

The families are the values of the SANA spacecraft body reference frame registry: https://sanaregistry.org/r/spacecraft_body_reference_frames/

Bind to an object with ReferenceFrame.body(object, body_frame).

Example 
1
2
3
4
import brahe as bh

bf = bh.BodyFrame.CSS("1")
frame = bh.ReferenceFrame.body("SC", bf)

Initialize instance.

ACC staticmethod 

ACC(designator: str = None) -> BodyFrame

Accelerometer frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The ACC body frame

ACTUATOR staticmethod 

ACTUATOR(designator: str = None) -> BodyFrame

Actuator frame.

Parameters:

Name Type Description Default
designator str

Actuator instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The ACTUATOR body frame

AST staticmethod 

AST(designator: str = None) -> BodyFrame

Autonomous star tracker frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The AST body frame

CSS staticmethod 

CSS(designator: str = None) -> BodyFrame

Coarse sun sensor frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The CSS body frame

DSS staticmethod 

DSS(designator: str = None) -> BodyFrame

Digital sun sensor frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The DSS body frame

ESA staticmethod 

ESA(designator: str = None) -> BodyFrame

Earth sensor assembly frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The ESA body frame

GYRO_FRAME staticmethod 

GYRO_FRAME(designator: str = None) -> BodyFrame

Gyroscope frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The GYRO_FRAME body frame

IMU_FRAME staticmethod 

IMU_FRAME(designator: str = None) -> BodyFrame

Inertial measurement unit frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The IMU_FRAME body frame

INSTRUMENT staticmethod 

INSTRUMENT(designator: str = None) -> BodyFrame

Instrument frame.

Parameters:

Name Type Description Default
designator str

Instrument instance designator (e.g. "A")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The INSTRUMENT body frame

MTA staticmethod 

MTA(designator: str = None) -> BodyFrame

Magnetic torque assembly frame.

Parameters:

Name Type Description Default
designator str

Actuator instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The MTA body frame

RW staticmethod 

RW(designator: str = None) -> BodyFrame

Reaction wheel frame.

Parameters:

Name Type Description Default
designator str

Actuator instance designator (e.g. "4")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The RW body frame

SA staticmethod 

SA(designator: str = None) -> BodyFrame

Solar array frame.

Parameters:

Name Type Description Default
designator str

Array instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The SA body frame

SC_BODY staticmethod 

SC_BODY(designator: str = None) -> BodyFrame

Spacecraft body frame.

Parameters:

Name Type Description Default
designator str

Instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The SC_BODY body frame

SENSOR staticmethod 

SENSOR(designator: str = None) -> BodyFrame

Generic sensor frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "10")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The SENSOR body frame

STARTRACKER staticmethod 

STARTRACKER(designator: str = None) -> BodyFrame

Star tracker frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "2")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The STARTRACKER body frame

TAM staticmethod 

TAM(designator: str = None) -> BodyFrame

Three-axis magnetometer frame.

Parameters:

Name Type Description Default
designator str

Sensor instance designator (e.g. "1")

 None

Returns:

Name Type Description
BodyFrame BodyFrame

The TAM body frame

See Also