Library Reference - Functions — Bonsu - The Interactive Phase Retrieval Suite 3.0 documentation

# Library Reference - Functions

## Transpose Array

Transposes an array from dimensions {x,y,z} to dimensions {z,y,x}.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided choice of memory keyword.

## Sum or Subtract Array

Takes the sum or difference of two input arrays and places the result in the output array.

Parameters:

Input file 1
  User provided path string to the input NumPy file.
Input file 2
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Add or Subtract
  Choose whether to add or subtract array 2 from array 1.

## Scale Array

Scales the input array by a given amount. Scaling is performed element-wise.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Scale factor
  Factor by which each voxel of the array is scaled.

## Rotate Support

Rotates a binary array (such as a support array) by the specified angle in degrees normal to the specified axis. This operation is only intended for binary arrays.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Axis
  Axis normal to the rotation. 1,2 and 3 correspond to axis x,y and z.
Angle
  Angle of rotation in degrees.

## Median Filter

Applies a median filter to the amplitude of the input array. Voxels are only replaced in the array if they deviate from the median filtered equivalent by an amount greater than the `Normal deviation`.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Filter kernel dimensions
  Dimensions of the median filtering kernel.
Normal deviation
  Median filter voxel replace cut-off value. This value is compared element-wise to the normalised difference in amplitude of voxels from the input array and from the median filtered equivalent, i.e. the magnitude of (`median filtered array` - `array`)/ `array`. Voxels that exceeed this cut-off are replaced with their median-filtered equivalent.

## Blank Line Fill Array

Applies an average filter to the amplitude of non-zero voxels of the input array within the specified region.

Parameters:

Input file
  User provided path string to the input NumPy file.
ROI path
  Region of interest within the `input HDF file`.
Output File
  User provided path string for the output NumPy file.
Filter kernel dimensions
  Dimensions of the averging kernel.

## HDF5 to Numpy

Provides a means to browse and import data within a Hierarchical Data Format (HDF) file. HDF5 is supported via the python H5Py package.

Parameters:

Input HDF file
  User provided path string to the input HDF file.
HDF key path
  Comma separated list of HDF keys found within the `input HDF file`.
Output File
  User provided path string for the output NumPy file.

## SPE to Numpy

Provides a means to import data from SPE format into NumPy format. During conversion, additional information is provided and appears in the Log.

Parameters:

Input SPE file
  User provided path string to the input SPE file.
Output File
  User provided path string for the output NumPy file.

## Image to Numpy

Provides a means to import image data into NumPy format. Accepted formats include Portable Network Graphics (PNG), JPEG, Portable PixMap (PPM) and Tagged Image File (TIF) format. Output Numpy arrays are three dimensional with unit length in the third dimension.

Parameters:

Input Image file
  User provided path string to the input image file.
Output File
  User provided path string for the output NumPy file.

## Array to Memory

Provides a means to load a NumPy array from disk directly into a memory by using either of the 10 keywords `memory0`, `memory1`, … , `memory9` as a string in place of a NumPy file path. See Array Creation and Storage for furthr details.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided choice of memory keyword.

## Memory to Array

Provides a means to save to disk a NumPy array stored in memory. See Array to Memory for furthr details.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided choice of memory keyword.

## Crop Pad

Provides a means to crop and zero pad a NumPy array. The input array is first cropped and subsequently zero padded according to the specified parameters.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Crop dimensions: Start: {i,j,k}
  Number of indices by which to crop the array along each {i,j,k} direction. Cropping direction begins from the start of the array (and counts forward) for each {i,j,k} direction.
Crop dimensions: End: {i,j,k}
  Number of indices by which to crop the array along each {i,j,k} direction. Cropping direction begins from the end of the array (and counts backward) for each {i,j,k} direction.
Pad dimensions: Start: {i,j,k}
  Number of indices by which to pad the array along each {i,j,k} direction. Padding direction begins from the start of the array for each {i,j,k} direction.
Pad dimensions: End: {i,j,k}
  Number of indices by which to pad the array along each {i,j,k} direction. Padding direction begins from the end of the array for each {i,j,k} direction.

## Cuboid Support

Creates a support array for use in phase retrieval. Voxels in this array take a value of inside the support and zero everywhere else. The support is automatically centred within the array.

If any array is supplied in the `(xyz) from array` field, the dimensions of this array will be used for the support array. Otherwise, the specified dimensions will be used.

Parameters:

Support file
  User provided path string for the output `support` NumPy file.
(xyz) from array
  Optional user provided path string for NumPy file used to provide the `support` array dimensions.
(xyz) from dimensions {x,y,z}
  Dimensions of the `support` array. This is overridden if the `(xyz) from array` field is used.
