nav.support

Bases: dict[str, Any]

Implements a dictionary that allows attribute-style access to its key-value pairs.

A dictionary subclass that exposes its keys as attributes, allowing dict items to be accessed using attribute notation (dict.key) in addition to the normal dictionary lookup (dict[key]).

Parameters:

  • *args – Variable length argument list passed to dict constructor.

  • **kwargs – Arbitrary keyword arguments passed to dict constructor.

Constants module for navigation calculations.

This module defines mathematical constants used throughout the navigation system.

Evaluate a candidate for the navigation.

Parameters:

  • image_pad – The padded image.

  • model_pad – The padded model.

  • mask_pad – The padded mask.

  • corr – The correlation matrix.

  • rc – The row and column of the candidate.

  • upsample_factor – The upsample factor.

  • model_shape – The shape of the model.

  • image_shape – The shape of the image.

  • prior_shift – The prior shift.

  • prior_weight – The prior weight.

  • metric – The metric to use for the navigation.

Returns:

A dictionary containing the navigation result.

Subpixel shift via Fourier shift theorem (positive = down/right).

Map [0 .. size-1] argmax index to a signed displacement coordinate.

Parameters:

  • idx – Peak index from correlation search in [0, size).

  • size – FFT / correlation length (modulus for wrapping).

Returns:

int signed offset equivalent to idx when idx < size // 2, else idx - size (negative branch for peaks in the second half).

Masked normalized cross-correlation surface between image and model.

Computes shift-wise NCC (Pearson r) using FFT-based sums. Also returns the unnormalized NCC numerator (mean-subtracted covariance) as a diagnostic.

The NCC surface contains values in [-1, 1] at every shift where the mask overlaps non-constant image content, and is the primary peak-selection surface: it is invariant to the image variance under the shifted mask and therefore does not suffer from the “scale bias” that causes the numerator to prefer shifts where the fixed template mask straddles bright/dark boundaries in the image (e.g., the limb of a Lambert-shaded body disc). The numerator surface scales with sqrt(image-variance-under-mask) times the NCC, which is useful as a sanity check but must not be used for peak finding when the template is dense.

Parameters:

  • image – Padded image array.

  • model – Padded model array (same shape as image).

  • mask – Padded boolean mask (same shape as image). True where model pixels are valid.

  • data_mask – Optional padded boolean mask indicating where image contains real sensor data (True) versus zero-padded margin (False). When provided, the NCC is computed in its bi-directional form so that pixel pairs where the shifted model mask straddles zero-padded image pixels do not bias the normalization. This removes the edge-ridge artifact that otherwise appears at |dV| = extfov_margin_v when the body model extends into the extfov margin. When None, the standard (single-mask) NCC formula is used.

Returns:

Tuple of (ncc, numerator) arrays, each with the same shape as the inputs. ncc is the Pearson-r surface used for peak localization; numerator is the mean-subtracted cross-covariance (unnormalized) returned as a diagnostic. When data_mask is provided, shifts with degenerate overlap or variance are set to -inf in the NCC surface.

One-scale masked NCC + top-K candidate evaluation.

Parameters:

  • image – The image to navigate.

  • model – The model to navigate.

  • mask – The mask to use for the navigation.

  • max_peaks – The number of peaks to use for the navigation.

  • upsample_factor – The upsample factor to use for the navigation.

  • metric – The metric to use for the navigation.

  • prior_shift – The prior shift to use for the navigation.

  • prior_weight – The prior weight to use for the navigation.

  • nms_radius – The radius to use for the non-maximum suppression.

  • logger – The logger to use for the navigation.

  • max_offset_vu – If given, only correlation peaks whose signed (V, U) offset satisfies |dV| <= max_offset_vu[0] and |dU| <= max_offset_vu[1] are considered candidates. Typically set to the extended-FOV margins so that offsets outside the physically-plausible range are never evaluated.

  • data_mask – Optional boolean mask (same shape as image) that is True where the image contains real sensor data and False inside the zero-padded extended-FOV margin. When provided, the NCC is computed in its bi-directional form so that the model extending into the padded margin does not bias the peak toward |dV| = margin_v.

Returns:

A dictionary containing the navigation result.

TODO Clean this up Build class-aware effective model + mask, run coarse->fine, then evaluate K peaks at final scale. Returns dict with shift, covariance, sigma_xy, quality, consistency, spurious flag.

