`Camera`#

class Camera(name: str, associated_body_spice_id: int | str, camera_frame: str, fov_angular: ArrayWUnits, fov_pixels: tuple, focal_length: ArrayWUnits, ifov_angle: ArrayWUnits, pp_offset: ArrayWUnits = None, measurement_type: str = 'opnav')#

Bases: Instrument

Represents a camera instrument on a spacecraft.

The pinhole (perspective) camera model maps a 3-D scene point \(\mathbf{P} = (X, Y, Z)^T\) (expressed in the camera frame) to image-plane pixel coordinates \((u, v)\):

\[\begin{split}\begin{pmatrix}u \\ v\end{pmatrix} = \mathbf{K}\,\begin{pmatrix}X/Z \\ Y/Z\end{pmatrix}, \qquad \mathbf{K} = \begin{pmatrix}f/\delta_u & 0 & c_u \\ 0 & f/\delta_v & c_v\end{pmatrix}\end{split}\]

where \(f\) is the focal length, \((\delta_u, \delta_v)\) are the instantaneous field-of-view (IFOV) dimensions per pixel, and \((c_u, c_v)\) is the principal-point offset. This matrix is stored in calibration_matrix.

Parameters:

name (str) – Camera name.
associated_body_spice_id (int | str) – SPICE ID of the associated body.
camera_frame (str) – Reference frame of the camera.
measurement_type (str) – Type of measurement (e.g., image, lidar, etc.).
fov_angular (ArrayWUnits) – Angular field of view of the camera.
fov_pixels (tuple[int, int]) – Number of pixels along horizontal and vertical axes.
focal_length (ArrayWUnits) – Focal length of the camera.
pp_offset (ArrayWUnits, optional) – Principal point offset in the image plane. If pp_offset = None, defaults to [0, 0] [unitless ... unitless].
pos_craft_cntrd (ArrayWFrame, optional) – Defaults to None.

See also

scarabaeus.Instrument: Parent class providing SPICE ID and measurement-type handling.
scarabaeus.CentroidingIdeal: Optical measurement model that uses Camera internally.

Attributes:

