Pyplis–A Python Software Toolbox for the Analysis of SO₂ Camera Images for Emission Rate Retrievals from Point Sources

Abstract

Ultraviolet (UV) SO₂ cameras have become a common tool to measure and monitor SO₂ emission rates, mostly from volcanoes but also from anthropogenic sources (e.g., power plants or ships). Over the past decade, the analysis of UV SO₂ camera data has seen many improvements. As a result, for many of the required analysis steps, several alternatives exist today (e.g., cell vs. DOAS based camera calibration; optical flow vs. cross-correlation based gas-velocity retrieval). This inspired the development of Pyplis (Python plume imaging software), an open-source software toolbox written in Python 2.7, which unifies the most prevalent methods from literature within a single, cross-platform analysis framework. Pyplis comprises a vast collection of algorithms relevant for the analysis of UV SO₂ camera data. These include several routines to retrieve plume background radiances as well as routines for cell and DOAS based camera calibration. The latter includes two independent methods to identify the DOAS field-of-view (FOV) within the camera images (based on (1) Pearson correlation and (2) IFR inversion method). Plume velocities can be retrieved using an optical flow algorithm as well as signal cross-correlation. Furthermore, Pyplis includes a routine to perform a first order correction of the signal dilution effect (also referred to as light dilution). All required geometrical calculations are performed within a 3D model environment allowing for distance retrievals to plume and local terrain features on a pixel basis. SO₂ emission rates can be retrieved simultaneously for an arbitrary number of plume intersections. Hence, Pyplis provides a state-of-the-art framework for more efficient and flexible analyses of UV SO₂ camera data and, therefore, marks an important step forward towards more transparency, reliability and inter-comparability of the results. Pyplis has been extensively and successfully tested using data from several field campaigns. Here, the main features are introduced using a dataset obtained at Mt. Etna, Italy on 16 September 2015.

1. Introduction

Sulfur dioxide (SO₂) is a toxic gas emitted by anthropogenic and natural sources (e.g., power plants, ships, volcanoes). The pollutant has impacts on the atmosphere both on local and global scales (e.g., particle formation, radiation budget, e.g., [1,2]). Furthermore, the monitoring of SO₂ emissions from active volcanoes can provide insight into the magmatic degassing behaviour and hence plays an important role for the development of new risk assessment approaches (e.g., [3,4,5,6], and references therein).

The gas composition of the emission plumes can, for instance, be studied using ground-based passive remote sensing techniques. The column-densities (CDs) of the gases in the plumes are quantified based on the absorption signature carried by scattered sunlight that has penetrated the plume. SO₂-CDs, for instance, can be retrieved at ultraviolet (UV) wavelengths (i.e., around 310 nm) where it exhibits distinct absorption bands. Prominent examples for passive remote sensing instrumentation are the correlation spectrometer (COSPEC, [7]), or instruments based on the technique of Differential Optical Absorption Spectroscopy (DOAS, [8], e.g., [9,10]). Over the past decade, the comparatively young technique of UV SO₂ cameras has gained in importance, since it enables the study of volcanic SO₂ emissions at unprecedented spatial and temporal resolution (e.g., [11,12,13,14,15]). This is particularly helpful to study multiple sources independently (e.g., [16]) or to investigate volcanic degassing characteristics by studying periodicities in the SO₂ emission rates (e.g., [17,18,19] and references therein). The technique of UV SO₂ cameras has seen remarkable improvements over the past decade (e.g., [20,21,22,23,24]) and can now be considered one of the standard methods for ground-based remote sensing of SO₂ plumes. A drawback, however, is the low spectral resolution, restricting the technique to a single species and furthermore requiring external calibration.

The retrieval of SO₂ emission rates from plume imagery comprises several analysis steps that are summarised in

Table 1. Analysis blocks for emission rate retrievals (for details see Section 2).

Analysis Block	Quantities	Analysis Options	Section
Geometrical Calculations	$\Delta s$		3.1
Plume Background Analysis	${\tau }_{\mathrm{on}}$, ${\tau }_{\mathrm{off}}$, ${\tau }_{\mathrm{AA}}$		3.3
Camera Calibration	$S_{\mathrm{SO}2}$	Cell, DOAS	3.4
Plume Velocity Retrieval	$〈\overline{\mathit{v}}·\widehat{\mathit{n}}〉$	Optical flow, cross-correlation	3.5
Emission rate	${\Phi }_{\mathrm{SO}2}$	Signal dilution correction	3.6, 3.7

and are illustrated in the flowchart shown in Appendix Figure A1. Thanks to ongoing developments, today, researchers can choose between several methods for nearly all of the required steps (e.g., cell vs. DOAS calibration, velocity retrieval using optical flow vs. cross-correlation method).

