This package is for analyzing pool boiling images and is from the paper: BubbleID:A deep learning framework for bubble interface dynamics analysis. It combines tracking, segmentation, and classification models and is trained on manually labeled pool boiling data. It is used for departure classification, velocity interface prediction, bubble statistics extraction. It is built on ocsort and detectron2.

This is an updated version of BubbleID for the past version please see here.

First download and install the latest Microsoft C++ Build Tools

Create a new environment with python 3.10, we used anaconda

conda create -n bubbleid python==3.10
conda activate bubbleid

Ensure git is installed, we used anaconda:

conda install anaconda::git

Update dependencies:

pip install --upgrade pip setuptools wheel

Install pytorch (Make sure cuda version matches if using gpu):

pip3 install torch torchvision torchaudio

Install detectron2:

pip install git+https://github.com/facebookresearch/detectron2

Install Additional Dependencies:

pip install numpy==1.23 opencv-python filterpy super-gradients

Install BubbleID:

pip install bubbleid

For in depth description of functions available please view the read the docs page.

1. Data Preperation: Data from pool boiling experiments must be saved as a video (.AVI) file and individual images (.JPG) for each frame.

2. AnalyzeData Class: The BubbleID frame work is set up as a class. You first instantiate a class for the experimental data you want.

   • Define the location of the saved boiling video and images.

   • Also define the folder you want all the data to be saved in and the extension you want each file to be saved with.

   • Define the location of the model weights you will be using. The BubbleID framework has pretrained models for our in lab pool boiling images. This section goes over how to use these models to analyze image data. These models may need finetuning with your own data. More on this is provided later.

     Model	Weights	Description
     Instance Segmentation (BubbleID <= 0.0.7	Link	Model weights for the instance segmentation model.
     Instance Segmentation (BubbleID >= 0.0.8	Link	Updated Model Weights for instance segmentation model.
     Classification	Link	Model weights for the departure classification model.

   • Define the device you will be running on; either "cpu" or "gpu"

3. GenerateData Function: When you call the generate data function multiple files are generated and saved in the defined save folder. Each file will contain the extension set previously. This function must be ran prior to the data visualization functions.

4. Data Visualization: There are several functions within the class that can be called to save and display plots of the data generated by the segmentation and tracking models. These include ploting vapor fraction, bubble count, and interface velocity.

• For convenience, a tutorial (using older version of BubbleID) is provided in the github to demonstrate how to use BubbleID to generate your own BubbleID results. The tutorial is zipped with data for running it. Different types of analysis is permitted based on the frame rate of the videos. For higher frame rates (>600fps) the tracking model can be used for analysis (e.g., interface velocity, departure, etc.). For lower frame rates, only information from each frame can be extracted (e.g., bubble count, size, vapor fraction).

  Download High Frame Rate Tutorial And Data Zip

1. Annotate image data, Lableme was used for our dataset. Find our annotated data here.
2. Convert labelme dataset to coco format
3. Run training
4. See Using the BubbleID Framework but use your new model weights

If none of the provided functions match your needs you can customize the code and add new ones by installing everything except BubbleID. Then clone the repo and use the Customizable folder.