nav.obs

class Obs(*, config: Config | None = None, **kwargs: Any)

Bases: ABC, NavBase

Represents an observation in the navigation system.

This abstract base class provides common functionality for all observation types, including configuration and logging capabilities.

class ObsSnapshot(snapshot: Snapshot, *, extfov_margin_vu: int | tuple[int, int] | None = None, config: Config | None = None, **kwargs: Any)

Bases: Obs, Snapshot

Provides cached Backplane and Meshgrid operations for snapshot observations.

This class extends both Obs and Snapshot to provide navigation-specific functionality for snapshot observations, including FOV management and backplane caching.

body_distance(body: str) → float

Computes the distance from the spacecraft to the specified celestial body.

Parameters:

body – Name of the celestial body.

Returns:

Distance in kilometers from the spacecraft to the specified body.

property bp: Backplane

Returns a Backplane for the entire original FOV, creating it if needed.

property center_bp: Backplane

Create a Backplane with only a single point in the center.

clip_extfov(u: int, v: int) → tuple[int, int]

Clips coordinates to ensure they are within the extended FOV boundaries.

Parameters:

• u – U coordinate to clip

• v – V coordinate to clip

Returns:

A tuple of (u, v) coordinates clipped to the extended FOV boundaries.

clip_fov(u: int, v: int) → tuple[int, int]

Clips coordinates to ensure they are within the original FOV boundaries.

Parameters:

• u – U coordinate to clip

• v – V coordinate to clip

Returns:

A tuple of (u, v) coordinates clipped to the FOV boundaries.

clip_rect_extfov(u_min: int, u_max: int, v_min: int, v_max: int) → tuple[int, int, int, int]

Clip a rectangle to the extended FOV bounds.

Returns:

(u0, u1, v0, v1) clipped to [extfov_u_min..extfov_u_max], [extfov_v_min..extfov_v_max]

clip_rect_fov(u_min: int, u_max: int, v_min: int, v_max: int) → tuple[int, int, int, int]

Clip a rectangle to the original FOV bounds.

Returns:

(u0, u1, v0, v1) clipped to [fov_u_min..fov_u_max], [fov_v_min..fov_v_max]

property closest_planet: str | None

property corner_bp: Backplane

Create a Backplane with points only in the four corners of the original FOV.

property data_shape_u: int

property data_shape_uv: tuple[int, int]

property data_shape_v: int

property data_shape_vu: tuple[int, int]

property ext_bp: Backplane

Create a Backplane for the entire extended FOV.

property ext_corner_bp: Backplane

Create a Backplane with points only in the four corners of the extended FOV.

property extdata: ndarray[tuple[Any, ...], dtype[floating[Any]]]

property extdata_shape_uv: tuple[int, int]

property extdata_shape_vu: tuple[int, int]

extfov_data_sensor_mask() → ndarray[tuple[Any, ...], dtype[bool]]

Boolean mask over extdata that is True where real sensor data lives.

extdata wraps data in a zero-padded margin so that correlation can search offsets outside the original field of view. The returned mask is True inside the original-FOV rectangle and False in the zero-padded margin.

Returns:

Boolean array with the same shape as extdata; True for the inner extfov_margin_v : extfov_margin_v + data_shape_v x extfov_margin_u : extfov_margin_u + data_shape_u region.

property extfov_margin_u: int

property extfov_margin_v: int

property extfov_margin_vu: tuple[int, int]

property extfov_u_max: int

property extfov_u_min: int

property extfov_v_max: int

property extfov_v_min: int

property extfov_vu_max: tuple[int, int]

property extfov_vu_min: tuple[int, int]

extract_offset_array(array: ndarray[tuple[Any, ...], dtype[NPType]], offset: tuple[float, float] | tuple[int, int] | None) → ndarray[tuple[Any, ...], dtype[NPType]]

Extracts a full-size array from the given extended FOV array.

Parameters:

• array – Array to extract the subimage from. This must be the same shape as the extended FOV.

• offset – Offset (dv,du) to extract the subarray at. An offset of (0,0) means to extract the center of the normal FOV. A positive offset means to extract in the negative direction of v and u.

Returns:

The extracted subimage. This will be the same shape as the original FOV.

property fov_u_max: int

property fov_u_min: int

property fov_v_max: int

property fov_v_min: int

property fov_vu_max: tuple[int, int]

property fov_vu_min: tuple[int, int]

inventory_body_in_extfov(inv: dict[str, Any]) → bool

Returns True if an inventory box overlaps the extended FOV.

inventory_body_in_fov(inv: dict[str, Any]) → bool

Returns True if an inventory box overlaps the original FOV.

make_extfov_false() → ndarray[tuple[Any, ...], dtype[bool]]

