dropclust 0.0.6

A microscopical image and video platform applied to the analysis of levitating droplet clusters

DropClust

DropClust is an analytical tool that combines computer vision and machine learning algorithms to assess the morphology, geometry, and dynamics of frame videos of droplet clusters (or similar objects).
Feature extraction capabilities were also added for further visual representation of the results.

Developed by the InfoChemistry scientific center, part of ITMO University.

Installation

We suggest throught conda and pip (with python>=3.9).

1. Install Anaconda.
2. Open an anaconda prompt / command prompt which has conda for python 3 in the path.
3. For a new environment for CPU only, run:
   conda create -n dropclust 'python==3.9'
4. To activate the new environment, run conda activate dropclust
5. For NVIDIA GPUs, run:
   pip install torch torchvision
   We suggest to install CUDA 12.6
6. To install the latest PyPi release of Dropclust and its dependencies (see setup.py), run:
   pip install dropclust.

System requirements

Linux, Windows and Mac OS are supported for running the code. For running the graphical interface you will need a Mac OS later than Yosemite. At least 8GB of RAM is required to run the software. 16GB-32GB may be required for larger images. The software has been tested on Windows 10, Windows 11, Ubuntu 24.04, Manjaro and limitedly tested on Mac OS.

Features

We calculate the following metrics / algorithms:

• Subject counting (amount of subjects).
• Area of subject (𝜇𝑚²).
• Roundness (0.0 - 1.0), having 1.0 for a perfect circle.
• Relative center coordinates.
• Voronoi diagram based on the centers.
• Voronoi entropy, a measure of order/chaos in the cells' positions.
• Convex hull.
• Continuous symmetry measure (CSM).
• Subjects segmentation and clustering.
• Color classification.
• Subject detection + tracking.

General workflow

In order to obtain metrics from segmented cells, the initial stained images are merged into a single image and organized into sub folders to be processed. A cell segmentation procedure is performed using Cellpose, then we extract the metrics and finally we store the results in the form of images and CSV files.

How to use

Launching Dropclust GUI:

• Activate the conda environment: conda activate dropclust
• Enter to launch the GUI python -m dropclust
• Now, you can load or drag-drop your desired image/video for analysis

Further, we present a usage example:

IMPORTANT: It’s mandatory to set a pixel-to-micrometer(μm) conversion value (μm per pixel), in order to calculate the droplets area. The input field for this value in the GUI, is named as “Length in μm”. By default this value is automatically acquired if the corresponding metadata file (generated by the microscope after image obtaining) is present in the same folder as the image, and if it shares the same name of the image + ”_Properties.xml”.

Along, there are geometrical and morphological metrics for droplets and droplets clusters respectively as: area, roundness, Voronoi entropy and Continuous Symmetry Measure.
There is also the option to calculate these metrics for a current single frame or a whole set of frames (video or gif). After clicking "calculate" it will take a few moments until we get a folder with the same name as the source image, containing the result values ​​in .csv and .png formats. For extra feedback about the processes and alerts, we suggest to stay pending of the python shell.

The second section offers to perform a clustering of droplets (with the option to use centroids as color seeds for each cluster).
This functionality can be performed post-segmentation, and it is aimed to group droplets by color as their most distinctive feature.

The third section presents a set of models and custom parameters for droplet segmentation. Allowing the user to preview the result of the segmentation and their outlines once is done (masks and outlines checkboxes), to estimate the size of each droplet (subject diameter) and to make a color distinction based on a predominant primary color present in the droplets (chan to segment).

Citation

Work in progress