Implementation of PC-Flow optical flow code in pytorch for spray image quantification.
Paper: https://doi.org/10.1016/j.fuel.2025.137433
Title: Time-resolved spray characterization via unified optical flow and binarization technique
Authors: Casey O'Briena, Kyungrae Kanga, Eric Wooda, Joshua Yoona, Eric Mayhewb, Alan Kastengrenc, Chol-Bum Kweonb, Tonghun Leea
aUniversity of Illinois at Urbana-Champaign bDEVCOM Army Research Laboratory cArgonne National Laboratory
The code in this project is adapted from UPFlow. We thank the authors for their significant contributions.
This code was built for a linux os system and is highly recommended for running of the code. For Windows users, it is recommended to use Windows Subsystem for Linux (WSL).
The installation has two main parts:
- install the python environment
- install the cuda correlation layer (this is much faster than the pytorch implementation)
- this is compiled through C++ code and needs a CUDA toolkit that aligns with the GNU Compiler Collection (GCC).
- this is seperate from the pytorch CUDA compute platfrom that you may install through pip.
python3.12 was used:
conda create -n pcflow python=3.12
source deactivate
source activate pcflow
use pip install -r requirements.txt to install python environment
This step compiles the custom C++ code that the model relies on. It is much faster than a pure-Python implementation.
Navigate to the package directory:
cd model/correlation_package
Clean old builds (if re-installing):
rm -rf build/ dist/ correlation_cuda.egg-info/
Run the installation using pip:
pip install . --no-build-isolation
Note: The --no-build-isolation flag is crucial. It tells pip to use your currently installed PyTorch to build the package, which prevents a ModuleNotFoundError: No module named 'torch' error.
If the pip install command fails, here are the most common errors and solutions:
Q1: OSError: CUDA_HOME environment variable is not set or nvcc: command not found Problem: The build script cannot find your CUDA Toolkit (the compiler). This is separate from your NVIDIA driver.
Solution: You must find your CUDA Toolkit path and export it to your shell.
Find your Toolkit: The path is usually in /usr/local/.
# Run this to see available toolkits
ls /usr/local/ | grep cuda
(You might see cuda-13.0, cuda-12.2, etc.)
Export the paths: Replace cuda-X.X with the version you found.
# Add the compiler to your PATH
export PATH=/usr/local/cuda-X.X/bin:$PATH
# Add the libraries to your LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/cuda-X.X/lib64:$LD_LIBRARY_PATH
Verify: Run nvcc --version. If it works, try the pip install command again.
Q2: Build fails with unsupported compiler or gcc errors Problem: Your CUDA Toolkit version (e.g., 13.0) might be incompatible with your system's default gcc compiler.
Solution: The setup.py script already includes '-allow-unsupported-compiler', which usually fixes this. If it still fails, check the NVIDIA CUDA documentation for your specific toolkit version to see which gcc versions are officially supported. If you need to force nvcc to use a different, compatible gcc version installed on your system, you can replace '-allow-unsupported-compiler' in nvcc_args with '-ccbin', '/path/to/your/gcc-X.X' (replacing X.X with your specific version, e.g., gcc-11.5).
- Note: cxx_args = ['-std=c++17'] tells your C++ compiler to use the C++17 language standard when building the package. This can also be changed to the desired C++ version.
Once the installation is complete, you can run training or inference from the root PC-Flow directory.
Train a new model where world_size is your gpu number for distributed processing and config contains training details as well as the path to your images:
python train_inference.py --mode train --world_size 3 --config "path/to/your_config.json"
Run inference with a pre-trained model:
python train_inference.py --mode inference --world_size 1 --config "path/to/your_config.json"