Parameters:

  • image – The source image to navigate, unpadded.

  • model – The model to navigate against, padded as necessary to include more data around the edges. It does not need to be the same size as the image.

  • mask – The mask indicating which pixels in the model are valid. Same size as the model.

  • pyramid_levels – The number of pyramid levels to use. Each pyramid level divides the image and model by an additional factor of 2 (pyramid_levels=3 means to start with 1/4, then 1/2, then 1/1 downsampling).

  • max_peaks – The number of peaks to look for in the correlation at each pyramid level.

  • upsample_factor – The upsample factor to use for increased FFT resolution around a peak.

  • metric – The metric to use for the navigation. Can be one of ‘psr’, ‘pmr’, or ‘per’.

  • quality_thresh – The quality threshold to use for the navigation.

  • consistency_tol – The consistency tolerance to use for the navigation.

  • nms_radius – The radius to use for the non-maximum suppression.

  • prior_weight_final – The prior weight to use for the final navigation.

  • max_offset_vu – Maximum permitted signed offset as (max_dV, max_dU) in full-resolution pixels. When given, correlation peaks outside this range are excluded at every pyramid level (the limit is scaled by the downsample factor at each level). Pass obs.extfov_margin_vu to restrict the search to offsets that are physically reachable given the extended FOV padding.

  • data_mask – Optional boolean mask (same shape as image) that is True where the image contains real sensor data and False inside the zero-padded extended-FOV margin. When provided, the NCC is computed in its bi-directional form at every pyramid level so that a body model extending into the extfov margin does not bias the peak toward |dV| = margin_v. Pass obs.extfov_data_sensor_mask().

  • logger – The logger to use for the navigation.

Returns:

  • offset: The offset.

  • cov: The covariance matrix.

  • sigma_xy: The sigma_xy.

  • quality: The quality of the navigation.

  • metric: The metric used for the navigation.

  • consistency: The consistency of the navigation.

  • spurious: True if the navigation is spurious, False otherwise.

Return type:

A dictionary containing the navigation result

Notes

The metrics are:

  • PSR (Peak-to-Sidelobe Ratio): Measures peak distinctness as (peak - mean_sidelobe) / std_sidelobe, where the sidelobe region excludes the peak neighborhood.

  • PMR (Peak-to-Mean Ratio): Ratio of the global maximum correlation value to the mean of all correlation values; indicates how dominant the main peak is over the average background.

  • PER (Peak-to-Energy Ratio): Ratio of the squared peak value to the total correlation energy (sum of squares); reflects how much of the total response energy is concentrated in the main peak.

Non-maximum suppression to get top-k peaks.

Parameters:

  • corr – 2-D correlation surface (V x U).

  • k – Maximum number of peaks to return.

  • radius – Suppression radius around each selected peak in pixels.

  • max_offset_vu – If given, only positions whose signed offset satisfies |dV| <= max_offset_vu[0] and |dU| <= max_offset_vu[1] are eligible. Signed offsets are derived from the FFT-convention wrap-around used by int_to_signed().

Returns:

List of (row, col, value) tuples for up to k peaks.

Localized upsampled DFT.

From Guizar-Sicairos, 2008. “Efficient subpixel image registration via cross-correlation.” Optics Leters, 33(2):156-158

Recursively converts NumPy types in any object to Python native types.

Parameters:

obj – The object to clean, can be a dict, list, tuple or scalar value.

Returns:

The object with all NumPy types converted to Python native types.

Dumps data as YAML output after converting NumPy types to Python types.

Parameters:

data – The data to dump as YAML.

Dumps data as a JSON string after converting NumPy types to Python types.

Parameters:

data – The data to dump as JSON.

Return a clean stellar classification such as A0 or M8.

Zoom down by an integer factor. Returned arrays are floating-point.

Zooms an array by the specified factor using array indexing.

Parameters:

  • a – The input array to zoom.

  • factor – The zoom factor for each dimension of the array.

Returns:

The zoomed array with dimensions multiplied by the corresponding factors.

Center crop to out_shape (h,w).

Parameters:

  • img – A 2-D array to crop.

  • out_shape – The target shape (height, width).

Returns:

The center-cropped array.

Raises:

ValueError – If img is not 2-dimensional or out_shape is larger than img.shape.

Draw a circle using Bresenham’s algorithm with the given thickness.

Parameters:

  • img – The 2-D (or higher) array to draw on.

  • x0 – The middle of the circle.

  • y0 – The middle of the circle.

  • r – The radius of the circle.

  • color – The scalar (or higher) color to draw.

  • thickness – The thickness (total width) of the circle.

Draw a line using Bresenham’s algorithm with the given thickness.

