Struct ImagePlaneModel 

pub struct ImagePlaneModel { /* private fields */ }

Algorithm-facing image-plane FPM model. It contains no LED or camera geometry.

Source-indexed vectors, crops, and optional subpixel offsets describe individual illuminations. Acquisition-frame-indexed gains, background, and multiplexing describe measured frames. Shapes are (height, width) and stored arrays own their data.

Implementations

impl ImagePlaneModel

pub fn new( k_vectors: Vec<KVector>, pupil: Pupil, crop_indices: CropIndices, sampling: Sampling, image_shape: (usize, usize), reconstruction_shape: (usize, usize), ) -> Result<Self>

Builds and validates a non-multiplexed model from explicitly compiled components.

k_vectors and crop_indices must have equal non-zero source counts. pupil and each crop must have image_shape; sampling and reconstruction_shape must be mutually consistent.

pub fn from_experiment( optics: &Optics, illumination: &Illumination, image_shape: (usize, usize), reconstruction_shape: ReconstructionShape, ) -> Result<Self>

Compiles an experiment using an explicit or automatically selected reconstruction shape.

pub fn suggest_reconstruction_shape( optics: &Optics, illumination: &Illumination, image_shape: (usize, usize), reconstruction_shape: ReconstructionShape, ) -> Result<(usize, usize)>

Resolves an explicit shape or suggests an automatic reconstruction grid from the actual illumination wave vectors.

pub fn compile( optics: &Optics, illumination: &ResolvedIllumination, image_shape: (usize, usize), reconstruction_shape: ReconstructionShape, ) -> Result<Self>

Compiles already resolved illumination into algorithm-facing numerical state.

Geometry positions and poses are intentionally not retained. Sparse frame weights are multiplied by stable source powers during compilation.

pub fn source_count(&self) -> usize

Returns the number of individual illumination sources.

pub fn frame_count(&self) -> usize

Returns the acquisition-frame count, which can differ when sources are multiplexed.

pub fn is_multiplexed(&self) -> bool

Returns whether acquisition frames contain incoherent combinations of sources.

pub fn k_vectors(&self) -> &[KVector]

Borrows transverse wave vectors in source order, in radians per metre.

pub fn pupil(&self) -> &Pupil

Borrows the low-resolution complex pupil and binary support.

pub fn pupil_mut(&mut self) -> &mut Pupil

Mutably borrows the pupil; callers must preserve its shape and support invariants.

pub fn crop_indices(&self) -> &CropIndices

Borrows integer Fourier crops in individual source order.

pub fn subpixel_offsets(&self) -> Option<&[FourierOffset]>

Borrows optional fractional (row, column) offsets in source order.

pub const fn sampling(&self) -> &Sampling

Borrows real- and Fourier-space sampling metadata.

pub const fn image_shape(&self) -> (usize, usize)

Returns low-resolution detector shape as (height, width).

pub const fn reconstruction_shape(&self) -> (usize, usize)

Returns high-resolution object shape as (height, width).

pub fn frame_gains(&self) -> Option<&[f64]>

Borrows optional non-negative multiplicative gains in acquisition-frame order.

pub fn background(&self) -> Option<&[f64]>

Borrows optional non-negative optical intensity background.

Length is one low-resolution frame (broadcast) or a complete row-major (frame, row, column) stack.

pub fn multiplexing_matrix(&self) -> Option<&MultiplexingMatrix>

Borrows optional acquisition-frame rows of non-negative source weights.

pub fn with_frame_gains(self, values: Option<Vec<f64>>) -> Result<Self>

Replaces gains, requiring one finite non-negative value per acquisition frame.

pub fn update_intensity_calibration( &mut self, source_power: &[f64], acquisition: &AcquisitionPlan, ) -> Result<()>

Refreshes only source powers, sparse acquisition weights, and frame gains.

Physical positions, propagation vectors, Fourier crops, subpixel offsets, pupil samples, sampling metadata, and reconstruction shapes are retained. This is the intensity-only update boundary used by physical illumination calibration.

pub fn update_illumination_geometry( &mut self, optics: &Optics, illumination: &Illumination, ) -> Result<()>

Recompiles illumination-dependent geometry into the existing numerical grid.

The low- and high-resolution shapes, optical sampling, pupil values, background, and other static model state are retained. A geometry that would move a crop outside the existing reconstruction grid is rejected.

pub fn replace_k_vectors(&mut self, values: Vec<KVector>) -> Result<()>

Replaces the source wave vectors while preserving the compiled crops.

This is intended for calibrated models whose replacement vectors use the same Fourier sampling and source ordering. The full model invariant set is revalidated before the replacement is committed.

pub fn with_background(self, values: Option<Vec<f64>>) -> Result<Self>

Replaces optical intensity background with a broadcast frame, full stack, or None.

pub fn with_multiplexing(self, matrix: MultiplexingMatrix) -> Result<Self>

Sets compiled sparse acquisition with one non-empty non-negative row per frame.

pub fn with_subpixel_offsets(self, offsets: Vec<FourierOffset>) -> Result<Self>

Sets one finite fractional Fourier-grid offset per individual source.

pub fn source_offset(&self, source: usize) -> Result<FourierOffset>

Returns a source’s fractional Fourier-grid offset, or zero when absent.

pub fn extract_patch( &self, object_spectrum: ArrayView2<'_, Complex64>, source: usize, destination: &mut [Complex64], ) -> Result<()>

Extracts one source patch from a standard-layout high-resolution object spectrum.

destination has image_shape.0 * image_shape.1 row-major complex values. Fractional offsets use bilinear Fourier-grid interpolation.

pub fn insert_patch_adjoint( &self, destination: ArrayViewMut2<'_, Complex64>, source: usize, update: &[Complex64], scale: f64, ) -> Result<()>

Adds an update into a high-resolution spectrum through the adjoint crop operator.

pub fn validate_source_offset( &self, source: usize, offset: FourierOffset, ) -> Result<()>

Checks that source exists and the interpolation stencil for offset is in bounds.

pub fn frame_gain(&self, frame: usize) -> Result<f64>

Returns a frame’s positive gain, defaulting to 1.0 when gains are absent.

pub fn background_value(&self, frame: usize, pixel: usize) -> Result<f64>

Returns background intensity for a frame and row-major pixel index.

Returns zero when background is absent and handles broadcast backgrounds.

pub fn validate(&self) -> Result<()>

Validates source/crop counts, shapes, pupil, sampling, vectors, interpolation bounds, gains, background, and optional multiplexing rows.

Trait Implementations

impl Clone for ImagePlaneModel

fn clone(&self) -> ImagePlaneModel

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ImagePlaneModel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ImagePlaneModel

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ImagePlaneModel

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.