Creates a boolean array of False values matching the extended FOV dimensions.

Returns:

A boolean array of False values with the same shape as the extended FOV.

make_extfov_zeros(dtype: DTypeLike = <class 'numpy.float64'>) → ndarray[tuple[Any, ...], dtype[floating[Any]]]

Creates a zero-filled array matching the extended FOV dimensions.

Parameters:

dtype – Data type for the array elements.

Returns:

A zero-filled array with the same shape as the extended FOV.

make_fov_zeros(dtype: DTypeLike = <class 'numpy.float64'>) → ndarray[tuple[Any, ...], dtype[floating[Any]]]

Creates a zero-filled array matching the original FOV dimensions.

Parameters:

dtype – Data type for the array elements.

Returns:

A zero-filled array with the same shape as the original data.

ra_dec_limits(apparent: bool = True) → tuple[float, float, float, float]

Finds the right ascension and declination limits of the observation using the standard FOV.

Parameters:

apparent – Whether to compensate for aberration and light travel time.

Returns:

A tuple containing (ra_min, ra_max, dec_min, dec_max) in radians.

ra_dec_limits_ext(apparent: bool = True) → tuple[float, float, float, float]

Finds the right ascension and declination limits of the observation using the extended FOV.

Parameters:

apparent – Whether to compensate for aberration and light travel time.

Returns:

A tuple containing (ra_min, ra_max, dec_min, dec_max) in radians.

reset_all() → None

Resets all cached Backplanes and Meshgrids to their initial state.

Clears all cached computations, forcing them to be regenerated on next access.

sun_body_distance(body: str) → float

Computes the distance from the Sun to the specified celestial body in kilometers.

Parameters:

body – Name of the celestial body.

Returns:

Distance in kilometers from the Sun to the specified body.

unpad_array_to_extfov(array: ndarray[tuple[Any, ...], dtype[NPType]]) → ndarray[tuple[Any, ...], dtype[NPType]]

Unpads an array to be the size of the extended FOV.

This is most useful for using the result of np.unpackbits.

Returns:

The unpadded array.

class ObsSnapshotInst(snapshot: Snapshot, **kwargs: Any)

Bases: ObsSnapshot, ObsInst

Mix-in of ObsSnapshot and ObsInst.

class ObsInst(**kwargs: Any)

Bases: ABC

Mix-in class for instrument models representing spacecraft cameras.

This class provides default functionality for methods related to instruments and abstract methods for instrument-specific functionality.

abstractmethod static from_file(path: str | Path | FCPath, *, config: Config | None = None, extfov_margin_vu: tuple[int, int] | None = None, **kwargs: Any) → Obs

Creates an instrument instance from an image file.

Parameters:

• path – Path to the image file.

• config – Configuration object to use. If None, uses DEFAULT_CONFIG.

• extfov_margin_vu – Optional tuple specifying the extended field of view margins in (vertical, horizontal) pixels.

• **kwargs – Additional keyword arguments to pass to the instrument constructor.

Returns:

An Obs object containing the image data and metadata.

abstractmethod get_public_metadata() → dict[str, Any]

Returns the public metadata for this instrument.

property inst_config: dict[str, Any] | None

Returns the instrument configuration.

abstractmethod star_max_usable_vmag() → float

Returns the maximum usable magnitude for stars in this observation.

Returns:

The maximum usable magnitude for stars in this observation.

abstractmethod star_min_usable_vmag() → float

Returns the minimum usable magnitude for stars in this observation.

Returns:

The minimum usable magnitude for stars in this observation.

star_psf() → PSF

Returns the point spread function (PSF) model appropriate for stars observed by this instrument.

This generic implementation uses the “star_psf_sigma” configuration value and creates a Gaussian PSF with that sigma.

Returns:

A PSF model appropriate for stars observed by this instrument.

star_psf_size(star: Star) → tuple[int, int]

Returns the size of the point spread function (PSF) to use for a star.

This generic implementation uses the “star_psf_sizes” configuration value and returns the appropriate value for the star’s magnitude.

Parameters:

star – The star to get the PSF size for.

Returns:

A tuple of the PSF size (v, u) in pixels.

class ObsCassiniISS(snapshot: Snapshot, **kwargs: Any)

Bases: ObsSnapshotInst

Implements an observation of a Cassini ISS image.

This class provides specialized functionality for accessing and analyzing Cassini ISS image data.

static from_file(path: str | Path | FCPath, *, config: Config | None = None, extfov_margin_vu: tuple[int, int] | None = None, **kwargs: Any) → ObsCassiniISS

Creates an ObsCassiniISS from a Cassini ISS image file.

Parameters:

• path – Path to the Cassini ISS image file.

• config – Configuration object to use. If None, uses the default configuration.