The line is drawn by drawing each point as a line perpendicular to the main line.

Parameters:

  • img – The 2-D (or higher) array to draw on.

  • x0 – The starting point.

  • y0 – The starting point.

  • x1 – The ending point.

  • y1 – The ending point.

  • color – The scalar (or higher) color to draw.

  • thickness – The thickness (total width) of the line.

Draws a line with an arrow head at the end point.

Parameters:

  • img – The 2-D (or higher) array to draw on.

  • color – The scalar (or higher) color to draw.

  • x0 – The x-coordinate of the starting point.

  • y0 – The y-coordinate of the starting point.

  • x1 – The x-coordinate of the ending point.

  • y1 – The y-coordinate of the ending point.

  • thickness – The thickness of the line.

  • arrow_head_length – The length of the arrow head lines.

  • arrow_head_angle – The angle in degrees between the arrow head and the main line.

Draw a rectangle with the given line thickness.

Parameters:

  • img – The 2-D (or higher) array to draw on.

  • xctr – The center of the rectangle.

  • yctr – The center of the rectangle.

  • xhalfwidth – The width of the rectangle on each side of the center.

  • yhalfwidth – This is the inner border of the rectangle.

  • color – The scalar (or higher) color to draw.

  • thickness – The thickness (total width) of the line.

  • dot_spacing – The spacing between dots in the rectangle. 1 means dots are adjacent (solid lines).

Downsamples an array by averaging blocks of pixels.

Parameters:

  • arr – The input array to downsample.

  • amt_y – The vertical downsampling factor.

  • amt_x – The horizontal downsampling factor.

Returns:

The downsampled array.

Raises:

AssertionError – If the array dimensions are not divisible by the downsampling factors.

Filter an array to find local maxima.

Process:

  1. Create a mask consisting of the pixels that are local maxima within maximum_boxsize

  2. Find the minimum value for the area around each array pixel using minimum_boxsize

  3. Remove maxima that are not at least maximum_tolerange times the local minimum

  4. Blur the maximum pixels mask to make each a square area of maximum_blur X maximum_blur

  5. Compute the median-subtracted value for each array pixel using median_boxsize

  6. Copy the median-subtracted array pixels to a new zero-filled array where the maximum mask is true

  7. Gaussian blur this final result

Parameters:

  • data – The array

  • maximum_boxsize – The box size to use when finding the maximum value for the area around each pixel.

  • median_boxsize – The box size to use when finding the median value for the area around each pixel.

  • maximum_blur – The amount to blur the maximum filter. If a pixel is marked as a maximum, then the pixels in a blur X blur square will also be marked as a maximum.

  • maximum_tolerance – The factor above the local minimum that a maximum pixel has to be in order to be included in the final result.

  • minimum_boxsize – The box size to use when finding the minimum value for the area around each pixel.

  • gaussian_blur – The amount to blur the final result.

Returns:

The filtered array.

Compute the median-subtracted value for each pixel.

Parameters:

  • data – The array

  • median_boxsize – The box size to use when finding the median value for the area around each pixel.

  • gaussian_blur – The amount to blur the median value before subtracting it from the array.

  • footprint – The shape of footprint to use (‘square’, ‘circle’).

Returns:

The median-subtracted array.

Blur by anisotropic Gaussian with covariance matrix in frequency domain.

Parameters:

  • img – A 2-D array to blur.

  • sigma – A 2x2 covariance matrix [[Syy, Syx], [Sxy, Sxx]].

Returns:

The blurred image.

Raises:

ValueError – If img is not 2-dimensional or sigma is not 2x2.

Compute isotropic gradient magnitude.

Parameters:

img – The input array.

Returns:

The gradient magnitude at each pixel, computed as sqrt(gx^2 + gy^2).

Computes the smallest power of 2 that is greater than or equal to n.

Parameters:

n – The input integer value.

Returns:

The smallest power of 2 that is greater than or equal to n.

Zero-mean, unit-std normalization (safe if nearly constant).

Parameters:

  • a – The input array to normalize.

  • eps – Minimum standard deviation threshold. If std < eps, returns zeros.

Returns:

Normalized array with mean 0 and std 1, or zeros if nearly constant.

Pad an array by the given margin at each edge.

Parameters:

  • array – The N-dimensional array to pad.

  • margin – A list or tuple of length N of margin amounts in the same order as the array indices. Each axis is padded to its original size plus 2*N and the original values are centered on the new axis.

  • fill – The value used to fill the newly created array elements.

Returns:

The array padded by the given amount.

Raises:

ValueError – If the array shape and margin list have different lengths.

