Metadata-Version: 2.4
Name: pendantdroppy
Version: 1.1.0
Summary: pendantdroppy - Tensiometry software for droplet shape analysis using Young-Laplace fitting
Home-page: https://github.com/pendantdroppy/pendantdroppy
Author: Josh
Author-email: c0cz89m5t@mozmail.com
Project-URL: Bug Tracker, https://github.com/pendantdroppy/pendantdroppy/issues
Project-URL: Documentation, https://github.com/pendantdroppy/pendantdroppy#readme
Project-URL: Source Code, https://github.com/pendantdroppy/pendantdroppy
Keywords: droplet tensiometry analysis young-laplace bond-number surface-tension pendant
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Environment :: X11 Applications :: Qt
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: numpy>=1.19.0
Requires-Dist: PyQt6>=6.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<img width="250" height="250" alt="droppy_logo_og" src="https://github.com/user-attachments/assets/e995bf4b-2346-49fd-9c93-9ec10889ec1b" />


# pendantdroppy - Tensiometry Analysis Software

A PyQt6-based GUI application for analyzing droplet shape using Young-Laplace equation fitting and Bond number calculation.


## Installation

### Prerequisites
- Python 3.8 or higher
- pip (Python package manager)

### From PyPI
```bash
pip install pendantdroppy
```

### From Source
```bash
# Clone the repository
git clone https://github.com/pendantdroppy/pendantdroppy.git
cd pendantdroppy

# Install in development mode
pip install -e .

# Or install normally
pip install .
```

### Manual Installation
```bash
# Install dependencies
pip install opencv-python PyQt6 numpy

# Run the GUI
python droppy.py
```

## Usage

### GUI Application
```bash
droppy
```

Or run directly:
```bash
python droppy.py
```

### Workflow
1. **Select Image** - Browse for droplet image (PNG, JPG, etc.)
2. **Draw Geometry** - Interactive cv2 window to define:
   - ROI (Region of Interest)
   - Needle tip (for diameter calibration)
3. **Configure Parameters** - Adjust processing and analysis settings across tabs
4. **Save Settings** - Button to save current configuration to `droppy.conf`
5. **Run Analysis** - Click "RUN ANALYSIS"
6. **View Results** - See overlaid YL curve, plateau points, and extrema

### Settings File
Configuration is automatically saved to `droppy.conf`. 

On startup, the program loads from this file if it exists, otherwise uses defaults.

Example `droppy.conf`:
```json
{
  "droplet_type": "rising",
  "needle_diameter_mm": 0.72,
  "sigma": 2.0,
  "canny1": 40,
  "canny2": 120,
  "plateau_width": 100,
  "lensing_factor": 1.0,
  "low_clarity_ratio": 0.1,
  "high_clarity_ratio": 0.01
}
```

### Output Files
Analysis generates:
- `result_yl_overlay.png` - Young-Laplace curve fitted to droplet
- `edges.png` - Edge detection result
- `summary.json` - Numerical results (Bond numbers, calibration)

## Parameters Explained

### Image Processing
- **Blur Sigma** - Gaussian blur level for edge detection resolution
- **Canny Low/High** - Edge detection thresholds

### Contour Analysis
- **Num Points** - Number of contour points to sample
- **Direction** - Traversal direction (+1 or -1)
- **Min r', z'** - Minimum thresholds to avoid numerical blowup

### Analysis
- **Plateau Width** - Number of points centered on equator with lowest variance
- **Lensing Factor** - Optical correction (1.0 = no correction, <1 = correnting horizontal stretching, >1 = correcting vertical stretching)
- **Clarity Ratios** - Fractions of points used for low/high clarity image smoothing 
- **Bo Wiggle Room** - Expansion of Bond number search range from pointwise estimates


## Troubleshooting

**"No contours found"** - Adjust Canny thresholds or sigma

**"Bo ~0 for rising droplets"** - Ensure plateau is centered on equator, edit sigma, or redraw needle line, it honestly can be pixels in it.

**Config not loading** - Check `droppy.conf` is valid JSON in output directory

**"The YL curve is visually off"** - Use an image with sharp edges and a known IFT for your setup, keep all settings standard and adjust lensing factor until it fits. Use that lensing factor for all the other runs with your setup. If you are already doing that, increase sigma until it aligns.

More detailed manuals in the works :) open issue if help is needed.


## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request

## Support

For issues, feature requests, or questions:
- Open an issue on GitHub
- Check existing documentation
- Review analysis parameters

## Acknowledgments

Inspired by Krystyna Prochaska's work in interfacial tensiometry and absorption.
