Particle Image Velocimetry (PIV) package developed in the Stramer Lab (King's College London, UK). Please check our publication on Nature Cell Biology for more details (release v1.0).
An introduction to the software and a live demonstration can be found here, in a recorded talk of the SORSE (Series of Online Research Software Events) series.
Tested on MATLAB v2018B. The Curve Fitting Toolbox is required.
This PIV code comes without a graphic user interface (GUI) and should be run in MATLAB as a script (open .m file and hit Run). It is used as follow. See here for further references.
Segmented stacks of biological samples to be analysed should be pre-processed as follows:
- Open stack in ImageJ
- Split channels (e.g. green - actin, magenta - nucleus)
- Save channel containing the entity to be measured by PIV (e.g. green - actin) as [cb#_m.tif], where cb stands for cell body, # is a progressive integer number, and m stands for moving
- Save channel containing the entity used for tracking (e.g. magenta - nucleus) as [n#_m.tif]
- If working with cells, segment out the cell body from the entity to be measured by PIV (e.g. green - actin) and save this one-channel stack as [no_cb#_m.tif] (no cell body). This is needed for the [eroded_heatmap.m] script (see below).
- Store [cb#_m.tif], [n#_m.tif] and [no_cb#_m.tif] in a folder (e.g. [cell1]), where the PIV output is going to be saved
Clone this repository locally in your machine. Make sure the MATLAB folder in which you set your environment contains the following scripts: [happy_piv.m], [run_piv.m], [create_retro_flow_image.m], [detectObjectBw.m], [generate_plot_normalized.m] and, if needed, [eroded_heatmap.m].
To run the PIV follow these instructions:
- Run [happy_piv.m]
- input requested to the user:
- stack of the entity to be measured by PIV [cb#_m.tif]
- name for the output stamp to be appended to all saved output files (e.g. [output_name]: cell1)
- PIV parameters:
- Source size [um]: size of the region of interest (ROI) to be tracked in the next frame [um]
- Search size [um]: size of the region to be used in the next frame for searching the ROI [um]
- Grid distance [um]: grid spacing for ROI mapping [um]
- Correlation threshold [-]
- Pixel size [um]: image calibration of the loaded movie (length of a pixel in [um])
- Frame interval [s]: time calibration of the loaded movie (frame interval in [s])
- Frame rate to be analysed [-]: interval of frames of the loaded movie to be analysed (if 1: all the frames will be analysed, if 2: every other frame, and so on)
- Max number of frames to be analysed [frames] : maximum number of frames to be analysed (the default value displays the total available frames, do not change if wanting to analyse the whole movie)
- Interpolation parameters (only prompted if interpolation is requested):
- Spatial kernel size [um]: size of the spatial Gaussian kernel for interpolation
- Spatial kernel sigma [um]: sigma (variance) of the spatial Gaussian kernel for interpolation
- Max flow velocity to be displayed in colourmap [um/min]: upper limit of colour map in [um/min] for the heatmap
- Flow field arrow distance [um]: distance of the arrow showing the vector field in the heatmap [um]
- if parameters need to be optimised it is possible to show the frame correlation for a single frame, by hitting Yes when prompted with the relevant question "Do you want to test frame correlation to adjust the parameters?". This can be done multiple times, until the user doesn't reply Yes to the following question "Are you happy with the frame correlation test?".
- Once the parameters are set, the PIV on all frames can be run by hitting No when prompted with the question "Do you want to test frame correlation to adjust the parameters?". The parameters are saved in the folder [parameters] which can be found where the loaded movie is stored (e.g. [cell1]).
- The first phase of the PIV works out the raw vector fields in [um/min], which is visually displayed for each frame. The stack ([piv_raw_(output_name).tif]) and the numerical data ([piv_field_raw_(output_name).mat]) are saved in the folder [images] and [data] respectively. Both folders can be found where the loaded movie is stored (e.g. [cell1]).
- The second phase of the PIV interpolates the raw vector fields to obtained the interpolated field heatmap in [um/min], which is visually displayed for each frame. This second part is optional, and will be run only if the user answer Yes when prompted with the question "Do you want to interpolate the vector field?". The spatial kernel parameters are chosen by the user, while the temporal kernel interpolates within 5 frames as default. The stack ([piv_interpolated_(output_name).tif]) and the numerical data ([piv_field_interpolated_(output_name).mat]) are saved in the folder [images] and [data] respectively.
- More refined interpolated heatmaps can be obtained by running the [eroded_heatmap.m] script
- input requested to the user:
- folder containing [cb#_m.tif], [no_cb#_m.tif] and PIV output (e.g. [cell1]). If working with cell images for which the [no_cb#_m.tif] is available, the final heatmaps will not show overlayed vectors for this area. If the file [no_cb#_m.tif] does not exist, the heatmap will display the original entity in full.
- name for the output stamp to be appended to all saved output files (e.g. [output_name]: cell1); need to be the same assigned when running [happy_piv.m]!
- the movie ID (# in [cb#_m.tif] and [no_cb#_m.tif])
- this script returns the refined stack ([piv_field_interpolated_eroded_(output_name).tif]), containing the heatmaps of the interpolated PIV field overlayed with the flow vectors (excluded the cell body if applicable).