holopy.core.process package¶

Routines for image processing. Useful for pre-processing raw holograms prior to extracting final data or post-processing reconstructions.

Submodules¶

The centerfinder module is a group of functions for locating the centers of holographic ring patterns. The module can find the center of a single-sphere holographic pattern, a dimer holographic pattern, or the centers of multiple (well-separated: clearly separate ring patterns with separate centers) single spheres or dimers. The intended use is for determining an initial parameter guess for hologram fitting.

We thank the Grier Group at NYU for suggesting the use of the Hough transform. For their independent implementation of a Hough-based holographic feature detection algorithm, see: http://physics.nyu.edu/grierlab/software/circletransform.pro For a case study and further reading, see: F. C. Cheong, B. Sun, R. Dreyfus, J. Amato-Grill, K. Xiao, L. Dixon & D. G. Grier, Flow visualization and flow cytometry with holographic video microscopy, Optics Express 17, 13071-13079 (2009).

center_find(image, centers=1, threshold=0.5, blursize=3.0)¶

Finds the coordinates of the center of a holographic pattern. The coordinates returned are in pixels (row number, column number). Intended for finding the center of single particle or dimer holograms which basically show concentric circles. The optional threshold parameter (between 0 and 1) gives a bound on what magnitude of gradients to include in the calculation. For example, threshold=.75 means ignore any gradients that are less than 75% of the maximum gradient in the image. The optional blursize parameter sets the size of a Gaussian filter that is applied to the image. This step improves accuracy when small features in the image have large gradients (e.g. dust particles on the camera). Without blurring, these features may be incorrectly identified as the hologram center. For best results, blursize should be set to the radius of features to be ignored, but smaller than the distance between hologram fringes. To skip blurring, set blursize to 0.

Parameters:	image (ndarray) – image to find the center(s) in centers (int) – number of centers to find threshold (float (optional)) – fraction of the maximum gradient below which all other gradients will be ignored (range 0-.99) blursize (float (optional)) – radius (in pixels) of the Gaussian filter that is applied prior to Hough transform
Returns:	res – row(s) and column(s) of center(s)
Return type:	ndarray

Notes

When threshold is close to 1, the code will run quickly but may lack accuracy. When threshold is set to 0, the gradient at all pixels will contribute to finding the centers and the code will take a little bit longer.

hough(col_deriv, row_deriv, centers=1, threshold=0.25)¶

Following the approach of a Hough transform, finds the pixel which the most gradients point towards or away from. Uses only gradients with magnitudes greater than threshold*maximum gradient. Once the pixel is found, uses a brightness-weighted average around that pixel to refine the center location to return. After the first center is found, the sourrounding area is blocked out and another brightest pixel is searched for if more centers are required.

Parameters:	col_deriv (numpy.ndarray) – y-component of image intensity gradient row_deriv (numpy.ndarray) – x-component of image intensity gradient centers (int) – number of centers to find threshold (float (optional)) – fraction of the maximum gradient below which all other gradients will be ignored (range 0-.99)
Returns:	res – row and column of center or centers
Return type:	ndarray

image_gradient(image)¶

Uses the Sobel operator as a numerical approximation of a derivative to find the x and y components of the image’s intensity gradient at each pixel.

Parameters:	image (ndarray) – image to find the gradient of
Returns:	gradx (ndarray) – x-components of intensity gradient grady (ndarray) – y-components of intensity gradient

Handles Fourier transforms of HoloPy images by using numpy’s fft package. Tries to correctly interpret dimensions from xarray.

fft(data, shift=True)¶

More convenient Fast Fourier Transform

An easier to use fft function, it will pick the correct fft to do based on the shape of the array, and do the fftshift for you. This is intended for working with images, and thus for dimensions greater than 2 does slicewise transforms of each “image” in a multidimensional stack

Parameters:	data (ndarray or xarray) – The array to transform shift (bool) – Whether to preform an fftshift on the array to give low frequences near the center as you probably expect. Default is to do the fftshift.
Returns:	fta – The fourier transform of a
Return type:	ndarray

ft_coord(c)¶

ft_coords(cs)¶

get_spacing(c)¶

ifft(data, shift=True)¶

More convenient Inverse Fast Fourier Transform