Available software solutions include Vulcamera [25], the IDL^® source code provided by [22] and Plumetrack [26]. The first two programs include routines for cell calibration and cross-correlation based plume velocity retrievals. The IDL^® program also includes a routine to perform a first order correction for the signal dilution effect (commonly referred to as light dilution, e.g., [22]). The software Plumetrack provides an interface to calculate gas velocities using an optical flow algorithm and can be applied to pre-calibrated SO₂-CD images in order to retrieve SO₂ emission rates.

Pyplis ([27,28]) is a cross-platform, open-source software toolbox for the analysis of UV SO₂ camera data. The code is written in Python 2.7 and emerged from the idea of a common software platform incorporating the most relevant analysis methods, including recent developments. The most important features of Pyplis 1.0.0 are (details follow in Section 3):

• 3D distance retrievals to plume and local terrain features at pixel-level,
• several methods to retrieve plume background radiances,
• cell and DOAS based camera calibration including two independent DOAS FOV search routines,
• cross-correlation and optical flow based plume velocity retrievals,
• histogram based correction for ill-posed optical flow vectors in low-contrast image regions,
• image based correction for the signal dilution effect,
• automated emission rate retrievals along linear plume intersections.

Pyplis comes with numerous example scripts providing an easy and comprehensive introduction into the software. The following Section 2 introduces the technique of UV SO₂ cameras and the required analysis steps for SO₂ emission rate retrievals. The implementation of the individual analysis methods is discussed in Section 3.

2. Methodology

2.1. UV SO₂ Cameras

UV SO₂ cameras analyse scattered sunlight that has penetrated a plume containing SO₂ gas. Plume optical densities (ODs) $\tau$ are retrieved in two wavelength windows of approximately 10 nm width, using optical bandpass filters. One filter is centred around 310–315 nm, where SO₂ has strong absorption bands (referred to as SO₂ on-band). A second filter is situated around 330 nm, where SO₂ absorption is weak (SO₂ off-band). The latter is used to correct for additional broadband light extinction, for instance, resulting from aerosols or water droplets in the plume. From the retrieved ODs in both channels, the apparent absorbance (AA) of SO₂ (${\tau }_{\mathrm{AA}}$, e.g., [20]) can be retrieved as

$${\tau }_{\mathrm{AA}}={\tau }_{\mathrm{on}}-{\tau }_{\mathrm{off}}=\ln {\left(\frac{I_0}{I}\right)}_{\mathrm{on}}-\ln {\left(\frac{I_0}{I}\right)}_{\mathrm{off}},$$

(1)

where I and $I_0$ denote the plume and plume background radiances, respectively, in both channels (on, off). Note that the method requires all additional optical densities in the on and off-band regime to be of broadband nature.

2.2. Image Analysis—Retrieval of S${}_{\mathit{SO}2}$ Images

AA images are determined from a set of pre-processed (e.g., dark / offset corrected) plume and background images using Equation (1). Next, the AA images are converted into SO₂ column-density (CD) images, where

$$S_{\mathrm{SO}2}(i,j)={\int }_{{\mathcal{C}}_{ij}}c(x,y,z)ds$$

(2)

denotes the SO₂-CD in the viewing direction ${\mathcal{C}}_{ij}$ of the image pixel $i,j$. $c(x,y,z)$ is the concentration distribution of SO₂ in real world coordinates $x,y,z$ (cf. Figure 1a) and $ds=\sqrt{d{x}^2+d{y}^2+d{z}^2}$ is the integration differential.

The camera calibration (i.e., the conversion of AA values into SO₂-CDs) can be performed either using gas cells (e.g., [11]) or a co-located DOAS spectrometer (e.g., [21]). The latter is more accurate in case aerosols are present in the plume [21,29]. The position and shape of the DOAS FOV within the camera images are required in order to perform the DOAS calibration. The DOAS FOV can either be measured experimentally (e.g., in the lab) or can be retrieved directly from the field data [21,30].

The camera calibration curve depends on the pixel-position in the images (e.g., [21]). This is due to shifts in the filter transmission curves for non-perpendicular illumination (i.e., off-axis image pixels), resulting in an increased SO₂ sensitivity towards the image edges (e.g., [31]). A first order correction for this effect can be performed using a normalised sensitivity correction mask retrieved from cell calibration data, as described in [21]. The impact of this effect can be dramatically reduced by placing the transmission filters between lens and detector rather than in front of the lens [31]. Please note that this effect of an increased SO₂ sensitivity towards the image edges is not to be confused with lens-vignetting effects, as discussed by [31].

2.3. Emission Rate Retrieval

