Struct LazyMeasurementStack 

pub struct LazyMeasurementStack { /* private fields */ }

File-backed measurement frames decoded, preprocessed, and cached on access.

Construction reads image headers to validate grayscale type and dimensions, but does not decode measurement pixel buffers. A bounded thread-safe LRU cache keeps the working set out of core while returned shared frame handles remain stable. Cache byte accounting covers frame pixel buffers retained by the cache, not handles that callers keep alive after eviction.

Frame decoding occurs without holding the cache mutex, so callers can read different uncached frames concurrently; a second lookup makes concurrent reads of the same frame converge on one cached handle. A poisoned cache is treated as corrupted state: Self::frame returns an error rather than reusing it. The infallible cache-statistics accessors report zero after poisoning because they cannot expose that error; rebuild the stack before using it again.

Implementations

impl LazyMeasurementStack

pub fn from_image_files<P: AsRef<Path>>( paths: &[P], frame_metadata: Vec<FrameMetadata>, ) -> Result<Self>

Opens same-shaped grayscale files without decoding their pixels until requested.

pub fn from_tiff_stack( path: impl AsRef<Path>, frame_metadata: Vec<FrameMetadata>, ) -> Result<Self>

Opens a multipage TIFF lazily. Page headers are validated up front, but each page’s pixels are decoded only when that frame is requested.

pub fn from_manifest(path: impl AsRef<Path>) -> Result<Self>

Loads a manifest while leaving measurement frames file-backed. Small shared correction images and optional per-frame backgrounds/masks are loaded once; configured corrections are applied during frame decoding.

pub fn from_manifest_definition( manifest: MeasurementSpec, base_directory: impl AsRef<Path>, ) -> Result<Self>

Opens a manifest value lazily, resolving relative paths beneath base_directory.

pub fn with_dark_frame(self, dark: Vec<f64>) -> Result<Self>

Stores one finite row-major dark frame and enables subtraction during decoding.

pub fn with_flat_field(self, flat: Vec<f64>) -> Result<Self>

Stores one positive finite row-major flat field and enables division during decoding.

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

Stores a finite broadcast frame or full (frame, row, column) background stack.

pub fn with_masks(self, masks: Vec<u8>) -> Result<Self>

Stores a binary broadcast mask or full row-major (frame, row, column) mask stack.

pub fn normalize_exposure(self) -> Self

Enables division by each frame’s positive exposure time during decoding.

pub fn clamp_negative(self) -> Self

Enables clamping corrected negative intensities to zero during decoding.

pub fn with_preprocessing( self, preprocessing: PreprocessingConfig, ) -> Result<Self>

Replaces the preprocessing flags. Required correction arrays must have already been supplied through the corresponding builder.

pub fn with_cache_capacity(self, capacity: usize) -> Result<Self>

Sets the maximum decoded frames retained in memory. The default is one.

pub fn with_cache_byte_capacity(self, capacity: usize) -> Result<Self>

Sets a second cache limit in bytes. It must fit at least one decoded f64 frame. Count and byte limits are enforced simultaneously.

pub fn frame_count(&self) -> usize

Returns the acquisition-frame count.

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

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

pub fn frame_len(&self) -> usize

Returns the row-major element count of one decoded frame.

pub fn frame_metadata(&self) -> &[FrameMetadata]

Borrows metadata in acquisition-frame order.

pub fn preprocessing(&self) -> &PreprocessingConfig

Borrows corrections applied when an uncached frame is decoded.

pub fn paths(&self) -> &[PathBuf]

Returns one path per frame. Multipage TIFF frames therefore repeat the stack path and can be distinguished by their metadata labels.

pub fn cached_frame_count(&self) -> usize

Returns the decoded-frame count, or zero if the cache lock is poisoned.

pub fn cached_byte_count(&self) -> usize

Returns bytes occupied by decoded f64 frames, or zero after lock poisoning.

pub fn frame(&self, index: usize) -> Result<Arc<Vec<f64>>>

Returns a shared row-major decoded intensity frame, loading and caching on a miss.

pub fn frame_weight(&self, index: usize) -> Result<f64>

Returns a frame’s non-negative reconstruction weight.

pub fn frame_mask(&self, index: usize) -> Result<Option<&[u8]>>

Borrows a frame’s binary row-major mask, including a broadcast mask.

pub fn materialize(&self) -> Result<MeasurementStack>

Decodes every frame into a new resident MeasurementStack.

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

Checks paths/page indices/metadata counts, shape and cache capacities, metadata, required correction buffers, background and mask lengths, and finite values.

Trait Implementations

impl Clone for LazyMeasurementStack

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LazyMeasurementStack

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

Formats the value using the given formatter.

impl MeasurementRead for LazyMeasurementStack

fn frame_count(&self) -> usize

Returns the number of acquisition frames.

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

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

fn frame_len(&self) -> usize

Returns height * width, the row-major element count of one frame.

fn frame(&self, index: usize) -> Result<impl Deref<Target = [f64]> + '_>

Borrows or shares a row-major intensity frame by zero-based acquisition index.

fn frame_weight(&self, index: usize) -> Result<f64>

Returns a frame’s non-negative reconstruction weight.

fn frame_mask(&self, index: usize) -> Result<Option<&[u8]>>

Borrows an optional row-major binary validity mask for one frame.

fn frame_metadata(&self) -> &[FrameMetadata]

Borrows metadata in acquisition-frame order.

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

Checks shapes, counts, finite intensities, metadata, weights, and masks.