Function Reference

A list of lower-level functions is available below, see the documentation for individual classes for class methods.

The PyBundle class implements most of the functionality of the package and is the preferred approach for most applications except for Mosaicing, which is handled by the Mosaic class.

PyFibreBundle uses numpy arrays as images throughout, wherever ‘image’ is specified this refers to a 2D (monochrome) or 3D (colour) numpy array. For colour images, the colour channels are along the third axis. There can be as many colour channels as needed.

Classes

PyBundle()

Provides object-oriented access to core functionality of PyFibreBundle. See PyBundle class for details.

Mosaic()

Provides object-oriented access to mosaicing functionality of PyFibreBundle. See Mosaic class for details.

SuperRes()

Functions for super-resolution. Normally these should be accessed using the PyBundle class. See Super Resolution Section for details.

BundleCalibration()

Stores a calibration for triangular linear interpolation, both normal and super-resolution.

Low-Level Functions for Bundle finding, cropping, masking

pybundle.auto_mask(img, loc=None, **kwargs)

Locates bundle and sets pixels outside to 0 .

Parameters:

img – input image as 2D numpy array

Keyword Arguments:

  • loc – optional location of bundle as tuple of (centreX, centreY, radius), defaults to determining this using find_bundle

  • radius – optional, int, radius of mask to use rather than the automatically determined radius

  • Others – if loc is not specified, other optional keyword arguments will be passed to find_bundle.

pybundle.auto_mask_crop(img, loc=None, **kwargs)

Locates bundle, sets pixels outside to 0, and returns cropped image around bundle.

Parameters:

img – input image as 2D numpy array

Keyword Arguments:

  • loc – optional location of bundle as tuple of (centreX, centreY, radius), defaults to determining this using find_bundle

  • Others – if loc is not specified, other optional keyword arguments will be passed to find_bundle.

pybundle.apply_mask(img, mask)

Sets all pixels outside bundle to 0 using a pre-defined mask. If the image is 3D, the mask will be applied to each colour plane.

Parameters:

  • img – input image as 2D numpy array

  • mask – mask as 2D numy array with same dimensions as img, with areas to be kept as 1 and areas to be masked as 0.

pybundle.crop_rect(img, loc)

Extracts a square around the bundle using specified co-ordinates. If the rectange is larger than the image then the returned image will be a rectangle, limited by the extent of the image.

Returns tuple of (cropped image as 2D numpy array, new location tuple)

Parameters:

  • img – input image as 2D numpy array

  • loc – location to crop, specified as bundle location tuple of (centreX, centreY, radius)

pybundle.find_bundle(img, **kwargs)

Locate fibre bundle by thresholding and searching for largest connected region.

Returns tuple of (centreX, centreY, radius).

Parameters:

img – input image of fibre bundle, 2D numpy array

Keyword Arguments:

filterSize – sigma of Gaussian filter applied to remove core pattern, defaults to 4

pybundle.find_core_spacing(img)

Estimates fibre bundle core spacing using peak in 2D Fourier transform.

If the image is not square, a square will be cropped from the centre. It is therefore usually best to crop the image to the bundle before passing it to this function.

Returns core spacing as float.

Parameters:

img – input image showing bundle as 2D/3D numpy array

pybundle.get_mask(img, loc)

Returns a circular mask, 1 inside bundle, 0 outside bundle, using specified bundle co-ordinates. Mask image has same dimensions as first two dimensions of input image (i.e. does not return a mask for each colour plane).

Returns mask as 2D numpy array.

Parameters:

  • img – img used to determine size of mask, 2D numpy array

  • loc – location of bundle used to determine location of mask, tuple of (centreX, centreY, radius)

Low Level Functions for Spatial Filtering

pybundle.g_filter(img, filterSize, kernelSize=None)

Applies 2D Gaussian filter to image. By default the kernel size is 4 times the filter_size (sigma).

Returns filtered image as numpy array.

Parameters:

  • img – input image as 2D/3D numpy array

  • filterSize – float, sigma of Gaussian filter

Keyword Arguments:

kernelSize – int, size of convolution kernal

pybundle.crop_filter_mask(img, loc, mask, filterSize, resize=False, **kwargs)

For convenient quick processing of images. Sequentially crops image to bundle, applies Gaussian filter and then sets pixels outside bundle to 0. Set loc to None to automatically locate bundle. Optional parameter ‘resize’ allows the output images to be rescaled. If using auto-locate, can optionally specify find_bundle() options as additional keyword arguments.

