OpFlowLab module

class OpFlowLab.OpFlowLab.OpFlowLab(main_folder, image_file, forward_velocity_folder=None, reverse_velocity_folder=None, object_segmentation_folder=None, velocity_type='dense', velocity_ext_type='*.bin', image_ext_type='*.tif', velocity_dtype='float16', kernel_size=5)

Bases: object

Methods

flowCurl_function([output_folder, …])	Calculates gradients and output the curl values for an image stack
flowDerivative_iteration(output_folder, frame_no)	Calculates gradients and output the various flow derivatives for a single iteration
flowDivergence_function([output_folder, …])	Calculates gradients and output the divergence values for an image stack
flowMatch_function([output_folder, …])	Wrapper function that calls flowMatch_iteration() for each individual pair of frames in the image stack.
flowMatch_iteration(frame_no, …[, …])	Perform flowMatch of segmented objects using the provided motion estimation vector information for a single iteration and outputs an interpolated vector field using the velocity obtained from the matched objects.
flowPath_function([output_folder, …])	Wrapper function that calls flowPath_iteration() for each frames in the image stack.
flowPath_initialization([frames, spacing, …])	Initializes the tracers that will be used for vector trace visualization
flowPath_iteration(frame_no, tracer_pos, …)	Calculates and outputs the flowPath for a single iteration based on the estimated velocity field.
flowShear_function([output_folder, …])	Calculates gradients and output the simple shear values for an image stack
flowTracer_first_frame(tracer_folder, …[, …])	Plots and draws the position of the tracers in the first frame
flowTracer_function([output_folder, …])	Iterates and plots positions of artificial tracers based on provided motion estimation vectors
flowTracer_initialization([…])	Initializes the tracers that will be used for vector trace visualization
flowTracer_iteration(tracer_folder, …[, …])	Calculates and outputs flowTracer for a single iteration
flowWarp_function([output_folder, start_frame])	Wrapper function that calls flowWarp_iteration() for each individual pair of frames in the image stack.
flowWarp_iteration(frame_no, …)	Performs flowWarp of an image using the calculated velocity field for that image and calculate the normalised root mean squared error between it and the next image in the sequence.
initialize_forward_velocities(folder[, …])	Initializes the internal folder path and file lists for the forward velocities
initialize_reverse_velocities(folder[, …])	Initializes the internal folder path and file lists for the forward velocities
initialize_segmentation_folder(folder[, …])	Initializes the internal folder path and file lists for the segmented images
load_velocities(filelist, img_no)	Helper function to call the correct loading function based on the type of vectors as specified in self._vector_type
parse_folder(folder)	Appends the main folder director to the folder name given

flowCurl_function(output_folder='curl', smoothing=None, colormap=None, colormap_min=None, colormap_max=None)

Calculates gradients and output the curl values for an image stack

Parameters

output_folderstr

Folder name that will be created in the main directory to store flow derivative images

smoothingint or Bool

Sigma value for gaussian smoothing

colormap_min, colormap_maxfloat

Minimum and/or maximum value that is used to determine the normalization of the colormap

See also

flowDerivative_iteration

base function to generate flow derivative images

flowDerivative_iteration(output_folder, frame_no, stat_matrix=None, file_string=None, smoothing=None, colormap=None, colormap_min=None, colormap_max=None)

Calculates gradients and output the various flow derivatives for a single iteration

Parameters

output_folderstr

Folder name that will be created in the main directory to store flow derivative images

frame_noint

Frame number with which to calculate flow derivatives

stat_matrix2D array of shape (2, 2)

Array containing formulation of

file_string: str

File name in the format ‘[name]_{:03d}.tif’

colormapstr or None

Colormap to plot

smoothingint

Size of gaussian smoothing kernel

colormap_min, colormap_maxfloat

Minimum and/or maximum value that is used to determine the normalization of the colormap

Returns

output_image2D array

Output image containing the colorized flow derivative

