Skip to main content

fpm_rs/datasets/
subset.rs

1use ndarray::{Array2, Array3};
2
3use crate::{
4    Complex64, Result,
5    array_layout::checked_len_2d,
6    configuration::{ExperimentDescription, SimulationConfiguration},
7    error::Error,
8    experiment::Illumination,
9    measurements::MeasurementStack,
10    model::{ImagePlaneModel, ReconstructionShape},
11    reconstruction::ReconstructionProblem,
12};
13
14use super::Dataset;
15
16/// Axis-aligned detector/object crop using zero-based pixel indices.
17#[derive(Clone, Copy, Debug, PartialEq, Eq)]
18pub struct Rect {
19    /// First included row (`y`).
20    pub row: usize,
21    /// First included column (`x`).
22    pub column: usize,
23    /// Positive number of rows.
24    pub height: usize,
25    /// Positive number of columns.
26    pub width: usize,
27}
28
29impl Rect {
30    /// Creates a non-empty rectangle; containment is checked when a subset is built.
31    pub fn new(row: usize, column: usize, height: usize, width: usize) -> Result<Self> {
32        if height == 0 || width == 0 {
33            return Err(Error::Dataset(
34                "dataset crop height and width must be non-zero".into(),
35            ));
36        }
37        Ok(Self {
38            row,
39            column,
40            height,
41            width,
42        })
43    }
44}
45
46/// Deterministic acquisition-frame selection for a dataset subset.
47#[derive(Clone, Debug, PartialEq, Eq)]
48pub enum FrameSelector {
49    /// Retain every acquisition frame in original order.
50    All,
51    /// Retain indices `0, step, 2*step, ...`; `step` must be positive.
52    EveryNth(usize),
53    /// Retain explicit unique acquisition-frame indices in the supplied order.
54    Indices(Vec<usize>),
55}
56
57/// Owned dataset values after deterministic frame selection and optional spatial crop.
58#[derive(Clone, Debug)]
59pub struct DatasetSubset {
60    measurements: MeasurementStack,
61    configuration: SimulationConfiguration,
62    ground_truth_object: Option<Array2<Complex64>>,
63    valid_object_mask: Option<Array2<u8>>,
64    provenance: std::collections::BTreeMap<String, String>,
65    measurement_units: Option<String>,
66    spatial_crop: Rect,
67}
68
69impl DatasetSubset {
70    /// Resolved detector rectangle in the original dataset's zero-based pixels.
71    ///
72    /// Frame-only selections resolve to the full original image rectangle.
73    pub fn spatial_crop(&self) -> Rect {
74        self.spatial_crop
75    }
76
77    /// Borrows subsetted resident measurements.
78    pub fn measurements(&self) -> &MeasurementStack {
79        &self.measurements
80    }
81
82    /// Borrows models and descriptions updated for the subset dimensions and sources.
83    pub fn configuration(&self) -> &SimulationConfiguration {
84        &self.configuration
85    }
86
87    /// Borrows optional cropped high-resolution complex ground truth.
88    pub fn ground_truth_object(&self) -> Option<&Array2<Complex64>> {
89        self.ground_truth_object.as_ref()
90    }
91
92    /// Borrows optional cropped binary object-validity mask.
93    pub fn valid_object_mask(&self) -> Option<&Array2<u8>> {
94        self.valid_object_mask.as_ref()
95    }
96
97    /// Borrows the original dataset's provenance; resolved selection is in frame
98    /// metadata and [`Self::spatial_crop`].
99    pub fn provenance(&self) -> &std::collections::BTreeMap<String, String> {
100        &self.provenance
101    }
102
103    /// Borrows unchanged semantic measurement units.
104    pub fn measurement_units(&self) -> Option<&str> {
105        self.measurement_units.as_deref()
106    }
107
108    /// Clones subset measurements and assumed model into a validated reconstruction problem.
109    pub fn reconstruction_problem(&self) -> Result<ReconstructionProblem<MeasurementStack>> {
110        ReconstructionProblem::new(
111            self.measurements.clone(),
112            self.configuration
113                .compiled_models
114                .reconstruction_model
115                .clone(),
116        )
117    }
118}
119
120/// Borrowing builder for deterministic dataset frame and spatial subsets.
121#[derive(Clone, Debug)]
122pub struct DatasetSubsetBuilder<'a> {
123    dataset: &'a Dataset,
124    frames: FrameSelector,
125    crop: Option<Rect>,
126}
127
128impl<'a> DatasetSubsetBuilder<'a> {
129    pub(crate) fn new(dataset: &'a Dataset) -> Self {
130        Self {
131            dataset,
132            frames: FrameSelector::All,
133            crop: None,
134        }
135    }
136
137    /// Selects acquisition frames; validation occurs in [`Self::build`].
138    pub fn frames(mut self, selector: FrameSelector) -> Self {
139        self.frames = selector;
140        self
141    }
142
143    /// Selects acquisition indices `0, step, 2*step, ...`.
144    pub fn every_nth_frame(self, step: usize) -> Self {
145        self.frames(FrameSelector::EveryNth(step))
146    }
147
148    /// Selects a low-resolution detector rectangle; corresponding object/model grids are updated.
149    pub fn crop(mut self, crop: Rect) -> Self {
150        self.crop = Some(crop);
151        self
152    }
153
154    /// Creates and selects a detector crop from zero-based row/column and positive size.
155    pub fn crop_pixels(
156        self,
157        row: usize,
158        column: usize,
159        height: usize,
160        width: usize,
161    ) -> Result<Self> {
162        Ok(self.crop(Rect::new(row, column, height, width)?))
163    }
164
165    /// Validates selection and crop bounds, then owns subsetted measurements, models,
166    /// optional ground truth/mask, and provenance.
167    pub fn build(self) -> Result<DatasetSubset> {
168        let source = self.dataset.measurements();
169        let model = &self
170            .dataset
171            .configuration()
172            .compiled_models
173            .reconstruction_model;
174        let indices = selected_indices(&self.frames, source.frame_count())?;
175        let source_shape = source.image_shape();
176        let crop = self.crop.unwrap_or(Rect {
177            row: 0,
178            column: 0,
179            height: source_shape.0,
180            width: source_shape.1,
181        });
182        validate_crop(crop, source_shape)?;
183        let crop_len = checked_len_2d((crop.height, crop.width))?;
184        let data_len = crop_len
185            .checked_mul(indices.len())
186            .ok_or_else(|| Error::ShapeOverflow {
187                shape: vec![indices.len(), crop.height, crop.width],
188            })?;
189
190        let mut data = Vec::with_capacity(data_len);
191        let mut metadata = Vec::with_capacity(indices.len());
192        for (new_index, &source_index) in indices.iter().enumerate() {
193            crop_frame(source.frame(source_index)?, source_shape, crop, &mut data);
194            let mut frame_metadata = source.frame_metadata()[source_index].clone();
195            frame_metadata.original_frame_index =
196                Some(frame_metadata.original_frame_index.unwrap_or(source_index));
197            frame_metadata.original_illumination_index = frame_metadata
198                .original_illumination_index
199                .or(frame_metadata.illumination_index);
200            frame_metadata.frame_index = new_index;
201            frame_metadata.illumination_index = (!model.is_multiplexed()).then_some(new_index);
202            metadata.push(frame_metadata);
203        }
204        let mut measurements =
205            MeasurementStack::from_vec(data, (crop.height, crop.width), metadata)?;
206        if let Some(values) = crop_optional_shared(source.dark_frame_slice(), source_shape, crop)? {
207            measurements = measurements
208                .with_dark_frame(Array2::from_shape_vec((crop.height, crop.width), values)?)?;
209        }
210        if let Some(values) = crop_optional_shared(source.flat_field_slice(), source_shape, crop)? {
211            measurements = measurements
212                .with_flat_field(Array2::from_shape_vec((crop.height, crop.width), values)?)?;
213        }
214        if let Some(values) = crop_optional_frames(
215            source.background_slice(),
216            source_shape,
217            source.frame_count(),
218            &indices,
219            crop,
220        )? {
221            if values.len() == crop_len {
222                measurements = measurements
223                    .with_background(Array2::from_shape_vec((crop.height, crop.width), values)?)?;
224            } else {
225                measurements = measurements.with_per_frame_background(Array3::from_shape_vec(
226                    (indices.len(), crop.height, crop.width),
227                    values,
228                )?)?;
229            }
230        }
231        if let Some(values) = crop_optional_masks(
232            source.masks_slice(),
233            source_shape,
234            source.frame_count(),
235            &indices,
236            crop,
237        )? {
238            if values.len() == crop_len {
239                measurements = measurements
240                    .with_masks(Array2::from_shape_vec((crop.height, crop.width), values)?)?;
241            } else {
242                measurements = measurements.with_per_frame_masks(Array3::from_shape_vec(
243                    (indices.len(), crop.height, crop.width),
244                    values,
245                )?)?;
246            }
247        }
248        measurements = measurements.with_preprocessing(source.preprocessing().clone())?;
249
250        let scale_y = model.reconstruction_shape.0 as f64 / model.image_shape.0 as f64;
251        let scale_x = model.reconstruction_shape.1 as f64 / model.image_shape.1 as f64;
252        let reconstruction_shape = (
253            (crop.height as f64 * scale_y).round() as usize,
254            (crop.width as f64 * scale_x).round() as usize,
255        );
256        let object_crop = scaled_object_crop(crop, scale_y, scale_x)?;
257        let ground_truth_object = self
258            .dataset
259            .ground_truth_object()
260            .map(|truth| crop_array(truth, object_crop))
261            .transpose()?;
262        let valid_object_mask = self
263            .dataset
264            .valid_object_mask()
265            .map(|mask| crop_array(mask, object_crop))
266            .transpose()?;
267        let source_configuration = self.dataset.configuration();
268        let true_experiment = subset_experiment(
269            &source_configuration.true_experiment,
270            &source_configuration.compiled_models.true_model,
271            &indices,
272            crop,
273        )?;
274        let reconstruction_experiment = subset_experiment(
275            &source_configuration.reconstruction_experiment,
276            &source_configuration.compiled_models.reconstruction_model,
277            &indices,
278            crop,
279        )?;
280        let configuration = SimulationConfiguration::new(
281            true_experiment,
282            reconstruction_experiment,
283            (crop.height, crop.width),
284            ReconstructionShape::Exact(reconstruction_shape),
285        )?
286        .with_random_seed(source_configuration.random_seed);
287        Ok(DatasetSubset {
288            measurements,
289            configuration,
290            ground_truth_object,
291            valid_object_mask,
292            provenance: self.dataset.provenance().clone(),
293            measurement_units: self.dataset.measurement_units().map(str::to_owned),
294            spatial_crop: crop,
295        })
296    }
297}
298
299fn subset_experiment(
300    description: &ExperimentDescription,
301    model: &ImagePlaneModel,
302    indices: &[usize],
303    crop: Rect,
304) -> Result<ExperimentDescription> {
305    let (k_vectors, frame_weights) = match &model.multiplexing_matrix {
306        Some(matrix) => (
307            model.k_vectors.clone(),
308            Some(
309                indices
310                    .iter()
311                    .map(|&index| matrix[index].clone())
312                    .collect::<Vec<_>>(),
313            ),
314        ),
315        None => (
316            indices
317                .iter()
318                .map(|&index| model.k_vectors[index])
319                .collect(),
320            None,
321        ),
322    };
323    let frame_gains: Vec<f64> = model.frame_gains.as_ref().map_or_else(
324        || vec![1.0; indices.len()],
325        |gains| indices.iter().map(|&index| gains[index]).collect(),
326    );
327    let acquisition = crate::experiment::AcquisitionPlan::from_sparse(match frame_weights {
328        Some(rows) => rows
329            .into_iter()
330            .zip(frame_gains)
331            .map(|(row, gain)| {
332                crate::experiment::IlluminationFrame::new(
333                    row.into_iter()
334                        .map(|(source, intensity_weight)| {
335                            crate::experiment::SourceContribution::new(source, intensity_weight)
336                        })
337                        .collect(),
338                    gain,
339                )
340            })
341            .collect(),
342        None => (0..k_vectors.len())
343            .zip(frame_gains)
344            .map(|(source, gain)| {
345                crate::experiment::IlluminationFrame::new(
346                    vec![crate::experiment::SourceContribution::new(source, 1.0)],
347                    gain,
348                )
349            })
350            .collect(),
351    })?;
352    let illumination = Illumination::new(
353        crate::experiment::KVectorList::new(k_vectors).into(),
354        crate::experiment::SourceCalibration::unity(),
355        acquisition,
356    );
357    let mut subset = ExperimentDescription::new(description.optics.clone(), illumination);
358    subset.optical_background = crop_optional_frames(
359        model.background.as_deref(),
360        model.image_shape,
361        model.frame_count(),
362        indices,
363        crop,
364    )?;
365    subset.validate()?;
366    Ok(subset)
367}
368
369fn selected_indices(selector: &FrameSelector, frame_count: usize) -> Result<Vec<usize>> {
370    let indices = match selector {
371        FrameSelector::All => (0..frame_count).collect(),
372        FrameSelector::EveryNth(0) => {
373            return Err(Error::Dataset(
374                "frame subset step must be greater than zero".into(),
375            ));
376        }
377        FrameSelector::EveryNth(step) => (0..frame_count).step_by(*step).collect(),
378        FrameSelector::Indices(indices) => indices.clone(),
379    };
380    if indices.is_empty() {
381        return Err(Error::Dataset(
382            "dataset frame subset must contain at least one frame".into(),
383        ));
384    }
385    let mut seen = vec![false; frame_count];
386    for &index in &indices {
387        if index >= frame_count {
388            return Err(Error::FrameOutOfRange {
389                index,
390                frames: frame_count,
391            });
392        }
393        if seen[index] {
394            return Err(Error::Dataset(format!(
395                "dataset frame subset contains duplicate index {index}"
396            )));
397        }
398        seen[index] = true;
399    }
400    Ok(indices)
401}
402
403fn validate_crop(crop: Rect, shape: (usize, usize)) -> Result<()> {
404    if crop
405        .row
406        .checked_add(crop.height)
407        .is_none_or(|end| end > shape.0)
408        || crop
409            .column
410            .checked_add(crop.width)
411            .is_none_or(|end| end > shape.1)
412    {
413        return Err(Error::Dataset(format!(
414            "crop {crop:?} is outside measurement shape {shape:?}"
415        )));
416    }
417    Ok(())
418}
419
420fn crop_frame<T: Copy>(source: &[T], shape: (usize, usize), crop: Rect, output: &mut Vec<T>) {
421    for row in crop.row..crop.row + crop.height {
422        let start = row * shape.1 + crop.column;
423        output.extend_from_slice(&source[start..start + crop.width]);
424    }
425}
426
427fn scaled_object_crop(crop: Rect, scale_y: f64, scale_x: f64) -> Result<Rect> {
428    let values = [
429        crop.row as f64 * scale_y,
430        crop.column as f64 * scale_x,
431        crop.height as f64 * scale_y,
432        crop.width as f64 * scale_x,
433    ];
434    if values
435        .iter()
436        .any(|value| (value - value.round()).abs() > 1e-9)
437    {
438        return Err(Error::Dataset(
439            "measurement crop does not map to integer reconstruction pixels".into(),
440        ));
441    }
442    Rect::new(
443        values[0].round() as usize,
444        values[1].round() as usize,
445        values[2].round() as usize,
446        values[3].round() as usize,
447    )
448}
449
450fn crop_array<T: Copy>(source: &Array2<T>, crop: Rect) -> Result<Array2<T>> {
451    validate_crop(crop, source.dim())?;
452    let mut output = Vec::with_capacity(checked_len_2d((crop.height, crop.width))?);
453    for row in crop.row..crop.row + crop.height {
454        for column in crop.column..crop.column + crop.width {
455            output.push(source[(row, column)]);
456        }
457    }
458    Ok(Array2::from_shape_vec((crop.height, crop.width), output)?)
459}
460
461fn crop_optional_shared(
462    source: Option<&[f64]>,
463    shape: (usize, usize),
464    crop: Rect,
465) -> Result<Option<Vec<f64>>> {
466    source
467        .map(|source| {
468            let mut output = Vec::with_capacity(checked_len_2d((crop.height, crop.width))?);
469            crop_frame(source, shape, crop, &mut output);
470            Ok(output)
471        })
472        .transpose()
473}
474
475fn crop_optional_frames(
476    source: Option<&[f64]>,
477    shape: (usize, usize),
478    frame_count: usize,
479    indices: &[usize],
480    crop: Rect,
481) -> Result<Option<Vec<f64>>> {
482    let Some(source) = source else {
483        return Ok(None);
484    };
485    let frame_len = checked_len_2d(shape)?;
486    if source.len() == frame_len {
487        return crop_optional_shared(Some(source), shape, crop);
488    }
489    let stack_len = frame_len
490        .checked_mul(frame_count)
491        .ok_or_else(|| Error::ShapeOverflow {
492            shape: vec![frame_count, shape.0, shape.1],
493        })?;
494    if source.len() != stack_len {
495        return Err(Error::InvalidMeasurements(
496            "source background length is inconsistent".into(),
497        ));
498    }
499    let output_len = checked_len_2d((crop.height, crop.width))?
500        .checked_mul(indices.len())
501        .ok_or_else(|| Error::ShapeOverflow {
502            shape: vec![indices.len(), crop.height, crop.width],
503        })?;
504    let mut output = Vec::with_capacity(output_len);
505    for &index in indices {
506        let start = index
507            .checked_mul(frame_len)
508            .ok_or_else(|| Error::ShapeOverflow {
509                shape: vec![index, shape.0, shape.1],
510            })?;
511        let end = start
512            .checked_add(frame_len)
513            .ok_or_else(|| Error::ShapeOverflow {
514                shape: vec![index.saturating_add(1), shape.0, shape.1],
515            })?;
516        crop_frame(
517            source.get(start..end).ok_or_else(|| {
518                Error::InvalidMeasurements("source background frame is out of range".into())
519            })?,
520            shape,
521            crop,
522            &mut output,
523        );
524    }
525    Ok(Some(output))
526}
527
528fn crop_optional_masks(
529    source: Option<&[u8]>,
530    shape: (usize, usize),
531    frame_count: usize,
532    indices: &[usize],
533    crop: Rect,
534) -> Result<Option<Vec<u8>>> {
535    let Some(source) = source else {
536        return Ok(None);
537    };
538    let frame_len = checked_len_2d(shape)?;
539    if source.len() == frame_len {
540        let mut output = Vec::with_capacity(checked_len_2d((crop.height, crop.width))?);
541        crop_frame(source, shape, crop, &mut output);
542        return Ok(Some(output));
543    }
544    let stack_len = frame_len
545        .checked_mul(frame_count)
546        .ok_or_else(|| Error::ShapeOverflow {
547            shape: vec![frame_count, shape.0, shape.1],
548        })?;
549    if source.len() != stack_len {
550        return Err(Error::InvalidMeasurements(
551            "source mask length is inconsistent".into(),
552        ));
553    }
554    let output_len = checked_len_2d((crop.height, crop.width))?
555        .checked_mul(indices.len())
556        .ok_or_else(|| Error::ShapeOverflow {
557            shape: vec![indices.len(), crop.height, crop.width],
558        })?;
559    let mut output = Vec::with_capacity(output_len);
560    for &index in indices {
561        let start = index
562            .checked_mul(frame_len)
563            .ok_or_else(|| Error::ShapeOverflow {
564                shape: vec![index, shape.0, shape.1],
565            })?;
566        let end = start
567            .checked_add(frame_len)
568            .ok_or_else(|| Error::ShapeOverflow {
569                shape: vec![index.saturating_add(1), shape.0, shape.1],
570            })?;
571        crop_frame(
572            source.get(start..end).ok_or_else(|| {
573                Error::InvalidMeasurements("source mask frame is out of range".into())
574            })?,
575            shape,
576            crop,
577            &mut output,
578        );
579    }
580    Ok(Some(output))
581}