Overview

This repository contains four high-speed video datasets of pool boiling phenomena and a suite of MATLAB scripts for quantitative image analysis. Detailed information about the experimental methods, datasets, and analysis methodologies can be found in our publication:

L. Zhang, et al., "Generalizable physical descriptors of pool boiling heat transfer from unsupervised learning of images," International Journal of Heat and Mass Transfer, 255 (2026) 127894.

The core of this work demonstrates that new descriptors extracted via Principal Component Analysis (PCA), namely the Dominant Amplitude ($D_a$) and Dominant Frequency ($D_f$), show strong positive correlations with conventional, manually measured parameters like bubble size and count. This unsupervised approach offers a robust and efficient alternative to traditional, labor-intensive image analysis.

Datasets Information

The experimental datasets feature two main boiling regimes: steady-state nucleate boiling at lower heat loads and the transient excursion to film boiling at the highest heat loads. High-speed videos were captured using Phantom high-speed cameras.

The four datasets were provided by the following research groups:

• Cu-H₂O Datasets (PCu-H2O, FCu-H2O): Deionized water boiling on plain copper and copper foam surfaces. Provided by the Nano Energy and Data-Driven Discovery Laboratory, University of Arkansas (Prof. Han Hu).
• Si-HFE Datasets (PSi-HFE, SSi-HFE): HFE-7100 boiling on plain silicon and micro-structured silicon surfaces. Provided by the Cooling Technologies Research Center, Purdue University (Prof. Justin Weibel).

Image Analysis Toolkit

The MATLAB-based toolkit is designed to process image frames from the experimental videos to quantify bubble dynamics. It is divided into two primary categories:

1. Conventional Descriptors: Tools for manually annotating bubble contours to calculate traditional statistics such as bubble count ($N_b$), average bubble area ($\overline{A_b}$), average bubble radius ($\overline{R_b}$), and vapor area fraction ($\mathrm{VAF}$).
2. Generalizable Descriptors: Tools for performing Principal Component Analysis (PCA) on image frames to extract dominant temporal modes, specifically the Dominant Frequency ($D_f$) and Dominant Amplitude ($D_a$) of the vapor mass.

Directory Structure

• ./PoolBoilingDatasets/: The root directory.
  • ./DataProcessTools/: Contains all MATLAB analysis scripts.
    • ./Conventional_descriptors/: Scripts for manual bubble annotation and conventional statistical analysis.
    • ./Generalizable_descriptors/: Scripts for Principal Component Analysis and dominant descriptors extraction.
  • /[Dataset Name]/ (e.g., ./PCu-H2O/): These folders contain the downsized experimental data as .mp4 videos, converted from the Phantom camera's native format using the Phantom Camera Control (PCC) software.
  • /[Dataset Name]/annotatedBubbles/: This folder contains datasets for calculating conventional physical descriptors, including megapixel-resolution images and a master JSON file that stores the bubble contour data.
    • Images: Named using the convention [Dataset Name]_heatLoad_imageSequenceNum.jpg.
    • JSON File: Contains an object for each image, which in turn holds a FileName and a Bubbles object with coordinates for each labeled bubble (b0001, b0002, etc.).

Tools and Scripts

Conventional Descriptors (/DataProcessTools/Conventional_descriptors/)

1. bubbles_annotator_v6.m

• Purpose: A MATLAB-based GUI for manually drawing and labeling bubble contours on image frames.
• How to Use:
  1. Run the script in MATLAB.
  2. You will be prompted to select a source folder containing the image frames to be annotated.
  3. A second prompt will ask you to select a destination folder for the output (an annotated_results subfolder will be created automatically).
  4. An interactive window will appear for each image with the following controls:
     • Left-click: Place the vertices of a polygon.
     • Backspace key: Undo the last point.
     • Double-click: Finalize the current bubble's shape.
     • A dialog box will then prompt for the next action (Define more, Redefine last bubble, etc.).
• Output: Annotated images and a single bubble_labeled_data.json file containing all contour data.

2. bubbleStat_calculator_v4.m

• Purpose: Processes the JSON file from the annotator to calculate bubble statistics.
• How to Use:
  1. Edit the script to define the pixel resolution (l_px) for the dataset.
  2. Run the script and select the .json file and the corresponding image folder.
• Output:
  • A summary table is displayed in the MATLAB Command Window with statistics grouped by heat load.
  • If save_contour_Mode is set to true, it saves annotated images to a new BubbleContours subfolder.

Generalizable Descriptors (/DataProcessTools/Generalizable_descriptors/)

1. PC_calculator_v4.m

• Purpose: Performs PCA on image frames by dividing them into manageable subsets.
• How to Use:
  1. Edit the script to set the MainData_DIR and the heatLoads array (e.g., "10W", "40W").
  2. Ensure image frames are named sequentially (e.g., 00000.jpg).
  3. Configure parameters like totalImages, numSubsets, and numPCs.
• Output: Creates a ./PC_Results directory with .csv files containing the PC scores for each image subset.

2. dominantDescriptor_calculator_v4.m

• Purpose: Analyzes the time series of a specific Principal Component (typically PC1) using an FFT to identify the Dominant Amplitude ($D_a$) and Dominant Frequency ($D_f$).
• How to Use:
  1. Important: You must run PC_calculator_v4.m first.
  2. Edit the script to set MainData_DIR, heatLoads, frameRate, and which PC to analyze (pcToAnalyze).
• Output: Creates a ./Dominant_Descriptors directory with a .csv file for each heat load, summarizing the $D_a$ and $D_f$ values.

Recommended Workflow

1. Data Preparation: Extract image frames (e.g., as .jpg) from the high-speed videos and organize them into subfolders based on heat load (e.g., ./FCu-H2O/15W/).
2. Manual Annotation: Collect a representative subset of images for annotation. Run bubbles_annotator_v6.m to draw contours and generate the bubble_labeled_data.json file.
3. Calculate Conventional Statistics: Run bubbleStat_calculator_v4.m on the generated JSON file to compute conventional bubble statistics.
4. PCA for Generalizable Descriptors:
   • Part A: Configure and run PC_calculator_v4.m to process the image sequences and generate PC score files.
   • Part B: Configure and run dominantDescriptor_calculator_v4.m on the PC scores to calculate the $D_a$ and $D_f$ descriptors.

Script Dependencies

• MATLAB: R2021a or newer is recommended.
• Image Processing Toolbox
• Statistics and Machine Learning Toolbox