See also

flowCurl_function

wrapper function to plot curl for all frames

flowDivergence_function

wrapper function to plot divergence for all frames

flowShear_function

wrapper function to plot simple shear for all frames

flowDivergence_function(output_folder='divergence', smoothing=None, colormap=None, colormap_min=None, colormap_max=None)

Calculates gradients and output the divergence values for an image stack

Parameters

output_folderstr

Folder name that will be created in the main directory to store flow derivative images

smoothingint or Bool

Sigma value for gaussian smoothing

colormap_min, colormap_maxfloat

Minimum and/or maximum value that is used to determine the normalization of the colormap

See also

flowDerivative_iteration

base function to generate flow derivative images

flowMatch_function(output_folder='FlowMatch', pairwise_threshold_distance=10, min_object_size=None, max_object_size=None)

Wrapper function that calls flowMatch_iteration() for each individual pair of frames in the image stack.

Parameters

output_folderstr

Folder name that will be created in the main directory to store the interpolated vector fields

pairwise_threshold_distanceint

Distance between the propagated centroid location and the actual centroid location that is used as a cutoff for flowMatch

min_object_sizeint or None

Minimum object size for it to be included in the matching process. Set to None to ignore this cutoff

max_object_sizeint or None

Maximum object size for it to be included in the matching process. Set to None to ignore this cutoff

Returns

total_number_listlist

List containing the total number of objects that are eligible for object matching for each frame

matched_number_listlist

List containing the total number of matched object for each frame

See also

flowMatch_iteration

function used to perform flowMatch for a single frame

flowMatch_iteration(frame_no, flowx_output_directory, flowy_output_directory, pairwise_threshold_distance=10, min_object_size=10, max_object_size=None, save_dtype='float16', save_velocity_as_tif=False)

Perform flowMatch of segmented objects using the provided motion estimation vector information for a single iteration and outputs an interpolated vector field using the velocity obtained from the matched objects.

Parameters

frame_noint

Frame number with which to load vector

flowx_output_directorystr

Path to folder that will be used to store the x component of the interpolated vector field

flowy_output_directorystr

Path to folder that will be used to store the y component of the interpolated vector field

pairwise_threshold_distanceint

Distance between the propagated centroid location and the actual centroid location that is used as a cutoff for object matching

min_object_sizeint or None

Minimum object size for it to be included in the matching process. Set to None to ignore this cutoff

max_object_sizeint or None

Maximum object size for it to be included in the matching process. Set to None to ignore this cutoff

save_dtypestr

Save vectors as either float16 or float32 file

save_velocity_as_tifbool

Save as float32 tif file instead of a float16 binary file

Returns

total_numberint

Total number of objects that are eligible for object matching for each frame

matched_numberint

Total number of matched object for each frame

flowPath_function(output_folder='FlowPath', start_frame=0, frames=10, alpha=0, spacing=8, max_tracers=None)

Wrapper function that calls flowPath_iteration() for each frames in the image stack.

Parameters

output_folderstr

Folder name that will be created in the main directory to store the vector trace images

start_frameint

Frame number with which to start vector trace visualization

framesint

Length of trails in number of frames that will be drawn for each artificial tracer

alphaint

Specifies the alpha value for the flowPath overlay over the original image

spacingint

Grid spacing used to initialize tracers

max_tracersint or None

Maximum number of tracers to be used in the calculation [Currently unused]

Returns

None

See also

initialize_flow_path

function used to initialize tracers

flow_path_iteration

function used to perform vector trace visualization for a single frame

flowPath_initialization(frames=10, spacing=8, max_tracers=None)

Initializes the tracers that will be used for vector trace visualization

Parameters

framesint

Length of trails in number of frames that will be drawn for each artificial tracer

spacingint

Grid spacing used to initialize tracers.

max_tracersint or None

Maximum number of tracers to be used in the calculation [Currently unused]

Returns

tracer_pos3D array of shape (frames, tracer_no, 2)

