PyBundle class
The PyBundle class is the recommended way to use most functionality of the package (other than Mosaicing which has its own class. All method are listed below, introductory guides on using the class are available for for Basic Processing, Linear Interpolation and Super Resolution .
Instantiatation
- PyBundle(optional arguments)
Creates a PyBundle object. There are a large number of optional keyword
arguments (.e.g autoLoc = True), which are listed below with their defaults
if not set. Each option also has a setter method (e.g. set_auto_loc) which
can be called after creating the object as an alternative to passing the
keyword arguement at creation. See the documentation for each setter, below,
for a detailed description of each option’s meaning.
GENERAL Settings:
autoContrast = False (
set_auto_contrast)background = None (
set_background)coreMethod = None (
set_core_method)outputType = ‘float64’ (
set_output_type)
CROP/MASK Settings:
applyMask = False (
set_apply_mask)autoMask = True (
set_auto_mask)autoLoc = False (
set_auto_loc)crop = False(
set_crop)loc = None (
set_loc)mask = None (
set_mask)radius = None (
set_radius)
CALIB/BACKGROUND/NORMALISATION Settings:
calibImage = None (
set_calib_image)backgroundImage = None (
set_background)normaliseImage = none (
set_normalise_image)
GAUSSIAN FILTER Settings:
filterSize = None (
set_filter_size)
EDGE_FILTER Settings:
edgeFilterShape = None (
set_edge_filter_shape)
LINEAR INTERPOLATION Settings:
coreSize = 3 (
set_core_size)gridSize = 512 (
set_grid_size)useNumba = True (
set_use_numba)whiteBalance = False (
set_white_balance)
SUPER RESOLUTION Settings:
superRes = False (
set_super_res)srShifts = None (
set_sr_shifts)srCalibImages = None (
set_sr_calib_images)srNormToBackgrounds = False (
set_sr_norm_to_backgrounds)srNormToImages = True (
set_sr_norm_to_images)srMultiBackgrounds = False (
set_sr_multi_backgrounds)srMultiNormalisation = False (
set_sr_multi_normalisation)srDarkFrame = None (
set_sr_dark_frame)srUseLut = False (
set_sr_use_lut)srParamValue = None (
set_sr_param_value)
Methods
- class pybundle.PyBundle(**kwargs)
- calibrate()
Peforms calibraion steps appropriate to chosen method. A calibration image must have been set prior to calling this.
For TRILIN, creates interpolation calibration.
For FILTER, EDGE_FILTER, a filtered normalisation image is created.
For FILTER, EDGE_FILTER the bundle will be located if autoLoc has been set.
For FILTER, EDGE_FILTER the mask will be located if autoMask has been set.
- calibrate_sr()
Creates calibration for TRILIN SR method. A calibration image, set of super-res shift images, coreSize and gridSize must have been set prior to calling this.
- calibrate_sr_lut(paramCalib, paramRange, nCalibrations)
Creates calibration LUT for TRILIN SR method. A calibration image, set of super-res shift images, coreSize and griSize must have been set prior to calling this.
- Parameters:
paramCalib – parameter shift calibration, as generated by calib_param_shift()
paramRange – tuple of (min, max) defining range of parameter values to generate for
nCalibration – int, number of parameter values to generate for
- create_and_set_mask(img, **kwargs)
Determine mask from provided calibration image and set as mask Optionally provide a radius rather than using radius of determined bundle location.
- Parameters:
img – calibration image from which size of mask is determined
- Keyword Arguments:
radius – radius of mask, default is to determine this automtically
- get_pixel_scale()
Returns the scaling factor between the pixel size in the raw image and the pixel size in the processed image. If the TRILIN method is selected, but a calibration has not yet been performed, returns None.
- process(img)
Process fibre bundle image using current settings.
Returns processed image as 2D/3D numpy array.
- Parameters:
img – input image as 2D/3D numpy array
- set_apply_mask(applyMask)
Determines whether areas outside the bundle are set to zero for FILTER and EDGE_FILTER method.
- Parameters:
applyMask – boolean, True to apply mask, False to not apply mask
- set_auto_contrast(ac)
Determines whether images are scaled to be between 0-255.
- Parameters:
ac – boolean, True to autocontrast
- set_auto_loc(img)
Sets whether the bundle is automatically located for cropping and masking, if these are turned on, depending on boolean value passed.
It is also possible to pass an image as a 2D numpy array instead of a Boolean, in which case the bundle location will be determined from this image. However, this is noq deprecated in favour of setting calibImg and then calling calibrate.
- Parameters:
img – boolean, True to auto-locate bundle, False to not.
- set_auto_mask(img, **kwargs)
Set whether to automically create mask using pre-determined bundle location.
It is also possible to provide an image as a 2D numpy array, in which case the mask will be generated of the correct size for this image, but this is deprecated, use calibrate() instead. Optionally provide a radius rather than using radius of determined bundle location.
- Parameters:
img – boolean, True to automically create mask
- Keyword Arguments:
radius – optional, int, overrides automically determined radius for mask.
- set_background(background)
Store an image to be used as background. If TRILIN is being used and a calibration has already been performed, the background will be added to the calibration.
- Parameters:
backgroundImage – background image as 2D/3D numpy array. Set as None to remove background.
- set_calib_image(calibImg)
Set image to be used for calibration.
- Parameters:
calibImg – calibration image as 2D/3D numpy array
- set_core_method(coreMethod)
Set the method to use to remove cores, FILTER, TRILIN or EDGE_FILTER
- Parameters:
coreMethod – PyBundle.FILTER, PyBundle.TRILIN or PyBundle.EDGE_FILTER
- set_core_size(coreSize)
Set the estimated centre-centre core spacing used to help find cores as part of TRILIN method.
- Parameters:
coreSize – float, estimate core spacing
- set_crop(crop)
Determines whether images are cropped to size of bundle for FILTER, EDGE_FILTER methods. crop is Boolean.
- Parameters:
crop – boolean, True to crop
- set_edge_filter_shape(edgePos, edgeSlope)
Creates and stores filter for EDGE_FILTER method.
- Parameters:
edgePos – float, spatial frequency of edge in pixels of FFT of image
edgeSlope – float, steepness of slope (range from 10% to 90%) in pixels of FFT of image
- set_filter_size(filterSize)
Set the size of Gaussian filter used if filtering method employed.
- Parameters:
filterSize – float, sigma of Gaussian filter
- set_grid_size(gridSize)
Sets output image size if TRLIN method used. If not called prior to calling ‘calibrate’, the default value of 512 will be used.
- Parameters:
gridSize – int, size of square image output
- set_loc(loc)
Store the location of the bundle. This will also set autoLoc = False.
- Parameters:
loc – bundle location, tuple of (centreX, centreY, radius)
- set_mask(mask)
Provide a mask to be used. Mask must be a 2D numpy array of same size as images to be processed
- Parameters:
mask – 2D numpy array, 1 inside bundle, 0 inside bundle. Must be same size as image to be processed.
- set_normalise_image(normaliseImage)
Store an image to be used for normalisation. If TRILIN is being used and a calibration has already been performed, the normalisation will be added to the calibration.
- Parameters:
normaliseImage – normalisation image as 2D/3D numpy array. Set as None to remove normalisation.
- set_output_type(outputType)
Specify the data type of input images returned from ‘process’. Returns False if type not valid.
- Parameters:
outputType – str, one of ‘uint8’, ‘unit16’ or ‘float’
- set_radius(radius)
Sets the radius of the bundle in the image. This will override any automically determined value.
- Parameters:
radius – int, bundle radius
- set_sr_backgrounds(backgrounds)
Provide a set of background images for background correction of each SR shifted image.
- Parameters:
backgrounds – 3D numpy array, stack of background images
- set_sr_calib_images(calibImages)
Provides the calibration images, a stack of shifted images used to determine shifts between images for super-resolution
- Parameters:
calibImages – 3D numpy array, stack of shifted images.
- set_sr_dark_frame(darkFrame)
Provide a dark frame for super-resolution calibration.
- Parameters:
darkFrame – 2D numpy array, dark frame
- set_sr_multi_backgrounds(mb)
Sets whether super-resolution should use individual backgrounds for each each shifted image.
- Parameters:
mb – boolean, True to use multiple backgrounds, False to not
- set_sr_multi_normalisation(mn)
Sets whether super-resolution should normalise to each core in each image
- Parameters:
mn – boolean, True to normalise each core in each image, False to not
- set_sr_norm_to_backgrounds(normToBackgrounds)
Sets whether super-resolution recon should normalise each input image w.r.t. a stack of backgrounds in srBackgrounds to have the same mean intensity.
- Parameters:
normToBackgrounds – boolean, True to normalise, False to not
- set_sr_norm_to_images(normToImages)
Sets whether super-resolution recon should normalise each input image to have the same mean intensity.
- Parameters:
normToImages – boolean, True to normalise, False to not
- set_sr_normalisation_images(normalisationImages)
Provide a set of normalisation images for normalising intensity of each SR shifted image.
- Parameters:
normalisationImages – 3D numpy array, stack of images
- set_sr_param_value(val)
Sets the current value of the parameter on which the shifts dependent for SR reconstruction.
- Parameters:
val – parameter value
- set_sr_shifts(shifts)
Provide shifts between SR images. If this is set then no registration will be performed.
- Parameters:
shifts – 2D numpy array, shifts for each image relative to first image. 1st axis is image number, 2nd axis is (x,y)
- set_sr_use_lut(useLUT)
Enables or disables use of calibration LUT for super resoution.
- Parameters:
useLUT – boolean, True to use calibration LUT.
- set_super_res(sr)
Enables or disables super resolution.
- Parameters:
sr – boolean, True to use super-resolution.
- set_use_numba(useNumba)
Sets whether Numba should be used for JIT compiler acceleration for functionality which supports this.
- Parameters:
useNumba – boolean, True to use Numba, False to not.
- set_white_balance(whiteBalance)
Sets whether each colour channel should be normalised independently when using linear interpolation method.
- Parameters:
whiteBalance – boolean, each channel normalised independently if True (default is False).