Support size {x,y,z}
  Dimensions of the support. This must be smaller than the size of the array.

## Mask

Creates a `mask` array for use in phase retrieval. Voxels in this array take a value of if the corresponding voxel of the `input file` is inside the range of `Minimum Value` to `Maximum Value`. Voxels outside the same range are set to zero.

Parameters:

Input file
  User provided path string to the input NumPy file from which `Minimum Value` and `Maximum Value` are obtained.
Output File
  User provided path string for the output `mask` NumPy file.
Maximum Value
  Values above (equal or below) `Maximum Value` in the `input file` will result in a corresponding voxel value of zero () in the `mask`.
Minimum Value
  Values below (equal or above) `Minimum Value` in the `input file` will result in a corresponding voxel value of zero () in the `mask`.

## Bin

Creates an array in which each voxel results from the grouping and addition of neighbouring voxels of the `input file`. The dimensions used (in each {x,y,z} direction) for each voxel group is dictated by the `Bin dimensions` parameter.

Parameters:

Input file
  User provided path string to the input NumPy file from which `bin` groups are defined.
Output File
  User provided path string for the output `bin` NumPy file.
Bin dimensions {x,y,z}
  Dimensions used for grouping voxels.

## Auto Centre

Centres the input NumPy array by placing the voxel with the largest amplitude at the centre of the array. The output NumPy array will necessarily increase in dimensions when compared to the input if centring is required.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.

## Centred Resize

Centres the input NumPy array by placing the voxel with the largest amplitude at the centre of the array and then resizes the cetered array to the specified dimensions.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Dimensions {x,y,z}
  Dimensions of the output array.

## Wrap Data

Reorders the data of the input NumPy file into wrap-around order.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Wrap Direction
  If an array dimension has an odd number of elements, a Forward followed by a Reverse wrap is required to obtain the original array.

## Gaussian Fill

Fill the input NumPy file with a Gaussian function.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Sigma
  Standard Deviation of the Gaussian function.

## Fourier Transform

Performs a Fast Fourier transform (FFT) on the input NumPy file in the specified direction.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
To
  - Fourier Space - Transform to Fourier space.
  - Real Space - Transform to Real space.

## Convolve

Performs a discrete convolution of the two input NumPy files.

Parameters:

First Input file
  User provided path string to the first input NumPy file.
Second Input file
  User provided path string to the second input NumPy file.
Output File
  User provided path string for the output NumPy file.

## Conjugate Reflect

Takes the complex conjugate and reflects the coordinates of the input NumPy file.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.

## Threshold Data

Creates an array using data from the `input file` for which voxels outside the range of `Minimum Value` to `Maximum Value` are set to zero.

Parameters:

Input file
  User provided path string to the input NumPy file from which `Minimum Value` and `Maximum Value` are obtained.
Output File
  User provided path string for the output `mask` NumPy file.
Maximum Value
  Values above `Maximum Value` in the `input file` will result in a corresponding voxel value of zero in the `output file`.
Minimum Value
  Values below `Minimum Value` in the `input file` will result in a corresponding voxel value of zero in the `output file`.

## Voxel Replace

Replaces all voxels with indices in the range of `Start dimensions` and `End dimensions` with the specified `complex value`.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Start dimensions: {i,j,k}
  Starting indices from which the replacement will begin.
End dimensions: {i,j,k}
  Final indices for which the replacement will end.
Complex Value
  Real and imaginary parts of a complex number used repeatedly to replace voxel data in the `input file`.

## Load Co-ordinates

Initialises or replaces the internally stored `Co-ordinates data` with the supplied array.

Parameters:

Input file
  User provided path string to the input NumPy file.

## Median Filter

Applies a median filter to the amplitude of the input NumPy file. Voxels are only replaced if they deviate in amplitude by an amount greater than the `Normal deviation` between the input NumPy array and the median filtered NumPy array.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output NumPy file.
Filter kernel dimensions: {x,y,z}
  Size of the kernel in pixels.
Normal deviaton
  Element-wise normalised deviation of the intensity between the input NumPy array and the median filtered NumPy array. Voxels with amplitude above this value are replaced with the median filtered alternative. All other voxels remain unfiltered.

## Array to VTK

Convert an input NumPy array into VTK file format. Uses either the amplitude or phase of the array.

Parameters:

Input file
  User provided path string to the input NumPy file.
Output File
  User provided path string for the output VTK file.
Type
  Use either the amplitude or the phase of the complex `input file` in order to construct a VTK array.

## Object to VTK

Convert an input NumPy array and it’s corresponding co-ordinates array into VTK file format. Uses either the amplitude or phase of the array.

Parameters:

Input file
  User provided path string to the input NumPy file.
