holopy.core.process package

Module contents

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

holopy.core.process.centerfinder module

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

holopy.core.process.fourier module

Handles Fourier transforms of HoloPy images by using scipy’s fftpack. Tries to correctly interpret dimensions from xarray.

fft(a, overwrite=False, 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 Marray, 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:
  • a (ndarray) – The array to transform
  • overwrite (bool) – Allow this function to overwrite the Marry you pass in. This may improve performance slightly. Default is not to overwrite
  • shift (bool) – Whether to preform an fftshift on the Marry 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(a, overwrite=False, 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 Marry, and do the fftshift for you. This is indendended for working with images, and thus for dimensions greater than 2 does slicewise transforms of each “image” in a multidimensional stack

Parameters:
  • a (ndarray) – The array to transform
  • overwrite (bool) – Allow this function to overwrite the Marry you pass in. This may improve performance slightly. Default is not to overwrite
  • shift (bool) – Whether to preform an fftshift on the Marry to give low frequences near the center as you probably expect. Default is to do the fftshift.
Returns:

ifta – The inverse fourier transform of a

Return type:

ndarray

ift_coord(c)
ift_coords(cs)
transform_metadata(a, inverse)

holopy.core.process.img_proc module

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 (ndarray or Image) – 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:

ndarray

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.

Return type:

xarray.DataArray

detrend(image)

Remove linear trends from an image.

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

Parameters:image (ndarray) – Image to process
Returns:image – Image with linear trends removed
Return type:ndarray
normalize(image)

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

Parameters:image (ndarray) – The array to normalize
Returns:normalized_image – The normalized image
Return type:ndarray
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 (numpy.ndarray) – 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 tuple of ints) – Desired shape of the region. If a single int is given the region will be that dimension in along every axis. Shape should be even
Returns:

sub – Subset of shape shape centered at center. For marrays, marray.origin will be set such that the upper left corner of the output has coordinates relative to the input.

Return type:

numpy.ndarray or RegularGrid marray object

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.

Parameters:image (ndarray) – 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:ndimage