Utilities

Data loading

lensless.utils.io.get_ctypes(dtype, is_torch)[source]
lensless.utils.io.get_dtype(dtype=None, is_torch=False)[source]

Get dtype for numpy or torch.

Parameters

  • dtype (str, optional) – “float32” or “float64”, Default is “float32”.

  • is_torch (bool, optional) – Whether to return torch dtype.

lensless.utils.io.load_data(psf_fp, data_fp, background_fp=None, return_bg=False, remove_background=True, return_float=True, downsample=None, bg_pix=(5, 25), plot=True, flip=False, flip_ud=False, flip_lr=False, bayer=False, blue_gain=None, red_gain=None, gamma=None, gray=False, dtype=None, single_psf=False, shape=None, use_torch=False, torch_device='cpu', normalize=False, bgr_input=True)[source]

Load data for image reconstruction.

Parameters

  • psf_fp (str) – Full path to PSF file.

  • data_fp (str) – Full path to measurement file.

  • return_float (bool, optional) – Whether to return PSF as float array, or unsigned int.

  • downsample (int or float) – Downsampling factor.

  • bg_pix (tuple, optional) – Section of pixels to take from top left corner to remove background level. Set to None to omit this step, although it is highly recommended.

  • plot (bool, optional) – Whether or not to plot PSF and raw data.

  • flip (bool) – Whether to flip data (vertical and horizontal).

  • bayer (bool) – Whether input data is Bayer.

  • blue_gain (float) – Blue gain for color correction.

  • red_gain (float) – Red gain for color correction.

  • gamma (float, optional) – Optional gamma factor to apply, ONLY for plotting. Default is None.

  • gray (bool) – Whether to load as grayscale or RGB.

  • dtype (float32 or float64, default float32) – Data type of returned data.

  • single_psf (bool) – Whether to sum RGB channels into single PSF, same across channels. Done in “Learned reconstructions for practical mask-based lensless imaging” of Kristina Monakhova et. al.

  • normalize (bool default True) – Whether to normalize data to maximum value of 1.

Returns

  • psf (ndarray) – 2-D array of PSF.

  • data (ndarray) – 2-D array of raw measurement data.

lensless.utils.io.load_image(fp, verbose=False, flip=False, flip_ud=False, flip_lr=False, bayer=False, black_level=256.3, blue_gain=None, red_gain=None, ccm=array([[2.0659, - 0.93119, - 0.13421], [- 0.11615, 1.5593, - 0.44314], [0.073694, - 0.4368, 1.3636]]), back=None, nbits_out=None, as_4d=False, downsample=None, bg=None, return_float=False, shape=None, dtype=None, normalize=True, bgr_input=True)[source]

Load image as numpy array.

Parameters

  • fp (str) – Full path to file.

  • verbose (bool, optional) – Whether to plot into about file.

  • flip (bool) – Whether to flip data (vertical and horizontal).

  • bayer (bool) – Whether input data is Bayer.

  • blue_gain (float) – Blue gain for color correction.

  • red_gain (float) – Red gain for color correction.

  • black_level (float) – Black level. Default is to use that of Raspberry Pi HQ camera.

  • ccm (ndarray) – Color correction matrix. Default is to use that of Raspberry Pi HQ camera.

  • back (array_like) – Background level to subtract.

  • nbits_out (int) – Output bit depth. Default is to use that of input.

  • as_4d (bool) – Add depth and color dimensions if necessary so that image is 4D: (depth, height, width, color).

  • downsample (int, optional) – Downsampling factor. Recommended for image reconstruction.

  • bg (array_like) – Background level to subtract.

  • return_float (bool) – Whether to return image as float array, or unsigned int.

  • shape (tuple, optional) – Shape (H, W, C) to resize to.

  • dtype (str, optional) – Data type of returned data. Default is to use that of input.

  • normalize (bool, default True) – If return_float, whether to normalize data to maximum value of 1.

Returns

img – RGB image of dimension (height, width, 3).

Return type

ndarray

lensless.utils.io.load_psf(fp, downsample=1, return_float=True, bg_pix=(5, 25), return_bg=False, flip=False, flip_ud=False, flip_lr=False, verbose=False, bayer=False, blue_gain=None, red_gain=None, dtype=<class 'numpy.float32'>, nbits_out=None, single_psf=False, shape=None, use_3d=False, bgr_input=True, force_rgb=False)[source]

Load and process PSF for analysis or for reconstruction.

Basic steps are: * Load image. * (Optionally) subtract background. Recommended. * (Optionally) resize to more manageable size * (Optionally) normalize within [0, 1] if using for reconstruction; otherwise cast back to uint for analysis.

Parameters

  • fp (str) – Full path to file.

  • downsample (int, optional) – Downsampling factor. Recommended for image reconstruction.

  • return_float (bool, optional) – Whether to return PSF as float array, or unsigned int.

  • bg_pix (tuple, optional) – Section of pixels to take from top left corner to remove background level. Set to None to omit this step, althrough it is highly recommended.

  • return_bg (bool, optional) – Whether to return background level, for removing from data for reconstruction.

  • flip (bool, optional) – Whether to flip up-down and left-right.

  • verbose (bool) – Whether to print metadata.

  • bayer (bool) – Whether input data is Bayer.

  • blue_gain (float) – Blue gain for color correction.

  • red_gain (float) – Red gain for color correction.

  • dtype (float32 or float64) – Data type of returned data.

  • nbits_out (int) – Output bit depth. Default is to use that of input.

  • single_psf (bool) – Whether to sum RGB channels into single PSF, same across channels. Done in “Learned reconstructions for practical mask-based lensless imaging” of Kristina Monakhova et. al.

