Automated detection and analysis of microfluidic droplets using deep learning (YOLOv8). Supports both real-time webcam analysis and static image batch processing, with rich statistics, annotated outputs, and visualizations.
| Feature | Description |
|---|---|
| π₯οΈ Live webcam analysis | Real-time droplet detection, statistics, and unified preview/plots |
| πΌοΈ Static image analysis | Batch or single-image processing, model benchmarking |
| π Cumulative statistics | Tracks droplet size/volume across frames/images |
| π Interactive plots | Live histograms, normal fits, and graphical UI |
| π CSV & annotated outputs | Exports per-droplet and summary data, images, GIFs |
| π·οΈ Model comparison | Test multiple YOLO weights, auto-select best |
| 𧩠Easy extensibility | Modular design, clear configs, and example suite |
- Features
- Repository Structure
- Installation & Requirements
- Quick Start
- Outputs & Results
- Configuration & Parameters
- Troubleshooting
- Maths and Processing Details
- Model Training and Weights
- More Information
- Contributing
- License
- Citation
- Credits
webcam-v1/β Real-time webcam droplet detection (live mode, unified UI, terminal mode)video-v1/β Analyse recorded videos; outputs annotated MP4 + per-frame images and full statistics/plotsstatic-image-v1/β Analyse single images or batches, benchmark models, export stats/plotsexamples/β Ready-to-run sample suite with images, weights, and scripts for demo/testingimgs/β (in each module) Holds input images and output resultsweights/β YOLOv8 model weights (.ptfiles)packages.py&requirements.txtβ Dependency management
- Python 3.8+
- Ultralytics YOLOv8
- numpy, pandas, matplotlib, seaborn, opencv-python, torch, tabulate, imageio
Install all dependencies:
python packages.py
# or
pip install -r requirements.txt- Go to
webcam-v1/and run:python main.py
- Choose mode: Graphical (G), Live View (L), Both (B), or Terminal (any other key)
- View live stats, plots, and annotated video in a unified UI window
- Go to
static-image-v1/and run:python main.py
- Choose to analyze a single test image or all images in
imgs/real_imgs/ - Optionally, test all YOLO weights and auto-select the best
- Results (annotated images, plots, CSVs, GIFs) saved in
imgs/results/<image_name>/
- Go to
video-v1/and run:python main.py
- Processes every
.mp4,.avi,.mov,.mkv, or.h264invideos/samples/(or specify one). - Generates
results/<video_name>/with:predictions/annotated_<name>.mp4&annotated_frames/statistics/folder containing histograms anddroplet_measurements.csv
- Go to
examples/and try:python see_ellipses.py python see_distributions.py
- Uses included sample images and weights for instant results
- predictions/ β Annotated images (
*_pred.jpg) or videos (annotated_<name>.mp4) plus optional per-frame PNGs - statistics/diameter_hist.png β Diameter histogram (Β΅m)
- statistics/volume_hist.png β Volume histogram (pL)
- statistics/droplet_measurements.csv β Per-droplet measurements + summary (mean, SD, mode, CV)
- statistics/model_comparison.png β Performance chart across all tested weights
- statistics/history.gif β Timeline GIF of predictions (static-image workflow)
Unified UI (webcam mode) shows live video, diameter, and volume stats in one window.
- Edit
PARAMETERS.pyin each folder to adjust:TEST_IMAGE,WEIGHT,IMGSZ,CONFIDENCE,MAX_DETECT,PIXEL_RATIO,UNIT
- Place your own images in
imgs/real_imgs/and YOLO weights inweights/ - For webcam: change camera index in
backend.pyif needed
- Performance drops: Unified UI is resource-intensive; use lower modes on low-end hardware
- Webcam not found: Check device index or permissions
- Plot/UI issues: Ensure all dependencies are installed; try running with admin rights
- Model errors: Confirm YOLOv8 weights are compatible and in the correct folder
Droplets touching the image borders are intentionally excluded from statistics. Although the model detects them, their true size is ambiguous (as they are not fully visible), which would skew mean and standard deviation calculations. Including these partial droplets can significantly distort the analysis:
Above: Including border droplets leads to visible errors in statistics.
-
Area: Each droplet is assumed to be an ellipse, with axes parallel to the image axes. The area is calculated as:
Area = Ο Γ (w / 2) Γ (h / 2)
wherewandhare the bounding box width and height.
-
Volume: Estimated by assuming a sphere with diameter equal to the mean of the bounding box width and height:
Volume = (4/3) Γ Ο Γ (d / 2)^3, whered = (w + h) / 2
-
Incremental Statistics: The standard deviation and mean are calculated using an incremental formula, allowing new images to be added without storing all individual droplet measurements:
-
Batching: Data is stored in batches (default: 60 images per batch, up to 5 batches). When the maximum number of batches is exceeded, the oldest batch is discarded. This allows the system to βforgetβ older data and focus on recent results, which is ideal for live analysis.
-
ImageData Class: All statistics are encapsulated in
ImageDataobjects, which can be combined using the+operator:image_data_combined = image_data1 + image_data2
This merges statistics, means, standard deviations, and distributions.
Droplet sizes are measured in pixels by default. To convert to physical units, adjust PIXEL_RATIO and UNIT in PARAMETERS.py:
PIXEL_RATIO = 1.0 # e.g., 0.5 for 0.5 mm/pixel
UNIT = "px" # e.g., "mm"This enables flexible adaptation to different microscopes or imaging setups.
YOLOv8 weights (.pt files) are trained using the train.py script in the training_field directory. Training uses NVIDIA CUDA for GPU acceleration (requires compatible hardware, CUDA Toolkit, and cuDNN).
- Process:
- The model predicts droplets on hundreds of labeled images.
- Loss is computed by comparing predictions to ground truth labels.
- The model iteratively improves, saving the best-performing weights.
- Data:
- Training images and labels are generated using
make_training_data.py. - Resulting weights are stored in the
weights/directory for use in analysis scripts.
- Training images and labels are generated using
For more information on training or customizing models, see the training_field/README.md (if available) or contact the maintainers.
<img src="images/pixel_ratio_1.png" alt="history gif" style="width: 600px; height: auto;">
```py
PIXEL_RATIO = 0.5
UNIT = "mm"
For more details on training or customizing models, see training_field/README.md or contact the maintainers.
- See each module's
README.mdfor detailed usage, controls, and advanced options - Example suite (
examples/README.md) provides a hands-on introduction - For support or questions, open an issue or contact the maintainers
Contributions, bug reports, and feature requests are welcome! To contribute:
- Fork the repository and create your branch from
main. - Make your changes and add descriptive commit messages.
- Ensure your code is well-documented and tested.
- Submit a pull request with a clear description of your changes.
See CONTRIBUTING.md for more guidelines (or create one if it does not exist).
This project is licensed under the MIT License. You are free to use, modify, and distribute this software with attribution.
If you use Droplet AInalysis in your research, please cite it as follows:
@misc{dropletAInalysis,
author = {Domingo Veloso-Arias and Pierre Padilla-Huamantinco and Tobias Wenzel},
title = {Droplet AInalysis: Automated Microfluidic Droplet Detection and Analysis},
year = {2025},
howpublished = {\url{https://github.com/wenzel-lab/droplet_AInalysis}},
note = {Version X.Y}
}If you publish work using this code, please include a citation and consider letting us know!
Authors: Domingo Veloso-Arias, Pierre Padilla-Huamantinco, and Tobias Wenzel
Special thanks to the open-source community and Ultralytics for YOLOv8.