To get started using OpticalFlow3D, you first need to install MATLAB, as described in the Dependencies section below. Once MATLAB is installed, a good starting point is the file example_processing_script.m, which provides examples of calculating optical flow. After opening the file, fill in the appropriate paths to the images to be processed, and then run the appropriate code section. To run the code section, first make sure the cursor is anywhere in the section containing the example you are testing, and then press the Run Section button at the top of the editor window. These same instructions can be used to explore the example_analysis_script.m file, which provides example of analyzing the calculated flow fields.
This implementation requires MATLAB R2023a or newer. Eigenvalues are calculated using pageeig, which was not available in previous versions. All testing of this implementation was done in R2024b. Usage in other versions is not guaranteed. In addition to the base installation, the MATLAB installation must include the Image Processing Toolbox.
The package natsort is from the MATLAB File Exchange. The colormaps used are from colorcet, courtesty of Peter Kovesi. Good Colour Maps: How to Design Them. arXiv:1509.03700 2015. Both packages are included in this repository already and do not need to be downloaded separately.
The actual calculation of optical flow is performed by the functions calc_flow3D and calc_flow2D, for 3D and 2D image sequences respectively. Inputs are an image sequence and three smoothing parameters. The only differences in usage between the two functions are (1) whether a 4D or 3D matrix of images is input, and (2) whether flow in the axial direction,
[vx,vy,rel] = calc_flow2D(images, xySig, tSig, wSig)
[vx,vy,vz,rel] = calc_flow3D(images, xyzSig, tSig, wSig)Input images should be of the format
xyzSig is the standard deviation used for Gaussian spatial smoothing and has a default value of 3. Larger values will remove noise but also remove spatial detail.
tSig is the standard deviation used for Gaussian temporal smoothing and has a default value of 1. Larger values remove noise but also remove temporal detail.
wSig is the standard deviation used for Gaussian weighting of the Lucas-Kanade neighborhood. Larger values create a larger neighborhood for the linear algebra solution, and will smooth over small spatial features in the flow.
The function process_flow organizes image sequences into the format required by calc_flow3D and calc_flow2D. If you have a non-tif file type, this function must be adapted to your images.
In addition to the three smoothing parameters described in Calculation, this function requires details about the images to be processed.
process_flow(imDir,imName,fileType,spatialDimensions,xyzSig,tSig,wSig)imDir is the full path to folder of image(s) to process.
imName is the name of the image(s) to process. For a single multi-page tif, this is simply the name of the tif file. For an image series composed of multiple tif files, the imName must be specified with a wildcard (*) for the time expression in the file names. For example, for a list of files with the names:
- myexperiment_t000_ch0.tif
- myexperiment_t001_ch0.tif
- myexperiment_t002_ch0.tif,
the correct ImName would be 'myexperiment_t*_ch0'.
fileType can be either 'OneTif' or 'SequenceT'. For the 'OneTif' type, the entire timelapse and all z-slices are assumed to be saved in one single tif file, and it is assumed the metadata is in the format generated by ImageJ/FIJI. For the 'SequenceT' type, the images are assumed to be saved as a sequence, with one tif per time point (but all z-slices per time point saved in one tif file).
spatialDimensions can be either 2 or 3 based on the number of spatial dimensions of the input data.
The function process_flow excludes the first and last
For each analyzed time point, the function saves four tif files (three for 2D processing). These files correspond to the intensity changes in each directory (
The example_processing_script.m file provides an example of using process flow to analyze a set of images. Example 1 shows how to analyze a series of files (i.e., the 'SequenceT' type), and Example 2 shows how to process multiple folders of 'OneTif' format files at once.
In example_analysis_script.m, the output of the processing script is visualized and analyzed. This analysis requires the image directory and the name of the dataset, as well as metadata about the images. Analysis parameters include a reliability threshold value and parameters to control the visualization. The outputs of this script include visualization of the reliability mask, a quiver visualization of theta, distributions of magnitude and theta, and examples of running these analyses over time.
Briefly, the remaining subfunctions in this folder support image loading and plotting.
natsortallows for appropriate sorting of'SequenceT'filenames.colorcetprovides perceptually uniform colormaps to be used in visualizations.TIFFvolumecan read large multi-page tif files that are greater than >4 GB in size, and is used inprocess_flow.TIFFwriteis used to save the output tif files that represent the optical flow field.