analysis.image_simulation

class DistortionWarper(optic, source_fov=None)[source]

Handles geometric distortion and lateral color by creating a warp map that transforms the ideal image coordinates to the distorted image plane.

Parameters:

  • optic (Optic) – The optical system.

  • source_fov (tuple) – (max_x, max_y) of the source field in system units (degrees for infinite, mm for finite). If None, attempts to infer from optic.fields.max_field.

generate_distortion_map(wavelength, image_shape, num_grid_points=25, degree=5)[source]

Generates the sampling grid required by grid_sample to warp the source image using a polynomial fit to the distortion.

warp_image(image, distortion_grid)[source]

Warps the input image using the provided distortion grid.

class ImageSimulationEngine(optic, config=None)[source]

Master engine for performing full image simulation including spatially variable blur, geometric distortion, and lateral color.

Parameters:

  • optic (Optic) – The optical system model.

  • config (dict) – Configuration dictionary. - wavelength (list[float]): List of 3 wavelengths (um) for R, G, B. - psf_grid_shape (tuple): (ny, nx) for PSF basis generation. - psf_size (int): Pixel size for PSFs. - num_rays (int): Number of rays for PSF generation. - n_components (int): Number of EigenPSFs. - oversample (int): Upsampling factor for simulation accuracy. - padding (int): Pixel padding (guard band) to avoid edge artifacts.

run(source_image)[source]

Executes the simulation pipeline.

Parameters:

source_image (ArrayLike) – The input source image with shape (H, W), (H, W, 3), or (B, C, H, W).

Returns:

The simulated image batch with shape (B, C, H, W).

Values defined by input dynamic range.

Return type:

be.ndarray

view(index: int = 0, *, show: bool = True)[source]

Visualizes one original and simulated image side-by-side from the batch.

Parameters:

  • index (int) – Batch index to visualize.

  • show (bool) – If True (default), calls plt.show(). Set False for headless use.

class PSFBasisGenerator(optic, wavelength, grid_shape=(5, 5), num_rays=128, psf_grid_size=None)[source]

Generates a basis of EigenPSFs for an optical system using SVD.

This class computes a grid of PSFs and decomposes them to find the EigenPSFs that efficiently represent the spatially varying blur.

Parameters:

  • optic (Optic) – The optical system to analyze.

  • wavelength (float) – The wavelength for PSF calculation.

  • grid_shape (tuple, optional) – (ny, nx) size of sampling grid. Default: (5, 5).

  • num_rays (int, optional) – Number of rays for pupil sampling. Default: 128.

  • psf_grid_size (int, optional) –

    PSF grid size (e.g., 256 for 256x256).

    If None, calculated from num_rays.

generate_basis(n_components=3)[source]

Computes the EigenPSFs and their corresponding coefficient maps.

Parameters:

n_components (int) – Number of principal components (EigenPSFs) to keep.

Returns: :returns: - eigen_psfs (be.ndarray): Basis PSFs, shape (n_components, H, W).

  • coefficient_grid (be.ndarray): Coefficient maps on low-res grid, shape (n_components, grid_ny, grid_nx).

  • mean_psf (be.ndarray): Average PSF across field, shape (H, W).

Return type:

tuple

static resize_coefficient_map(coeff_map, target_shape)[source]

Resizes the coefficient map to the target shape using bicubic interpolation.

Parameters:

  • coeff_map (be.ndarray) – Input map (H_in, W_in) or (C, H_in, W_in).

  • target_shape (tuple) – (H_out, W_out).

Returns:

Resized map.

Return type:

be.ndarray

class SpatiallyVariableSimulator[source]

Simulates image formation with spatially variable point spread functions (PSFs) using the EigenPSF method.

This simulator decomposes the spatially variant PSF into a set of basis functions (EigenPSFs) and coefficient maps, efficiently computing the resulting image via weighted sums of convolutions.

optic

The optical system to simulate.

Type:

Optic

wavelength

Wavelength of operation.

Type:

float

simulate(source_image, eigen_psfs, coefficient_maps, mean_psf)[source]

Simulate the image using provided EigenPSFs and Coefficient Maps.

Parameters:

  • source_image (be.ndarray) – The high-resolution source image (B, H, W).

  • eigen_psfs (be.ndarray) – Basis PSFs (K, P, P).

  • coefficient_maps (be.ndarray) – Spatial coefficient maps (K, H, W).

  • mean_psf (be.ndarray) – The average PSF (P, P).

Returns:

The simulated image (B, H, W).

Return type:

be.ndarray