SO₂ emission rates $\Phi$ are retrieved from SO₂-CD images by performing a discrete path integration along a suitable plume cross section (PCS) projected into the image plane, for instance a straight line $\ell$ (illustrated in Figure 1b). Then,

$$\Phi (\ell )=f^{-1}\sum _{m=1}^M{S}_{\mathrm{SO}2}(m)·〈\overline{\mathit{v}}(m)·\widehat{\mathit{n}}(m)〉·d_{\mathrm{pl}}(m)·\Delta s(m)$$

(3)

corresponds to the SO₂ emission rate through $\ell$, where m denotes one of a total of M sample positions along $\ell$ in the image plane and $\Delta s$ is the integration step length, measured in physical distances on the detector. f is the focal length of the camera, $d_{\mathrm{pl}}$ is the distance between camera and plume and $\widehat{\mathit{n}}$ is the normal of $\ell$. $\overline{\mathit{v}}$ is a 2-vector containing projected plume velocities averaged in the viewing direction.

The plume distances $d_{\mathrm{pl}}$ can be estimated from the measurement geometry and require information about the camera position and viewing direction as well as the source position and the meteorological wind direction. The gas velocities are usually retrieved from the images directly either using cross-correlation based methods (e.g., [32]) or optical flow algorithms (e.g., [23]).

Equation (3) is equivalent to commonly used retrieval methods (e.g., [11,29]) and is based on the assumption that over or underestimations of the measured quantities S${}_{\mathrm{SO}2}$ and $\overline{\mathit{v}}$ (e.g., due to non-perpendicular plume transects) cancel out in the emission rate retrieval. This is a valid approximation for typical measurement conditions (i.e., plume nearly perpendicular to the optical axis, and plume extent small compared to plume distance). However, care has to be taken for unfavourable geometries (e.g., tilted or overhead plume; retrieval close to the image edges), which may require additional corrections (e.g., [33]). The software Plumetrack [26] includes an alternative “2D” method to compute the emission rates, which considers all image pixels that are crossing the PCS line between consecutive frames. This method is not included in the current version of Pyplis but may be a valuable extension in a future release of the software.

If a locally uniform gas velocity can be assumed (i.e., $\overline{\mathit{v}}(i,j)\to \overline{\mathit{v}}$) and a planar PCS is used for the retrieval (i.e., $\widehat{\mathit{n}}(i,j)\to \widehat{\mathit{n}}$), then, Equation (3) can be further approximated as $\Phi (\ell )\approx 〈\overline{\mathit{v}}·\widehat{\mathit{n}}〉·\chi (\ell )$, where

$$\chi (\ell )=f^{-1}\sum _{m=1}^M{S}_{\mathrm{SO}2}(m)·d_{\mathrm{pl}}(m)·\Delta s(m)$$

(4)

denotes the integrated column amount (ICA) along $\ell$.

2.4. Radiative Transfer Corrections

Radiative transfer effects may introduce systematic errors in the retrieved emission rates (see e.g., [34,35]). The signal dilution effect describes a decrease in the measured CDs due to scattering between instrument and plume. The magnitude of this effect primarily depends on the local visibility (i.e., amount of molecules and particles in the ambient atmosphere) and on the distance between camera and plume. A first order correction can be performed using the atmospheric scattering extinction coefficients in the viewing direction between camera and source (e.g., [12,36]). The latter can be retrieved, for instance, by studying brightness variations of topographic terrain features in the images as a function of their distance to the instrument [22]. More complicated radiative transfer issues (e.g., optically thick plumes) require corrections using radiative transfer models (e.g., [29]). Pyplis can correct for the signal dilution effect based on the method suggested by [22].

3. Implementation