Array containing the positions of the tracers in the format [y,x]

all_pos_index: iter

Iterable that outputs the tracer number

x_array_shape: (int, int)

Tuple containing the shape of the grid used to generate tracers

See also

flowPath_iteration

function used to perform vector trace visualization for a single frame

flowPath_iteration(frame_no, tracer_pos, all_pos_index, x_array_shape, flow_trace_folder, alpha=0, img_frame=None, frames=10, spacing=8, colormap=None, colormap_min=None, colormap_max=None, metric_type='angle')

Calculates and outputs the flowPath for a single iteration based on the estimated velocity field.

Parameters

frame_noint

Frame number with which to perform vector trace visualization

tracer_pos3D array of shape (frames, tracer_no, 2)

Array containing the positions of the tracers in the format [y,x]

all_pos_index: iter

Iterable that outputs the tracer number

x_array_shape: (int, int)

Tuple containing the shape of the grid used to generate tracers

flow_trace_folderstr

Folder name that will be created in the main directory to store the vector trace images

alphaint

Specifies the alpha value for the flowPath overlay over the original image

framesint

Length of trails in number of frames that will be drawn for each artificial tracer

spacingint

Grid spacing used to initialize tracers

colormapColormap, str, or None

Colormap to be used to colorize the flowPaths

colormap_min, colormap_maxfloat

Minimum and/or maximum value that is used to determine the normalization of the colormap

metric_typestr

Type of metric that is used to colorize the flowPaths

Returns

tracer_pos3D array of shape (frames, tracer_no, 2)

Array containing the positions of the tracers in the format [y,x]

output_image3D array of shape (m, n, 3)

RGB image showing the tails of the tracers

See also

flowPath_initialization

function used to initialize tracers

flowShear_function(output_folder='shear', smoothing=None, colormap=None, colormap_min=None, colormap_max=None)

Calculates gradients and output the simple shear values for an image stack

Parameters

output_folderstr

Folder name that will be created in the main directory to store flow derivative images

smoothingint or Bool

Sigma value for gaussian smoothing

colormap_min, colormap_maxfloat

Minimum and/or maximum value that is used to determine the normalization of the colormap

See also

flowDerivative_iteration

base function to generate flow derivative images

flowTracer_first_frame(tracer_folder, frame_no, tracer_centroids, color, radius=3)

Plots and draws the position of the tracers in the first frame

Parameters

tracer_folderstr

Folder name that will be created in the main directory to store the flowTracer images

frame_noint

Frame number with which to perform vector trace visualization

tracer_centroids3D array of shape (frames, tracer_no, 2)

Array containing the positions of the tracers in the format [y,x]

color2D array

Array containing the color information for each tracer

radiusint

Specifies the radius of the drawn circle

Returns

output_image3D array of shape (m, n, 3)

RGB image showing the position of tracers

flowTracer_function(output_folder='FlowTracer', save_initial_tracer_pos=True, use_random_tracers=True, tracer_no=10000, spacing=16, start_frame=0)

Iterates and plots positions of artificial tracers based on provided motion estimation vectors

Parameters

output_folderstr

Folder name that will be created in the main directory to store the artificial tracer images

save_initial_tracer_posBool

Save initial tracer positions

use_random_tracersBool

If true, generate tracer positions based on a regular grid. If false, generate random position for tracers.

tracer_noint

Maximum number of artificial tracers to use

start_frameint

Frame number with which to start vector trace visualization

spacingint

Grid spacing used to initialize tracers

start_frameint

Frame number with which to start vector trace visualization

flowTracer_initialization(save_initial_tracer_pos=True, use_random_tracers=True, tracer_no=10000, spacing=16, segmentation_filelist=None)

Initializes the tracers that will be used for vector trace visualization

Parameters

save_initial_tracer_posbool

Set to True to save initial positions

use_random_tracersbool

Set to True to use tracers with randomly defined starting x,y positions

