Version 3.0

Smarter Fitting.
Better Workflow.

BubbleTrack v3 brings intelligent parameter tuning, batch processing, interactive visualization, and a streamlined workflow to high-speed bubble analysis.

10 key improvements highlighted below
Auto-Tune Quality Scoring Advanced Filters Batch Processing Video Input Playback R-t Chart Comparison Modes Session & Presets PDF Report
Analysis

Auto-Tune

One click to find the optimal Threshold and Removing Factor. Two-phase coarse-to-fine grid search evaluates ~192 parameter combinations and picks the best by quality score.

  • Phase 1: 9 × 8 = 72 coarse combinations
  • Phase 2: Top 5 candidates refined in 5×5 fine grid
  • Step precision: Threshold ±0.02, RF ±3
  • Binary ROI caching avoids redundant image loads
Coarse-to-Fine Grid Search
Best Top 5 Fine grid
✔ thr = 0.48   RF = 78   confidence 83%
Analysis

Fit Quality Scoring

Every fitted frame gets a quality score from four independent metrics, combined via weighted geometric mean. Bad fits can no longer hide.

  • Edge Density (25%) — Points per circumference pixel
  • RMS Residual (30%) — How tightly points hug the circle
  • Sector Coverage (30%) — Angular spread of edge points
  • Plausibility (15%) — Radius vs. ROI sanity check
85%
Density
72%
RMS
88%
Coverage
100%
Plausible
→
83%
Good Fit
Analysis

Advanced Filters

A collapsible panel of pre-processing filters applied before binarization. Each filter can be independently toggled on/off with real-time preview.

  • Gaussian Blur — Suppress tracer-bead noise
  • CLAHE — Fix uneven lighting
  • Morph Close — Fill gaps in bubble boundary
  • Morph Open — Remove thin spurs on edges
▾ Advanced Filters
Gauss Blur
3
CLAHE
2
Morph Close
5
Morph Open
3
Save Preset
Load Preset
Workflow

Batch Multi-Folder Processing

Process dozens of experiment folders with identical parameters in one go. Select a parent directory and BubbleTrack automatically discovers all image subfolders, fits every frame in parallel, and exports results.

  • Auto-discovers subfolders containing TIFF/PNG/JPG/BMP images
  • Multi-process parallel fitting (4 workers) per folder
  • Exports R_data (pixel) to each folder with timestamp
  • Optional RofT_data (physical) with shared FPS & µm/px
  • Real-time progress: folder count + per-folder frame progress
Batch Multi-Folder
📁 parent_directory/
✔ experiment_001/ 256/256 fitted
✔ experiment_002/ 180/200 fitted
▶ experiment_003/ 72/150...
⏳ experiment_004/ waiting
📄 R_data_20260324.mat 📄 RofT_data_20260324.mat
Workflow

Video File Support

Directly open AVI, MP4, MOV, or MKV video files. No need to pre-extract frames — BubbleTrack reads them on the fly with frame-accurate seeking.

  • OpenCV VideoCapture backend for broad codec support
  • Auto-detects FPS and applies to R(t) time-axis export
  • Virtual frame list — existing pipeline works unchanged
  • Works with both image folders and video files
🎬
.AVI
.MP4
.MOV
.MKV
1200 frames  |  experiment_01.avi  |  5000.0 fps
Workflow

Frame Playback

Review results frame-by-frame or hit play to watch the full sequence animate. Adjustable speed from 1 to 60 fps.

  • Play / Pause with on-screen button or Space key
  • Auto-stops at end of sequence
  • Starting from end wraps back to frame 1
  • Arrow keys for single-frame stepping
Frame 42 / 120
⏪
⏸
⏩
10 fps
← Prev
Space — Play/Pause
Next →
Visualization

Interactive R-t Chart

Replaced Matplotlib with pyqtgraph for real-time, GPU-accelerated scatter plotting. Click any point to jump to that frame; right-click to delete or refit a single result on the spot.

  • Hover to see frame number, radius, and quality score
  • Mouse-wheel zoom and pan to inspect dense regions
  • Click-to-jump with generous 3% hit tolerance
  • Double-click or "Reset Zoom" to restore full view
  • Right-click → Delete point or Refit frame instantly
Reset Zoom
Radius (px) Frame Frame: 8   R: 91.2 px   Q: 82%
⬤ Good fit ⬤ Fair fit ⬤ Poor fit
Visualization

Image Comparison Modes

Instantly switch between three viewing modes to inspect how binarization performs on the current frame.

  • Side by Side — Original and binary in separate panels
  • Overlay — Green-tinted binary mask blended over grayscale
  • Wipe — Drag-split with red divider line
Side by Side Overlay Wipe
R = 87.3 px
Data Management

Session & Presets

Save your entire workspace as a .brt session file and resume later. Share filter configurations across experiments with JSON presets.

  • Session — Saves parameters, results, ROI, folder path
  • Presets — Save/load threshold, RF, edges, and all filter values
  • Auto-persist — Last-used parameters restored on next launch
.brt
Session File
.json
Preset File
⚙
Auto Config
File → Save Session  |  File → Load Session
Data Management

PDF Report

Generate a one-page PDF summary with processing parameters, statistical results, and the R-t chart — ready to paste into a lab notebook or share with collaborators.

  • Parameters table: threshold, RF, ROI, filters
  • Statistics: frame count, mean/std radius, quality distribution
  • Embedded R-t chart image
  • Auto-named with timestamp
BubbleTrack Report
Parameters
Threshold: 0.48   RF: 78
ROI: [42, 230] × [15, 188]
Statistics
Frames: 120   Fitted: 118
Mean R: 87.3 ± 2.1 px
R-t Chart
Generated by BubbleTrack v3

Ready to try BubbleTrack v3?

Clone the repo, install dependencies, and start analyzing.

View on GitHub →