In the following, the main features and modules of Pyplis are presented. The application programming interface (API) is designed to be modular using an object oriented architecture. It can therefore be used in parts or as a whole. Figure 2 illustrates the Pyplis API for SO₂ emission rate retrievals (see also Appendix E). Pyplis includes 19 example scripts, which provide an introduction to the main features of the software (summarised in

Table A2. Pyplis example scripts, sub-categorised into introductory scripts (0.1–0.7) and scripts related to the emission rate analysis of the Etna test data (1–12).

No.	Name	Description	Section
0.1	ex0_1_img_handling.py	The $\mathrm{Img}$ class - Image import and dark correction	3.2
0.2	ex0_2_camera_setup.py	The $\mathrm{Camera}$ class - Definition of camera specifications and image file name convention	E
0.3	ex0_3_imglists_manually.py	Introduction into $\mathrm{ImgList}$ objects	E.2
0.4	ex0_4_imglists_auto.py	Automatic creation of $\mathrm{ImgList}$ objects using the ECII default $\mathrm{Camera}$ type	E.2
0.5	ex0_5_optflow_livecam.py	Interactive optical flow using web cam	3.5.2
0.6	ex0_6_pcs_lines.py	Plume cross section lines (creation and orientation of $\mathrm{LineOnImage}$ objects)	3.7
0.7	ex0_7_cellcalib_manual.py	Introduction into cell calibration and the $\mathrm{CellCalibData}$ object (manually)	3.4.1
1	ex01_analysis_setup.py	Create $\mathrm{MeasSetup}$ class and initiate analysis $\mathrm{Dataset}$ object from that (see Figure 2)	3.4.1
2	ex02_meas_geometry.py	Introduction into the $\mathrm{MeasGeometry}$ class	3.1
3	ex03_plume_background.py	The $\mathrm{PlumeBackgroundModel}$ class - background modelling and $\tau$ image retrieval	3.3
4	ex04_prep_aa_imglist.py	Preparation of image list containing AA images	E.2
5	ex05_cell_calib_auto.py	Automatic cell calibration using the $\mathrm{CellCalibEngine}$ class	3.4.1
6	ex06_doas_calib.py	DOAS calibration and FOV search	3.4.2
7	ex07_doas_cell_calib.py	Retrieval of AA sensitivity correction mask	3.4
8	ex08_velo_crosscorr.py	Plume velocity retrieval using cross-correlation	3.5.1
9	ex09_velo_optflow.py	Plume velocity retrieval using Farnebäck optical flow algorithm using $\mathrm{OptflowFarneback}$ class	3.5.2
10	ex10_bg_imglists.py	Retrieval of background image lists (on, off) using $\mathrm{Dataset}$ class	E
11	ex11_signal_dilution.py	Correction for signal dilution and the $\mathrm{DilutionCorr}$ class	3.6
12	ex12_emission_rate.py	Emission rate retrieval for the test dataset	3.7
	SETTINGS.py	Global settings for example scripts

). The scripts are based on an example dataset recorded at Mt. Etna in Italy on 16 September 2015 between 6:40 a.m. and 7:30 a.m. UTC. These data are freely available and can be downloaded from the website (for details, see Appendix F.1).

3.1. Geometrical Calculations

Geometrical calculations are performed within an instance of the $\mathrm{MeasGeometry}$ class (part of the geometry.py module). The plume distances $d_{\mathrm{pl}}$ (cf. Equation (3)) can be retrieved per pixel-column i using intersections of the respective viewing azimuth with the plume azimuth (see Figure 3). This requires specification of the camera position, viewing direction and optics (e.g., detector specifications, focal length), source coordinates and meteorological wind direction. The distances are determined based on the horizontal plume distance and the altitude difference between source and camera (i.e., assuming a horizontally aligned plume). It is pointed out that this approach may be inapplicable for complicated measurement geometries (e.g., overhead plumes), which would require a more detailed knowledge of the plume shape and altitude.

Further features of the $\mathrm{MeasGeometry}$ class include a routine to retrieve the camera viewing direction based on the position of distinct objects in the images (e.g., summit of volcano, cf. Figure 3), or the calculation of distances to topographic features in the images (cf. Figure 10). The $\mathrm{MeasGeometry}$ class makes use of the Geonum library [37], which is briefly introduced in Appendix A, and which provides automatic online access to topographic data from the NASA shuttle radar topography mission (SRTM, [38]) and also supports the ETOPO1 dataset [39]. Furthermore, 2D and 3D topographic overview maps of the measurement setup can be created automatically (as shown in Figure 3, see also Figure 10c).

3.2. Image Representation and Pre-Processing Routines

Images are represented by the $\mathrm{Img}$ class (image.py module). The $\mathrm{Img}$ class includes reading routines for all image formats supported by the Python Imaging Library (PIL, e.g., png, tiff, jpeg, bmp) as well as the FITS format (Flexible Image Transport System). It further allows to store relevant meta information (e.g., exposure and acquisition time, focal length, f-number) and includes several basic processing methods (e.g., smoothing, cropping or resizing using a Gaussian pyramid approach). The image data itself is loaded and stored as a 2D-NumPy array within an $\mathrm{Img}$ object. Automatic dark and offset correction can be performed as described in Appendix C. $\mathrm{Img}$ objects can be saved as FITS files at any stage of the analysis (e.g., dark corrected image, ${\tau }_{\mathrm{AA}}$ image, calibrated SO₂-CD image).

3.3. Retrieval of Plume Background Radiances