spacingint

Grid spacing used to initialize tracers.

tracer_noint or None

Maximum number of tracers to be used in the calculation [Currently unused]

segmentation_filelistlist

List containing the segmented images. Used for setting the location of the intial flowTracers to the center of the segmented objects.

Returns

tracer_pos2D array of shape (tracer_no, 2)

Array containing the positions of the tracers in the format [y,x]

all_pos_index: iter

Iterable that outputs the tracer number

x_array_shape: (int, int)

Tuple containing the shape of the grid used to generate tracers

flowTracer_iteration(tracer_folder, frame_no, tracer_centroids, color, radius=3)

Calculates and outputs flowTracer for a single iteration

Parameters

tracer_folderstr

Folder name that will be created in the main directory to store the flowTracer images

frame_noint

Frame number with which to perform vector trace visualization

tracer_centroids3D array of shape (frames, tracer_no, 2)

Array containing the positions of the tracers in the format [y,x]

color2D array

Array containing the color information for each tracer

radiusint

Specifies the radius of the drawn circle

Returns

tracer_centroids3D array of shape (frames, tracer_no, 2)

Array containing the positions of the tracers in the format [y,x]

output_image3D array of shape (m, n, 3)

RGB image showing the position of tracers

See also

flowTracer_initialization

function used to initialize tracers

flowWarp_function(output_folder='FlowWarp', start_frame=0)

Wrapper function that calls flowWarp_iteration() for each individual pair of frames in the image stack.

Parameters

output_folderstr

Folder name that will be created in the main directory to store the interpolated vector fields

start_frameint

Specify the starting frame to calculate flowWarp

See also

flowWarp_iteration

function used to perform flowWarp for a single frame

flowWarp_iteration(frame_no, transformation_folder)

Performs flowWarp of an image using the calculated velocity field for that image and calculate the normalised root mean squared error between it and the next image in the sequence.

Parameters

frame_noint

Frame number with which to load vector

transformation_folderstr

Path to folder that will be used to store the x component of the interpolated vector field

Returns

nrmseint

Returns the normalized root mean square error between the warped image and the ground truth image

output_imageint

Returns the warped image

initialize_forward_velocities(folder, velocity_type=None, velocity_ext_type=None)

Initializes the internal folder path and file lists for the forward velocities

Parameters

folderstr

Either full path of the directory or the name of the folder in the main path

velocity_typestr or None

Specify if the velocity field is a dense or sparse velocity field

velocity_ext_typestr or None

Specify the extension of file containing the velocity field

initialize_reverse_velocities(folder, velocity_type=None, velocity_ext_type=None)

Initializes the internal folder path and file lists for the forward velocities

Parameters

folderstr

Either full path of the directory or the name of the folder in the main path

velocity_typestr or None

Specify if the velocity field is a dense or sparse velocity field

velocity_ext_typestr or None

Specify the extension of file containing the velocity field

initialize_segmentation_folder(folder, img_ext_type=None)

Initializes the internal folder path and file lists for the segmented images

Parameters

folderstr

Either full path of the directory or the name of the folder in the main path

img_ext_typestr or None

Specify the extension of the image file

load_velocities(filelist, img_no)

Helper function to call the correct loading function based on the type of vectors as specified in self._vector_type

Parameters

filelist(list, list) or (list,)

List of files to be loaded

img_noint

Index to indicate which file number to load

Returns

velocity_y2D numpy array

Array containing the y component of the vectors from motion estimation analysis

velocity_x2D numpy array

Array containing the x component of the vectors from motion estimation analysis

See also

utils.load_vectors_bin

Function to load vector information from optical flow generated *.bin files

utils.load_vectors_piv

Function to load vector information from PIV generated *.mat files

parse_folder(folder)

Appends the main folder director to the folder name given

Parameters

folderstr

Name of folder

Returns

folderstr

Full path string containing the main folder path along with the provided folder

API reference Colormap module