====== PTV Matlab program ======

This T-SAIL WiKi page details the capabilities and the working procedures of a PTV program (Matlab) originally built by Dan. The current version of the program (.zip) can be downloaded [[https://tsail.cv.technion.ac.il:5006//Software/PTV/V1_2016.zip|here]], use liberzon@technion.ac.il for questions.

----
===== Download and install =====
 

The program is Matlab routine available [[https://tsail.cv.technion.ac.il:5006//Software/PTV/V1_2016.zip|here]] for download. After downloading the archive extract its contents into a folder of choice, an additional folder will be created named VXXX (XXX being the current software version number).

===== Short description =====

This PTV routine/program allows you to process series of consecutive images taken at time intervals of dt (frame rate 1/dt) to obtain paths and velocities of particles. The program operates using a GUI (call Main-GUI) and requires the data (series of images) to be prepared in a specific way. See explanations below.

===== Preparing your data (series of images) =====

All images must be saved in .jpeg format, file names may include only letters, numbers and _. Each image file must be numbered in sequential order, numbers appearing after _, for example: 
<code>
ImageL_0123.jpeg
ImageL_0124.jpeg
ImageL_0125.jpeg
ImageL_0126.jpeg
</code>
Make sure enough digits are used and the preceding digits are zeros for numbers of smaller size, e.g. if series contain 1052 images the numbers should be of 4 digits (_0001 or _0123 or _1010). **First image number is 1, not 0**!

Images should contain dark background and bright particles, see example below.

{{ :seed_11817.jpg?600 |Example PTV image}}

Try to avoid blinks, unwanted features and sharp gradients in background/particles illumination. Particles detection is based on brightness threshold. 
Before running the program perform a detailed examination of the images to ne the following features, they will be useful in setting the PTV processing parameters:
Spatial resolution of the images [pix/cm].
Typical diameter of particles [pix].
Brightness value of the bright particles. The images will be converted by the program into 256 shades of gray images.
Total number of particles in each frame and the typical displacement of particles between images. The combinatorics algorithm calculating each particle displacement between each pair of consecutive images has it's limitations. You will have to practice to achieve acceptable seeding parameters for the specific velocities range, but generally 30-50 particles being displaced by 20-40 diameters between each pair of images is the limit.  


===== Using the PTV program =====

Direct Matlab to work in the folder containing the PTV program (i.e. VXXX) and execute/run the main function 
<code>
Main_GUI;
</code>
The program GUI will appear,

{{ :gui.png?600 | GUI, initial view}}

Then follow the routine:
  - Set the ''//Skip # Images//'' parameter (min 1) first.
  - Use the ''**Load Files**'' button to load images to be processed.
  - Use the ''**Select ROI**'' button to select the desired ROI (a Region Of Interest) if only part of the image area is of interest.
  - Set all the required [[ptv_matlab#Parameters|parameters]] to detect all particles. 
  - Use the ''**Preview**'' button to examine the results. If ROI was selected only the relevant part of the image will be displayed in the main plot area. 
  - Set additional [[ptv_matlab#Parameters|parameters]] and perform the calculations. 
  - Use the ''**Calculate Tracks**'' button to calculate the detected particles tracks.
  - Use the ''**Calculate Velocities**'' button to calculate horizontal and vertical velocities. 
  - All resulted/calculated paths and velocities will be stored in .mat and text files in the folder containing the data images. See [[ptv_matlab#Results|Results]] for details. 
    - //Alternatively you can choose previously calculated tracks to recalculate velocities. Choose previously obtained tracks file using the the ''**Browse**'' button to choose the file and use the the ''**Calculate Velocities**'' button again.// 
  - Use the ''**Show Velocities**'' button to plot the obtained velocities as vectors. You can browse between images using the ''**<<**'' and ''**>>**'' buttons below the main plot area.
  - Finally you can use the ''**Save Current Image**'' button to save an screen image of the whole GUI at it's current stage, including the presented results.


===== Parameters =====
A list of parameters required to perform the PTV processing of the images:

^  Parameter      ^  Details/Meaning       ^  Comments          ^
|**Skip # Images**    |Number images to count until the next image to be taken as a pair. Value of 1 means no skipping.      |Useful when only small changes in particles positions between each pair of images are detected. Effectively decreasing velocity detection resolution        |
|**Process plot**    |Turning On/Off real time plotting of each image processing.      |Turning On will result in longer working time, as each image will be re-plotted.        |
|**Particle Size**    |Typical particle diameter, [pix]      |        |
|**Spatial Filter**    |Dimension [pix] threshold for low-pass spatial filter    |Any bright objects of smaller dimensions will be removed from the images       |
|**Brightness Thrsh**    |Brightness threshold, only particles with brightness values above this value will be detected      |        |
|**Centroid part. X**    |Parameter for the centroid detection, [pix]. Helps in detecting the centers of arbitrary shaped particles   |Use value of 1 or 3 or 5 for most cases       |
|**FPS**    |Frame Rate [frames per second] at which the series of images were captured |        |
|**Resolution**    |Spatial resolution of the images [pix/cm]      |        |
|**Min Tracks to show**    |Only particles' paths with number of tracks (displacement between individual pairs of images) above this value will be showed in the final plots. Particles not fulfilling this requirement will anyway be included in the results data files.   | To show all paths use value of 1       |
|**Lost Frames**    | Maximum number of consecutive images allowed for an individual particle to "disappear" from detection      | Using any value greater than 1 is not recommended        |
|**Min. Tracks to detect**    | Only particles' paths with number of tracks (displacement between individual pairs of images) above this value will be included in the results data files.      |To include all paths use value of 1      |
|**Results File Name**    | Base name for all results files. The name includes the date/time of the calculation completion      |See [[ptv_matlab#Results|Results]] for details on the various files containing the results data.      |
|**Scale**    | Scale value for velocity vectors to be plotted. | Values from 0.01 to 1, 1 meaning full scale       |
|**Show Values**    | Turning On/Off presentation of the actual velocity values on top of the plotted velocity vectors     |        |


===== Results=====

The results of PTV processing will be saved in several files and images in the same folder with the original image files. All results containing files and images will have a specific //_NNNN// ending to their respective names, the //NNNN// being the unique name given to the current PTV calculation session. The full list of files is given below.

^  File name  ^  Extension       ^  Contents          ^
|pos_NNNN    |.dat  |Text file containing PTV detected X, Y (first two columns) positions of individual particles. Third column contains "frame" number (consecutive image number), and the forth column contains respective particle number.   |
|velocities_NNNN    |.dat  |Text file containing horizontal and vertical velocities (calculated U and V in the first two columns), in addition to the contents of the pos_NNN file.   |
|parameters_NNNN    |.xls  |Excel table containing all details and parameters used in the current PTV session.   |
|rect_NNNN    |.dat  |Text file containing ROI position and dimensions. NaNs are used if no ROI was selected.   |
|path_NNNN    |.mat  |Matlab file containing the full path to the folder where processed images are stored.   |
|imnames_NNNN    |.mat  |Matlab file containing the list of image files names.   |

Two images are also stored, one depicting the calculated tracks of all particles
{{ :tracks_20110524t113524.png?300 |}}

Second of velocities vectors (if relevant option is selected)
{{ :velocities_20110524t135117.png?300 |}}