Co-ord’s File
  User provided path string to the corresponding co-ordinates NumPy file. Generating coordinates files is achieved using the Coordinate transformation operation.
Output File
  User provided path string for the output VTK file.
Type
  Use either the amplitude or the phase of the complex `input file` in order to construct a VTK array.

## Interpolate Object

Interpolates an input NumPy array and it’s corresponding co-ordinates onto regular grid NumPy array with dimensions dictated by `Array grid size`. Shepards famous algorithm is used for the interpolation.

Parameters:

Input file
  User provided path string to the input NumPy file.
Co-ord’s File
  User provided path string to the corresponding co-ordinates NumPy file. Generating coordinates files is achieved using the Coordinate transformation operation.
Output File
  User provided path string for the output NumPy file.
Array grid size
  Dimensions of the output NumPy array.
Interpolation range
  fraction of the input array used for interpolating each point. Larger values approaching unity will significantly slow down the interpolation process.

## View Array

Render an image of the two or three-dimensional input Numpy array to the Visualisation tab.

Parameters:

Input file
  User provided path string to the input NumPy file.
Type
  - Amplitude - An iso-surface of the array amplitude.
  - Phase - An interactive scalar cut plane of the array phase.
  - Amplitude and Phase - An iso-surface of the array amplitude and an interactive scalar cut plane of the array phase.
  - Amplitude with Phase - An iso-surface of the array amplitude with the array phase mapped onto the iso-surface.
  - Amplitude (cut plane) - An interactive scalar cut plane of the array amplitude.
Amplitude
  - Iso-surface - Scalar value for the rendered iso-surface.
  - Opacity - Opacity of the isosurface when viewing `Amplitude and Phase`.
  - Feature angle - Minimum angle between two surface normals of the rendered object.
Phase
  - Max - Maximum phase.
  - Min - Minimum phase.
Origin
  Origin point of the interactive scalar cut plane.
Normal
  Normal vector to the interactive scalar cut plane.
Spacing
  Spacing of the input array indices.
View Axes
  Optionally view the axes of the array.

## View Object

Render an object of the three-dimensional input Numpy array with it’s corresponding co-ordinates array to the Visualisation tab.

Parameters:

Input file
  User provided path string to the input NumPy file.
Co-ord’s File
  User provided path string to the corresponding co-ordinates NumPy array file. Alternatively, the memory array keyword `memorycoords` provides access to the internally stored coordinate array. Generating a coordinate array is achieved using the Coordinate transformation operation.
Type
  - Amplitude - An iso-surface of the object amplitude.
  - Phase - An interactive scalar cut plane of the object phase.
  - Amplitude and Phase - An iso-surface of the object amplitude and an interactive scalar cut plane of the object phase.
  - Amplitude with Phase - An iso-surface of the object amplitude with the object phase mapped onto the iso-surface.
  - Amplitude (cut plane) - An interactive scalar cut plane of the object amplitude.
Amplitude
  - Iso-surface - Scalar value for the rendered iso-surface.
  - Opacity - Opacity of the isosurface when viewing `Amplitude and Phase`.
  - Feature angle - Minimum angle between two surface normals of the rendered object.
Phase
  - Max - Maximum phase.
  - Min - Minimum phase.
Origin
  Origin point of the interactive scalar cut plane.
Normal
  Normal vector to the interactive scalar cut plane.
View Axes
  Optionally view the axes of the object.

## View VTK Array

Render an input VTK array to the Visualisation tab.

Parameters:

Input file
  User provided path string to the input NumPy file.
Type
  - Amplitude - An iso-surface of the array amplitude.
  - Phase - An interactive scalar cut plane of the array phase.
  - Amplitude (cut plane) - An interactive scalar cut plane of the array amplitude.
Amplitude
  - Iso-surface - Scalar value for the rendered iso-surface.
  - Feature angle - Minimum angle between two surface normals of the rendered object.
Phase
  - Max - Maximum phase.
  - Min - Minimum phase.
Origin
  Origin point of the interactive scalar cut plane.
Normal
  Normal vector to the interactive scalar cut plane.
View Axes
  Optionally view the axes of the array.

## View Support

Render an image of a three-dimensional input Numpy data array and its Support array to the Visualisation tab.

Parameters:

Support file
  User provided path string to the NumPy array file.
Data array file
  User provided path string to the NumPy array file.
Isosurface options
  - Support iso-surface - Scalar value for the rendered iso-surface on the interval [0,1].
  - Opacity - Opacity of the support isosurface.
  - Data file iso-surface - Scalar value for the rendered iso-surface.
  - Feature angle - Minimum angle between two surface normals of the rendered object.
View Axes
  Optionally view the axes of the array.

## Comments

Input comments into the pipeline.

## Python Script

Execute python script. Memory arrays are exposed to this function.