Camera#
- class Camera(name: str, associated_body_spice_id: int | str, camera_frame: str | Frame, fov_angular: ArrayWUnits, fov_pixels: tuple, focal_length: ArrayWUnits, ifov_angle: ArrayWUnits, pp_offset: ArrayWUnits = None, measurement_type: str = 'opnav')#
Bases:
InstrumentRepresents 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:
- namestr
Camera name.
- associated_body_spice_idint | str
SPICE ID of the associated body.
- camera_framestr or Frame
Reference frame of the camera. Either a SPICE frame name or a
Frame; it is normalised to the name and the object is available fromcamera_frame_object.- measurement_typestr
Type of measurement (e.g., image, lidar, etc.).
- fov_angularArrayWUnits
Angular field of view of the camera.
- fov_pixelstuple[int, int]
Number of pixels along horizontal and vertical axes.
- focal_lengthArrayWUnits
Focal length of the camera.
- pp_offsetArrayWUnits, optional
Principal point offset in the image plane. If
pp_offset = None, defaults to[0, 0] [unitless ... unitless].- pos_craft_cntrdArrayWFrame, optional
Defaults to
None.
- Attributes:
areaThe cross-sectional area of the spacecraft.
associated_body_spice_idSPICE ID of craft or body camera is attached to.
attitude_matrixFallback (3, 3) rotation matrix (J2000 to camera frame) used when SPICE does not have the camera frame defined.
body_fixed_frame_idThe SPICE ID assigned to the spacecraft’s body-fixed frame.
calibration_matrixCamera calibration matrix.
camera_frameName of the SPICE-defined camera frame.
camera_frame_objectThe camera frame as a
Frameobject.focal_lengthThe focal length of the camera.
focal_length_pixelsThe focal length of the camera.
fov_angularAngular field-of-view of the camera (horizontal, vertical) in radians.
fov_pixelsSensor resolution (horizontal, vertical).
ifovInstantaneous field-of-view of the sensor.
instrument_listThe list of instruments attached to the spacecraft.
mass_profileStored constant or polynomial mass profile.
max_sample_lineMaximum sampling line.
measurement_typeString tag describing the type of measurement this instrument produces (e.g.
n_plate_modelThe N-Plate model representing the spacecraft’s geometry.
nameThe name of the spacecraft.
pp_offsetOffset of the principal point.
ref_coeffThe reflectivity coefficient of the spacecraft.
spice_idThe SPICE ID of the Body object.
thrusterThruster actuator attached to this spacecraft, or
Noneif not set.
Methods
add_instrument(instruments)Adds an instrument or instruments to the spacecraft.
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 rotation from a given inertial frame to the spacecraft-fixed frame, from the C-kernel of frame ID
spice_id * 1000.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.
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.
Restore the mass the body was built with and forget fitted profiles.
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.
See also
scarabaeus.InstrumentParent class providing SPICE ID and measurement-type handling.
scarabaeus.CentroidingIdealOptical measurement model that uses Camera internally.
- add_instrument(instruments) None#
Adds an instrument or instruments to the spacecraft.
- Parameters:
- instrumentslist of Instrument
The instruments to be attached to the spacecraft.
- Returns:
- None
- field_of_view()#
Return the field of view of the instrument.
- Returns:
- None
Not yet implemented in the base class; subclasses override this method to return instrument-specific FOV data.
- 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_arraynumpy.ndarray
Time values in seconds (ephemeris time).
- m_arraynumpy.ndarray
Corresponding mass values.
- degint
Degree of the polynomial.
- domaintuple
Domain [t0, tf] for the polynomial conversion.
- unitsArrayWUnits
Units to assign to the mass profile. If None, uses existing mass profile units.
- Returns:
- None
- get_attitude(from_frame: Frame, epoch: EpochArray, tol: int = 0) ndarray#
Computes the rotation from a given inertial frame to the spacecraft-fixed frame, from the C-kernel of frame ID
spice_id * 1000.- Parameters:
- from_frameFrame
The intertial reference frame for which the spacecraft-fixed frame will be transformed from.
- epochEpochArray
The epoch at which the transformation will be performed. Given in ephemeris time (seconds past J2000).
- tolint, optional
The time tolerance for retrieving attitude and angular velocity from the specified spacecraft clock time, given in sclock ticks. Defaults to
0.
- Returns:
- quatnumpy.ndarray
The
(4,)SPICE quaternion (spice.m2q) of the rotation fromfrom_frameto spacecraft-fixed coordinates.
Notes
The
epochargument 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:
- idsdict
A dictionary containing the keys:
'instruments': list The SPICE ID’s of all attachedInstrumentobjects.'plates': list The SPICE ID’s of all C-frames for CK type panels defined in thenPlateModelif one has been assigned to the Spacecraft.
- get_mass(t: EpochArray) ArrayWUnits#
Evaluates the time-varying mass profile at specified epochs.
- Parameters:
- tEpochArray
Time(s) in ephemeris seconds (TDB).
- Returns:
- massArrayWUnits
Evaluated mass at each input epoch.
- 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_0EpochArray
The epoch times for which the state is to be computed.
- reference_framestr
The reference frame in which the state is desired. Defaults to ‘J2000’.
- originstr
The origin body relative to which the state is computed. Defaults to
'EARTH'.
- Returns:
- state_vectorArrayWFrame
The state vector of the body relative to the origin.
- inertial_to_body_DCM_nadirPointingSun(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.
Deprecated since version 2026.0.0: Use
nadirPointingSun(), which returns the spacecraft-fixed to inertial DCM (the transpose of this one) and, on request, its position and velocity derivatives. This method now delegates to it.- Parameters:
- origin_namestr
Name of the origin at which current_state is defined (e.g., ‘EARTH’, ‘SUN’).
- frameFrame or str
Frame in which current_state is expressed (e.g., J2000).
- sun2body_posArrayWUnits
Position of the body w.r.t. SUN (km).
- current_statedict
State of the body w.r.t. the origin, keyed either by
('velocity', spice_id)or by'velocity', with an array orArrayWUnitsvalue (and similarly for'position'if ever needed).- epochfloat
Epoch (TDB seconds past J2000) at which the state is computed.
- bodyCelestialBody or Spacecraft
The body whose state we are extracting from current_state (used for spice_id lookup).
- Returns:
- DCM_inertial_to_body(3,3) ndarray
DCM that rotates inertial vectors into the body-fixed frame realizing the nadir-to-sun pointing.
- Raises:
- DynamicalUtils.MissingVelocityError
If current_state holds no velocity for body (a
KeyError).
- 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:
- tEpochArray, float, or np.ndarray, optional
Time(s) in ephemeris seconds (TDB) at which to evaluate the mass. Or None for constant mass.
- Returns:
- ArrayWUnits
Mass at time t or constant mass.
- reset_mass_history() None#
Restore the mass the body was built with and forget fitted profiles.
Every propagated leg appends the profile it fitted, and the next leg starts from the last one. Propagating the same mission again (a filter re-linearizing its reference, say) would otherwise start the first leg from the mass the previous run ended with, and
get_mass()would return profiles from earlier runs that cover the same epochs.The profile lists are cleared in place: force-model copies of this body share them by reference.
- Returns:
- None
- set_mass_profile(poly: SCBPolynomial, units: Units) None#
Sets the mass profile of the body using a polynomial function and associated units.
- Parameters:
- polySCBPolynomial
A polynomial object representing the mass profile.
- unitsUnits
The units associated with the mass profile.
- Returns:
- 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:
- targetBody or Spacecraft
The target body. Its SPICE name is used to query its state.
- epochEpochArray
The epoch or sequence of epochs at which to evaluate visibility.
- Returns:
- in_fovbool or np.ndarray of bool
Trueif the target projects into the camera sensor bounds. Returns a scalar for a single epoch or an array for multiple epochs.
- property area: ArrayWUnits#
The cross-sectional area of the spacecraft. Expressed in units of square meters.
- property attitude_matrix: ndarray#
Fallback (3, 3) rotation matrix (J2000 to camera frame) used when SPICE does not have the camera frame defined. Identity by default.
- property camera_frame: str#
Name of the SPICE-defined camera frame.
Always the frame name, whether the camera was built from a string or from a
Frame. This is what the SPICE calls (pxform,spkezr) expect; usecamera_frame_objectwhere aFrameis needed.
- property camera_frame_object: Frame#
The camera frame as a
Frameobject.Built lazily from
camera_frameand cached, so cameras whose frame is not known to SPICE only fail if this is actually used.
- property fov_angular: ArrayWUnits#
Angular field-of-view of the camera (horizontal, vertical) in radians.
- property ifov: ArrayWUnits#
Instantaneous field-of-view of the sensor.
- 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").Noneif unset.
- property n_plate_model: nPlateModel#
The N-Plate model representing the spacecraft’s geometry.
- property pp_offset: ArrayWUnits#
Offset of the principal point. Expressed in units of kilometers.
- property thruster#
Thruster actuator attached to this spacecraft, or
Noneif not set.