OpenLPT - Open-source Lagrangian Particle Tracking GUI

OpenLPT is a powerful, user-friendly open-source software for 3D Lagrangian Particle Tracking (LPT), designed for experimental fluid dynamics and flow visualization. Developed by the Ni Research Lab at Johns Hopkins University (JHU), it provides a comprehensive GUI-based workflow for high-precision particle tracking and reconstruction.

🚀 Key Capabilities

• 3D Particle Tracking: Robust Lagrangian tracking (LPT) and Shake-the-Box (STB) methods.
• Multi-Camera Calibration: Easy-to-use tools for wand and plate calibration (intrinsic & extrinsic parameters).
  • Note: The current calibration implementation assumes no refraction. For experimental setups involving observation windows, it is critical that the cameras are oriented as close to the surface normal (orthogonal) as possible.
• Cross-Platform: Full support for Windows, macOS, and Linux.
• Performance: High-performance C++ core with Python Python bindings for flexibility and speed.

Keywords: Lagrangian Particle Tracking (LPT), Shake-the-Box (STB), 3D Flow Visualization, PIV, Particle Reconstruction, Multi-camera Calibration, Experimental Fluid Dynamics, JHU Ni Research Lab.

Quick Start

[!TIP] Ensure you have activated your environment before running these commands: conda activate OpenLPT (On Windows, we recommend using Command Prompt (CMD) as PowerShell may have execution policy restrictions).

1. Graphical User Interface (GUI)

# Launch the interactive GUI
openlpt-gui

2. Command Line Interface (CLI)

# Run STB tracking directly with a config file
openlpt path/to/config.txt

# Show image preprocessing CLI help
openlpt preprocess --help

3. Python API

import openlpt as lpt

# Run tracking programmatically
lpt.run('path/to/config.txt')

# Or launch GUI from within a script
lpt.launch_gui()

Demo

https://github.com/user-attachments/assets/60579007-4f24-4989-8b36-3de2224c9797

Features

• User-friendly interface in python
• Lagrangian particle tracking for multiple objects (point-like particles, spherical particles, etc.)
• Support stereomatching with multiple cameras (at least 2)
• Include multiple test cases for users to test and understand the code
• Better structure for adding new functions

Installation

Method 1: One-Click Installation (Recommended for developers)

We provide automated scripts that set up everything for you (including Conda, environment, and dependencies).

1. Download the code:

   git clone https://github.com/JHU-NI-LAB/OpenLPT_GUI.git
   cd OpenLPT_GUI
   

2. Run the Installer:

   • Windows: Double-click install_windows.bat (Or run in terminal: install_windows.bat)

   • macOS: Run in terminal:

     bash install_mac.command
     

   • Linux: Run in terminal:

     bash install_linux.sh
     

3. Launch the GUI: After installation, simply run:

   openlpt-gui
   

Method 2: Direct Pip Installation (Easiest)

You can install OpenLPT directly from PyPI:

• For GUI Support (Recommended):

  pip install "openlpt[gui]"
  

• For CLI-only:

  pip install "openlpt"
  

export CC="$CONDA_PREFIX/bin/clang"
export CXX="$CONDA_PREFIX/bin/clang++"
export CPPFLAGS="-I$CONDA_PREFIX/include"
export LDFLAGS="-L$CONDA_PREFIX/lib -lomp"
pip install -e .

Samples and Tests

Please see the sample format of configuration files, camera files and image files in /test/test_STB or /test/test_STB_Bubble.

To run the sample:

1. Open OpenLPT GUI.
2. Load the project configuration from the sample folders.
3. Click 'Run tracking'.

CLI Image Preprocessing

Use openlpt preprocess to convert TIFF image lists, direct TIFF files, or Phantom CINE files into processed TIFF outputs plus OpenLPT image lists.

Auto-detect cameras from a data root

openlpt preprocess \
  --input-root I:/VONSET/Data/20230123/T2 \
  --frames 0 999