The calculation of the OD images in both wavelength channels requires the retrieval of the sky-background intensities $I_0$ behind the plume (cf. Equation (1)). The plumebackground.py module provides several alternatives to retrieve the background intensities, either from the plume images directly or using an additional sky reference image ($I_0$-image). For the latter, several methods are available to correct for offsets and non-uniformities in the sky-background between the plume and $I_0$-image. The corrections are based on suitable sky-reference-areas in the plume image (rectangles or profile-lines, cf.

Table 2. Available plume background modelling methods of the $\mathrm{PlumeBackgroundModel}$ class (cf. names of sky reference areas in Figure 4).

Method	${\mathit{I}}_0$-img	Corrections
		Scaling	Vertical	Horizontal
1	yes	Scaling in scale_rect	None	None
2	yes	See 1	Linear correction using scale_rect and ygrad_rect	None
3	yes	See 1	Curvature correction by fitting polynomial of n-th order using sky reference pixels along vertical profile line (default: n = 2, i.e., quadratic polynomial)	None
4	yes	See 1	Linear correction (see 2)	Linear correction using scale_rect and xgrad_rect
5	yes	See 1	Curvature correction (see 3)	Linear correction (see 4)
6	yes	See 1	Curvature correction (see 3)	Curvature correction by fitting polynomial of n-th order using sky reference pixels along horizontal profile line (default: n = 2, i.e., quadratic polynomial)
0	no	Masked 2D polynomial surface fit
99	yes	None (use $I_0$-img as is)

) and use polynomials of a suitable order (e.g., linear or quadratic) to model the $I_0$-image such that the corresponding OD image satisfies $\tau =0$ within the specified sky reference areas.

If no $I_0$-image is available, the plume background radiances can also be estimated from the plume images directly using a masked 2D polynomial surface fit. The required mask specifies clear-sky image pixels that are considered during the fit. The mask can either be provided by the user or can be retrieved automatically using the function $\text{find\_sky\_background}$ of the plumebackground.py module.

The $\mathrm{PlumeBackgroundModel}$ class (part of plumebackground.py) provides high level access to eight default methods for the background retrieval (in the code denoted with mode). These different retrieval methods are summarised in Table 2. Figure 4 shows four example plume on-band OD images calculated using the background modelling methods 0, 1, 4 and 6 (cf. Table 2). It is not intended to give a recommendation for a “best” method here, as this strongly depends on the data (e.g., availability of suitable reference areas; acquisition time and relative viewing direction of $I_0$-image; solar position).

3.4. Camera Calibration

The camera calibration can either be performed using data based on cuvettes (gas cells) filled with a known amount of SO₂-gas, or using plume SO₂-CDs retrieved from a co-located DOAS spectrometer (cf. Table 1).

3.4.1. Calibration Using SO₂ Cells

Cell calibration can be performed using the $\mathrm{CellCalibEngine}$ class (cellcalib.py module) and requires a dataset containing both cell and sky background images. It is assumed that the camera is pointed into a gas and cloud free area of the sky and that the cells (containing different SO₂-CDs) are consecutively placed in front of the lens, such that they cover the whole FOV of the camera. Figure 5a shows a time-series of the image mean intensities retrieved from such a dataset. The individual cells can be identified by abrupt intensity drops in the time-series while the ambient background only changes gradually. The corresponding time-intervals for cell and background images can be specified by the user or, alternatively, detected automatically within an instance of the $\mathrm{CellCalibEngine}$ class (shown in Figure 5a, see also example scripts 0.7 and 5).

Cell OD images in both channels (${\tau }_{\mathrm{on}}$, ${\tau }_{\mathrm{off}}$) can be determined using a suitable background image. Care has to be taken for measurements performed at large solar zenith angles (early morning, late afternoon) due to rapid changes of the ambient sky intensity (cf. Figure 5a). In this case, the background image needs to be scaled to the sky intensity present at the acquisition time of each cell in order to calculate the OD images. This correction was performed for the data shown in Figure 5a (i.e., dashed line “Fitted BG polynomial”). It requires at least two background images, one recorded before, and a second one after the cells were put in front of the lens.

The calibration results (e.g., one AA image for each cell) are stored within $\mathrm{CellCalibData}$ objects together with the corresponding cell SO₂-CDs (which need to be provided by the user). Calibration curves can then be retrieved per image pixel or within a certain pixel neighbourhood. Figure 5b shows example calibration curves for ${\tau }_{\mathrm{on}}$, ${\tau }_{\mathrm{off}}$ and ${\tau }_{\mathrm{AA}}$ images.

3.4.2. Calibration Using DOAS Data