area: The cross-sectional area of the spacecraft.
associated_body_spice_id: SPICE ID of craft or body camera is attached to.
attitude_matrix: Fallback 3×3 rotation matrix (J2000 → camera frame) used when SPICE does not have the camera frame defined.
body_fixed_frame_id: The SPICE ID assigned to the spacecraft’s body-fixed frame.
calibration_matrix: Camera calibration matrix.
camera_frame: SPICE-defined frame.
focal_length: The focal length of the camera.
focal_length_pixels: The focal length of the camera.
fov_angular: Angular field-of-view of the camera (horizontal, vertical) in radians.
fov_pixels: Sensor resolution (horizontal, vertical).
ifov: Instantaneous field-of-view of the sensor.
instrument_list: The list of instruments attached to the spacecraft.
mass_profile: Stored constant or polynomial mass profile.
max_sample_line: Maximum sampling line.
measurement_type: String tag describing the type of measurement this instrument produces (e.g.
n_plate_model: The N-Plate model representing the spacecraft’s geometry.
name: The name of the spacecraft.
pp_offset: Offset of the principal point.
ref_coeff: The reflectivity coefficient of the spacecraft.
spice_id: The SPICE ID of the Body object.
thruster: Thruster actuator attached to this spacecraft, or None if not set.

Methods

`add_instrument`(instruments)	Adds an instrument or instruments to the spacecraft.
`field_of_view`()	Return the field of view of the instrument.
`fit_mass_profile_from_data`(t_array, m_array, ...)	Fits a polynomial to a mass time history and sets it as the new mass profile.
`get_attitude`(from_frame, epoch[, tol])	Computes the Direction Cosine Matrix (DCM) to transform vectors from a given inertial frame to the spacecraft-fixed frame.
`get_dependent_spice_ids`()	Collects the SPICE ID's of all attached frames and instruments into a dictionary.
`get_mass`(t)	Evaluates the time-varying mass profile at specified epochs.
`get_rotation_to_camera`(epoch_time)	Return the 3×3 rotation matrix that maps vectors from J2000 to camera frame.
`get_state`(epoch_0[, reference_frame, origin])	Retrieves the state of the body relative to a given origin in a specified reference frame.
`inertial_to_body_DCM_nadir_pointing_to_sun`(...)	Computes the Direction Cosine Matrix (DCM) that points the body frame's -X axis toward the Sun (nadir-to-sun), using inertial quantities.
`mass`([t])	Returns the mass of the body.
`set_mass_profile`(poly, units)	Sets the mass profile of the body using a polynomial function and associated units.
`target_in_fov`(target, epoch)	Determines whether a target body is within the camera FOV for a single epoch or a sequence of epochs.

add_instrument(instruments) → None#

Adds an instrument or instruments to the spacecraft.

Parameters:: instruments (Instrument or list of Instrument) – The instrument or instruments to be attached to the spacecraft.
Return type:: None

field_of_view()#

Return the field of view of the instrument.

Returns:: Not yet implemented in the base class; subclasses override this method to return instrument-specific FOV data.
Return type:: None

fit_mass_profile_from_data(t_array: ndarray, m_array: ndarray, domain: tuple, units: Units) → None#

Fits a polynomial to a mass time history and sets it as the new mass profile.

Parameters:

t_array (numpy.ndarray) – Time values in seconds (ephemeris time).
m_array (numpy.ndarray) – Corresponding mass values.
deg (int) – Degree of the polynomial.
domain (tuple) – Domain [t0, tf] for the polynomial conversion.
units (ArrayWUnits) – Units to assign to the mass profile. If None, uses existing mass profile units.

Return type:

None

get_attitude(from_frame: Frame, epoch: EpochArray, tol: int = 0) → ndarray#

Computes the Direction Cosine Matrix (DCM) to transform vectors from a given inertial frame to the spacecraft-fixed frame.

Parameters:

from_frame (Frame) – The intertial reference frame for which the spacecraft-fixed frame will be transformed from.
epoch (EpochArray) – The epoch at which the transformation will be performed. Given in ephemeris time (seconds past J2000).
tol (int, optional) – The time tolerance for retrieving attitude and angular velocity from the specified spacecraft clock time, given in sclock ticks. Defaults to 0.

Returns:

DCM – The DCM for transforming inertial vectors to spacecraft-fixed coordinates.

Return type:

numpy.ndarray

Notes

The epoch argument is converted from ephemeris time in seconds to continuous encoded spacecraft clock ticks.

get_dependent_spice_ids()#

Collects the SPICE ID’s of all attached frames and instruments into a dictionary.

Parameters:

None

Returns:

ids – A dictionary containing the keys:

'instruments' : list The SPICE ID’s of all attached Instrument objects.
'plates' : list The SPICE ID’s of all C-frames for CK type panels defined in the nPlateModel if one has been assigned to the Spacecraft.

Return type:

dict

get_mass(t: EpochArray) → ArrayWUnits#

Evaluates the time-varying mass profile at specified epochs.

Parameters:: t (EpochArray) – Time(s) in ephemeris seconds (TDB).
Returns:: mass – Evaluated mass at each input epoch.
Return type:: ArrayWUnits

get_rotation_to_camera(epoch_time: float) → ndarray#

Return the 3×3 rotation matrix that maps vectors from J2000 to camera frame.

Tries SPICE first (requires a SPICE camera-frame kernel). Falls back to a manually set attitude matrix (camera.attitude_matrix = R), or identity if neither is available.

get_state(epoch_0, reference_frame: str = 'J2000', origin: str = 'EARTH') → ArrayWFrame#

Retrieves the state of the body relative to a given origin in a specified reference frame.

Parameters:

epoch_0 (EpochArray) – The epoch times for which the state is to be computed.
reference_frame (str) – The reference frame in which the state is desired. Defaults to ‘J2000’.
origin (str) – The origin body relative to which the state is computed. Defaults to 'EARTH'.

Returns:

state_vector – The state vector of the body relative to the origin.

Return type:

ArrayWFrame

inertial_to_body_DCM_nadir_pointing_to_sun(origin_name, frame, sun2body_pos, current_state: dict, epoch, body)#

Computes the Direction Cosine Matrix (DCM) that points the body frame’s -X axis toward the Sun (nadir-to-sun), using inertial quantities.

Parameters:

origin_name (str) – Name of the origin at which current_state is defined (e.g., ‘EARTH’, ‘SUN’).
frame (Frame or str) – Frame in which current_state is expressed (e.g., J2000).
sun2body_pos (ArrayWUnits) – Position of the body w.r.t. SUN (km).
current_state (dict) –
State of the body w.r.t. the origin. Accepts either: - {(‘velocity’, spice_id): Array/ArrayWUnits or ‘velocity’: Array/ArrayWUnits}

(and similarly for ‘position’ if ever needed)
epoch (float) – Epoch (TDB seconds past J2000) at which the state is computed.
body (CelestialBody or Spacecraft) – The body whose state we are extracting from current_state (used for spice_id lookup).

Returns:

DCM_inertial_to_body – DCM that rotates inertial vectors into the body-fixed frame realizing the nadir-to-sun pointing.

Return type:

(3,3) ndarray

mass(t: EpochArray | float | ndarray = None) → ArrayWUnits#

Returns the mass of the body. If the mass is time-varying, evaluates it at time t. If the mass is constant, returns the same value regardless of t.

Parameters:: t (EpochArray, float, or np.ndarray, optional) – Time(s) in ephemeris seconds (TDB) at which to evaluate the mass. Or None for constant mass.
Returns:: Mass at time t or constant mass.
Return type:: ArrayWUnits

set_mass_profile(poly: SCBPolynomial, units: Units) → None#

Sets the mass profile of the body using a polynomial function and associated units.

Parameters:

poly (SCBPolynomial) – A polynomial object representing the mass profile.
units (Units) – The units associated with the mass profile.

Return type:

None

target_in_fov(target, epoch: EpochArray) → bool | np.ndarray#

Determines whether a target body is within the camera FOV for a single epoch or a sequence of epochs.

Uses pinhole projection in the camera frame: the target is considered visible when its z-component (along the boresight) is positive and the projected pixel coordinates fall within the sensor bounds defined by max_sample_line.

Parameters:

target (Body or Spacecraft) – The target body. Its SPICE name is used to query its state.
epoch (EpochArray) – The epoch or sequence of epochs at which to evaluate visibility.

Returns:

in_fov – True if the target projects into the camera sensor bounds. Returns a scalar for a single epoch or an array for multiple epochs.

Return type:

bool or np.ndarray of bool

property area: ArrayWUnits#: The cross-sectional area of the spacecraft. Expressed in units of square meters.

property associated_body_spice_id: int | str#: SPICE ID of craft or body camera is attached to.

property attitude_matrix: ndarray#: Fallback 3×3 rotation matrix (J2000 → camera frame) used when SPICE does not have the camera frame defined. Identity by default.

property body_fixed_frame_id: int#: The SPICE ID assigned to the spacecraft’s body-fixed frame.

property calibration_matrix: ndarray#: Camera calibration matrix.

property camera_frame: int | str#: SPICE-defined frame.

property focal_length: float#: The focal length of the camera. Expressed in units of kilometers.

property focal_length_pixels: tuple[int, int]#: The focal length of the camera. Expressed in pixels

property fov_angular: ArrayWUnits#: Angular field-of-view of the camera (horizontal, vertical) in radians.

property fov_pixels: tuple[float, float]#: Sensor resolution (horizontal, vertical).

property ifov: ArrayWUnits#: Instantaneous field-of-view of the sensor.

property instrument_list: list#: The list of instruments attached to the spacecraft.

property mass_profile: ArrayWUnits | SCBPolynomial#: Stored constant or polynomial mass profile.

property max_sample_line: ArrayWUnits#: Maximum sampling line. Unitless.

property measurement_type#: String tag describing the type of measurement this instrument produces (e.g. "opnav"). None if unset.

property n_plate_model: nPlateModel#: The N-Plate model representing the spacecraft’s geometry.

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

property pp_offset: ArrayWUnits#: Offset of the principal point. Expressed in units of kilometers.

property ref_coeff: float#: The reflectivity coefficient of the spacecraft.

property spice_id: int | str#: The SPICE ID of the Body object.

property thruster#: Thruster actuator attached to this spacecraft, or None if not set.

Camera#

`Camera`#