Returns

psf – 4-D array of PSF.

Return type

ndarray

lensless.utils.io.save_image(img, fp, max_val=255, normalize=True)[source]

Save as uint8 image.

Plotting

lensless.utils.plot.compare_models(model_paths, max_epoch=None, linewidth=2, fontsize=18, metrics=None)[source]

Plot train and test loss for multiple models, and print metrics for best epoch.

Parameters

  • model_paths (dict) – Dictionary of model names and their paths.

  • max_epoch (int, optional) – Maximum epoch to plot. Default is None.

  • linewidth (int, optional) – Line width for plot. Default is 2.

  • fontsize (int, optional) – Font size for plot. Default is 18.

  • metrics (list, optional) – List of metrics to print. Default is [“PSNR”, “SSIM”, “LPIPS_Vgg”].

lensless.utils.plot.pixel_histogram(img, nbits=None, ax=None, log_scale=True)[source]

Plot pixel value histogram.

Parameters

  • img (py:class:~numpy.ndarray) – 2D or 3D image.

  • nbits (int, optional) – Bit-depth of camera data.

  • ax (Axes, optional) – Axes object to fill, default is to create one.

  • log_scale (bool, optional) – Whether to use log scale in counting number of pixels.

Returns

ax – Axes on which histogram is plot.

Return type

Axes

lensless.utils.plot.plot_autocorr2d(vals, pad_mode='reflect', ax=None)[source]

Plot 2-D autocorrelation of image.

Parameters
Returns

  • ax (Axes) – Axes on which auto-correlation is plot.

  • autocorr (py:class:~numpy.ndarray) – Auto-correlation.

lensless.utils.plot.plot_autocorr_rgb(img, width=3, figsize=None, plot_psf=False, psf_gamma=2.2, verbose=False)[source]

Plot autocorrelation of each channel of an image.

Parameters

  • img (py:class:~numpy.ndarray) – 2-D image.

  • width (int, optional) – Width of cross-section to plot. Default is 3dB.

lensless.utils.plot.plot_cross_section(vals, idx=None, ax=None, dB=True, plot_db_drop=3, min_val=0.0001, max_val=None, plot_width=None, **kwargs)[source]

Plot cross-section of a 2-D image.

Parameters

  • vals (py:class:~numpy.ndarray) – 2-D image data.

  • idx (int, optional) – Row for which to plot cross-section. Default is to take middle.

  • ax (Axes, optional) – Axes object to fill, default is to create one.

  • dB (bool, optional) – Whether to plot in dB scale.

Returns

ax – Axes on which cross-section is plot.

Return type

Axes

lensless.utils.plot.plot_image(img, ax=None, gamma=None, normalize=True)[source]

Plot image data.

Parameters

  • img (ndarray) – Data to plot.

  • ax (Axes, optional) – Axes object to fill for plotting/saving, default is to create one.

  • gamma (float, optional) – Gamma correction factor to apply for plots. Default is None.

  • normalize (bool, optional) – Whether to normalize data to maximum range. Default is True.

Returns

ax – Axes on which image is plot.

Return type

Axes

Image processing

lensless.utils.image.resize(img, factor=None, shape=None, interpolation=<Mock name='mock.INTER_CUBIC' id='128698081583008'>)[source]

Resize by given factor.

Parameters
Returns

img – Resized image.

Return type

ndarray

lensless.utils.image.bayer2rgb(X_bayer, pattern)[source]

Converting 4-channel Bayer image to RGB by averaging the two green channels.

Parameters

  • X_bayer (ndarray) – Image in RGB format.

  • pattern (str) – Bayer pattern: RGGB, BGGR, GRBG, GBRG.

Returns

Image converted to the RGB format.

Return type

ndarray

lensless.utils.image.rgb2gray(rgb, weights=None, keepchanneldim=True)[source]

Convert RGB array to grayscale.

Parameters

  • rgb (ndarray or Tensor) – ([Depth,] Height, Width, Channel) image.

  • weights (ndarray) – [Optional] (3,) weights to convert from RGB to grayscale. Only used for NumPy arrays.

  • keepchanneldim (bool) – Whether to keep the channel dimension. Default is True.

Returns

Grayscale image of dimension ([depth,] height, width [, 1]).

Return type

img ndarray

lensless.utils.image.gamma_correction(vals, gamma=2.2)[source]

Apply gamma correction.

Parameters

  • vals (ndarray) – RGB values to gamma correct.

  • gamma (float, optional) – Gamma correction factor.

Returns

vals – Gamma-corrected data.

Return type

ndarray

Image analysis

lensless.utils.image.autocorr2d(vals, pad_mode='reflect')[source]

Compute 2-D autocorrelation of image via the FFT.

Parameters
Returns

autocorr

Return type

ndarray

lensless.utils.image.print_image_info(img)[source]

Print dimensions, data type, max, min, mean.