The DOAS calibration is performed using a set of plume optical density images (usually AA images) and a corresponding time-series of SO₂-CDs retrieved from a DOAS spectrometer. In a first step, the AA images are stacked into a 3D-NumPy array and merged in time with the DOAS data. The latter can be performed in three different ways (for details see Appendix D.1). The calibration data (i.e., merged time-series of SO₂-CDs and camera AA values within the DOAS FOV) can be retrieved by convolving the AA stack with a mask specifying position and shape of the DOAS field-of-view (FOV) within the image plane. The calibration data is stored within instances of the $\mathrm{DoasCalibData}$ class, which is also used to retrieve the calibration curve. The latter is done by fitting a polynomial of appropriate order to the calibration data. Optionally, the fit can be performed using a weighted regression, to account for statistical uncertainties in the DOAS SO₂-CDs (e.g., fit-errors, cf. Figure 6). $\mathrm{DoasCalibData}$ objects can be stored using the FITS standard (including the FOV mask).

Note that the DOAS calibration curve is only valid within the image pixel area covered by the DOAS FOV. This is due to cross-detector variations in the SO₂ sensitivity (see Section 2.2) and can be corrected for using a mask retrieved from a cell calibration dataset. The mask is determined by fitting a 2D polynomial to a cell AA image (see prev. Section 3.4.1), which is then normalised to the centre-position of the DOAS FOV (illustrated in example script 7). Please also note that Pyplis cannot perform the DOAS analysis. Thus, the SO₂-CDs need to be retrieved using a suitable 3rd party software (e.g., DOASIS, [40]).

3.4.3. DOAS FOV Search

Pyplis includes two routines to retrieve the DOAS FOV mask (included in the $\mathrm{DoasFOVEngine}$ class) based on a stack of AA images and a DOAS data vector:

• Pearson routine: this method loops over all image pixels in the AA stack and determines the Pearson correlation coefficient between the corresponding AA time-series (${\tau }_{AA}(t)$) and the DOAS SO₂-CD vector ($S_{\mathrm{SO}2}(t)$). The method yields a correlation image as shown in Figure 7a, from which the pixel coordinate with highest correlation ($i_0,j_0$) is extracted (see also [21]). Assuming a circular FOV shape, the pixel extent of the FOV is estimated around $i_0,j_0$, by iteratively searching the disk radius with highest correlation between the AA and the DOAS time-series.
• In-operation field-of-view retrieval (IFR) routine: this method is based on [30] and uses an inversion algorithm to retrieve the FOV. Position and shape of the FOV is parametrised by fitting a 2D Super-Gaussian to the retrieved FOV distribution (shown in Figure 7b, see Appendix D.2 for details).

The retrieved FOV information (position, shape, convolution mask) is represented by the $\mathrm{DoasFOV}$ class and can be stored as a FITS file.

3.5. Plume Velocity Analysis

Plume velocities can be retrieved either using the ICA cross-correlation method or using an optical flow algorithm. Both methods yield displacement estimates in units of pixels/time. These are converted into plume gas velocities based on the measurement geometry ($\mathrm{MeasGeometry}$, see Section 3.1). The relevant code is implemented in the plumespeed.py module.

3.5.1. Velocity Retrieval Using the ICA Cross-Correlation Method

For the cross-correlation method, ICA time-series (see Equation (4)) are determined using two PCS lines located at different positions downwind the emission source. Ideally, the PCS lines should be parallel and should cover an entire plume cross-section (indicated in Figure 8, left).

In a first step, the two time-series are re-sampled onto a regular grid (default is 1 s resolution). In a second step, a correlation analysis is applied to the re-sampled data vectors in order to find the time lag corresponding to the highest correlation between both signals. The method yields one average velocity vector, which is representative for the used image region and time-series. Note that the method intrinsically assumes that the average plume propagation direction $\overline{\phi }$ in the $i,j$-plane is aligned with the PCS normal (i.e., $\overline{\phi }\parallel \widehat{\mathit{n}}$) and furthermore that SO₂ is conserved between the two PCS lines used. Figure 8 shows results from an example cross-correlation analysis, resulting in a plume velocity of 3.5 m/s.

3.5.2. Optical Flow Based Velocity Retrievals

Optical flow velocity retrievals are performed using the Farnebäck algorithm [41], which is implemented in the OpenCV library [42]. The algorithm can estimate motion at the pixel-level by tracking local contrast features between consecutive frames. Note, however, that optical flow algorithms may fail to detect motion in extended homogeneous image areas. In this case, appropriate corrections may be required (e.g., [43]).

All relevant calculations for optical flow based velocity retrievals are performed within the $\mathrm{OptflowFarneback}$ class. The class includes the Farnebäck algorithm itself as well as several pre- and post-analysis routines. The latter includes a routine that can detect and correct for unphysical motion estimates in homogeneous image regions based on the method proposed by [43]. The correction identifies the local average velocity vector using peaks in histograms of an optical flow motion field.

