corrct.struct_illum
Provide structured illumination support.
Created on Sun Jan 9 17:39:02 2022
@author: Nicola VIGANÒ, Computational Imaging group, CWI, The Netherlands, and ESRF - The European Synchrotron, Grenoble, France
Module Contents
Classes
Define mask collection class. |
|
Define mask generation interface. |
|
Pencil beam masks generator class. |
|
Bernoulli mask generator class. |
|
Half-Gaussian mask generator class. |
|
MURA mask generator class. |
|
Projector class for the ghost imaging reconstructions. |
Functions
Reorder masks, with a simple rot-n algorithm. |
|
Compute QR decomposition of the given masks. |
|
Estimate the mask collection resolution through auto-correlation. |
Data
API
- corrct.struct_illum.NDArrayInt
None
- corrct.struct_illum.reorder_masks(masks: numpy.typing.NDArray, buckets: numpy.typing.NDArray, shift: int) tuple[numpy.typing.NDArray, numpy.typing.NDArray][source]
Reorder masks, with a simple rot-n algorithm.
Parameters
masks : NDArray The masks to re-order. buckets : NDArray The corresponding buckets. shift : int The length of the shift.
Returns
Tuple[NDArray, NDArray] The reordered masks and buckets.
- corrct.struct_illum.decompose_qr_masks(masks: numpy.typing.NDArray, verbose: bool = False) tuple[numpy.typing.NDArray, numpy.typing.NDArray][source]
Compute QR decomposition of the given masks.
Parameters
masks : NDArray The masks to decompose verbose : bool, optional Whether to emite verbose output, by default False
Returns
Tuple[NDArray, NDArray] The Q and R components.
- corrct.struct_illum.estimate_resolution(masks: numpy.typing.NDArray, verbose: bool = True, plot_result: bool = True) tuple[float, float][source]
Estimate the mask collection resolution through auto-correlation.
Parameters
masks : NDArray The list of encoding masks verbose : bool, optional Whether to produce verbose output, by default True plot_result : bool, optional Whether to plot the results, by default True
Returns
tuple[float, float] The mean and minimum HWHM of the auto-correlation functions for all the masks.
- class corrct.struct_illum.MaskCollection(masks_enc: numpy.typing.NDArray, masks_dec: Union[numpy.typing.NDArray, None] = None, mask_dims: int = 2, mask_type: str = 'measured', mask_support: Union[None, collections.abc.Sequence[int], corrct.struct_illum.NDArrayInt] = None)[source]
Define mask collection class.
Initialization
Initialize mask collection.
Parameters
masks_enc : NDArray The encoding masks. masks_dec : NDArray | None, optional The decoding masks. The default (None) will assume them identical to the encoding masks. mask_dims : int, optional The dimensions of a single mask. The default is 2. mask_type : str, optional The type of masks. The default is “measured”. mask_support : Sequence[int] | NDArray[np.integer] | None, optional The extent of the mask support in pixels. The default (None) will consider it equal to the FoV.
- masks_enc: numpy.typing.NDArray
None
- masks_dec: numpy.typing.NDArray
None
- mask_dims: int
None
- mask_support: corrct.struct_illum.NDArrayInt
None
- mask_type: str
None
- property shape_fov: collections.abc.Sequence[int]
Return the mask shape.
Returns
Sequence[int] The mask shape.
- property shape_shifts: collections.abc.Sequence[int]
Compute the shape of the available shifts.
Returns
Sequence[int] The shape of the available shifts.
- property num_buckets: int
Compute the total number of available buckets.
Returns
int The total number of buckets.
- property num_pixels: int
Compute the number of pixels in the image.
Returns
int The number of pixels in the image.
- upper() str[source]
Return the upper case name of the mask.
Returns
str Upper case string name of the mask.
- lower() str[source]
Return the lower case name of the mask.
Returns
str Lower case string name of the mask.
- get_mask(mask_inds_vu: Union[collections.abc.Sequence, numpy.typing.NDArray], mask_encoding: bool = True) numpy.typing.NDArray[source]
Return the requested mask.
Parameters
mask_inds_vu : Union[Sequence, NDArray] The mask position. mask_encoding : bool, optional Whether it is an encoding or decoding mask, by default True
Returns
NDArray The requested mask.
- get_QR_decomposition(buckets: numpy.typing.NDArray, shift: int = 0) tuple[corrct.struct_illum.MaskCollection, numpy.typing.NDArray][source]
Compute and return the QR decomposition of the masks.
Parameters
buckets : NDArray The buckets corresponding to the masks. shift : int, optional Index of the first mask, by default 0.
Returns
Tuple[MaskCollection, NDArray] The new mask collection and the matrix for modifying buckets accordingly.
Raises
ValueError In case the masks have encoding-decoding form.
- bin_masks(binning: float) corrct.struct_illum.MaskCollection[source]
Bin the masks.
Parameters
binning : float The binning size.
Returns
MaskCollection A new collection of binned masks.
- inspect_masks(mask_inds_vu: Union[None, collections.abc.Sequence[int], corrct.struct_illum.NDArrayInt] = None)[source]
Inspect the encoding and decoding masks at the requested shifts.
Parameters
mask_inds_vu : Sequence[int] | NDArray[np.integer] | None, optional The requested axes shifts. The default (None) is the first mask.
- class corrct.struct_illum.MaskGenerator(shape_fov: Union[collections.abc.Sequence[int], corrct.struct_illum.NDArrayInt], shape_mask: Union[collections.abc.Sequence[int], corrct.struct_illum.NDArrayInt], shape_shifts: Union[collections.abc.Sequence[int], corrct.struct_illum.NDArrayInt], transmittance: float = 1.0, dtype: numpy.typing.DTypeLike = np.float32)[source]
Bases:
abc.ABCDefine mask generation interface.
Initialization
Initialize mask collection.
Parameters
shape_fov : Sequence[int] | NDArray[np.integer] The shape of the field-of-view. shape_mask : Sequence[int] | NDArray[np.integer] The shape of the masks. shape_shifts : Sequence[int] | NDArray[np.integer] The shape of the shifts to generate. transmittance : float The maximum transmittance of the structuring elements. dtype : DTypeLike The dtype of the created masks.
- shape_fov: corrct.struct_illum.NDArrayInt
None
- shape_mask: corrct.struct_illum.NDArrayInt
None
- shape_shifts: corrct.struct_illum.NDArrayInt
None
- transmittance: float
None
- dtype: numpy.typing.DTypeLike
None
- _enc_dec_mismatch: bool
None
- __mask_name__
‘generated’
- __repr__() str[source]
Produce the string representation of the object.
Returns
str The string representation.
- property max_buckets: int
Compute the maximum number of buckets.
Returns
int The maximum number of buckets.
- property num_pixels: int
Compute the number of pixels in the image.
Returns
int The number of pixels in the image.
- _init_fov_mm(fov_size_mm: Union[float, collections.abc.Sequence[float], numpy.typing.NDArray], req_res_mm: float) corrct.struct_illum.NDArrayInt[source]
- generate_collection(buckets_fraction: float = 1, shift_type: str = 'sequential') corrct.struct_illum.MaskCollection[source]
Generate the mask collection.
Parameters
buckets_fraction : float, optional The fraction of buckets to generate, by default 1 shift_type : str, optional The type of shift to implement, by default “sequential” abs_fraction : float, optional The attenuation fraction of the pixels
Returns
MaskCollection The generated mask collection.
Raises
ValueError In case of wrong shift type.
- abstract generate_shifted_mask(mask_inds_vu: Union[collections.abc.Sequence, numpy.typing.NDArray], mask_encoding: bool = True) numpy.typing.NDArray[source]
Produce the shifted masks.
Parameters
mask_inds_vu : tuple | list | NDArray The vertical and horizontal shifts. mask_encoding : bool, optional Is the mask encoding (False = decoding). The default is True.
Returns
NDArray The shifted mask.
- _generate_mask_shifts(shifts_v: Union[collections.abc.Sequence, numpy.typing.NDArray], shifts_u: Union[collections.abc.Sequence, numpy.typing.NDArray], mask_encoding: bool = True) numpy.typing.NDArray[source]
Produce all the masks.
Parameters
shifts_v : tuple | list | NDArray List of all the vertical shifts. shifts_u : tuple | list | NDArray List of all the horizontal shifts. mask_encoding : bool, optional Are the masks encoding (False = decoding). The default is True. abs_fraction : float, optional Absorption fraction of the mask elements. The default is 1.
Returns
NDArray The collection of all the shifted masks.
- get_interval_shifts(interval: Union[int, collections.abc.Sequence[int], numpy.typing.NDArray], axes_order: collections.abc.Sequence[int] = (-2, -1)) collections.abc.Sequence[numpy.typing.NDArray][source]
Produce shifts for the “interval” shift type.
Parameters
interval : int | tuple(int, int) | list(int, int) The shift interval. axes_order : int | tuple | list, optional Order of the axes to shift. The default is (-2, -1).
Returns
tuple The collection of shifts.
- get_random_shifts(num_shifts: int, axes_order: collections.abc.Sequence[int] = (-2, -1)) collections.abc.Sequence[numpy.typing.NDArray][source]
Produce shifts for the “random” shift type.
Parameters
num_shifts : int Number of shifts.
Returns
NDArray The collection of shifts.
- get_sequential_shifts(num_shifts: Union[int, None] = None, axes_order: collections.abc.Sequence[int] = (-2, -1)) collections.abc.Sequence[numpy.typing.NDArray][source]
Produce shifts for the “sequential” shift type.
Parameters
num_shifts : int, optional Number of shifts. The default is None. axes_order : tuple | list | NDArray, optional Order of the axes to shift. The default is (-2, -1).
Returns
NDArray The collection of shifts.
- class corrct.struct_illum.MaskGeneratorPoint(fov_size_mm: Union[float, collections.abc.Sequence[float], numpy.typing.NDArray], req_res_mm: float = 1.0)[source]
Bases:
corrct.struct_illum.MaskGeneratorPencil beam masks generator class.
Initialization
Initialize the pencil beam mask collection.
Parameters
fov_size_mm : float Size of the Field-of-View in millimiters. req_res_mm : float Requested resolution in millimiters.
- __mask_name__
‘pencil’
- generate_shifted_mask(mask_inds_vu: Union[collections.abc.Sequence, numpy.typing.NDArray], mask_encoding: bool = True) numpy.typing.NDArray[source]
Produce the shifted masks.
Parameters
mask_inds_vu : tuple | list | NDArray The vertical and horizontal shifts. mask_encoding : bool, optional Is the mask encoding (False = decoding). The default is True.
Returns
NDArray The shifted mask.
- class corrct.struct_illum.MaskGeneratorBernoulli(fov_size_mm: Union[float, collections.abc.Sequence[float], numpy.typing.NDArray], req_res_mm: float = 1.0, max_masks_ratio: float = 1.2)[source]
Bases:
corrct.struct_illum.MaskGeneratorBernoulli mask generator class.
Initialization
Bernulli masks collection class.
It computes and stores the original mask pattern for a given resolution and Field-ofView.
Parameters
fov_size_mm : float Size of the Field-of-View in mm. req_res_mm : float The required pixel size in mm. max_masks_ratio : float The ratio of maximum available masks per pixels in each direction, by default 1.2.
- __mask_name__
‘bernoulli’
- generate_shifted_mask(mask_inds_vu: Union[collections.abc.Sequence, numpy.typing.NDArray], mask_encoding: bool = True) numpy.typing.NDArray[source]
Produce the shifted masks.
Parameters
mask_inds_vu : tuple | list | NDArray The vertical and horizontal shifts. mask_encoding : bool, optional Is the mask encoding (False = decoding). The default is True.
Returns
NDArray The shifted mask.
- class corrct.struct_illum.MaskGeneratorHalfGaussian(fov_size_mm: Union[float, collections.abc.Sequence[float], numpy.typing.NDArray], req_res_mm: float = 1.0, max_masks_ratio: float = 1.2)[source]
Bases:
corrct.struct_illum.MaskGeneratorHalf-Gaussian mask generator class.
Initialization
Half Gaussian masks collection class.
It computes and stores the original mask pattern for a given resolution and Field-ofView.
Parameters
fov_size_mm : float Size of the Field-of-View in mm. req_res_mm : float The required pixel size in mm. max_masks_ratio : float The ratio of maximum available masks per pixels in each direction, by default 1.2.
- __mask_name__
‘half-gaussian’
- generate_shifted_mask(mask_inds_vu: Union[collections.abc.Sequence, numpy.typing.NDArray], mask_encoding: bool = True) numpy.typing.NDArray[source]
Produce the shifted masks.
Parameters
mask_inds_vu : tuple | list | NDArray The vertical and horizontal shifts. mask_encoding : bool, optional Is the mask encoding (False = decoding). The default is True.
Returns
NDArray The shifted mask.
- class corrct.struct_illum.MaskGeneratorMURA(fov_size_mm: float, req_res_mm: float = 1.0)[source]
Bases:
corrct.struct_illum.MaskGeneratorMURA mask generator class.
Initialization
MURA masks collection class.
Parameters
fov_size_mm : float Size of the Field-of-View in mm. req_res_mm : float The required pixel size in mm.
- __mask_name__
‘mura’
- generate_shifted_mask(mask_inds_vu: Union[collections.abc.Sequence, numpy.typing.NDArray], mask_encoding: bool = True) numpy.typing.NDArray[source]
Produce the shifted masks.
Parameters
mask_inds_vu : tuple | list | NDArray The vertical and horizontal shifts. mask_encoding : bool, optional Is the mask encoding (False = decoding). The default is True.
Returns
NDArray The shifted mask.
- static compute_possible_mask_sizes(fov_size: int) numpy.typing.NDArray[source]
Compute MURA masks sizes.
MURA masks require specific edge sizes: prime numbers x that also satisfy the rule: x = 4 * l + 1, where l is integer.
Parameters
fov_size : int Edge size of the fov in pixels.
Returns
NDArray Array of all possible MURA mask sizes in that range.
- class corrct.struct_illum.ProjectorGhostImaging(mask_collection: Union[corrct.struct_illum.MaskCollection, numpy.typing.NDArray], backend: str = 'torch')[source]
Bases:
corrct.operators.ProjectorOperatorProjector class for the ghost imaging reconstructions.
Initialization
Initialize the Ghost Imaging projector class.
Parameters
mask_collection : MaskCollection Container of the masks.
- mc: corrct.struct_illum.MaskCollection
None
- fp(image: numpy.typing.NDArray) numpy.typing.NDArray[source]
Compute forward-projection (prediction) of the bucket values.
Parameters
image : NDArray The image for which we want to predict the bucket values.
Returns
NDArray The predicted bucket values.
- bp(bucket_vals: numpy.typing.NDArray) numpy.typing.NDArray[source]
Compute back-projection of the bucket values.
Parameters
bucket_vals : NDArray The list of bucket values. subtract_mean : bool, optional Whether to subtract the mean of the values. The default is False.
Returns
NDArray Back-projected image.
- adjust_sampling_scaling(image: numpy.typing.NDArray) numpy.typing.NDArray[source]
Adjust reconstruction scaling and bias, due to the undersampling.
Parameters
image : NDArray Unscaled image.
Returns
NDArray Scaled image.
- fbp(bucket_vals: numpy.typing.NDArray, use_lstsq: bool = True, adjust_scaling: bool = False) numpy.typing.NDArray[source]
Compute cross-correlation reconstruction of the bucket values.
Parameters
bucket_vals : NDArray The bucket vales to reconstruct. use_lstsq : bool, optional If True, uses least squares for reconstruction, by default True. adjust_scaling : bool, optional If True, adjusts scaling of the reconstructed image, to account for the intensity loss, by default False.
Returns
NDArray The reconstructed image.