Particle Tracking

A particle tracker is available for use with the Weather in a Tank apparatus.  Black or white paper dots floating on the surface of the water make excellent ‘particles’ to track. The tracking software can be driven from the live video source provided by the turntable camera or from a recorded file.

The provided particle tracker is currently only for Windows platforms. The tracker can be downloaded here:  Particle Tracker 2.2b

A Manual describing how to use the particle tracker can be found here:  ptrack 1.9b. The manual reviews options in the software’s side-panel, tabs, and right-click menus.

The developer page is here.

We describe below how to input video sources to the tracker and output tracking data for analysis.

Video input from live sources or recorded file

The checkbox [   ] Connect to camera (at top-left of particle tracker program window) is used to select from available camera sources:

  • For tracking particles live or from DVD-playback of recorded videos, as described in video signals, select the (RCA-to-USB) frame-grabber’s camera source.
  • Recorded video playback of an experiment (for example, an MP4 in a media player) can be streamed into the particle tracker as a camera source, as described in ‘Screen-casting playback to a virtual camera’ below.  In this case, select Spout Cam as your source.

Note: If an incoming video source is appearing but not filling the particle tracker’s view-frame window, adjust the application-scaling percentage in the Display Settings of the computer.

Natively, the [>] button (in the upper-left of the tracker program window) will load a video file, in a tracker-specific format: uncompressed AVI, 640×480 pixel resolution, ≤ 2.5 minutes in length. If you wish to use this built-in player, details of how the video must be configured are described in the Conversion section below.

Be aware, when playing back a file in-tracker, the video will loop by default, clearing any track data when the clip restarts. To avoid losing data, stop tracking & halt video playback with the [ II ] button before the clip completes (frame-count displayed in program side-panel), then proceed to select tracks for export.

Outputting track data to a file

Whenever a video (with particles moving) is active in the tracker’s view frame, check the “Track” box to initiate logging of particle positions over time. The tracks themselves are displayed as color trails, comprised of dots marked at a definable frame sampling interval.

Right-clicking a displayed track will open a context menu. In the Tracking sub-menu, ‘Select a Track’ will save the logged track data to a .txt file of comma separated values in the user’s Documents folder. Particle position data is stored in ‘pixel coordinates’ within the 640×480 view frame.

You can work with the track data in ‘pixel coordinates’, or convert to Cartesian or Polar coordinates as described here. Mousing over the video view frame, a pixel’s coordinates <x y> are displayed in the tracker’s side-panel. This can be helpful, for example, in approximating a circular tank’s center for polar transformations.

This step-by-step guide examples a process of using the particle tracker on a Windows platform. Some steps are specific to the local lab’s computer-IP camera set-up, others more general. With updating operating systems, parts of this guide are elaborated or modified as follows.

Taking a snapshot

A screenshot of the active window can be taken in Windows 10 with the Win+Alt+Print Screen keys, or Win+G to open the game-bar and selecting the camera icon. These are saved to “C:\Users\[username]\Videos\Captures” by default. Optionally, the game-bar can enable video to be recorded of the tracking in action.

When an individual track is selected for output, the track data being logged to file is displayed temporarily in a prioritized tab. It can be useful to take a screenshot of your sequence of selected tracks, to aid in filtering out erroneous tracks / selecting the clearest tracks to analyze.

Conversion to tracker’s native video format

For a video file to load directly into the particle tracker (with [>] ), the format should be an AVI with:

  • no compression,
  • 24-bit color scale,
  • 640×480 image resolution,
  • under 2 min 35sec duration

Thus, files in compressed formats need to be converted, wider videos need to be cropped to 4:3 proportions, and longer recordings need to be clipped.

Conversion scripts from formats such as MP4, assisting in clipping, cropping, and rescaling video can be found in the Resources at page bottom. Converted clips can be loaded into the particle tracker with the [>] button in the program’s Video Control panel.

Screen-casting playback to a virtual camera

As an alternative to clip, crop, and converting files, one may use the provided screen-casting companion tool to capture on-screen playback of experiment video and route it to a virtual camera readable by the particle tracker. After confirming or configuring the screen-region containing the media to be casted, check “Connect to Camera” in the tracker and select SpoutCam as source.

Spoutcam screencast

