Turbulence Realm – Tracker

TR-Tracker Version 1.0

Download

This is a windows x64 installer file and tested to work with intel computers running Windows 11

Note: Software provides analysis based on the quality of input data, applicability, settings and other parameters

How to Use Turbulence Realm – Tracker

The Turbulence Realm-Tracker is a dedicated application designed for analyzing the motion of selected regions, such as bubbles, within video recordings. It provides tools to quantify velocity and displacement, offering valuable insights for fluid dynamics studies.

Launch the Application

  • Run the setup file, install and run the application. Note: Depending on the configuration of the computer, there would be delays in loading the application. You can use the video below to see an example (AI generated fluid flow video file) or use written instructions below.

The analysis process within the Turbulence Realm-Tracker follows a clear, step-by-step workflow:

  1. Load Video
    • Initiate by selecting ‘File’ > ‘Open Video’ from the menu bar or by clicking the ‘Load Video’ button.
    • The application supports common video formats, including MP4, AVI, MOV, and MPEG.
  2. Calibrate
    • Click the ‘Calibrate’ button to begin the calibration process.
    • Input the known real-world distance corresponding to your calibration line into the “Calibration Distance (m)” field.
    • On the video frame, click and drag to draw a line that represents this known distance.
    • The software will automatically calculate and display the scale (meters per pixel).
    • Press the ‘Esc’ key at any time to cancel the calibration drawing.
  3. Select Bubbles
    • Once calibration is complete, the ‘Select Bubbles’ button will become active. Click it to enter bubble selection mode.
    • Click and drag on the video frame to define rectangular Regions of Interest (ROIs) around the bubbles you intend to track.
    • Each newly selected bubble will be added to the “Selected Bubble” drop-down list. The initial size of the selected bubble, in both pixels and meters, will be displayed beneath the drop-down.
    • Press the ‘Esc’ key to exit bubble selection mode.
  4. Start Tracking
    • The ‘Start Tracking’ button will be enabled after at least one bubble has been selected. Click it to commence tracking.
    • The application will process the video frame by frame, continuously tracking the defined bubbles.
    • The button’s text will change to “Stop Tracking.” You can click it again or press the ‘Esc’ key to halt the tracking process prematurely.
  5. View Analysis
    • During or after tracking, select a specific bubble from the “Selected Bubble” drop-down.
    • The corresponding velocity and displacement plots for that bubble will be displayed and updated automatically in real-time.
  6. Save Data
    • To save the raw tracking data, click ‘Save Data’ or navigate to ‘File’ > ‘Save Results’.
    • The data, including positions, velocities, and displacements, will be saved as CSV files within a timestamped sub-folder.
    • Each CSV file will include the initial bubble size (in pixels and meters) as a comment for reference.
  7. Export Plots
    • To save the currently displayed velocity and displacement plots, click ‘Export Plots’ or go to ‘File’ > ‘Export Plots’.
    • The plots will be saved as high-resolution PNG image files.
  8. Show Statistics
    • Click the ‘Analyze’ button to view a summary of key statistics for all tracked bubbles.
    • This summary includes average and maximum speeds, as well as final displacement values, and the initial bubble size.

Controls & Features

  • Video Display: The central area for viewing the video, overlaid with calibration lines, selected bubble ROIs, and tracking paths.
  • Zoom Functionality: Adjust the video display’s magnification using ‘View’ > ‘Zoom In’, ‘Zoom Out’, or ‘Reset’. Keyboard shortcuts Ctrl++, Ctrl+-, and Ctrl+0 are also available.
  • Status Bar: Located at the bottom of the window, it provides real-time feedback on current operations, loaded video information, and calibration status.
  • Mouse Interaction: Essential for drawing calibration lines and defining bubble ROIs through click-and-drag actions.
  • Escape Key (Esc): A universal key for:
    • Canceling the current drawing mode (calibration or bubble selection).
    • Stopping an active tracking session.

Data Output

  • CSV Files: Detailed, per-frame data for each tracked bubble. This includes:
    • Time (in seconds)
    • X and Y pixel positions
    • Velocity components (Vx, Vy in m/s) and total speed (m/s)
    • Displacement components (ΔX, ΔY in m) and total displacement magnitude (m)
    • Initial bubble size (pixels and meters) as a comment.
  • PNG Images: High-resolution image files of the generated velocity and displacement plots.

Troubleshooting

  • Performance Issues: If video playback is slow or the user interface becomes unresponsive during tracking, it may indicate that the video resolution is too high for your system’s capabilities or that the system is under-powered.
  • Accuracy of Results: Accurate calibration is paramount for obtaining precise metric results. Ensure the calibration line accurately represents the known real-world distance.