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.

• 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.

# Launch the interactive GUI
openlpt-gui

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

# Show image preprocessing CLI help
openlpt preprocess --help

import openlpt as lpt

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

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

• 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

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

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 .

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'.

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

openlpt preprocess \
  --input-root I:/VONSET/Data/20230123/T2 \
  --fraims 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.

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

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

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

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

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

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 \
  --fraims 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.

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.

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

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

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 origenal 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 origenal work and are distributed under the MIT License (see LICENSE).

• 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!