Metadata-Version: 2.3
Name: pypendentdrop
Version: 0.0.1.dev10
Summary: Python scripts (GUI and command line) to measure surface tension from images of pendent drops.
Project-URL: Homepage, https://github.com/Moryavendil/pypendentdrop
Project-URL: Issues, https://github.com/Moryavendil/pypendentdrop/issues
Author-email: G2L <GDoubleL@proton.me>
License-File: LICENSE
Keywords: analysis,drop,image,measure,pendant,pendent,surface,tension
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: contourpy>=1.0
Requires-Dist: pillow
Requires-Dist: scipy>=1.7
Provides-Extra: cli
Requires-Dist: matplotlib; extra == 'cli'
Provides-Extra: full
Requires-Dist: matplotlib; extra == 'full'
Requires-Dist: pyqt5; extra == 'full'
Requires-Dist: pyqtgraph; extra == 'full'
Provides-Extra: gui
Requires-Dist: pyqt5; extra == 'gui'
Requires-Dist: pyqtgraph; extra == 'gui'
Description-Content-Type: text/markdown

# PyPendentDrop

Python library (with graphical and command line interfaces) to measure surface tension from images of pendent drops.

* On PyPI: [https://pypi.org/project/pypendentdrop/](https://pypi.org/project/pypendentdrop/)
* Source code: [https://github.com/Moryavendil/pypendentdrop](https://github.com/Moryavendil/pypendentdrop)


## Installation

Simply use

    pip install pypendentdrop[full]

or, if you only want to use the command-line version (resp. the graphical version), you can replace `[full]` by `[cli]` (resp. `[gui]`). See [dependencies](#dependencies) for the difference between these options. Use no option to download a minimal working version of the library.

## Use PyPendentDrop

### Graphical interface

To launch the gui version, use the command

    ppt-gui

or, alternatively, 

    python -m pypendentdrop.gui

### Command-line

To use the command-line version, use

    ppt-cli

or, alternatively, 

    python -m pypendentdrop

Use the `-h` option to list the availables options. If you use the `-o` option (graph generation), ensure that you have matplotlib installed.

### In a python script

In the import section, write

    import pypendentdrop as ppd

and you can then use the functions defined in the library. An example script `examplescript.py` is provided on the GitHub repository. 

## How it works

### The pendent drop method

[...] see scientific litterature

### Using PyPendentDrop

The main steps of measuring the surface tension of a liquid using the pendent drop method are

1. Select an image (if possible a high quality, high contrast image of a symmetric drop) using `ppd.import_image(filename)`

    *Optionally:* select the Region Of Interest in your image

2. Choose a threshold for your image (or use `ppd.best_threshold(image)` to find it for you)

3. Detect the contour of the drop using `ppd.detect_main_contour(image, threshold)`

4. Specify the pixel density (or pixel size) of the image

5. Obtain a coarse estimation of the parameters of the drop (tip position, angle of gravity, radius at apex, capillar length of liquid) using `ppd.estimate_parameters(image, contour, pixeldensity)`

    *Optionally:* set some of the parameters yourself if the automatically-estimated parameters are not accurate enough

6. Fit the drop profile using the estimated parameters as initial condition using `ppd.optimize_profile(contour, estimated_parameters)`

7. Knowing the density contrast (density difference between the fluids times gravity acceleration), compute the surface tension.

## Dependencies

* The PypendentDrop library rely on

 * `numpy` (for algebra)
 * `pillow` (for image reading via `Image.open()`)
 * `contourpy` (for contour detection via `ContourGenerator.lines()`)
 * `scipy` (for parameters optimization via `minimize`)

* The graphical application depends on

 * `pyqtgraph` (fast responsive graphs)
 * Any Qt distribution for Python supported by PyQtGraph: `PyQt6`, `PySide6`, `PyQt5` or `PySide2` (when using the `[gui]` option, `PyQt5` is installed) 
 
* The command-line application depends on
 * `matplotlib`, when requesting graphs to be plotted (see `-o` option for `ppt-cli`)

to test the module, you can run (from the main directory)

    python -m pypendentdrop -n src/pypendentdrop/tests/testdata/water_2.tif -p 57 -g 9.81 -v

## Contact

if needed: contact me at `pypendentdrop@protonmail.com`