The Farnebäck algorithm itself requires specification of several input parameters (see e.g., [23], or OpenCV documentation). The Pyplis default settings follow the suggestions of [23]. An example flow field is shown in Figure 9 including results from the histogram post analysis within a narrow region-of-interest (ROI) around an example retrieval line. The latter yields an average velocity magnitude of $4.2(\pm 0.4)\mathrm{m}/\mathrm{s}$ and a predominant movement direction of $\phi =-65(\pm 14){}^{\circ }$ within the image plane. Optical flow plume velocity retrievals, including the histogram post analysis method, are introduced in example script 9 (see Table A2).

3.6. Image Based Signal Dilution Correction

A correction for the signal dilution effect (see Section 2.4) can be performed using the $\mathrm{DilutionCorr}$ class. The method is based on [22] and uses the model function

$$I_{\mathrm{meas}}(\lambda )=I_0(\lambda )e^{-ϵ(\lambda )d}+I_A(\lambda )(1-e^{-ϵ(\lambda )d})$$

(5)

to retrieve atmospheric extinction coefficients $ϵ$ in the on and off-band regime. Here, $\lambda$ denotes the wavelength, $I_{\mathrm{meas}}$ are measured intensities of dark terrain features within the images, d is the distance to these features and $I_0$ their initial intensity. The ambient intensity $I_A$ can be approximated using gas free sky areas in the plume images [22]. For the retrieval, a set of measured intensities $I_{\mathrm{meas}}$ is extracted from vignetting corrected plume images using suitable terrain features (e.g., pixels along a volcanic flank). These intensities are fitted to Equation (5) (as a function of their distance d) in order to retrieve the extinction coefficients in both wavelength regimes. The required distances d to the features can be retrieved automatically, based on intersections of individual pixel viewing directions with the local topography (using the Geonum library; for details, see Appendix A).

The plume images can then be corrected for the signal dilution effect using the retrieved extinction coefficients (see Equation (4) in [22]). The correction is only applied to plume pixels (e.g., using a ${\tau }_{AA}$ threshold mask). The required plume distances can be retrieved from the measurement geometry (for details, see Section 3.1).

Figure 10 shows results of an example dilution correction using an on and off-band image from the Etna example data, recorded at 6:45 a.m. UTC. Extinction coefficients of ${ϵ}_{\mathrm{on}}=0.0743{\mathrm{km}}^{-1}$ (Figure 10a) and ${ϵ}_{\mathrm{off}}=0.0654{\mathrm{km}}^{-1}$ (Figure 10b) were retrieved using the two topographic profile lines shown in Figure 10c,d. The correction yields an emission rate of $4.8(\pm 1.2)\mathrm{kg}/\mathrm{s}$ using the PCS line shown in Figure 10d. The emission rate of the uncorrected image is $1.6(\pm 0.8)\mathrm{kg}/\mathrm{s}$, corresponding to an underestimation of approximately 67% at an average plume distance of $10.4(\pm 0.1)$ km.

3.7. Emission Rate Retrieval

Emission rates can be determined using the $\mathrm{EmissionRateAnalysis}$ class. The analysis is performed based on an image list containing calibrated SO₂-CD images (see also Appendix E.2) and a specification of one or more retrieval PCS lines ($\mathrm{LineOnImage}$ objects, cf. Figure 2). Plume velocities can be provided by the user (e.g., using the result of a cross-correlation analysis, see Section 3.5.1) or can be retrieved automatically during the emission rate analysis using the Farnebäck optical flow routine (see Section 3.5.2). For the latter, three options are available:

• flow_raw → the raw output of the Farnebäck algorithm is used. This should only be done if it can be assured that the algorithm yields reliable output in the considered plume area (i.e., ROI around the PCS line) and for all images of the time-series.
• flow_histo → performs the histogram post-analysis proposed by [43] (cf. Section 3.5.2). The retrieved local average velocity vector for each PCS line is then used as a velocity estimate for the corresponding retrieval line.
• flow_hybrid → reliable motion vectors from the flow field are used while unreliable ones are identified and replaced based on the histogram post-analysis (see previous point).

Figure 11 shows results from an emission rate analysis for the Etna test data (upper panel) including plume velocities retrieved using the flow_hybrid method (lower panel). The AA images were calculated from dilution corrected on and off-band plume images using background modelling method 6 (cf. Section 3.3) and were corrected for cross-detector sensitivity variations using a mask retrieved from cell “a53” (cf. Figure 5a). The AA images were calibrated using the Pearson DOAS calibration curve shown in Figure 6.

Remark on Performance

