Tutorials

Installation & setup

Both Turbulence Realm-Tracker and Turbulence Realm SINDy ship as platform-specific installers that bundle every dependency — no Python installation is required. This tutorial covers the Windows setup installer and the Linux .deb / .run installers for both apps.

Windows — setup installer (recommended)

Both apps use an Inno Setup installer wizard with a no-liability disclaimer on the license page.

1. Download the setup installer:
   • Tracker: TurbulenceRealmTracker-3.0.0-setup.exe (78 MB) from the download page
   • SINDy: TurbulenceRealmSINDy-2.2.0-Setup.exe (120 MB) from the download page
2. Double-click the downloaded .exe to launch the installer.
3. Read and accept the no-liability disclaimer on the license page.
4. Choose the install location (defaults to Program Files).
5. Select Start Menu shortcuts and an optional desktop icon.
6. Click Install — the app is ready to use from the Start Menu.

Uninstall: Add/Remove Programs (Settings → Apps) → Turbulence Realm-Tracker / Turbulence Realm SINDy → Uninstall.

Linux — .deb package (Debian/Ubuntu)

The .deb package installs to /opt, creates an XDG Applications menu entry (Science category) with icon, adds a PATH symlink, and includes clean uninstall scripts.

Launch from Applications → Science → Turbulence Realm-Tracker (or SINDy), or run TurbulenceRealmTracker / TurbulenceRealmSINDy in a terminal.

Uninstall: sudo dpkg -r turbulencerealmtracker (or turbulencerealm-sindy).

Linux — .run self-extracting installer (any distro)

The .run installer works on any Linux distribution. It displays the no-liability disclaimer in the terminal, installs to /opt (or $HOME/.local for non-root), creates a menu entry, and offers a desktop shortcut.

Read and accept the no-liability disclaimer (type y). Launch from the Applications menu or run the app command in a terminal.

Uninstall:

• Tracker: sudo /opt/TurbulenceRealmTracker/uninstall.sh
• SINDy: /opt/TurbulenceRealmSINDy/install.sh --uninstall

System requirements

• Windows: Windows 10/11 (x64)
• Linux: Ubuntu 20.04+ / Debian 11+ / Fedora 33+ (x64) with X11, OpenGL, fontconfig, libGL, libEGL, and libglib2.0
• Tracker: 4 GB RAM (8 GB recommended), 500 MB disk
• SINDy: 8 GB RAM (16 GB recommended for ML), 1 GB disk, optional NVIDIA GPU with CUDA for ML training
• A display (the GUI requires a desktop environment)

Verifying the installation

After installation, launch either app. You should see the Turbulence Realm gold/cream UI with the brand logo. If you get missing library errors on Linux, install them:

Once the app launches, continue to Tutorial 01 — Your first tracking run or Tutorial 05 — From video to equation.

Your first tracking run

This tutorial walks through the basic workflow end to end — from loading a video to exporting your first velocity dataset.

1. Load a video

File → Open Video… (Ctrl+O) or the Load Video button. Supported formats: MP4, AVI, MOV, MPEG, MKV.

2. Calibrate

1. Enter the real-world distance in Calibration Distance (m).
2. Click Calibrate.
3. Click and drag on the frame to draw a line spanning that distance.
4. The scale (m/px) is computed and shown in the status bar.

3. Select bubbles

Click Select Bubbles (Ctrl+B) and drag rectangles around each bubble. Use Tools → Auto-detect Bubbles to let the app propose ROIs you can accept or refine.

4. Track

Click Start Tracking (Ctrl+T). Tracking runs on a background thread; the UI stays responsive. Live velocity/displacement plots and metrics update as frames are processed.

5. Review & export

• Pick a bubble from the dropdown to view its plots.
• Analyze shows summary statistics.
• Save Data (Ctrl+S) exports CSV + JSON.
• File → Export Plots… saves high-resolution PNGs.
• Session → Save Session persists the whole run for later re-analysis.

6. Auto-save & recovery

Progress is auto-saved to ~/.tr_track/.tr_track_autosave/. If the app crashes, restart and choose File → Recover Auto-saved Progress….

Multi-point & grid calibration

Multi-point calibration

Draw several calibration lines of known length. The app combines them into a robust scale (median of per-point scales) and reports an error margin (coefficient of variation). A margin below 5% is considered reliable.

Grid / checkerboard calibration

For camera distortion correction, print a standard checkerboard pattern and hold it in the camera's field of view. Use Tools → Grid Calibration, enter the square size, and the app will:

1. Detect the inner corners with cv2.findChessboardCorners.
2. Derive the scale from the average corner spacing.
3. Report the per-corner variation as an accuracy indicator.

Calibration history

Every calibration is recorded per video. Use Tools → Calibration History to reuse or compare previous calibrations for the same footage.