An easier to use ifft function, it will pick the correct ifft to do based on the shape of the array, and do the fftshift for you. This is intended for working with images, and thus for dimensions greater than 2 does slicewise transforms of each “image” in a multidimensional stack

Parameters:	data (ndarray or xarray) – The array to transform shift (bool) – Whether to preform an fftshift on the array to give low frequences near the center as you probably expect. Default is to do the fftshift.
Returns:	The inverse fourier transform of data
Return type:	ndarray

ift_coord(c)¶

ift_coords(cs)¶

transform_metadata(a, inverse)¶

Image enhancement through background subtraction, contrast adjustment, or detrending

add_noise(image, noise_mean=0.1, smoothing=0.01, poisson_lambda=1000)¶

Add simulated noise to images. Intended for use with exact calculated images to make them look more like noisy ‘real’ measurements.

Real image noise usually has correlation, so we smooth the raw random variable. The noise_mean can be controlled independently of the poisson_lambda that controls the shape of the distribution. In general, you can stick with our default of a large poisson_lambda (ie for imaging conditions not near the shot noise limit).

Defaults are set to give noise vaguely similar to what we tend to see in our holographic imaging.

Parameters:	image (xarray.DataArray) – The image to add noise to. smoothing (float) – Fraction of the image size to smooth by. Should in general be << 1 poisson_lambda (float) – Used to compute the shape of the noise distribution. You can generally leave this at its default value unless you are simulating shot noise limited imaging.
Returns:	noisy_image – A copy of the input image with noise added.
Return type:	xarray.DataArray

bg_correct(raw, bg, df=None)¶

Correct for noisy images by dividing by a background. The calculation used is (raw-df)/(bg-df).

Parameters:	raw (xarray.DataArray) – Image to be background divided. bg (xarray.DataArray) – background image recorded with the same optical setup. df (xarray.DataArray) – dark field image recorded without illumination.
Returns:	corrected_image – A copy of the background divided input image with None values of noise_sd updated to match bg.
Return type:	xarray.DataArray

detrend(image)¶

Remove linear trends from an image.

Performs a 2 axis linear detrend using scipy.signal.detrend

Parameters:	image (xarray.DataArray) – Image to process
Returns:	image – Image with linear trends removed
Return type:	xarray.DataArray

normalize(image)¶

Normalize an image by dividing by the pixel average. This gives the image a mean value of 1.

Parameters:	image (xarray.DataArray) – The array to normalize
Returns:	normalized_image – The normalized image
Return type:	xarray.DataArray

simulate_noise(shape, mean=0.1, smoothing=0.01, poisson_lambda=1000)¶

Create an array of correlated noise. The noise_mean can be controlled independently of the poisson_lambda that controls the shape of the distribution. In general, you can stick with our default of a large poisson_lambda (ie for imaging conditions not near the shot noise limit).

Defaults are set to give noise vaguely similar to what we tend to see in our holographic imaging.

Parameters:	shape (int or array_like of ints) – shape of noise array smoothing (float) – Fraction of the image size to smooth by. Should in general be << 1 poisson_lambda (float) – Used to compute the shape of the noise distribution. You can generally leave this at its default value unless you are simulating shot noise limited imaging.
Returns:	noisy_image – A copy of the input image with noise added.
Return type:	ndarray

subimage(arr, center, shape)¶

Pick out a region of an image or other array

Parameters:	arr (xarray.DataArray) – The array to subimage center (tuple of ints or floats) – The desired center of the region, should have the same number of elements as the arr has dimensions. Floats will be rounded shape (int or (int, int)) – Desired shape of the region in x & y dimensions. If a single int is given it is applied along both axes. Shape values must be even.
Returns:	sub – Subset of shape shape centered at center. DataArray coords will be set such that the upper left corner of the output has coordinates relative to the input.
Return type:	xarray.DataArray

zero_filter(image)¶

Search for and interpolate pixels equal to 0. This is to avoid NaN’s when a hologram is divided by a BG with 0’s. Interpolation fails if any of the four corner pixels are 0.

Parameters:	image (xarray.DataArray) – Image to process
Returns:	image – Image where pixels = 0 are instead given values equal to average of neighbors. dtype is the same as the input image
Return type:	xarray.DataArray