The emission rate analysis (cf. Figure 11) was performed using a Gaussian pyramid level of 1 (i.e., reduction of image size by a factor of 2). For these settings, the typical computation time to calculate a calibrated SO₂-CD image from the raw data amounts to approximately 0.2 s using an Intel(R) Core(TM) i7-6500U CPU (2.50 GHz, 8 GB RAM) (Santa Clara, CA, USA). Approximately the same time of 0.2 s is required to compute the optical flow between two frames at this pyramid level (cf.

Table A1. Performance analysis of the five image preparation steps listed above, dependent on Gaussian pyramid level (pyrlevel) and Gaussian blurring (blur) including the relative percentage impact of the optical flow computation.

Blur	Pyrlevel	Computation Time [s]
		Image Preparation (Steps 1–4)	Optical Flow (Step 5)	Total
10	0	0.350	0.823 (70 %)	1.173
0	0	0.188	0.813 (81 %)	1.001
0	1	0.205	0.202 (50 %)	0.407
0	2	0.203	0.103 (34 %)	0.306

). For the discussed dataset of 209 on-band plume images, this results in a total computation time of about two minutes, including the four different velocity retrieval methods introduced above and shown in Figure 11. Note that the latter does not include the time to compute the DOAS FOV and calibration data, nor the time required for the cross-correlation velocity retrieval, since these analyses were performed beforehand (for details, see Appendix B and example script 12).

3.8. Remark on Uncertainties

The uncertainties in the emission rates (cf. shaded areas in Figure 11) were calculated using Gaussian error propagation (see method $\text{det\_emission\_rate}$ of the fluxcalc.py module) considering (1) uncertainties in the meteorological wind direction and camera viewing direction (accessible using the method $\text{plume\_dist\_err}$ of the $\mathrm{MeasGeometry}$ class); (2) uncertainties in the calibration curve (based on slope error retrieved from covariance matrix of fit result, accessible using the attribute $\text{slope\_err}$ of either the $\mathrm{DoasCalibData}$ or the $\mathrm{CellCalibData}$ class); and (3) the uncertainties in the velocity retrieval. For optical flow based velocity analyses, the uncertainties are calculated as discussed in Section 2.4.1 in [43], based on the retrieved effective velocities ${\mathit{v}}_{\mathrm{eff}}=〈\overline{\mathit{v}}·\widehat{\mathit{n}}〉$ along $\ell$ (cf. Equation (3)). Note that Pyplis does not provide a method to estimate the uncertainties of cross-correlation based velocity retrievals. These need to be provided by the user (cf. example script 12). The errors in the effective velocities can be accessed via the $\text{velo\_eff\_err}$ attribute of the $\mathrm{EmissionRates}$ class. Note that all uncertainties computed by Pyplis are assumed to be of statistical nature. Hence, they do not account for any potential systematic errors, for instance arising from ill-constrained optical flow vectors when using the flow_raw retrieval method (see discussion in Section 2.4.1 in [43]).

4. Conclusions

In this paper, the software package Pyplis was introduced. Pyplis contains an extensive collection of relevant algorithms for the analysis of UV SO₂ camera data, particularly for the retrieval of emission rates from SO₂-emitters (e.g., volcanoes, power plants, ships).

Apart from established analysis methods, such as cross-correlation based velocity retrievals (e.g., [32]) or cell and DOAS calibration (e.g., [21]), Pyplis incorporates more recent developments. These include an implementation of the DOAS FOV retrieval algorithm proposed by [30], a routine to correct for the signal dilution effect based on [22], or pixel based gas velocity retrievals using an optical flow algorithm (e.g., [23]). The latter incorporates a method to detect and correct for ill constrained optical flow motion-vectors based on [43]. Furthermore, Pyplis includes a framework to perform a detailed 3D-analysis of the observed camera scene including automatic online access to high resolution topography data from the SRTM dataset. This enables, for example, to retrieve the camera viewing direction based on distinct topographic features in the images (e.g., volcano summit), or to calculate distances between the camera and the local topography at a pixel-level. The latter is of particular relevance for the image based correction of the signal dilution effect.

Due to this extensive collection of algorithms, Pyplis provides flexibility with regard to the analysis strategy and is highly adaptable to different data situations. The object oriented architecture of the API gives intuitive access to the main features and makes it easy to compare individual methods (e.g., different plume velocity retrievals, as illustrated in this paper). Pyplis is open-source and can be operated both on Windows and Unix machines. Thus, it is well suited for inter-comparison studies, the exchange of analysis results or for the development and verification of new methods.

The Pyplis installation includes numerous example scripts that were used in this paper to introduce the main features of the software. The examples are based on a 15 min dataset recorded at Mt. Etna, Italy in September 2015, which is freely available and can be downloaded from the website.

Finally, the authors wish to point out that Pyplis may also be used for other applications based on the same measurement principle (e.g., NO₂ cameras) and that parts of it can also be useful for other remote sensing applications (e.g., the engine for geometrical calculations). The Pyplis software is hosted on GitHub ([27,28]). The code documentation and further information (e.g., installation instructions) can be found on the documentation website (see [27,28]).