scico.examples

Utility functions used by example scripts.

Functions

create_3d_foam_phantom(im_shape, N_sphere[, ...])	Construct a 3D phantom with random radii and centers.
create_block_phantom(out_shape)	Construct a blocky 3D phantom.
create_circular_phantom(shape, radius_list, ...)	Construct a circular phantom with given radii and intensities.
create_cone(shape[, center])	Compute a map of distances from a center pixel.
create_conv_sparse_phantom(Nx, Nnz)	Construct a disc dictionary and sparse coefficient maps.
create_tangle_phantom(nx, ny, nz)	Construct a 3D phantom using the tangle function.
downsample_volume(vol, rate)	Downsample a 3D array.
epfl_deconv_data(channel[, verbose, cache_path])	Get deconvolution problem data from EPFL Biomedical Imaging Group.
gaussian(shape[, sigma])	Construct a multivariate Gaussian distribution function.
get_epfl_deconv_data(channel, path[, verbose])	Download example data from EPFL Biomedical Imaging Group.
get_ucb_diffusercam_data(path[, verbose])	Download data from UC Berkeley Waller Lab diffusercam project.
phase_diff(x, y)	Distance between phase angles.
rgb2gray(rgb)	Convert an RGB image (or images) to grayscale.
spnoise(img, nfrac[, nmin, nmax])	Return image with salt & pepper noise imposed on it.
tile_volume_slices(x[, sep_width])	Make an image with tiled slices from an input volume.
ucb_diffusercam_data([verbose, cache_path])	Get example data from UC Berkeley Waller Lab diffusercam project.
volume_read(path[, ext])	Read a 3D volume from a set of files in the specified directory.

scico.examples.rgb2gray(rgb)

Convert an RGB image (or images) to grayscale.

Parameters:

rgb (ndarray) – RGB image as Nr x Nc x 3 or Nr x Nc x 3 x K array.

Return type:

ndarray

Returns:

Grayscale image as Nr x Nc or Nr x Nc x K array.

scico.examples.volume_read(path, ext='tif')

Read a 3D volume from a set of files in the specified directory.

All files with extension ext (i.e. matching glob *.ext) in directory path are assumed to be image files and are read. The filenames are assumed to be such that their alphanumeric ordering corresponds to their order as volume slices.

Parameters:

• path (str) – Path to directory containing the image files.

• ext (str) – Filename extension.

Return type:

ndarray

Returns:

Volume as a 3D array.

scico.examples.get_epfl_deconv_data(channel, path, verbose=False)

Download example data from EPFL Biomedical Imaging Group.

Download deconvolution problem data from EPFL Biomedical Imaging Group. The downloaded data is converted to .npz format for convenient access via numpy.load. The converted data is saved in a file epfl_big_deconv_<channel>.npz in the directory specified by path.

Parameters:

• channel (int) – Channel number between 0 and 2.

• path (str) – Directory in which converted data is saved.

• verbose (bool) – Flag indicating whether to print status messages.

scico.examples.epfl_deconv_data(channel, verbose=False, cache_path=None)

Get deconvolution problem data from EPFL Biomedical Imaging Group.

If the data has previously been downloaded, it will be retrieved from a local cache.

Parameters:

• channel (int) – Channel number between 0 and 2.

• verbose (bool) – Flag indicating whether to print status messages.

• cache_path (Optional[str]) – Directory in which downloaded data is cached. The default is ~/.cache/scico/examples, where ~ represents the user home directory.

Return type:

Tuple[ndarray, ndarray]

Returns:

tuple –

A tuple (y, psf) containing:

• y : (np.ndarray): Blurred channel data.

• psf : (np.ndarray): Channel psf.

scico.examples.get_ucb_diffusercam_data(path, verbose=False)

Download data from UC Berkeley Waller Lab diffusercam project.

Download deconvolution problem data from UC Berkeley Waller Lab diffusercam project. The downloaded data is converted to .npz format for convenient access via numpy.load. The converted data is saved in a file ucb_diffcam_data.npz.npz in the directory specified by path.

Parameters:

• path (str) – Directory in which converted data is saved.

• verbose (bool) – Flag indicating whether to print status messages.

scico.examples.ucb_diffusercam_data(verbose=False, cache_path=None)

Get example data from UC Berkeley Waller Lab diffusercam project.

If the data has previously been downloaded, it will be retrieved from a local cache.

Parameters:

• verbose (bool) – Flag indicating whether to print status messages.

• cache_path (Optional[str]) – Directory in which downloaded data is cached. The default is ~/.cache/scico/examples, where ~ represents the user home directory.

Return type:

Tuple[ndarray, ndarray]

Returns:

tuple –

A tuple (y, psf) containing:

• y : (np.ndarray): Measured image

• psf : (np.ndarray): Stack of psfs.

scico.examples.downsample_volume(vol, rate)

Downsample a 3D array.