Zero-pad a 2-D array on all sides to be a power of 2 in each dimension.

If the original array has a side that is not a power of 2, it must be even.

Returns: A tuple containing the padded array and the amount of padding added.

Place array at (0,0) inside zeros(v_size, u_size).

Parameters:

  • array – A 2-D array to place.

  • v_size – The height of the output array.

  • u_size – The width of the output array.

Returns:

A (v_size, u_size) array with the input array at the top-left corner. If the input array is larger than the target size, it will be truncated.

Shift an array by an offset, filling with zeros or a specified value.

Parameters:

  • array – The N-dimensional array to shift.

  • offset – A list or tuple of length N of offsets in the same order as the array indices. A positive offset shifts to higher numbers on the axis.

  • fill – The value used to fill the newly created array elements.

Returns:

The array shifted by the given amount.

Raises:

ValueError – If the array shape and offset list have different lengths.

Remove a padded margin from each edge.

Parameters:

  • array – The N-dimensional array to unpad.

  • margin – A list or tuple of length N of margin amounts in the same order as the array indices. Each axis is unpadded to its original size minus 2*N and the original centered values are used on the new axis.

Returns:

The array unpadded by the given amount.

Raises:

ValueError – If the array shape and margin list have different lengths.

Return the git version of the current repo, caching the result.

The result is cached because the git version cannot change during a single program run.

Returns:

The git describe string, or ‘GIT DESCRIBE FAILED’ if the command fails.

Converts declination in radians to a formatted string in degrees, minutes, and seconds.

Parameters:

dec – Declination value in radians.

Returns:

Formatted string in the form “+/-DDDdMMmSS.SSSs”.

Flattens a list of lists into a single list.

Parameters:

lst – The list to flatten.

Returns:

A flattened list.

Return this machine’s fully qualified domain name as a string.

The value is obtained from socket.getfqdn() on the first call and stored in the module-level _LOCAL_HOST_NAME_CACHE so later calls return the same string without calling getfqdn again.

Returns:

The FQDN string on success, or the literal 'LOCAL HOST NAME FAILED' if socket.getfqdn() raises any exception.

Side effects:

On the first successful call, sets _LOCAL_HOST_NAME_CACHE to the FQDN. On the first failing call, sets _LOCAL_HOST_NAME_CACHE to 'LOCAL HOST NAME FAILED'. Subsequent calls return the cached value and do not call socket.getfqdn() again.

Log host, git, and command-line context to the given logger.

Call once at process startup on the main logger (e.g. nav_mosaic after setup_logging). Per-image loggers may omit this to avoid duplicating the same block on the console when handlers mirror output to MAIN_LOGGER.

Parameters:

  • logger – The logger to write to.

  • command_list – The command-line arguments for the current run (typically sys.argv[1:]).

Median absolute deviation (MAD) standard deviation.

Converts right ascension in radians to a formatted string in hours, minutes, and seconds.

Parameters:

ra – Right ascension value in radians.

Returns:

Formatted string in the form “HHhMMmSS.SSSs”.

Raises:

ValueError – If the right ascension value is negative.

Strips leading zeros from a string but leaves one zero behind if that’s all there is.

Parameters:

s – The string to strip leading zeros from.

Returns:

The string with leading zeros stripped.

Bases: object

Provides a base class with configuration and logging capabilities for navigation components.

Serves as the foundation for navigation-related classes by providing common functionality for configuration management and logging.

Parameters:

config – Configuration object for this instance. Uses DEFAULT_CONFIG if not provided.

Returns the configuration object associated with this instance.

Returns the logger instance associated with this object.

Bases: Protocol

Returns the difference between two datetime objects as a string representation.

Parameters:

  • start_time – The starting datetime.

  • end_time – The ending datetime.

Returns:

String representation of the time difference.

Returns the UTC time for a given ET time.

Parameters:

  • et – The SPICE ET time (equivalent to TDB).

  • digits – The number of digits to include after the decimal point.

Returns:

The UTC time as a string.

Returns the current time as a datetime object with timezone information.

Returns:

Current time as a timezone-aware datetime object.

Returns the current time as an ISO 8601 formatted string with timezone information.

Returns:

Current time as an ISO 8601 formatted string.

Returns the ET time (TDB seconds) for a given UTC time string.

Parameters:

utc – The UTC time as an ISO 8601 formatted string (e.g., “2008-01-01 12:00:00” or “2008-01-01T12:00:00”).

Returns:

The SPICE ET time (equivalent to TDB) in seconds as a float.