This tool may be used in conjunction with a media player & the particle tracker, as a virtual camera source appearing when the program is loaded, to circumvent the need to convert video files. However, because it works via screen capture, all events displayed in the capture region will appear in the tracker, including the mouse cursor if it enters the media player’s window during playback / tracking!

Note then that the computer used for analysis needs sufficient display space to show the particle tracker and the playing video (or live stream) without them obstructing each other; in this respect, an additional monitor for dedicated playback might be considered to reduce window clutter. Of course, the media playback window can be scaled-down if necessary, to the limit of resolving particles in the tracker’s view frame, but if you change these settings between tracking sessions on the same experiment, you might consider making note of the pixel coordinates of tank center and a length scale (like tank width, or a ruler’s length) to normalize your measures by.

Once the particle tracker and media player windows have their locations fixed on screen, bring up the Spout-caster and configure the capture region by identifying either:

METHOD I: experiment center

With the Spout-cast window in focus, hover the mouse cursor over the displayed experiment’s center in the media player and press 8 or * on the keyboard. This will create a 640×480 capture region around that point. You may use the zoom slider to adjust the size of the capture region around this center point, until the video / fluid volume fits well into the screen-cast frame.

METHOD II: corners of the INPUT VIDEO

With the Spout-cast window in focus, hover the mouse cursor over the top left corner of the video in the media player and press 9 or ( on keyboard. Then hover the mouse over the bottom right corner of the video in the media player and press 0 or ) on keyboard. This will set a rectangle of 4:3 proportion as the capture region, according to the height of defined area.

After (or during) configuring,  check the [   ] “Connect to camera” box in the particle tracker side-panel, and select the Spout Cam source. A stream, captured live from the screen, will be displayed into the Particle Tracker’s view frame window. Adjust settings in the screen-caster tool if necessary, then minimize the program.

Particle track analysis on video playback

In the particle tracker view frame window, double click the tank’s center to position any exterior/interior masks—applied to remove the counter-rotating environment or noise from, e.g., tank edge/can center etc. You are now ready to track particles by checking “Track”.

Halt the tracker (uncheck “Track”) before stopping the video player. To output a particular track to file, right click a color track to open up a context menu, and under “Tracking >” choose “Select Track” to save to a .txt file in user’s Documents folder. From the Selected Track tab, go back to the Video tab in the tracker, and repeat this process 1-by-1 for all the tracks desired for saving to output file.

Sometimes tracks that overlap can be difficult to select, outputting multiple tracks together as one. This can be a surprise. For this reason, taking a snapshot of each track output (on Windows 10, using Win+Alt+Print Screen, or Win + G gives options to save a picture of the Tracker window) can be helpful in reviewing or parsing track data in subsequent analysis.

Right click anywhere in the particle tracker view frame and in “Tracking >” select “Clear Logs” to start fresh, retry tracking with a different starting time, or process another section of the video. The tracker will report the position data timestamped to the system time that playback occurred.

Resources / provided software + scripts:

PARTICLE TRACKER

Application for Windows:    Particle Tracker 2.2b
Manual:     ptrack 1.9b            Developer page

Using the Particle Tracker, walk-through – Fluids Lab, 2011

SPOUTCAM SCREENCASTER, FOR PARTICLE TRACKER

Application for Windows:   Spoutcam Screencaster
Zipped executable; created with Max MSP / Jitter.
For casting video playing on-screen into the particle tracker as a live source.
{ For reference guide, see above. }

CONVERSION SCRIPT TO Particle TRACKer NATIVE AVI

Zipped batch files; using ffmpeg
Requires install of ffmpeg, instructions for Windows  / Mac

To convert to the native format, download the .zip file containing scripts and unzip to a directory. The desired operations will be performed with ffmpeg. For these scripts to function, first install and carefully add ffmpeg to the Windows’ system PATH as described here.

Then:

  1. Place an mp4 file in the directory, with compat.avi and the included batch files.
  2. Drag & drop the file(s) through the operations, “CLIP,” “CROP,” “CONVERT,” with the respective .BAT files. Each will output a file to be used in the subsequent stage, which you can configure by right clicking that .bat, to open with > a text editor.
  3. The final AVI file should now load in to particle tracker with the [>] button.

Related Links:

Recording co-rotating video

Transforming from Pixel coordinates to Cartesian and Polar coordinates

Weather in a Tank Apparatus