.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "OPENDROP" "1" "Mar 18, 2024" "" "OpenDrop"
.SH NAME
opendrop \- OpenDrop 
.SH RELEASE BUILDS
.sp
Stand\-alone builds for Windows are provided for certain major releases and do not require the installation of
additional software: \fI\%https://github.com/jdber1/opendrop/releases/\fP\&.
.sp
Releases for Linux and macOS don\(aqt exist yet and OpenDrop should instead be installed as a Python package. See next section.
.SH BUILDING PACKAGE FROM SOURCE
.sp
OpenDrop requires Python 3.6 or higher, the GTK 3 library, OpenCV Python bindings, and the following build dependencies:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Boost.Math
.IP \(bu 2
SUNDIALS ARKODE
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Other required Python packages will be automatically installed by pip.
.sp
Platform specific build instructions follow.
.SS Ubuntu
.INDENT 0.0
.IP 1. 3
Install OpenCV.
.INDENT 3.0
.IP \(bu 2
If on Ubuntu 17.10 (or later):
.INDENT 3.0
.INDENT 3.5
.sp
.EX
sudo apt install python3\-opencv
.EE
.UNINDENT
.UNINDENT
.IP \(bu 2
Alternatively there is an unofficial \fI\%opencv\-python\fP package that can be installed using pip:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
pip3 install opencv\-python
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.IP 2. 3
Install SUNDIALS. Unfortunately \fBlibsundials\-dev\fP from the Ubuntu repositories are too old, we require at least version 4.0.0 and above. Here are brief instructions for installing SUNDIALS from source.
.INDENT 3.0
.IP 1. 3
Download the latest version from the \fI\%releases page\fP\&. (Note: the latest version requires a CMake version newer than available in Ubuntu < 20.04. If this affects you, try an older version of SUNDIALS like 4.0.0 instead.)
.IP 2. 3
Extract and change into the source directory, e.g.:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
tar \-xvf sundials\-5.7.0.tar.gz
cd sundials\-5.7.0/
.EE
.UNINDENT
.UNINDENT
.IP 3. 3
Create a build directory:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
mkdir build
cd build/
.EE
.UNINDENT
.UNINDENT
.IP 4. 3
Configure, build, and install (make sure \fBcmake\fP and \fBbuild\-essential\fP are installed from the Ubuntu repos):
.INDENT 3.0
.INDENT 3.5
.sp
.EX
cmake \e
  \-DEXAMPLES_INSTALL=OFF \e
  \-DBUILD_ARKODE=ON \e
  \-DBUILD_CVODE=OFF \e
  \-DBUILD_CVODES=OFF \e
  \-DBUILD_IDA=OFF \e
  \-DBUILD_IDAS=OFF \e
  \-DBUILD_KINSOL=OFF \e
  \-DBUILD_STATIC_LIBS=OFF \e
  \-DCMAKE_BUILD_TYPE=Release \e
  ..
make
sudo make install
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.IP 3. 3
Install Boost.Math. If on Ubuntu 20.04 or newer, run:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
sudo apt install libboost\-dev
.EE
.UNINDENT
.UNINDENT
.sp
The \fBlibboost\-dev\fP package on older versions of Ubuntu is not recent enough and Boost will need to be
installed from source. We need at least Boost 1.71.0.
.IP 4. 3
Follow the \fI\%installation instructions here\fP for installing PyGObject and GTK.
.IP 5. 3
Use pip to install OpenDrop from the repo:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
pip3 install git+https://github.com/jdber1/opendrop.git
.EE
.UNINDENT
.UNINDENT
.sp
Run \fBpip3 uninstall opendrop\fP to uninstall.
.IP 6. 3
Run \fBpython3 \-m opendrop\fP to launch the app.
.UNINDENT
.SS macOS
.INDENT 0.0
.IP 1. 3
Install the latest version of Python 3 and pip. You can do so using a third\-party package manager like \fI\%MacPorts\fP or \fI\%Homebrew\fP\&.
.IP 2. 3
.INDENT 3.0
.IP \(bu 2
Install the unofficial \fI\%opencv\-python\fP package by running:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
pip install opencv\-python
.EE
.UNINDENT
.UNINDENT
.sp
(Make sure \fBpip\fP refers to your Python 3\(aqs pip installation.)
.IP \(bu 2
Alternatively, OpenCV and its python bindings can also be installed using the \fI\%opencv Homebrew formula\fP or \fI\%opencv MacPorts port\fP\&.
.UNINDENT
.IP 3. 3
.INDENT 3.0
.IP \(bu 2
If Homebrew was used to install Python 3, PyGObject and GTK can also be installed by running:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
brew install pygobject3 gtk+3
.EE
.UNINDENT
.UNINDENT
.IP \(bu 2
or if MacPorts was used, run:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
sudo port install py36\-gobject3 gtk3
.EE
.UNINDENT
.UNINDENT
.sp
(Instead of the \fBpy36\-\fP prefix, use \fBpy37\-\fP or \fBpy38\-\fP if Python 3.7/3.8 is the version installed.)
.UNINDENT
.IP 4. 3
Install Boost.Math and SUNDIALS. (todo: Add MacPorts and Homebrew example).
.UNINDENT
.INDENT 0.0
.IP 4. 3
Use pip to install OpenDrop from the repo:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
pip install git+https://github.com/jdber1/opendrop.git
.EE
.UNINDENT
.UNINDENT
.sp
Run \fBpip uninstall opendrop\fP to uninstall.
.IP 5. 3
Run \fBpython3 \-m opendrop\fP to launch the app.
.UNINDENT
.SS Windows
.sp
Installing OpenDrop as a Python package is possible on Windows using platforms like MSYS2 or Anaconda.
The process is not very straightforward so your mileage may vary.
(todo: This page is out of date and should be updated.)
.sp
When OpenDrop is launched, the Main Menu window will first appear.
[image: Main Menu window]
[image]
.sp
Click on either of the \(aqInterfacial Tension\(aq or \(aqContact Angle\(aq buttons to begin a new analysis of the respective type.
.SH INTERFACIAL TENSION
.sp
A wizard\-style window will guide you through the process of performing an interfacial tension analysis.
.SS Image acquisition
.sp
First, choose an image input method. OpenDrop currently supports opening images from the local filesystem or capturing images with a USB camera.
.SS Local filesystem
[image: IFT Image acquisition, local filesystem]
[image]
.sp
Click on \(aqChoose files\(aq to open the file chooser dialog and select an individual image or a sequence of images. When analysing a sequence of images, \(aqFrame interval\(aq refers to the time interval (in seconds) between each image. Sequences of images are ordered in lexicographic order.
.SS USB camera
[image: IFT Image acquisition, USB camera]
[image]
.sp
Click on \(aqConnect camera\(aq to open the camera chooser dialog.
[image: IFT Image acquisition, USB camera chooser dialog]
[image]
.sp
OpenDrop uses OpenCV to capture images from a connected camera. \(aqCamera index\(aq refers to the device index argument passed to the OpenCV function \fBcv2.VideoCapture()\fP\&. An index of 0 refers to the first connected camera (usually a laptop\(aqs in\-built webcam if present), an index of 1 refers to the second camera, and so on. Currently, there does not appear to be a way in OpenCV to query a list of valid device indices and associated device names, so in a multi\-camera setup, some trial\-and\-error is required.
.sp
\(aqFrame interval\(aq refers to the time interval (in seconds) between capturing images.
.SS Physical parameters
[image: IFT Physical parameters]
[image]
.sp
\(aqInner density\(aq refers to the density of the drop.
.sp
\(aqOuter density\(aq refers to the density of the surrounding medium.
.sp
\(aqNeedle diameter\(aq refers to the diameter of the needle the drop is suspended from.
.sp
\(aqGravity\(aq refers to the gravitational acceleration.
.SS Image processing
[image: IFT Image processing]
[image]
.sp
The image processing window requires you to define the \(aqdrop region\(aq and \(aqneedle region\(aq of the image. Click on the \(aqDrop region\(aq or \(aqNeedle region\(aq buttons in the \(aqTools\(aq panel, then drag over the image preview to define the associated region.
[image: IFT Image processing, regions defined]
[image]
.sp
Once each region is defined, a blue outline will be drawn over the preview showing the drop or needle profile that has been extracted.
.sp
OpenDrop uses OpenCV\(aqs Canny edge detector to detect edges in the image, click on the \(aqEdge detection\(aq button in the \(aqTools\(aq panel to open a dialog bubble which will allow you to adjust the lower and upper threshold parameters of the Canny edge detector. Thin blue lines are drawn over the preview to show detected edges.
.sp
The extracted needle profile is used to determine the diameter in pixels of the needle in the image. Along with the needle diameter in millimetres given in the \(aqPhysical parameters\(aq page, a metres\-per\-pixel scale can be determined, which is then used to derive other physical properties of the drop after the image is analysed.
.sp
Click on \(aqStart analysis\(aq to begin analysing the input images, or begin capturing and analysing images if using a camera.
.SS Results
[image: IFT Results]
[image]
.sp
The results page shows the current status of the analysis. Data shown in the window is updated as the analysis progresses.
.sp
There are two main views, the \(aqIndividual Fit\(aq view and the \(aqGraphs\(aq view. The \(aqGraphs\(aq view is not available when analysing a single image.
.SS Individual Fit
.sp
The \(aqIndividual Fit\(aq view shows analysis details for an individual image. Pick an analysis in the lower panel to preview its details in the upper panel.
.sp
The \(aqDrop profile\(aq tab on the right of the upper panel shows the fitted drop profile (drawn in magenta) over the extracted drop profile (drawn in blue).
[image: IFT Results, drop profile]
[image]
.sp
The \(aqFit residuals\(aq tab shows a plot of the fit residuals. The horizontal axis is the \(aqdrop profile parameter\(aq, ranging from 0 to 1, with 0 corresponding to one end of the drop edge outline, and 1 corresponding to the other end. The vertical axis is some dimensionless quantity indicating the deviation of the extracted profile from the fitted profile.
[image: IFT Results, fit residuals]
[image]
.sp
The \(aqLog\(aq tab shows the history of any messages logged by the fitting routine.
[image: IFT Results, log]
[image]
.SS Graphs
[image: IFT Results, graphs]
[image]
.sp
The \(aqGraphs\(aq view shows plots of interfacial tension, volume, and surface area over time.
.SS Cancel or discard analysis
.sp
You may cancel an in progress analysis by clicking on the \(aqCancel\(aq button in the footer (not shown in the screenshots above). To discard the results of a finished analysis, click the \(aqBack\(aq button, which will return you to the \(aqImage processing\(aq page, or close the window to return to the Main Menu.
.SS Saving
[image: IFT Save dialog]
[image]
.sp
Once an analysis is finished, click on the \(aqSave\(aq button in the footer to open the save dialog. All data will be saved in a folder with name determined by the \(aqName\(aq entry, and in a parent directory determined by the \(aqParent\(aq selection.
.sp
As a convenience, you may choose to save some pre\-made plots.
[image: IFT Example save output]
[image]
.sp
An example save output is shown above, and screenshots of the contents of some files are shown below.
.INDENT 0.0
.INDENT 2.5
[image: IFT timeline.csv screenshot]
[image]
timeline.csv.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: IFT profile_fit.csv screenshot]
[image]
water_in_air1/profile_fit.csv (each row is an (x, y) coordinate pair).UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: IFT profile_extracted.csv screenshot]
[image]
water_in_air1/profile_extracted.csv (each row is an (x, y) coordinate pair).UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: IFT profile_fit_residuals.csv screenshot]
[image]
water_in_air1/profile_fit_residuals.csv (first column is \(aqdrop profile parameter\(aq, second column is residual).UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: IFT params.ini screenshot]
[image]
water_in_air1/params.ini.UNINDENT
.UNINDENT
.SH CONTACT ANGLE
.sp
A wizard\-style window will guide you through the process of performing a contact angle analysis.
.SS Image acquisition
.sp
The contact angle image acquisition page is the same as the one for interfacial tension analyses.
.SS Image processing
[image: Contact Angle Image processing]
[image]
.sp
The image processing window requires you to define the \(aqdrop region\(aq and \(aqsurface line\(aq of the image. Click on the \(aqDrop region\(aq button in the \(aqTools\(aq panel then drag over the image preview to define the region. Similarly, click on the \(aqSurface line\(aq button and drag a line to define the surface that the drop is sitting on. With the \(aqSurface line\(aq button depressed and the preview widget focused, use the arrow keys for finer adjustments of the surface line.
[image: Contact Angle Image processing, regions defined]
[image]
.sp
Once the drop region is defined, a blue outline will be drawn over the preview showing the drop profile that has been extracted.
.sp
The intersection angle between the drop profile and the surface line will be the contact angle measured.
.sp
In a contact angle analysis, OpenDrop uses image thresholding to separate the foreground from the background. Click on the \(aqForeground detection\(aq button to open a dialog bubble which will allow you to adjust the threshold value. A blue overlay is painted over parts of the image deemed to be in the foreground.
.sp
Click on \(aqStart analysis\(aq to begin analysing the input images, or begin capturing and analysing images if using a camera.
.SS Results
[image: Contact Angle Results]
[image]
.sp
The results page for a contact angle analysis is quite simple.
.sp
A summary table is shown on the bottom half with a results visualizer on the top half. Graphs of the left and right contact angles are also available if more than one image is analysed.
.SS Saving
[image: Contact Angle Save dialog]
[image]
.sp
Once an analysis is finished, click on the \(aqSave\(aq button in the footer to open the save dialog. All data will be saved in a folder with name determined by the \(aqName\(aq entry, and in a parent directory determined by the \(aqParent\(aq selection.
.sp
As a convenience, you may choose to save some pre\-made plots.
[image: Contact Angle Example save output]
[image]
.sp
An example save output is shown above, and screenshots of the contents of some files are shown below. (All coordinates are with respect to the origin being on the top\-left corner of the image with increasing x and y in the right and down directions respectively.)
.INDENT 0.0
.INDENT 2.5
[image: Contact Angle timeline.csv screenshot]
[image]
timeline.csv.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: Contact Angle profile_extracted.csv screenshot]
[image]
drop1/profile_extracted.csv (each row is an (x, y) coordinate pair).UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: Contact Angle surface.csv screenshot]
[image]
drop1/surface.csv (The coefficients of the surface line; first column is gradient, second column is y\-intercept).UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: Contact Angle tangents.csv screenshot]
[image]
drop1/tangents.csv (The coefficients of the tangent lines at the contact point. First row is left tangent, second row is right tangent. First column is gradient, second column is y\-intercept).UNINDENT
.UNINDENT
.SH GENICAM INTEGRATION
.sp
Install a GenTL producer, (e.g. see \fI\%harvesters README\fP).
.sp
OpenDrop checks the environment variable GENICAM_GENTL64_PATH (specified by the GenTL standard) for GenTL producers. To verify that a GenTL producer is installed correctly, you can run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ echo $GENICAM_GENTL64_PATH
/opt/mvIMPACT_Acquire/lib/x86_64
.EE
.UNINDENT
.UNINDENT
.sp
(todo: Add details.)
.SH NOTES
.sp
User input validation is not yet implemented, invalid user input may cause OpenDrop to crash or print errors to the console.
.sp
Stub.
[image]
.nf

.fi
.sp
\fI\%\fP
.sp
OpenDrop is a fully\-featured image analysis software for performing pendant drop tensiometry and contact angle measurements. Images can be loaded from the file system or acquired directly from USB webcams or GenICam (GigE\ Vision, USB3\ Vision) compliant industrial cameras.
.sp
The software is released under the \fBGNU GPL\fP open source license, and available for free.
.sp
For installation instructions, see \(dq\fI\%Installation\fP\(dq.

.sp
.ce
----

.ce 0
.sp
.nf
\fBGit repo:\fP
\fI\%https://github.com/jdber1/opendrop/\fP
.fi
.sp
.nf
\fBQuestions, issues, or feedback:\fP
\fI\%https://github.com/jdber1/opendrop/issues\fP
.fi
.sp
.SH AUTHOR
OpenDrop Contributors
.SH COPYRIGHT
OpenDrop Contributors
.\" Generated by docutils manpage writer.
.