• extfov_margin_vu – Optional tuple that overrides the extended field of view margins found in the config.

• **kwargs –

  Additional keyword arguments:

  • fast_distortion: Whether to use a fast distortion model.

  • return_all_planets: Whether to return all planets.

Returns:

An ObsCassiniISS object containing the image data and metadata.

get_public_metadata() → dict[str, Any]

Returns the public metadata for Cassini ISS.

Returns:

A dictionary containing the public metadata for Cassini ISS.

star_max_usable_vmag() → float

Returns the maximum usable magnitude for stars in this observation.

Returns:

The maximum usable magnitude for stars in this observation.

star_min_usable_vmag() → float

Returns the minimum usable magnitude for stars in this observation.

Returns:

The minimum usable magnitude for stars in this observation.

class ObsVoyagerISS(snapshot: Snapshot, **kwargs: Any)

Bases: ObsSnapshotInst

Implements an observation of a Voyager ISS image.

This class provides specialized functionality for accessing and analyzing Voyager ISS image data.

static from_file(path: str | Path | FCPath, *, config: Config | None = None, extfov_margin_vu: tuple[int, int] | None = None, **_kwargs: Any) → ObsVoyagerISS

Creates an ObsVoyagerISS from a Voyager ISS image file.

Parameters:

• path – Path to the Voyager ISS image file.

• config – Configuration object to use. If None, uses the default configuration.

• extfov_margin_vu – Optional tuple that overrides the extended field of view margins found in the config.

• **_kwargs – Additional keyword arguments (none for this instrument).

Returns:

An ObsVoyagerISS object containing the image data and metadata.

get_public_metadata() → dict[str, Any]

Returns the public metadata for Voyager ISS.

Returns:

A dictionary containing the public metadata for Voyager ISS.

star_max_usable_vmag() → float

Returns the maximum usable magnitude for stars in this observation.

Returns:

The maximum usable magnitude for stars in this observation.

star_min_usable_vmag() → float

Returns the minimum usable magnitude for stars in this observation.

Returns:

The minimum usable magnitude for stars in this observation.

class ObsGalileoSSI(snapshot: Snapshot, **kwargs: Any)

Bases: ObsSnapshotInst

Implements an observation of a Galileo SSI image.

This class provides specialized functionality for accessing and analyzing Galileo SSI image data.

static from_file(path: str | Path | FCPath, *, config: Config | None = None, extfov_margin_vu: tuple[int, int] | None = None, **_kwargs: Any) → ObsGalileoSSI

Creates an ObsGalileoSSI from a Galileo SSI image file.

Parameters:

• path – Path to the Galileo SSI image file.

• config – Configuration object to use. If None, uses the default configuration.

• extfov_margin_vu – Optional tuple that overrides the extended field of view margins found in the config.

• **_kwargs – Additional keyword arguments (none for this instrument).

Returns:

An ObsGalileoSSI object containing the image data and metadata.

get_public_metadata() → dict[str, Any]

Returns the public metadata for Galileo SSI.

Returns:

A dictionary containing the public metadata for Galileo SSI.

star_max_usable_vmag() → float

Returns the maximum usable magnitude for stars in this observation.

Returns:

The maximum usable magnitude for stars in this observation.

star_min_usable_vmag() → float

Returns the minimum usable magnitude for stars in this observation.

Returns:

The minimum usable magnitude for stars in this observation.

class ObsNewHorizonsLORRI(snapshot: Snapshot, **kwargs: Any)

Bases: ObsSnapshotInst

Implements an observation of a New Horizons LORRI image.

This class provides specialized functionality for accessing and analyzing New Horizons LORRI image data.

static from_file(path: str | Path | FCPath, *, config: Config | None = None, extfov_margin_vu: tuple[int, int] | None = None, **_kwargs: Any) → ObsNewHorizonsLORRI

Creates an ObsNewHorizonsLORRI from a New Horizons LORRI image file.

Parameters:

• path – Path to the New Horizons LORRI image file.

• config – Configuration object to use. If None, uses the default configuration.

• extfov_margin_vu – Optional tuple that overrides the extended field of view margins found in the config.

• **_kwargs – Additional keyword arguments (none for this instrument).

Returns:

An ObsNewHorizonsLORRI object containing the image data and metadata.

get_public_metadata() → dict[str, Any]

Returns the public metadata for New Horizons LORRI.

Returns:

A dictionary containing the public metadata for New Horizons LORRI.

star_max_usable_vmag() → float

Returns the maximum usable magnitude for stars in this observation.

Returns:

The maximum usable magnitude for stars in this observation.

star_min_usable_vmag() → float

Returns the minimum usable magnitude for stars in this observation.

Returns:

The minimum usable magnitude for stars in this observation.