Presets

Tools → Calibration Presets offers common reference distances (1 mm capillary, 10 cm tank, 50 cm flume, 1 m basin) so you don't have to type the number each time.

Advanced analysis & data science

Turn raw tracks into publishable insight with the analysis and data-science tools.

Statistics & smoothing

Analysis → Statistics Summary shows average and maximum speed, final displacement, and per-bubble sizing. Advanced Analysis runs the full pipeline: Savitzky-Golay smoothing (configurable window), acceleration computation, comparative cross-correlation between bubble pairs, bootstrap confidence intervals, and Welch's t-test for significance.

Statistical report

Analysis → Statistical Report generates a comprehensive Markdown report with descriptive statistics, per-bubble summaries, and comparative tables — ready to drop into a paper.

FFT analysis

Analysis → FFT Analysis computes the Fast Fourier Transform of each bubble's velocity signal, reporting the dominant frequency (Hz) and its magnitude. Useful for detecting oscillation patterns.

Bubble classification & prediction

• Bubble Classification classifies each bubble's motion pattern (e.g. "rising", "oscillating", "turbulent") based on statistical features, with a confidence score.
• Trajectory Prediction predicts the future trajectory using linear extrapolation. Configure the prediction horizon (number of frames) and review the predicted final position.

Visualization export

File → Visualization Export produces 3D trajectories, movement heatmaps, contact-sheet time-lapses, and time-lapse videos for every bubble.

From video to equation

The core SINDy workflow: extract a velocity field with optical flow, fit a sparse dynamics model, and read off the discovered governing equation.

1. Open a video & select ROI

Click Browse… in the Video Source card or use File → Open Video (Ctrl+O). Then click Select ROI & Calibrate: draw a rectangle over the region of interest, draw a calibration line of known physical length, enter the real-world length in meters, and click OK. The calibration readout updates to show meters-per-pixel.

2. Configure optical flow

Choose a backend and options in the Optical Flow card:

• Backend: farneback (default, robust), lucas_kanade (sparse, fast), tvl1 (needs opencv-contrib), raft / pwcnet (deep learning, needs torch).
• Smoothing: none, ema, or moving to reduce flicker between frames.
• Multi-scale pyramid for large motions; Gaussian / NLM denoise for cleaner flow.

3. Configure SINDy

• Library: polynomial, fourier, combined (poly × Fourier), custom, trig.
• Degree: polynomial degree (1–5).
• Optimizer: stlsq (default), sr3, frols, constrained_sr3.
• Threshold: sparsity threshold (0.001–1.0). Higher = sparser model.
• Divergence-free: enforce incompressibility (∇·u = 0).

4. Run the pipeline

Click the buttons in order:

1. ① Process Optical Flow — extracts the velocity field. A live HSV + quiver preview appears with progress and ETA.
2. ② Run SINDy Modeling — fits the sparse dynamics model. Use Equation to view the discovered equation, Cross-validate for k-fold CV, or Compare to try multiple libraries.
3. ③ Run SINDy Prediction — reconstructs the predicted velocity field.

5. Read the equation

After modeling, the Equation view shows the discovered sparse coefficients as a human-readable system of ODEs — the governing equation of your flow, learned directly from video.

ML models & visualization

Train a physics-informed model

On the ML Models page select a model, adjust hyperparameters in the parameter panel, and click Train. Training logs appear in the in-app log widget. Trained models can be exported to TorchScript / ONNX.

• PINN — Physics-Informed Neural Network with Navier-Stokes residuals.
• Autoencoder-SINDy — compressed latent-space SINDy.
• FNO — Fourier Neural Operator for flow prediction.
• DeepONet — Deep Operator Network.
• ConvLSTM — recurrent convolutional model for temporal sequences.
• VAE / beta-VAE — variational autoencoder for flow generation.
• GAN — Generative Adversarial Network for flow synthesis.
• Ensemble — SINDy ensemble with uncertainty quantification.
• Granger causality — causal analysis between flow variables.

Visualize the results

On the Visualization page, after running the pipeline:

• Quiver plot — side-by-side actual vs SINDy-predicted velocity arrows.
• Contour / streamlines — velocity magnitude contours or streamline plots.
• Vorticity / strain — color-mapped vorticity and strain-rate fields.
• Animated heatmap — play through frames as an animated velocity heatmap.
• Custom colormap — choose from matplotlib colormaps.
• Data table — tabular view of the velocity data.

Export with provenance

Export to CSV, HDF5, NetCDF, Parquet, or JSON metadata — each export embeds full provenance (git commit, package versions, config, seed, input SHA-256) so every result is reproducible. File → Export can also produce a PDF report and an MP4 quiver animation (FFmpeg required).