Installation
pip
The easiest way to install pyplis is using pip. You can do this by running the following command in your terminal:
pip install pyplis
conda
If you use conda as package manager, you can also install pyplis using conda-forge:
conda install -c conda-forge pyplis
This will install pyplis and all it’s dependencies into the current conda environment. If you are unfamiliar with conda, please see here.
From source
You may also install from source by cloning the Pyplis GitHub repository and running:
pip install .
from the command line in the project’s root directory. Note that this will not install any dependencies. If you use conda, you may install the dependencies using the provided pyplis_env.yml file via:
conda env update --file pyplis_env.yml
Optional dependencies (to use extra features)
Pillow (PIL fork) >= 3.3.0 - may be used to define custom image read functions, see e.g. this example
Installation remarks and known issues
If you work on a Windows machine and run into problems with installation of one of the requirements check out the pre-compiled binary wheels on Christoph Gohlke’s webpage
Sometimes it is helpful, to reinstall your whole Python environment (or, if you use Anaconda, create a new one) rather than trying to upgrade all dependencies to the required version
If you find a bug or detect a specific problem with one of the requirements (e.g. due to future releases) please let us know or raise an issue.
Do not hesitate to contact us (or raise an issue here), if you have problems installing pyplis.
Main features
Measurement Geometry: Detailed analysis and representation of the measurement geometry including automatic retrieval of distances to the emission plume and/or to topographic features in the camera images (at pixel-level).
Plume background: Several routines for the retrieval of plume background intensities (either from plume images directly or using an additional sky reference image).
Camera calibration: Several routines for SO2 calibration from optical densities:
Cell calibration: Cell calibration engine to perform automatic camera calibration based on SO2 cells.
DOAS calibration: DOAS calibration engine including two methods to identify the field of view of a DOAS instrument within the camera images.
Cross-detector SO2 sensitivity correction: Correction arising from wavelength shifts in the filter transmission windows.
Plume velocities: Several methods to retrieve plume velocities needed for emission rate retrieval:
Optical flow: Velocity retrieval using optical flow methods.
Signal cross correlation: Velocity retrieval using signal cross-correlation.
Optical flow histogram: Post-analysis of optical flow field for gas velocity analysis in low contrast image regions, where the optical flow fails to detect motion (cf. Gliss et al., 2018, AMT).
Signal scattering dilution: Routine for image-based correction of the signal dilution effect based on contrast variations of dark terrain features located at different distances in the images.
Emission rate retrieval: High-level engine to retrieve SO2 emission rates for a batch of images.
Various image formats: Support of standard image formats including FITS format.
Modular design and high flexibility: Easy to integrate with custom code.
A detailed description of pyplis and its features (including analysis examples) can be found in Gliss et al., 2017, MDPI Geosciences.
Architecture
The following two flowcharts illustrate details about the Pyplis architecture, for details, please checkout Gliss et al., 2017, MDPI Geosciences.
Flowchart emission-rate retrieval (scientific)
The following flowchart illustrates the main analysis steps for emission-rate retrievals using UV SO2 cameras. The colours indicate geometrical calculations (yellow), background modelling (light grey), camera calibration (light blue), plume speed retrieval (light purple) and the central processing steps for the emission-rate retrieval (light green). Shaded and dashed symbols indicate optional or alternative analysis methods.
Flowchart showing the main analysis steps for emission rate retrievals
Flowchart API (code architecture)
The following flowchart illustrates the most relevant classes / methods of the pyplis API with a focus on the required routines for SO2 emission-rate retrievals. Italic denotations correspond to class names in Pyplis. Optional / alternative analysis procedures are indicated by dashed boxes. Setup classes (red) include relevant meta information and can be used to create Dataset objects (blue). The latter perform file separation by image type and create ImgList objects (green) for each type (e.g. on, off, dark). Further analysis classes are indicated in yellow. Note that the routine for signal dilution correction is not shown here.
Flowchart illustrating the basic architecture of pyplis (note: the engine for signal dilution correction is not included here).
Calibrated SO2 column density image showing 2 plume cross section lines and the position of the FOV of a co-located DOAS instrument.
Click here to see a video showing an animation of Mt. Etna SO2 emissions recorded on 16/09/2015
Getting started
Pyplis comes with an extensive set of example scripts which can be downloaded by cloning the repository and are introduced in the Example scripts section of the documentation.
The scripts are an excellent starting point to familiarize yourself with the vast features and the modular nature of pyplis. They can serve as a starting point to writing your own customised analysis scripts. The scripts require downloading the Etna example dataset (see following section for instructions). If you require more thorough testing, refer to this wiki entry
Example and test data
The pyplis example data (required to run example scripts) is not part of the installation. It can be downloaded from here or automatically downloaded in a Python shell (after installation) using:
import pyplis
pyplis.inout.download_test_data(<desired_location>)
which downloads the data into the my_pyplis directory if <desired_location> is unspecified. Else, (and if <desired_location> is a valid location) it will be downloaded into <desired_location> which will then be added to the supplementary file _paths.txt located in the installation data directory. It can then be found by the test data search method:
pyplis.inout.find_test_data()
The latter searches all paths that pyplis uses to manage local data and checks if the data are already available locally. It raises an Exception, if the data cannot be found.
Note
If the data is downloaded manually (e.g. using the link provided above), please make sure to unzip it into a local directory <desired_location> and let pyplis know about it, using:
import pyplis
pyplis.inout.set_test_data_path(<desired_location>)
Acknowledgement
If you find pyplis useful for your data analysis, we would highly appreciate if you acknowledge our work by citing the paper. Citing details can be found here.
We also want to express our gratitude to all contributors who have helped improve pyplis through their valuable feedback, code contributions, and suggestions. Open-source projects thrive on community support, and your contributions are deeply appreciated. If you contribute to pyplis, please feel free to add your name to the list of contributors in the documentation or reach out to be acknowledged.
Scientific background
A detailed description of pyplis and its features can be found in the paper:
In addition to a comprehensive introduction and scientific documentation of the software, the article provides a comprehensive review of the technique of SO2 cameras with a focus on the required image analysis. The paper was published in December 2017 as part of a special issue on Volcanic plumes of the Journal Geosciences (MDPI).
List of citations
Pyplis has been referenced in a number of scientific works since its publication and a list of citations can be found here: Google scholar citations.