Returns output image as 2D/3D numpy array

Parameters:

  • img – input image, 2D/3D numpy array

  • loc – location of bundle as tuple of (centreX, centreY, radius), set to None to determining this using find_bundle

  • mask – 2D numpy array with value of 1 inside bundle and 0 outside bundle

  • filterSize – sigma of Gaussian filter

Keyword Arguments:

  • resize – size to rescale output image to, default is no resize

  • Others – if loc is not specified, other optional keyword arguments will be passed to find_bundle.

pybundle.edge_filter(imgSize, edgePos, skinThickness)

Creates a 2D edge filter with cosine smoothing.

Returns the filter in spatial frequency domain filter as a 2D numpy array.

Parameters:

  • imgSize – size of (square) images which will be processed, and size of filter output

  • edgePos – spatial frequency of cut-off

  • skinThickness – slope of edge, the distance, in spatial frequency, over which it goes from 90% to 10%

pybundle.filter_image(img, filt)

Applies a Fourier domain filter to an image, such as created by edge_filter(). Filter must be same size as image (x and y) but not multi-channel (i.e. a 2D array).

Returns filtered image as 2D/3D numpy array.

Parameters:

  • img – input image (spatial domain), 2D/3D numpy array

  • filt – spatial frequency domain representation of filter, 2D numpy array

pybundle.median_filter(img, filterSize)

Applies 2D median filter to an image.

Returns the filtered image as a 2D numpy array.

Parameters:

  • img – input image as 2D/3D numpy array

  • filterSize – float, sigma of Gaussian filter

Functions for Triangular Linear Interpolation

High-level functions

pybundle.calib_tri_interp(img, coreSize, gridSize, **kwargs)

Performs calibration to allow subsequent core removal by triangular linear interpolation. Reconstructed images will be of size (gridSize, gridSize). ‘coreSize’ is used by the core finding routine, and should be an estimate of the core spacing. This function returns the entire calibration as an instance of BundleCalibration which can subsequently by used by recon_tri_interp. If background and/or normalisation images are specified, subsequent reconstructions will have background subtraction and/or normalisation respectively.

Returns an instance of BundleCalibration

Thanks to Cheng Yong Xin, Joseph, who collaborated in implementation of this function.

Parameters:

  • img – calibration image of bundle as 2D (mono) or 3D (colour) numpy array

  • coreSize – float, estimate of average spacing between cores

  • gridSize – int, output size of image, supply a single value, image will be square

Keyword Arguments:

  • centreX – int, optional, x centre location of bundle, if not specified will be determined automatically

  • centreY – int, optional, y centre location of bundle, if not specified will be determined automatically

  • radius – int, optional, radius of bundle, if not specified will be determined automatically

  • filterSize – float, optional, sigma of Gaussian filter applied, defaults to 0 (no filter)

  • background – optional, image used for background subtraction as 2D numpy array

  • normalise – optional, image used for normalisation, as 2D numpy array. Can be same as calibration image, defaults to no normalisation

  • autoMask – optional, boolean, if True the calibration image will be masked to prevent spurious core detections outside of bundle, defualts to True

  • mask – optional, boolean, when reconstructing output image will be masked outside of bundle, defaults to True

  • whiteBalance – optional, boolean, if True then each colour channel is normalised individually, defaults to False.

pybundle.recon_tri_interp(img, calib, **kwargs)

Removes core pattern using triangular linear interpolation. Requires an initial calibration using calib_tri_interp.

Returns reconstructed image as 2D/3D numpy array.

Parameters:

  • img – raw image to be reconstructed as 2D (mono) or 3D (colour) numpy array

  • calib – bundle calibration as instance of BundleCalibration

Keyword Arguments:

numba – optional, if true use JIT acceleration using Numba, default is False

Low-level functions

pybundle.find_cores(img, coreSpacing)

Find cores in bundle image using regional maxima. Generally fast and accurate.

Returns tuple of (x_pos, y_pos) where x_pos and y_pos are 1D numpy arrays.

Parameters:

  • img – 2D/3D numpy array

  • coreSpacing – float, estimate of the separation between cores in pixels.

pybundle.core_values(img, coreX, coreY, filterSize, **kwargs)