--input-root auto-detects cameras in natural order. It first looks for CINE files in ROOT/Cam1/*.cine, ROOT/Cam2/*.cine, ... (case-insensitive directory names are fine), and also supports flat roots such as ROOT/cam1.cine, ROOT/cam2.cine. If --output-dir is omitted in this mode, output defaults to ROOT/imgFile.

TIFF list preprocessing

openlpt preprocess \
  --input-list cam1_images.txt \
  --input-list cam2_images.txt \
  --output-dir processed_tiffs

CINE preprocessing on a cluster

openlpt preprocess \
  --input-root /scratch/run01 \
  --frames 0 999 \
  --background mean

You can still use direct --cine paths when needed:

openlpt preprocess \
  --cine /scratch/cam1.cine \
  --cine /scratch/cam2.cine \
  --frames 0 999 \
  --output-dir /scratch/preprocessed \
  --background mean

Mean background, invert, and output image lists

openlpt preprocess \
  --input-list cam1_images.txt \
  --output-dir processed_tiffs \
  --background mean \
  --bg-count 50 \
  --bg-stride 5 \
  --invert

Parallel processing with multiple workers

openlpt preprocess \
  --input-list cam1_images.txt \
  --input-list cam2_images.txt \
  --output-dir processed_tiffs \
  --workers 4

Use --workers 0 to use all available CPU cores, which is convenient for cluster jobs:

openlpt preprocess \
  --cine /scratch/cam1.cine \
  --frames 0 999 \
  --output-dir /scratch/preprocessed \
  --workers 0

Processed TIFFs are written under OUTPUT_DIR/camN/, and per-camera image lists are written as OUTPUT_DIR/camN_image_list.txt.

For --input-root, TIFF camera folders under the root are also auto-detected and processed in natural camera order. TIFF root mode currently expects per-camera subdirectories; flat TIFF roots are not auto-grouped.

In the GUI preprocessing panel, use Generate CLI below Process Image (Batch Export) to create a command from the current GUI settings. When all loaded CINE files share a common ROOT/CamN/ layout, the generated command prefers --input-root ROOT and uses ROOT/imgFile rather than imgFile_processed.

[!NOTE] CINE preprocessing requires pycine, which is listed in this repository's requirements.txt and pyproject.toml. The preprocessing CLI modules are headless/Qt-free, but some full-repository install routes also include GUI dependencies such as PySide6.

Citation

If you use OpenLPT in your research, please cite our publications:

• Tan, S., Salibindla, A., Masuk, A.U.M. and Ni, R., 2020. Introducing OpenLPT: new method of removing ghost particles and high-concentration particle shadow tracking. Experiments in Fluids, 61(2), p.47.
• Tan, S., Zhong, S. and Ni, R., 2023. 3D Lagrangian tracking of polydispersed bubbles at high image densities. Experiments in Fluids, 64(4), p.85.

License

This repository contains a mix of original code and MATLAB Coder-generated files under a MathWorks Academic License.

⚠️ Restricted Paths (MATLAB Coder-generated)

The following paths contain code generated by MATLAB Coder and are NOT covered by the general MIT/Open-source license of this repository:

• /src/srcObject/BubbleCenterAndSizeByCircle
• /src/srcObject/BubbleCenterAndSizeByCircle/CircleIdentifier.cpp
• /src/srcObject/BubbleResize
• /inc/libObject/BubbleCenterAndSizeByCircle
• /inc/libObject/CircleIdentifier.h
• /inc/libObject/BubbleResize

📜 Terms and Conditions

For the paths listed above:

• ACADEMIC INTERNAL OPERATIONS ONLY: Usage is restricted to teaching, academic research, and course requirements.
• NO Commercial Use: Government, commercial, or other organizational use is NOT permitted.
• Header Preservation: Do not modify or remove the "Academic License" header comments in these files.
• No Sublicensing: These files are not sublicensed under this repository's open-source license.
• Redistribution: If you redistribute this repository, you must keep the original Academic License headers in the generated files.
• Modification: If you need to modify the generated code, you must hold a valid MathWorks MATLAB Coder license.

All other files in this repository are original work and are distributed under the MIT License (see LICENSE).

Contact & Contribution

• Issues: Please report bugs or request features via GitHub Issues.
• Contact: For questions, please contact szhong12@jhu.edu or tanshiyong84@gmail.com.
• Organization: Ni Research Lab, Johns Hopkins University.
• Support: If you find this tool helpful, please give us a ⭐ on GitHub!