Downsample a 3D array. If the volume dimensions can be divided by rate, this is achieved via averaging distinct rate x rate x rate block in vol. Otherwise it is achieved via a call to scipy.ndimage.zoom.

Parameters:

• vol (ndarray) – Input volume.

• rate (int) – Downsampling rate.

Return type:

ndarray

Returns:

Downsampled volume.

scico.examples.tile_volume_slices(x, sep_width=10)

Make an image with tiled slices from an input volume.

Make an image with tiled xy, xz, and yz slices from an input volume.

Parameters:

• x (ndarray) – Input volume consisting of a 3D or 4D array. If the input is 4D, the final axis represents a channel index.

• sep_width (int) – Number of pixels separating the slices in the output image.

Return type:

ndarray

Returns:

Image containing tiled slices.

scico.examples.gaussian(shape, sigma=None)

Construct a multivariate Gaussian distribution function.

Construct a zero-mean multivariate Gaussian distribution function

\[f(\mb{x}) = (2 \pi)^{-N/2} \, \det(\Sigma)^{-1/2} \, \exp \left( -\frac{\mb{x}^T \, \Sigma^{-1} \, \mb{x}}{2} \right) \;,\]

where \(\Sigma\) is the covariance matrix of the distribution.

Parameters:

• shape (Tuple[int, ...]) – Shape of output array.

• sigma (Optional[ndarray]) – Covariance matrix.

Return type:

ndarray

Returns:

Sampled function.

Raises:

ValueError – If the array sigma cannot be inverted.

scico.examples.create_cone(shape, center=None)

Compute a map of distances from a center pixel.

Parameters:

• shape (Tuple[int, ...]) – Shape of the array for which the distance map is to be computed.

• center (Optional[List[float]]) – Tuple of center coordinates. If None, it is set to the center of the array.

Return type:

ndarray

Returns:

An array containing a map of the distances.

scico.examples.create_circular_phantom(shape, radius_list, val_list, center=None)

Construct a circular phantom with given radii and intensities.

This functions supports both circular (shape is 2D) and spherical (shape is 3D) phantoms.

Parameters:

• shape (Tuple[int, ...]) – Shape of the phantom to be created.

• radius_list (list) – List of radii of the rings in the phantom.

• val_list (list) – List of intensity values of the rings in the phantom.

• center (Optional[list]) – Tuple of center coordinates. If None, it is set to the center of the array.

Return type:

ndarray

Returns:

The computed phantom.

scico.examples.create_3d_foam_phantom(im_shape, N_sphere, r_mean=0.1, r_std=0.001, pad=0.01, is_random=False)

Construct a 3D phantom with random radii and centers.

Parameters:

• im_shape (Tuple[int, ...]) – Shape of input image.

• N_sphere (int) – Number of spheres added.

• r_mean (float) – Mean radius of sphere (normalized to 1 along each axis). Default 0.1.

• r_std (float) – Standard deviation of radius of sphere (normalized to 1 along each axis). Default 0.001.

• pad (float) – Padding length (normalized to 1 along each axis). Default 0.01.

• is_random (bool) – Flag used to control randomness of phantom generation. If False, random seed is set to 1 in order to make the process deterministic. Default False.

Return type:

ndarray

Returns:

3D phantom of shape im_shape.

scico.examples.create_conv_sparse_phantom(Nx, Nnz)

Construct a disc dictionary and sparse coefficient maps.

Construct a disc dictionary and a corresponding set of sparse coefficient maps for testing convolutional sparse coding algorithms.

Parameters:

• Nx (int) – Size of coefficient maps (3 x Nx x Nx).

• Nnz (int) – Number of non-zero coefficients across all coefficient maps.

Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple consisting of a stack of 2D filters and the coefficient

map array.

scico.examples.create_tangle_phantom(nx, ny, nz)

Construct a 3D phantom using the tangle function.

Parameters:

• nx (int) – x-size of output.

• ny (int) – y-size of output.

• nz (int) – z-size of output.

Return type:

ndarray

Returns:

An array with shape (nz, ny, nx).

scico.examples.create_block_phantom(out_shape)

Construct a blocky 3D phantom.

Parameters:

out_shape (Tuple[int, ...]) – desired phantom shape.

Return type:

ndarray

Returns:

Phantom.

scico.examples.spnoise(img, nfrac, nmin=0.0, nmax=1.0)

Return image with salt & pepper noise imposed on it.

Parameters:

• img (Union[ndarray, Array]) – Input image.

• nfrac (float) – Desired fraction of pixels corrupted by noise.

• nmin (float) – Lower value for noise (pepper). Default 0.0.

• nmax (float) – Upper value for noise (salt). Default 1.0.

Return type:

Union[ndarray, Array]

Returns:

Noisy image

scico.examples.phase_diff(x, y)

Distance between phase angles.

Compute the distance between two arrays of phase angles, with appropriate phase wrapping to minimize the distance.

Parameters:

• x (Array) – Input array.

• y (Array) – Input array.

Return type:

Array

Returns:

Array of angular distances.