Extract intensity of each core in fibre bundle image. First applies a Gaussian filter unless filterSize is None. Supports JIT acceleration if numba is installed.

Parameters:

  • coreX – 1D numpy array giving x co-ordinates of core centres

  • coreY – 1D numpy array giving y co-ordinates of core centres

  • filterSize – float, sigma of Gaussian filter

Keyword Arguments:

numba – optional, if true numba JIT used for faster execution, defaults to False.

pybundle.init_tri_interp(img, coreX, coreY, centreX, centreY, radius, gridSize, **kwargs)

Used by calib_tri_interp to perform Delaunay triangulation of core positions, and find each pixel of reconstruction grid in barycentric co-ordinates w.r.t. enclosing triangle.

Returns instance of BundleCalibration.

Parameters:

  • img – calibration image as 2D (mono) or 3D (colour) numpy array

  • coreX – x centre of each core as 1D numpy array

  • coreY – y centre of each core as 1D numpy array

  • centreX – x centre location of bundle (reconstruction will be centred on this)

  • centreY – y centre location of bundle (reconstruction will be centred on this)

  • radius – radius of bundle (reconstruction will cover a square out to this radius)

Keyword Arguments:

  • gridSize – output size of image, supply a single value, image will be square

  • filterSize – optional, sigma of Gaussian filter applied, defaults to no filter

  • background – optional, image used for background subtractionn as 2D numpy array

  • normalise – optional, image used for normalisation, as 2D numpy array. Can be same as calibration image, defaults to no normalisation

  • mask – optional, boolean, when reconstructing output image will be masked outside of bundle, defaults to True

  • whiteBalance – optional, boolean, if True then each colour channel is normalised individually, defaults to False.

Utility Functions

pybundle.average_channels(img)

Returns an image which is the the average pixel value across all channels of a colour image. It is safe to pass a 2D array which will be returned unchanged.

Parameters:

img – image as 2D/3D numpy array

pybundle.extract_central(img, boxSize=None)

Extract a central square from an image. The extracted square is centred on the input image, with size 2 * boxSize if possible, otherwise the largest square that can be extracted.

Returns cropped image as 2D numpy array.

Parameters:

img – input image as 2D numpy array

Keyword Arguments:

boxSize – size of cropping square, default is largest possible

pybundle.max_channels(img)

Returns an image which is the the maximum pixel value across all channels of a colour image. It is safe to pass a 2D array which will be returned unchanged.

Parameters:

img – image as 2D/3D numpy array

pybundle.radial_profile(img, centre)

Produce angular averaged radial profile through image img centred on centre, a tuple of (x_centre, y_centre)

Returns radial profile as 1D numpy array

Parameters:

  • img – input image as 2D numpy array

  • centre – centre point for radial profile, tuple of (x,y)

pybundle.save_image8(img, filename)

Saves image as 8 bit tif without scaling

pybundle.save_image8_scaled(img, filename)

Saves image as 8 bit tif with scaling to use full dynamic range.

Parameters:

  • img – image as 2D/3D numpy array

  • filname – str, path to file. Folder must exist.

pybundle.save_image16(img, filename)

Saves image as 16 bit tif without scaling.

Parameters:

  • img – image as 2D/3D numpy array

  • filname – str, path to file. Folder must exist.

pybundle.save_image16_scaled(img, filename)

Saves image as 16 bit tif with scaling to use full dynamic range.

Parameters:

  • img – image as 2D/3D numpy array

  • filname – str, path to file. Folder must exist.

pybundle.to8bit(img, **kwargs)
Returns an 8 bit representation of image. If min and max are specified,

these pixel values in the original image are mapped to 0 and 255 respectively, otherwise the smallest and largest values in the whole image are mapped to 0 and 255, respectively.

Arguments:

img : input image as 2D numpy array

Keyword Arguments:

  • minVal – optional, pixel value to scale to 0

  • maxVal – optional, pixel value to scale to 255

pybundle.to16bit(img, **kwargs)

Returns an 16 bit representation of image. If min and max are specified, these pixel values in the original image are mapped to 0 and 2^16 respectively, otherwise the smallest and largest values in the whole image are mapped to 0 and 2^16 - 1, respectively.

Parameters:

img – input image as 2D numpy array

Keyword Arguments:

  • minVal – optional, pixel value to scale to 0

  • maxVal – optional, pixel value to scale to 2^16 - 1