openlpt 2.2.2

Open-source Lagrangian Particle Tracking (LPT) with GUI and CLI

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"
  

Method 3: Manual Installation (Click to expand)

If you prefer to set up the environment manually:

1. Prerequisites:

   • Miniforge or Anaconda
   • C++ Compiler (Visual Studio 2022 for Windows, Clang for macOS/Linux)

2. Create Environment and Install:

   # Create environment
   conda create -n OpenLPT python=3.10
   conda activate OpenLPT
   
   # Build and install the package
   pip install .
   

Troubleshooting

Problem	Solution
Windows: Build fails	Install VS Build Tools and Win11 SDK
macOS: omp.h not found	See macOS OpenMP Fix section below
macOS: Architecture	python -c "import platform; print(platform.machine())"
Linux: Permissions	Use chmod +x or sudo
All: Stale cache	Delete build/ folder and retry
Installation: Build isolation	If compilation fails due to network, try pip install . --no-build-isolation

macOS OpenMP Fix

If you get fatal error: 'omp.h' file not found:

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 [e-mail] or [e-mail].
• Organization: Ni Research Lab, Johns Hopkins University.
• Support: If you find this tool helpful, please give us a ⭐ on GitHub!