API 

print_setup()[source]

Print the current setup.

Returns:: print string representation
Return type:: str

class pyplis.setupclasses.Camera(cam_id: str | None = None, filter_list: list | None = None, default_filter_on=None, default_filter_off=None, ser_no=9999, cam_info_file: Path | None = None, try_load_from_registry=True, **geom_info)[source]

Base class to specify a camera setup.

Class representing a UV camera system including detector specifications, optics, file naming convention and the bandpass filters that are equipped with the camera (managed via an instance of the FilterSetup class).

Parameters:

cam_id (str) – camera ID (e.g “ecII”), if this ID corresponds to one of the default cameras, the information is automatically loaded from supplementary file cam_info.txt
filter_list (list) – list containing pyplis.utils.Filter objects specifying the camera filter setup. If unspecified (empty list) and input param cam_id is a valid default ID, then the default filter setup of the camera will be loaded.
default_filter_on (str) – string ID of default on band filter (only relevant if collection contains more than one on band filter)
default_filter_off (str) – string ID of default off band filter (only relevant if collection contains more than one off band filter)
ser_no (int) – optional, camera serial number
cam_info_file (Path) – camera info file from which the default information for provided cam_id shall be imported.
try_load_from_registry (bool) – if True, and if cam_id is provided, the camera information is loaded from the pyplis camera registry. Default is True.
**geom_info – additional keyword args specifying geometrical information, e.g. lon, lat, altitude, elev, azim

Examples

Example creating a new camera (using ECII default info with custom filter setup):

import pyplis

#the custom filter setup
filters= [pyplis.utils.Filter(type="on", acronym="F01"),
          pyplis.utils.Filter(type="off", acronym="F02")]

cam = pyplis.setupclasses.Camera(cam_id="ecII", filter_list=filters,
                                  lon=15.11, lat=37.73, elev=18.0,
                                  elev_err=3, azim=270.0,
                                  azim_err=10.0, focal_lengh=25e-3)
print cam

__init__(cam_id: str | None = None, filter_list: list | None = None, default_filter_on=None, default_filter_off=None, ser_no=9999, cam_info_file: Path | None = None, try_load_from_registry=True, **geom_info)[source]

Init object.

Parameters:

cam_id (str) – string ID of camera (e.g. “ecII”)
cam_info_file (Path) – path to cam_info.txt file to be used to load default.

Note

if input cam_id is valid (i.e. can be found in database) then any additional input using info_dict is ignored.

property lon: Camera longitude.

property lat: Camera latitude.

property altitude: Camera altitude in m.

Note

This is typically the local topography altitude, which can for instance be accessed automatically based on camera position (lat, lon) using get_altitude_srtm(). Potential offsets (i.e. elevated positioning due to tripod or measurement from a house roof) can be specified using alt_offset.

property elev

Return viewing elevation angle (center pixel) in degrees.

0 refers to horizon, 90 to zenith

property elev_err: Uncertainty in viewing elevation angle in degrees.

property azim: Return viewing azimuth angle in deg relative to north (center pixel).

property azim_err: Uncertainty in viewing azimuth angle in degrees.

property alt_offset

Height of camera position above topography in m.

This offset can be added in case the camera is positioned above the ground and is only required if :param:`altitude` corresponds to the topographic elevation

load_default(cam_id: str, cam_info_file: Path | None = None)[source]: Redefinition of method from base class CameraBaseInfo.

update(**settings)[source]

Update camera parameters.

Parameters:: settings (dict) – dictionary containing camera parametrs (valid keys are all keys of self.__dict__ and from dictionary self.geom_data)

get_altitude_srtm()[source]: Try load camera altitude based on lon, lat and SRTM topo data.

Note

Requires geonum package to be installed and lon and lat to be set.

prepare_filter_setup(filter_list: list | None = None, default_key_on: str | None = None, default_key_off: str | None = None)[source]

Create FilterSetup object.

This method defines the camera filter setup based on an input list of Filter instances.

Parameters:

filter_list – list containing pyplis.utils.Filter objects
default_key_on – string specifiying the string ID of the main onband filter of the camera (usually “on”). If unspecified (None), then the ID of the first available on bandfilter in the filter input list will be used.
default_key_off – string specifiying the string ID of the main offband filter of the camera (usually “on”). If unspecified (None), then the ID of the first available off band filter in the filter input list will be used.

to_dict()[source]: Convert this object into a dictionary.

change_camera(cam_id=None, make_new=False, **kwargs)[source]

Change current camera type.

Parameters:

cam_id (str) – ID of new camera
make_new (bool) – if True, a new instance will be created and returned
**kwargs – additional keyword args (see __init__())

Returns:

either this object (if :param:`make_new` is False) or else, new instance

Return type:

Camera

dx_to_decimal_degree(pix_num_x)[source]

Convert horizontal distance (in pixel units) into angular range.

Parameters:: pix_num_x (int) – number of pixels for which angular range is determined
Returns:: dx in units of decimal degrees
Return type:: float

dy_to_decimal_degree(pix_num_y)[source]

Convert vertical distance (in pixel units) into angular range.

Parameters:: pix_num_y (int) – number of pixels for which angular range is determined
Returns:: dy in units of decimal degrees
Return type:: float

class pyplis.setupclasses.FormSetup(line_dict=None, rect_dict=None)[source]

Setup class for all forms (lines, rectangles etc.) used for evaluation.

__init__(line_dict=None, rect_dict=None)[source]

class pyplis.setupclasses.BaseSetup(base_dir: str, start: datetime | None = None, stop: datetime | None = None, **opts)[source]

Abstract base class for basic measurement setup.

Specifies image base path and start / stop time stamps of measurement as well as the following boolean access flags:

USE_ALL_FILES

SEPARATE_FILTERS

USE_ALL_FILE_TYPES

INCLUDE_SUB_DIRS

ON_OFF_SAME_FILE

LINK_OFF_TO_ON

REG_SHIFT_OFF

Parameters:

base_dir (str) – Path were e.g. imagery data lies
start (datetime) – start time of Dataset (can also be datetime.time)
stop (datetime) – stop time of Dataset (can also be datetime.time)
**opts – setup options for file import (see specs above)

__init__(base_dir: str, start: datetime | None = None, stop: datetime | None = None, **opts)[source]

property start: Start time of setup.

property stop: Stop time of setup.

property USE_ALL_FILES

File import option (boolean).

If True, all files in image base folder are used (i.e. start / stop time stamps are disregarded)

property SEPARATE_FILTERS

File import option (boolean).

If true, files are separated by filter type (e.g. “on”, “off”)

property USE_ALL_FILE_TYPES

File import option (boolean).

If True, all files found are imported, disregarding the file type (i.e. if image file type is not specified. It is strongly recommended NOT to use this option)

property INCLUDE_SUB_DIRS

File import option (boolean).

If True, sub directories are included into image search

property ON_OFF_SAME_FILE

File import option (boolean).

If True, it is assumed, that each image file contains both on and offband images. In this case, both the off and the onband image lists are filled with the same file paths. Which image to load in each list is then handled within the ImgList`itself on :func:`load using the attribute list_id which is passed using the key filter_id to the respective customised image import method that has to be defined in the custom_image_import file of the pyplis installation and linked to your Camera settings in the cam_info.txt file which can be found in the data directory of the installation.

An example for such a file convention is the SO2 camera from CVO (USGS) See e.g. load_usgs_multifits() in custom_image_import.

property LINK_OFF_TO_ON

File import option (boolean).

If True, the offband ImgList is automatically linked to the onband list on initiation of a Dataset object.

property REG_SHIFT_OFF

File import option (boolean).

If True, the images in an offband image list that is linked to an onband image list (cf. LINK_OFF_TO_ON) are shifted using the registration offset specified in the reg_shift_off attribute of the Camera instance.

base_info_check()[source]

Check if all necessary information if available.

Checks if path and times are valid

Returns:

2-element tuple, containing
- bool, True or False
- str, information

class pyplis.setupclasses.MeasSetup(base_dir=None, start=None, stop=None, camera=None, source=None, wind_info=None, cell_info_dict=None, rects=None, lines=None, auto_topo_access=True, **opts)[source]

Setup class for plume image data.

In this class, everything related to a full measurement setup is defined. This includes the image base directory, start / stop time stamps (if applicable), specifications of the emission source (i.e. Source object), camera specifications (i.e. Camera object) as well as meteorology information (i.e. wind direction and velocity). The latter is not represented as an own class in Pyplis but is stored as a Python dictionary. MeasSetup objects are the default input for pyplis.dataset.Dataset objects (i.e. also pyplis.cellcalib.CellCalibEngine).

Parameters:

base_dir (str) – Path were e.g. imagery data lies
start (datetime) – start time of Dataset (may as well be datetime.time)
stop (datetime) – stop time of Dataset (may as well be datetime.time)
camera (Camera) – general information about the camera used
source (Source) – information about emission source (e.g. lon, lat, altitude)
**opts – setup options for file handling (currently only INCLUDE_SUB_DIRS option)

__init__(base_dir=None, start=None, stop=None, camera=None, source=None, wind_info=None, cell_info_dict=None, rects=None, lines=None, auto_topo_access=True, **opts)[source]

update_wind_info(info_dict)[source]

Update wind info dict using valid entries from input dict.

Parameters:: info_dict (dict) – dictionary containing wind information

base_info_check()[source]: Check if all req. info is available.

check_geometry_info()[source]

Check if all req. info for measurement geometry is available.

Relevant parameters are:

Lon, Lat of

source

camera

Meteorology info

Wind direction

Wind velocity (rough estimate)

Viewing direction of camera

Azimuth (N)

Elvation(from horizon)

Alitude of camera and source

Camera optics

Pixel size

Number of pixels detector

focal length

update_meas_geometry()[source]: Update the meas geometry based on current settings.

short_str()[source]: Return a short info string.

Data Set object

Assorted data import functionality.

The Dataset object is doing all sorts of stuff related to the general data import setup, for instance the automated separation of image files by their type (e.g. on-band, off-band, dark, offset) using information from a file naming convention specified within a Camera object. For more information how to customise your data import see pyplis.setupclasses or read this little introductory tutorial

class pyplis.dataset.Dataset(input=None, lst_type=<class 'pyplis.imagelists.ImgList'>, init=1)[source]

Class for data import management.

Default input is a pyplis.setupclasses.MeasSetup object, which specifies the camera used (e.g. file naming convention, detector specifics) the measurement geometry and information about the source and meteorological wind direction, start / stop time stamps and the image base directory.

setup

class containing measurement setup information

Type:: MeasSetup

lst_type

default type of ImgList objects (cf. CellCalibEngine)

Type:: object

lists_access_info

dictionary filled on data import based on camera specifications. Used to map API IDs of filters and dark / offset information (e.g. “on”, “off”, “dark0”) onto internal list keys. It is normally not required to use this dictionary or apply changes to it. For EC2 camera standard this will look like:

>>> self.lists_access_info
OrderedDict([('on', ['F01', 'F01']),
             ('off', ['F02', 'F02']),
             ('offset0', ['D0L', 'D0L']),
             ('dark0', ['D1L', 'D1L']),
             ('offset1', ['D0H', 'D0H']),
             ('dark1', ['D1H', 'D1H'])])

Type:: OrderedDict

Parameters:

input – Usable input includes MeasSetup instance or a valid image directory. input is passed to load_input().
lst_type (object) – default type of image list objects (e.g. ImgList, CellImgList), defaults to ImgList.
init (bool) – init

__init__(input=None, lst_type=<class 'pyplis.imagelists.ImgList'>, init=1)[source]

property camera: Return camera base info object.

property source: Get / set current Source.

property cam_id: Return current camera ID.

property base_dir: Getter / setter of current image base_dir.

property USE_ALL_FILES: Return USE_ALL_FILES boolen from setup.

property USE_ALL_FILE_TYPES: Return USE_ALL_FILE_TYPES option from setup.

property INCLUDE_SUB_DIRS: Return boolean sub directory inclusion option.

property LINK_OFF_TO_ON: I/O option defined in BaseSetup.

property start: Getter / setter for current start time stamp.

property stop: Getter / setter for current stop time stamp.

property file_type: Return current image file type.

property meas_geometry: Return current measurement geometry.

property filters: Return the current filter setup.

property filter_acronyms: Make a dictionary of filter IDs and corresponding acronyms.

property num_of_filters: Return the number of filters in self.filters.

property rects: Return rectangle collection.

property lines: Return rectangle collection.

load_input(input)[source]

Extract information from input and set / update self.setup.

Parameters:: input – Usable input includes MeasSetup instance or a valid image directory.
Returns:: True, if input could be utilised, False if not
Return type:: bool

set_setup(stp)[source]

Set the current measurement setup.

Parameters:: stp (MeasSetup) – Class containing information about measurement setup

init_image_lists()[source]: Create and fill image lists.

create_lists_default()[source]: Initialize of default lists (if camera specs not available).

create_lists_cam()[source]: Initialize of all image lists, old lists are deleted.

fill_image_lists()[source]: Import all images and fill image list objects.

get_all_filepaths()[source]

Find all valid image filepaths in current base directory.

Returns:: list containing all valid image file paths (Note, that these include all files found in the folder(s) in case the file type is not explicitely set in the camera class.)
Return type:: list

check_filename_info_access(filepath)[source]

Check which information can be accessed from file name.

The access test is performed based on the filename access information specified in the Camera object of the measurement setup

Parameters:: filepath (str) – valid file path of an example image
Returns:: Dictionary containing information about which meta information could be identified from the image file path based on the current camera
Return type:: dict

change_img_base_dir(img_dir)[source]

Set or update the current base_dir.

Parameters:: p (str) – new path

extract_files_time_ival(all_paths)[source]

Extract all files belonging to specified time interval.

Parameters:: all_paths (list) – list of image filepaths

find_closest_img(filename, in_list, acronym, meas_type_acro)[source]

Find closest-in-time image to input image file.

Parameters:

filename (str) – image filename
in_list (str) – input list with filepaths
acronym (str) – the acronym of the image type to be searched (e.g. an acronym for a dark image as specified in camera)
meas_type_acro (str) – meas type acronym of image type to be searched (e.g. an acronym for a dark image as specified in camera)

all_lists()[source]

Return list containing all available image lists.

Loops over self._lists_intern and the corresponding sub directories

property dark_ids: Get all dark IDs.

assign_dark_offset_lists(into_list=None)[source]

Assign dark and offset lists to image lists self.lists.

Assign dark and offset lists in filter lists for automatic dark and offset correction. The lists are set dependent on the read_gain mode of the detector

Parameters:: (None) (ImgList into_list) – optional input, if specified, the dark assignment is performed only in the input list

get_all_dark_offset_lists()[source]: Get all dark and offset image lists.

property dark_lists: Call and return get_all_dark_offset_lists().

property dark_lists_with_data: Return all dark/offset lists that include image data.

property filter_ids: Get all dark IDs.

get_all_image_lists()[source]: Get all image lists (without dark and offset lists).

property img_lists: Wrap get_all_image_lists().

property img_lists_with_data: Wrap get_all_image_lists().

check_dark_lists()[source]: Check all dark lists whether they contain images or not.

find_master_dark(dark_list)[source]

Search master dark image for a specific dark list.

Search a master dark image for all dark image lists that do not contain images

find_master_darks(dark_ids=None)[source]

Search master dark image for dark image lists.

Search a master dark image for all dark image lists that do not contain images.

check_image_access_dark_lists()[source]: Check whether dark and offset image lists contain at least one img.

images_available(filter_id)[source]

Check if image list has images.

Parameters:: filter_id (str) – string (filter) ID of image list

current_image(filter_id)[source]

Get current image of image list.

Parameters:: filter_id (str) – filter ID of image list

get_list(list_id)[source]

Get image list for one filter.

Parameters:: filter_id (str) – filter ID of image list (e.g. “on”)

get_current_img_prep_dict(list_id=None)[source]

Get the current image preparation settings from one image list.

Parameters:: list_id (str) – ID of image list

load_images()[source]: Load the current images in all image lists.

Note

Gives warning for lists containing no images

update_image_prep_settings(**settings)[source]: Update image preparation settings in all image lists.

update_times(start, stop)[source]

Update start and stop times of this dataset and reload.

Parameters:

start (datetime) – new start time
stop (datetime) – new stop time

duplicate()[source]: Duplicate Dataset object.

show_current_img(filter_id, add_forms=False)[source]

Plot current image.

Parameters:: filter_id (str) – filter ID of image list (e.g. “on”)

plot_mean_value(filter_id, yerr=1, rect=None)[source]

Plot the pixel mean value of specified filter.

Only pixel values in the time span covered by this dataset are used.

draw_map_2d(*args, **kwargs)[source]: Call and return draw_map_2d() of self.meas_geometry.

draw_map_3d(*args, **kwargs)[source]: Call and return draw_map_3d() of self.meas_geometry.

print_list_info()[source]: Print overview information about image lists.

connect_meas_geometry()[source]: Set pointer to current measurement geometry within image lists.

plot_tau_preview(on_id='on', off_id='off', pyrlevel=2)[source]

Plot a preview of current tau_on, tau_off and AA images.

AA is plotted twice in 1st row of subplots in 2 diffent value ranges.

Parameters:

on_id (str) – string ID of onband filter (“on”)
off_id (str) – string ID of offband filter (“off”)
pyrlevel – provide any integer here to reduce the image sizes using a gaussian pyramide approach (2)

Geometrical calculations

Module containing functionality for all relevant geometrical calculations.

class pyplis.geometry.MeasGeometry(source_info=None, cam_info=None, wind_info=None, auto_topo_access=True)[source]

Class for calculations and management of the measurement geometry.

All calculations are based on provided information about camera (stored in dictionary _cam, check e.g. self._cam.keys() for valid keys), source (stored in dictionary _source, check e.g. self._source.keys() for valid keys) and meteorological wind direction (stored in dictionary _wind). The keys of these dictionaries (i.e. identifiers for the variables) are the same as the corresponding attributes in the respective classes pyplis.Camera and pyplis.Source.

If you want to change these parameters, it is recommended to use the correpdonding update methods update_cam_specs(), update_source_specs() and update_wind_specs() or use the provided getter / setter methods for each parameter (e.g., cam_elev for key elev of _cam dictionary, cam_azim for key azim of _cam dictionary, cam_lon for key lon of _cam dictionary, cam_lat for key lat of _cam dictionary, source_lon for key lon of _source dictionary, source_lat for key lat of _source dictionary, wind_dir for key dir of _dir dictionary.

Note that in the dictionary based update methods update_cam_specs(), update_source_specs() and update_wind_specs(), the dict keys are supposed to be inserted, e.g.:

geom = MeasGeometry()
# either update using valid keywords as **kwargs ...
geom.update_cam_specs(lon=10, lat=20, elev=30, elev_err=0.5)

# ... or update using a dictionary containing camera info, e.g.
# retrieved from an existing camera ...
cam = pyplis.Camera(altitude=1234, azim=270, azim_err=10)
cam_dict = cam.to_dict()

geom.update_cam_specs(cam_dict)

# ... or directly using the getter / setter attributes
print geom.cam_altitude #1234 (value of geom._cam["altitude"])

geom.cam_altitude=111
print geom.cam_altitude #111 (new value of geom._cam["altitude"])

# analogous with source and wind

# This ...
geom.update_wind_specs(dir=180, dir_err=22)

# ... is the same as this:
geom.wind_dir=180
geom.wind_dir_err=22

# load Etna default source info
source = pyplis.Source("etna")
geom.update_source_specs(**source.to_dict())

The latter by default also update the most important attribute of this class geo_setup which is an instance of the geonum.GeoSetup class and which is central for all geometrical calculations (e.g. camera to plume distance).

geo_setup

class containing information about the current measurement setup. Most of the relevant geometrical calculations are performed within this object

Type:: GeoSetup

_source

dictionary containing information about emission source (valid keys: name, lon, lat, altitude)

Type:: dict

_wind

dictionary containing information about meteorology at source position (valid keys: dir, dir_err, velo, velo_err)

Type:: dict

_cam

dictionary containing information about the camera (valid keys: cam_id, serno, lon, lat, altitude, elev, elev_err, azim, azim_err, focal_length, pix_width, pix_height, pixnum_x, pixnum_y alt_offset

Type:: dict

Parameters:

source_info (dict) – dictionary containing source parameters (see source for valid keys)
cam_info (dict) – dictionary containing camera parameters (see cam for valid keys)
wind_info (dict) – dictionary conatining meteorology information (see wind for valid keys)

__init__(source_info=None, cam_info=None, wind_info=None, auto_topo_access=True)[source]

property cam_id: ID of current camera (string).

property cam_serno: Return serial number of camera.

property cam_lon: Longitude position of camera.

property cam_lat: Latitude position of camera.

property cam_altitude: Altitude of camera position.

property cam_elev: Elevation angle of camera viewing direction (CFOV).

property cam_elev_err: Elevation angle error of camera viewing direction (CFOV).

property cam_azim: Azimuth of camera viewing direction (CFOV).

property cam_azim_err: Azimuth error of camera viewing direction (CFOV).

property cam_focal_length: Focal length of camera.

property cam_pix_width: Pixel width of camera detector (horizonzal pix-to-pix distance).

property cam_pix_height: Pixel height of camera detector (vertical pix-to-pix distance).

property cam_pixnum_x: Return Number of camera detector pixels in x-direction (horizontal).

property cam_pixnum_y: Return Number of camera detector pixels in y-direction (vertical).

property cam_altitude_offs: Camera elevation above topography.

Note

This can be used as offset above the ground, if the camera altitude (cam_altitude) is retrieved based on local topography level (e.g. using automatic SRTM access based on camera lat and lon).

property source_lon: Longitude position of source.

property source_lat: Latitude position of source.

property source_altitude: Altitude of source position.

property wind_dir: Azimuth of wind direction.

property wind_dir_err: Azimuth error of wind direction.

update_cam_specs(info_dict: dict, update_geosetup=True)[source]

Update camera settings.

Update dictionary containing geometrical camera information (cam) by providing a dictionary containing valid key / value pairs for camera parameters.

Parameters:

info_dict (dict) – dictionary containing camera information (see cam for valid keys)
update_geosetup (bool) – If True, the method update_geosetup() is called at the end of this method

update_source_specs(info_dict: dict, update_geosetup: bool = True) → None[source]

Update source settings.

Update source info dictionary (source) either by providing a dictionary containing valid key / value pairs (:param:`info_dict` or by providing valid key / value pairs directly using :param:`kwargs`)

Parameters:

info_dict (dict) – dictionary containing source information (see source for valid keys)
update_geosetup (bool) – If True, the method update_geosetup() is called at the end of this method

update_wind_specs(info_dict, update_geosetup=True)[source]

Update meteorological settings.

Update wind info dictionary (wind) either by providing a dictionary containing valid key / value pairs (:param:`info_dict` or by providing valid key / value pairs directly using :param:`kwargs`)

Parameters:

info_dict (dict) – dictionary containing meterology information (see wind for valid keys)
update_geosetup (bool) – If True, the method update_geosetup() is called at the end of this method

update_geosetup() → bool[source]

Update the current GeoSetup object.

Note

The borders of the range are determined considering cam pos, source pos and the position of the cross section of viewing direction with plume

Return type:: Whether or not all required information for analysing the geometry is available.

get_coordinates_imgborders()[source]: Get elev and azim angles corresponding to camera FOV.

horizon_analysis(skip_cols=30)[source]

Search pixel coordinates of horizon for image columns.

The algorithm performs a topography analysis for a number of image columns. Elevation profiles are determined for each column (azimuth) and from those, the horizon elevation angle is searched. The retrieved values are returned in pixel coordinates.

Parameters:: skip_cols – distance between pixel columns for which the analysis is performed

Note

This is a Beta version, please report any problems

get_viewing_directions_line(line: LineOnImage) → Tuple[ndarray, ndarray, ndarray, ndarray][source]

Determine viewing direction coords for a line in an image.

Parameters:

line (LineOnImage) – line on image object

Returns:

4-element tuple containing 4 arrays of same length:

1-d array containing azimuth angles of pixels on line
1-d array containing elevation angles of pixels on line
1-d array containing corresponding x-pixel coordinates
1-d array containing corresponding y-pixel coordinates

Return type:

get_topo_distance_pix(pos_x_abs, pos_y_abs, topo_res_m=5.0, min_slope_angle=5.0)[source]

Retrieve distance to topography for a certain image pixel.

The computation of the distance is being done by retriving a elevation profile in the azimuthal viewing direction of tge pixel (i.e. pixel column) and then using this profile and the corresponding camera elevation (pixel row) to find the first intersection of the viewing direction (line) with the topography

Parameters:

pos_x_abs (int) – x-pixel position of point in image in absolute coordinate (i.e. pyramid level 0 and not cropped)
pos_y_abs (int) – y-pixel position of point in image in absolute coordinate (i.e. pyramid level 0 and not cropped)
topo_res_m (float) – desired resolution of topographic data (is interpolated)
min_slope_angle (float) – mininum required slope (steepness) of topography at pixel position (raises ValueError if topograpy is too flat)

Returns:

3-element tuple, containing

estimated distance to topography in m based on intersection of pixel viewing direction with topographic data
corresponding uncertainty in m
GeoPoint corresponding to intersection position

Return type:

get_topo_distances_line(line, skip_pix=30, topo_res_m=5.0, min_slope_angle=5.0)[source]

Retrieve distances to topography for a line on an image.

Calculates distances to topography based on pixels on the line. This is being done by retriving a elevation profile in the azimuthal viewing direction of each pixel (i.e. pixel column) and then using this profile and the corresponding camera elevation (pixel row) to find the first intersection of the viewing direction (line) with the topography

Parameters:

line (list) – list with line coordinates: [x0, y0, x1, y1] (can also be LineOnImage object)
skip_pix (int) – step width for retrieval along line
topo_res_m (float) – desired resolution of topographic data (is interpolated)
min_slope_angle (float) – mininum angle of slope, pixels pointing into flatter topographic areas are ignored

get_angular_displacement_pix_to_cfov(pos_x, pos_y)[source]

Get the angular difference between pixel and detector center.

Parameters:

pos_x (int) – x position on detector
pos_y (int) – y position on detector

get_azim_elev(pos_x, pos_y)[source]

Get values of azimuth and elevation in pixel (x|y).

Parameters:

pos_x (int) – x position on detector
pos_y (int) – y position on detector

get_elevation_profile(col_num=None, azim=None, dist_hor=None, topo_res_m=5.0)[source]

Retrieve elev profile from camera into a certain azim direction.

Parameters:

col_num (int) – pixel column number of profile, if None or not in image detector range then try to use second input parameter azim
azim (float) – is only used if input param col_num == None, then profile is retrieved from camera in direction of specified azimuth angle
dist_hor (float) – horizontal distance (from camera, in km) up to witch the profile is determined. If None, then use 1.05 times the camera source distance
topo_res_m (float) – desired horizontal grid resolution in m ()

get_distance_to_topo(col_num=None, row_num=None, azim=None, elev=None, min_dist=0.2, max_dist=None)[source]

Determine distance to topography based on pixel coordinates.

Parameters:

col_num (int) – pixel column number for elevation profile, from which the intersection with viewing direction is retrieved. If None or not in image detector range then try to use third input parameter (azim)
row_num (int) – pixel row number for which the intersection with elevation profile is is retrieved. If None or not in image detector range then try to use 4th input parameter elev, row_num is only considerd if col_num is valid
azim (float) – camera azimuth angle of intersection: is only used if input param col_num == None
elev (float) – camera elevation angle for distance estimate: is only used if input param row_num == None
min_dist (float) – minimum distance (in km) from camera for retrieval of first intersection. Intersections of viewing direction with topography closer than this distance are disregarded (default: 0.2)
max_dist (float) – maximum distance (in km) from camera for which intersections with topography are searched

find_viewing_direction(pix_x, pix_y, pix_pos_err=10, obj_id='', geo_point=None, lon_pt=None, lat_pt=None, alt_pt=None, update=True, draw_result=False)[source]

Retrieve camera viewing direction from point in image.

Uses the geo coordinates of a characteristic point in the image (e.g. the summit of a mountain) and the current position of the camera (Lon / Lat) to determine the viewing direction of the camera (azimuth, elevation).

Parameters:

pix_x (int) – x position of object on camera detector (measured from left)
pix_y (int) – y position of object on camera detector (measured from top)
pix_pos_err (int) – radial uncertainty in pixel location (used to estimate and update self._cam["elev_err"], self._cam["azim_err"])
update (bool) – if True current data will be updated and self.geo_setup will be updated accordingly
obj_id (str) – string ID of object, if this object is available as GeoPoint in self.geo_setup then the corresponding coordinates will be used, if not, please provide the position of the characteristic point either using :param:`geo_point` or by providing its coordinates using params lat_pt, lon_pt, alt_pt
geo_point (GeoPoint) – geo point object of characteristic point
lon_pt (float) – longitude of characteristic point
lat_pt (float) – latitude of characteristic point
alt_pt (float) – altitude of characteristic point (unit m)
update – if True, camera azim and elev are updated within this object
draw_result (bool) – if True, a 2D map is drawn showing results

Returns:

float, retrieved camera elevation
float, retrieved camera azimuth
MeasGeometry, initial state of this object, a deepcopy of this class, before changes where applied (if they were applied, see also update)

pix_dist_err(col_num, pyrlevel=0)[source]

Get uncertainty measure for pixel distance of a pixel column.

Parameters:

colnum (int) – column number for which uncertainty in pix-to-pix distance is computed
pyrlevel (int) – convert to pyramid level

Returns:

pix-to-pix distance in m corresponding to input column number and pyramid level

Return type:

compute_all_integration_step_lengths(pyrlevel=0, roi_abs=None)[source]

Determine images containing pixel and plume distances.

Computes and returns three images where each pixel value corresponds to:

the horizontal physical integration step length in units of m
the vertical physical integration step length in units of m (is the same as 1. for standard detectors where the vertical and horizontal pixel pitch is the same)
image where each pixel corresponds to the computed plume distance

Parameters:

pyrlevel (int) – returns images at a given gauss pyramid level
roi_abs (list) – ROI [x0, y0, x1, y1] in absolute detector coordinates. If valid, then the images are cropped accordingly

Returns:

3-element tuple, containing

Img: image where each pixel corresponds to pixel column distances in m
Img: image where each pixel corresponds to pixel row distances in m (same as col_dist_img if pixel width and height are equal)
Img: image where each pixel corresponds to plume distance in m

Return type:

get_plume_direction()[source]: Return the plume direction plus error based on wind direction.

plot_view_dir_pixel(col_num, row_num)[source]

2D plot of viewing direction within elevation profile.

Determines and plots elevation profile for azimuth angle of input pixel coordinate (column number). The viewing direction line is plotted based on the specified elevation angle (corresponding to detector row number)

Parameters:

col_num (int) – column number of pixel on detector
row_num (int) – row number of pixel on detector (measured from top)

Returns:

elevation profile

draw_map_2d(draw_cam=True, draw_source=True, draw_plume=True, draw_fov=True, draw_topo=True, draw_coastline=True, draw_mapscale=True, draw_legend=True, *args, **kwargs)[source]

Draw the current setup in a map.

Parameters:

draw_cam (bool) – insert camera position into map
draw_source (bool) – insert source position into map
draw_plume (bool) – insert plume vector into map
draw_fov (bool) – insert camera FOV (az range) into map
draw_topo (bool) – plot topography
draw_coastline (bool) – draw coastlines
draw_mapscale (bool) – insert a map scale
draw_legend (bool) – insert a legend
*args –
additional non-keyword arguments for setting up the base map (see here)
**kwargs –
additional keyword arguments for setting up the base map (see here)

draw_azrange_fov_2d(m, fc='lime', ec='none', alpha=0.15, poly_id='fov')[source]

Insert the camera FOV in a 2D map.

Parameters:

m (geonum.mapping.Map) – the map object
fc – face color of polygon
alpha (float) – alpha value of polygon

Param ec:

edge color of polygon

draw_map_3d(draw_cam=True, draw_source=True, draw_plume=True, draw_fov=True, cmap_topo='Oranges', contour_color='#708090', contour_antialiased=True, contour_lw=0.2, ax=None, **kwargs)[source]

Draw the current setup in a 3D map.

Parameters:

draw_cam (bool) – insert camera position into map
draw_source (bool) – insert source position into map
draw_plume (bool) – insert plume vector into map
draw_fov (bool) – insert camera FOV (az range) into map
cmap_topo (str) – string ID of colormap for topography surface plot, defaults to “Oranges”
contour_color (str) – string specifying color of contour lines colors of topo contour lines (default: “#708090”)
contour_antialiased (bool) – apply antialiasing to surface plot of topography, defaults to False
contour_lw – width of drawn contour lines, defaults to 0.5, use 0 if you do not want contour lines inserted
ax (Axes3D) – 3D axes object (default: None -> creates new one)
*args –
non-keyword arguments for setting up the base map (see here)
**kwargs (keyword arguments for setting up the basemap) –
(see here)

Returns:

plotted basemap

Return type:

Basemap

draw_azrange_fov_3d(m, fc='lime', ec='none', alpha=0.8)[source]

Insert the camera FOV in a 2D map.

Parameters:

m (geonum.mapping.Map) – the map object
fc – face color of polygon (“lime”)
alpha (float) – alpha value of polygon (0.8)

Param ec:

edge color of polygon (“none”)

property plume_dir: Return current plume direction angle.

property plume_dir_err: Return uncertainty in current plume direction angle.

property cam: Camera location (geonum.GeoPoint).

property source: Return camera Geopoint.

property intersect_pos: Return camera Geopoint.

property plume_vec: Return the plume center vector.

property source2cam: Return vector pointing camera to source.

property cam_view_vec: Return vector corresponding to CFOV azimuth of camera view dir.

haversine(lon0, lat0, lon1, lat1, radius=6371.0)[source]

Haversine formula to compute distances on a sphere

Approximate horizontal distance between 2 points assuming a spherical earth.

Parameters:

lon0 (float) – longitude of first point in decimal degrees
lat0 (float) – latitude of first point in decimal degrees
lon1 (float) – longitude of second point in decimal degrees
lat1 (float) – latitude of second point in decimal degrees
radius (float) – average earth radius in km, defaults to 6371 km

Returns:

distance of both points in km

Return type:

geo_len_scale()[source]

Return the distance between cam and source in km.

Uses haversine formula (haversine()) to determine the distance between source and cam to estimate the geoprahic dimension of this setup

Returns:: float, distance between source and camera

del_az(pixcol1=0, pixcol2=1)[source]

Determine the difference in azimuth angle between 2 pixel columns.

Parameters:

pixcol1 (int) – first pixel column
pixcol2 (int) – second pixel column

Returns:

azimuth difference in degrees

Return type:

del_elev(pixrow1=0, pixrow2=1)[source]

Determine the difference in azimuth angle between 2 pixel columns.

Parameters:

pixrow1 (int) – first pixel row
pixrow2 (int) – second pixel row

Returns:

elevation difference in degrees

Return type:

plume_dist(az=None, elev=None)[source]

Return plume distance for input azim and elev angles.

Computes the distance to the plume for the whole image plane, assuming that the horizontal plume propagation direction is given by the meteorological wind direction. The vertical component of the plume distance for each pixel row and column is computed based on the corresponding elevation angle and horizontal distance to the plume.

Parameters:

az (float or list, optional) – azimuth value(s) (single val or array of values). If None, then the azimuth angle of the camera CFOV is used.
elev (float or list, optional) – elevation angle(s) (single val or array of values). If None, then the elevation angle of the camera CFOV is used.

Returns:

plume distance(s) in m for input azimuth(s) and elevations

Return type:

float or list

plume_dist_err(az=None)[source]

Compute uncertainty in plume distances.

The computation is based on uncertainties in the camera azimuth and the uncertainty in the horizontal wind direction (i.e. plume propagation direction).

Parameters:: az (float, optional) – camera azimuth angle for which the uncertainty is computed (if None then the CFOV azimuth is used).
Returns:: absolute uncertainty in plume distance in units of m
Return type:: float

all_elevs_camfov()[source]: Return array containing elevation angles for each image row.

all_azimuths_camfov()[source]: Return array containing azimuth angles for each image row.

col_to_az(colnum)[source]

Convert pixel column number (in absolute coords) into azimuth angle.

Note

See also az_to_col() for the inverse operation
Not super efficient, just convenience function which should not
be used if performance is required

Parameters:: colnum (int) – pixel column number (left column corresponds to 0)
Returns:: corresponding azimuth angle
Return type:: float

az_to_col(azim)[source]

Convert azimuth into pixel number.

Note

The pixel number is calculated relative to the leftmost column of the image

Parameters:: azim (float) – azimuth angle which is supposed to be converted into column number
Returns:: column number
Return type:: int
Raises:: IndexError – if input azimuth is not within camera FOV

Image base module

Class representing image data and corresponding processing features.

The image base class Img is a powerful object for image data, containing I/O routines for many data formats, processing classes and keeping track on changes applied to the images. The actual image data is stored as numpy array in the img of an instance of the Img object.

The ProfileTimeSeriesImg class is used to store and process time series of pixel profiles (e.g. along a LineOnImage). These are, for instance used when performing a plume velocity cross-correlation analysis (where the optimal lag between a time-series of two plume intersection lines is searched, for details see pyplis.plumespeed.VeloCrossCorrEngine).

class pyplis.image.Img(input=None, import_method=None, dtype=None, **meta_info)[source]

Image base class.

Implementation of image object for pyplis library. The image data is represented as numpy.ndarray objects and the is stored in the attribute self.img.

Supported file formats include those supported by the Python Imaging Library (see here) and the FITS format. Img objects can also be created from numpy arrays directly.

The object includes several loading routines and basic image editing. Image meta information can be provided on creation of this instance by providing valid meta keys and the corresponding values, i.e.:

png_image_file = "C:/Test/my_img_file.png"
acq_time = datetime(2016, 10, 10, 13, 15, 12) #10/10/2016, 13:15:12
exposure_time = 0.75 #s
img = Img(png_image_file, start_acq = acq_time, texp = exposure_time)

Meta information is stored in the dictionary self.meta and can be printed using print_meta(). The two most important image meta parameters are the acquisition time (img.meta["start_acq"]) and the exposure time (img.meta["texp"]). These two parameters have class own access methods (start_acq() and texp()).

The class provides several image editing routines, of which the most important ones (within this library) are (please see documentation of the individual functions for more information):

subtract_dark_image() (subtract a dark image)

correct_dark_offset() (Correct for dark and offset. Models
a dark image based on one dark and one offset image using the exposure time of this image, then uses 1. for subtraction)

crop() (crop image within region of interest)

apply_median_filter() (median filtering of image)

add_gaussian_blurring() (Add blurring to image taking into
account current blurring amount)

apply_gaussian_blurring() (applies gaussian filter to image)

pyr_down() (reduce image size using gaussian pyramide)

pyr_up() (increase image size using gaussian pyramide)

All image editing steps performed using these functions are logged in the dictionary self.edit_log, it is therefore recommended to use the class own methods for these image editing routines (and not apply them manually to the image data, e.g. by using cv2.pyrDown(img.img) for resizing or img.img = img.img[y0:y1, x0:x1] for cropping a ROI [x0, x1, y0, y1] ) in order to keep track of the changes applied.

The default data accuracy is 32 bit floating point and can be changed on initiation (see __init__()).

Parameters:

input – image data input (e.g. file path to an image type which can be read or numpy array)
import_method – custom image load method, must return tuple containing image data (2D ndarray) and dictionary containing meta information (can be empty if read routine does not import any meta information)
dtype – datatype for image data (float32)
**meta_info – keyword args specifying meta data (only valid metadata is stored, for valid keys see meta)

dtype: data type of image numpy array

vign_mask

vignetting mask used to correct for vignetting (is set in correct_vignetting())

Type:: ndarray, optional

import_method

custom method used to import image data

Type:: callable, optional

edid_log

dictionary containing information about editing status

Type:: dict

meta[source]

dictionary containing meta information.

Type:: dict

__init__(input=None, import_method=None, dtype=None, **meta_info)[source]

property img: Get / set image data.

property start_acq

Get image acquisition time.

Returns:: acquisition time if available (i.e. it deviates from the default 1/1/1900), else, raises ImgMetaError

property stop_acq: Return stop time of acquisition (if available).

property texp

Get image acquisition time.

Returns:: acquisition time if available (i.e. it deviates from the default 1/1/1900), else, raises ImgMetaError

property gain: Return read gain value from meta info.

property shape: Return shape of image data.

property xy_aspect: Aspect ratio (delx / dely).

property pyr_up_factor

Return coordinates conversion factor.

This factor is used to convert coordinates at current pyramid level into original size coordinates.

property is_darkcorr: Boolean specifying whether image is dark corrected.

property is_tau: Return boolean whether image is a tau image or not.

property is_aa: Return boolean whether current image is AA image.

property is_calibrated: Flag for image calibration status.

property is_vignetting_corrected: Boolean stating whether image is vignetting corrected or not.

property is_gray: Check if image is gray image.

property is_binary: Attribute specifying whether image is binary image.

property is_inverted: Flag specifying whether image was inverted or not.

property is_vigncorr: Bool specifying whether or not image is vignetting corrected.

property is_dilcorr: Return whether this image is corrected for signal dilution.

property is_cropped: Boolean specifying whether image is cropped.

property is_resized: Boolean specifying whether image pyramid level unequals 0.

property is_shifted

Boolean specifying whether image was shifted.

This may be e.g. the case for stereo imaging

property modified: Check if this image was already modified.

property pyrlevel: Return current gauss pyramid level (stored in self.edit_log).

property roi: Return current roi in consideration of current pyrlevel.

property roi_abs: Get / set current ROI in absolute image coordinates.

Note

use roi() to get ROI for current pyrlevel

set_data(input)[source]: Try load input.

reload()[source]: Try reload from file.

load_input(input)[source]: Try to load input as numpy array and additional meta data.

make_histogram()[source]: Make histogram of current image.

get_brightness_range()[source]: Analyses the Histogram to retrieve a suited brightness range.

Note

Currently not in use (was originally used for App)

avg_in_roi(mask=None, roi_rect=None, pos_x=None, pos_y=None, radius=1)[source]

Get mean value in an ROI.

The ROI can be specified either by providing a mask, an rectangular ROI, or x and y position and a specific radius. The input is dealt with in the specified order, i.e. if :param:`mask` is valid, none of the other input parameters is tested.

Parameters:

mask (ndarray or Img) – convolution mask (e.g. DOAS FOV mask).
roi_rect (list) – rectangular ROI [x0, y0, x1, y1] specifying upper left and lower right corners of region
pos_x (int) – detector x-position
pos_y (int) – detector y-position
radius (int) – radius of ROI

Raises:

TypeError – if none of the provided input works

Returns:

mean value within specified ROI

Return type:

crop(roi_abs=[0, 0, 9999, 9999], new_img=False)[source]

Cut subimage specified by rectangular ROI.

Parameters:

roi_abs (list) – region of interest (i.e. [x0, y0, x1, y1]) in ABSOLUTE image coordinates. The ROI is automatically converted with respect to current pyrlevel
new_img (bool) – creates and returns a new image object and leaves this one uncropped

Returns:

Img, cropped image

correct_dark_offset(dark, offset)[source]

Perform dark frame subtraction, 3 different modi possible.

Parameters:

dark (Img) – dark image object (dark with long(est) exposure time)
offset (Img) – offset image (dark with short(est) exposure time)

Return Img:

modelled dark image

Uses model_dark_image() (in Processing) to model a dark image based on the exposure time of this image object. This is then subtracted from the current image.

Note

This algorithm works only, if no other image processing operations were applied to the input image beforehand, i.e. if modified() returns False.

subtract_dark_image(dark)[source]

Subtracts a dark (+offset) image and updates self.edit_log.

Parameters:: dark (Img) – dark image data

Simple image subtraction without any modifications of input image

correct_vignetting(mask, new_state=True)[source]

Apply vignetting correction.

Performs either of the following operations:

self.img * mask     (if input param ``new_state=False``)
self.img / mask     (if input param ``new_state=True``)

Parameters:

mask (ndarray) – vignetting correction mask
reverse (bool) – if False, the inverse correction is applied (img needs to be corrected)

set_roi_whole_image()[source]: Set current ROI to whole image area based on shape of image data.

apply_median_filter(size_final=3)[source]

Apply a median filter.

Parameters:: (3,3) (tuple shape) – size of the filter

add_gaussian_blurring(sigma_final=1)[source]

Add blurring to image.

Parameters:: sigma_final (int) – the final width of gauss blurring kernel

apply_gaussian_blurring(sigma, **kwargs)[source]

Add gaussian blurring.

Uses scipy.ndimage.filters.gaussian_filter

Parameters:: sigma (int) – amount of blurring

get_masked_img(mask, fill_value=None)[source]

Return a np.ma.masked_array of the img array.

Parameters:

mask (numpy.ndarray) – entries which should be masked (True=invalid entry) has to be same shape as current state of self.img
fill_value (float) – (optional, default None) If defined, invalid entries are replaced by fill_value

Returns:

masked array

Return type:

numpy.ma.masked_array

get_thresh_mask(threshold)[source]: Apply threshold and get binary mask.

to_binary(threshold=None, new_img=False)[source]

Convert image to binary image using threshold.

Note

The changes are applied to this image object

Parameters:: threshold (float) – threshold, if None, use mean value of image data
Returns:: binary image
Return type:: Img

invert()[source]

Invert image.

Note

Does not yet work for tau images

Returns:: inverted image object
Return type:: Img

convolve_with_mask(mask)[source]

Convolves this image data with input mask and return value.

Note

This is not an image convolution with a kernel that is applied to each image pixel (e.g. blurring, etc.). The input mask is supposed to be of the same shape as this image

Parameters:: mask (ndarray) – 2D array of same dimension (height, width) as this image
Returns:: corresponding value after normalisation and convolution
Return type:: float

dilate(kernel=array([[1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1]], dtype=uint8))[source]

Apply morphological transformation Dilation to image.

Uses cv2.dilate() for dilation. The method requires specification of a smoothing kernel, if unspecified, a 9x9 neighbourhood is used

Note

This operation can only be performed to binary images, use to_binary() if applicable.

Parameters:: kernel (array) – kernel used for cv2.dilate(), default is 9x9 kernel
Returns:: dilated binary image
Return type:: Img

erode(kernel=array([[1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1, 1, 1, 1]], dtype=uint8))[source]

Apply morphological transformation Erosion to image.

Uses cv2.erode() to apply erosion. The method requires specification of a kernel, if unspecified, a 9x9 neighbourhood is used

Note

This operation can only be performed to binary images, use to_binary() if applicable.

Parameters:: kernel (array) – kernel used for cv2.dilate(), default is 9x9 kernel
Returns:: dilated binary image
Return type:: Img

fit_2d_poly(mask=None, polyorder=3, pyrlevel=4, **kwargs)[source]

Fit 2D surface poly to data.

Parameters:

mask (array) – mask specifying pixels considered for the fit (if None, then all pixels of the image data are considered
polyorder (int) – order of polynomial for fit (default=3)
pyrlevel (int) – level of Gauss pyramid at which the fit is performed (relative to Gauss pyramid level of input data)
**kwargs – additional optional keyword args passed to PolySurfaceFit

Returns:

new image object corresponding to fit results

Return type:

to_tau(bg, new_img=True)[source]

Convert into tau image.

Converts this image into a tau image using a provided input background image (which is used without any modifications).

Note

By default, creates and returns new instance of Img object (i.e. this object remains unchanged if not other specified using

:param:`new_img`)

Parameters:

bg (Img) – background image used to determin tau image (REMAINS UNCHANGED, NO MODELLING PERFORMED HERE)
new_img (bool) – boolean specifying whether this object remains unchanged

Returns:

new Img object containing tau image data (this object remains unchanged)

Return type:

to_pyrlevel(final_state=0)[source]: Down / upscale image to a given pyramid level.

pyr_down(steps=0)[source]

Reduce the image size using gaussian pyramide.

Parameters:: steps (int) – steps down in the pyramide

Algorithm used: cv2.pyrDown()

pyr_up(steps)[source]

Increasing the image size using gaussian pyramide.

Parameters:: steps (int) – steps down in the pyramide

Algorithm used: cv2.pyrUp()

bytescale(cmin=None, cmax=None, high=255, low=0)[source]

Convert image to 8 bit integer values.

Parameters:

cmin (float) – minimum intensity for mapping, if None, the current self.min() is used.
cmax (float) – maximum intensity for mapping, if None, the current self.max() is used.
high (int) – mapping value of cmax
low (int) – mapping value of cmin

is_8bit()[source]: Flag specifying whether image is 8 bit.

print_meta()[source]: Print current image meta information.

make_info_header_str()[source]: Make header string for image (using image meta information).

duplicate()[source]: Duplicate this image.

normalise(blur=1)[source]: Normalise this image.

mean()[source]: Return mean value of current image data.

sum()[source]: Return the sum of all pixel values.

std()[source]: Return standard deviation of current image data.

min()[source]: Return minimum value of current image data.

max()[source]: Return maximum value of current image data.

set_val_below_thresh(val, threshold)[source]

Set value in all pixels with intensities below threshold.

Note

Modifies this Img object

Parameters:

val (float) – new value for all pixels below the input threshold
threshold (float) – considered intensity threshold

set_val_above_thresh(val, threshold)[source]

Set value in all pixels with intensities above threshold.

Note

Modifies this Img object

Parameters:

val (float) – new value for all pixels above the input threshold
threshold (float) – considered intensity threshold

blend_other(other, fac=0.5)[source]

Blends another image to this and returns new Img object.

Uses cv2 addWeighted() method”

Parameters:: fac (float) – percentage blend factor (between 0 and 1)

meta(meta_key)[source]: Return current meta data for input key.

load_file(file_path)[source]: Try to import file specified by input path.

load_fits(file_path)[source]

Import a FITS file.

This import method assumes, that data and corresponding meta-info is stored in the first HDU of the FITS file (index = 0).

Fits info

save_as_fits(save_dir=None, save_name=None)[source]

Save this image as FITS file.

Parameters:

save_dir (str) – optional, if None (default), then the current working directory is used
save_name (str) – opional, if None (default), try to use file name of this object (if set) or use default name

Returns:

name of saved file

Return type:

str

get_cmap(vmin=None, vmax=None, **kwargs)[source]: Determine and return default cmap for current image.

show(zlabel=None, tit=None, **kwargs)[source]: Plot image.

show_img(zlabel=None, tit=None, cbar=True, ax=None, zlabel_size=18, **kwargs)[source]: Show image using matplotlib method imshow.

show_img_with_histo(**kwargs)[source]: Show image using plt.imshow.

shift(dx_abs=0.0, dy_abs=0.0)[source]

Apply constant image shift to this object.

Parameters:

dx_abs (float) – shift in x-direction
dy_abs (float) – shift in y-direction

show_histogram(ax=None)[source]: Plot histogram of current image.

Todo

Needs more edit (i.e. better representation of labels)

info()[source]: Print image info from string representation.

pyplis.image.model_dark_image(texp, dark, offset)[source]

Model a dark image for input image based on dark and offset images.

Determine a modified dark image (D_mod) from the current dark and offset images. The dark image is determined based on the image exposure time of the image object to be corrected (t_exp,I). D_mod represents dark and offset signal for this image object and is then subtracted from the image data.

Formula for modified dark image:

$D_{mod} = O + \\frac{(D - O)*t_{exp,I}}{(t_{exp, D}-t_{exp, O})}$

Parameters:

img (Img) – the image for which dark and offset is modelled
dark (Img) – dark image object (dark with long(est) exposure time)
offset (Img) – offset image (dark with short(est) exposure time)

Returns:

Img, modelled dark image

class pyplis.image.ProfileTimeSeriesImg(img_data=None, time_stamps=array([], dtype=float64), img_id='', dtype=<class 'numpy.float32'>, profile_info_dict=None, **meta_info)[source]

Image representing time series of line profiles.

The y axis of the profile image corresponds to the actual profiles (retrieved from the individual images) and the x axis corresponds to the image time axis (i.e. the individual frames). Time stamps (mapping of x indices) can also be stored in this object.

Example usage is, for instance to represent ICA time series retrieved along a profile (e.g. using LineOnImage) for plume speed cross correlation

__init__(img_data=None, time_stamps=array([], dtype=float64), img_id='', dtype=<class 'numpy.float32'>, profile_info_dict=None, **meta_info)[source]

property img: Get / set image data.

property start: Return first datetime from self.time_stamps.

property stop: Return first datetime from self.time_stamps.

save_as_fits(save_dir=None, save_name=None, overwrite_existing=True)[source]

Save stack as FITS file.

Parameters:

save_dir (str) – directory where image is stored (can also be full file path, then parameter save_name is not considered)
save_name (str) – name of file
overwrite_existing (bool) – if True, an existing file with the same name will be overwritten

load_fits(file_path, profile_type='LineOnImage')[source]

Load stack object (fits).

Parameters:: file_path (str) – file path of fits image

Image list objects

Image list objects.

Image list objects (e.g. BaseImgList, ImgList, DarkImgList, CellImgList) contain a list of image file paths and are central for the data analysis. Images are loaded as Img objects and are loaded and processed iteratively. Typically one list contains all images of a certain type (e.g. onband, offband, see Dataset object). ImgList objects (inherited from BaseImgList) contain powerful pre-processing modes (e.g. load images as dark corrected and calibrated images, compute optical flow between current and next image).

class pyplis.imagelists.DarkImgList(files=None, list_id=None, list_type=None, read_gain=0, camera=None, init=True)[source]

A :class:`BaseImgList`object only extended by read_gain value.

This class is meant for storage of dark and offset images.

Note

It is recommended to perform the dark and offset correction using non-edited raw dark offset images. Therefore, the default edit state of these list (edit_active) is set to False. This means, if you have such a list and want to add blurring, cropping, etc., you first have to activate the image edit on image load via the edit_active.

__init__(files=None, list_id=None, list_type=None, read_gain=0, camera=None, init=True)[source]

class pyplis.imagelists.AutoDilcorrSettings(tau_thresh=0.05, erosion_kernel_size=0, dilation_kernel_size=0)[source]

Store settings for automatic dilution correction in ImgLists.

tau_thresh

OD threshold for computation of plume pixel mask

Type:: float

erosion_kernel_size

size of erosion kernel applied to plume pixel mask

Type:: int

dilation_kernel_size

size of dilation kernel applied to plume pixel mask after erosion was applied

Type:: int

bg_model

plume background model used to compute tau images (i.e. correction mode 99, is e.g. used in _apply_edit() of ImgList)

Type:: PlumeBackgroundModel

Parameters:

tau_thresh (float) – OD threshold for computation of plume pixel mask
erosion_kernel_size (int) – size of erosion kernel applied to plume pixel mask
dilation_kernel_size (int) – size of dilation kernel applied to plume pixel mask after erosion was applied

__init__(tau_thresh=0.05, erosion_kernel_size=0, dilation_kernel_size=0)[source]

class pyplis.imagelists.ImgList(files=None, list_id=None, list_type=None, camera=None, geometry=None, init=True, **dilcorr_settings)[source]

Image list object with expanded functionality (cf. BaseImgList).

Additional features:

Optical flow determination

Linking of lists (e.g. on and offband lists)

Dark and offset image correction

Plume background modelling and tau image determination

Methods for dilution correction

Automatic vignetting correction

Assignment of calibration data and automatic image calibration

Parameters:

files (list) – list containing image file paths, defaults to [] (i.e. empty list)
list_id (str, optional) – string ID of this list, defaults to None
list_type (str, optional) – string specifying type of image data in this list (e.g. on, off)
camera (Camera, optional) – camera specifications, defaults to None
geometry (MeasGeometry, optional) – measurement geometry
init (bool) – if True, the first two images in list files are loaded
**dilcorr_settings – additional keyword args corresponding to settings for automatic dilution correction passed to __init__ of :class:´AutoDilcorrSettings`

__init__(files=None, list_id=None, list_type=None, camera=None, geometry=None, init=True, **dilcorr_settings)[source]

property darkcorr_opt

Return the current dark correction mode.

The following modes are available:

0 => no dark correction possible (is e.g. set if camera is
unspecified)

1 => individual correction with separate dark and offset
(e.g. ECII data)

2 => one dark image which is subtracted (including the offset,
e.g. HD cam data)

For details see documentation of CameraBaseInfo

property darkcorr_mode: Return current list darkcorr mode.

property optflow_mode: Activate / deactivate optical flow calc on image load.

property vigncorr_mode: Activate / deactivate vignetting correction on image load.

property dilcorr_mode: Activate / deactivate dilution correction on image load.

property sensitivity_corr_mode: Activate / deactivate AA sensitivity correction mode.

property tau_mode: Return current list tau mode.

property shift_mode: Return current list registration shift mode.

property aa_mode: Return current list AA mode.

property calib_mode: Acitivate / deactivate current list gas calibration mode.

property ext_coeff: Atmosphere aerosol extinction coefficient closest in time to current image

property ext_coeffs: Series: Dilution extinction coefficients.

set_ext_coeffs(values: Sequence[float], timestamps: Sequence[datetime]) → None[source]

Set extinction coefficients.

The extinction coefficients are assigned as a timeseries and used if dilcorr_mode mode is activated. The extinction coefficients are used to correct the images for signal dilution due to ambient aerosol.

Note: Ideally, the extinction coefficients should be retrieved for each image in this: list, to achieve the highest accuracy of correction. However, in stable atmospheric settings and for short image sequences, it may suffice to set less.

Parameters:

values – List of extinction coefficient values.
timestamps – List of timestamps corresponding to the values.

property bg_img: Return background image based on current vignetting corr setting.

property dark_img: Return current dark image.

property bg_list: Return background image list (if assigned).

property senscorr_mask: Get / set AA correction mask.

property calib_data: Get set object to perform calibration.

property doas_fov: Try access DOAS FOV info (in case cailbration data is available).

init_bg_model(**kwargs)[source]: Init clear sky reference areas in background model.

activate_darkcorr(value=True)[source]

Activate or deactivate dark and offset correction of images.

If dark correction turned on, dark image access is attempted, if that fails, Exception is raised including information what did not work out.

Parameters:: val (bool) – new mode

activate_vigncorr(value=True)[source]

Activate / deactivate vignetting correction on image load.

Note

Requires self.vign_mask to be set or an background image to be available (from which self.vign_mask is then determined)

Parameters:: value (bool) – new mode

activate_shift_mode(value=True)[source]

Activate / deactivate image shift on load.

The shift that is set in the assigned Camera class is used

Parameters:: value (bool) – new mode

activate_tau_mode(value=True)[source]

Activate tau mode.

In tau mode, images will be loaded as tau images (if background image data is available).

Parameters:: value (bool) – new mode

activate_aa_mode(value=True)[source]

Activates AA mode (i.e. images are loaded as AA images).

In order for this to work, the following prerequisites need to be fulfilled:

This list needs to be an on band list
(self.list_type = "on")

At least one offband list must be linked to this list (if more
offband lists are linked and input param off_id is unspecified, then the first offband list found is used)

The number of images in the off band list must exceed a minimum
of 50% of the images in this list

Parameters:: val (bool) – Activate / deactivate AA mode

activate_calib_mode(value=True)[source]: Activate calibration mode.

activate_dilcorr_mode(value=True)[source]

Activate dilution correction mode.

Please see correct_dilution() for details.

Parameters:: value (bool) – New mode: True or False

activate_optflow_mode(value=True, draw=False)[source]

Activate / deactivate optical flow calculation on image load.

Parameters:

val (bool) – activate / deactivate
draw (bool) – if True, flow field is plotted into current image

get_dark_image(key='this')[source]

Prepare the current dark image dependent on darkcorr_opt.

The code checks current dark correction mode and, if applicable, prepares the dark image.

self.darkcorr_opt == 0 (no dark correction)
return False

self.darkcorr_opt == 1 (model dark image from a sample dark
and offset image) Try to access current dark and offset image from self.dark_lists and self.offset_lists (so these must exist). If this fails for some reason, set self.darkcorr_opt = 2, else model dark image using model_dark_image() and return this image

self.darkcorr_opt == 2 (subtract dark image if exposure
times of current image does not deviate by more than 20% to current dark image) Try access current dark image in self.dark_lists, if this fails, try to access current dark image in self.darkImg (which can be set manually using set_dark_image()). If this also fails, set self.darkcorr_opt = 0 and return False. If a dark image could be found and the exposure time differs by more than 20%, set self.darkcorr_opt = 0 and raise ValueError. Else, return this dark image.

get_off_list(list_id=None)[source]

Search off band list in linked lists.

Parameters:: list_id (str, optional) – ID of the list. If unspecified (None), the default off band filter key is attempted to be accessed (self.camera.filter_setup.default_key_off) and if this fails, the first off band list found is returned.
Raises:: AttributeError – if not offband list can be assigned
Returns:: the corresponding off-band list
Return type:: ImgList

set_bg_img(bg_img)[source]

Update the current background image object.

Check input background image and, in case a vignetting mask is not available in this list, determine a vignetting mask from the background image. Furthermore, if the input image is not blurred it is blurred using current list blurring factor and in case the latter is 0, then it is blurred with a Gaussian filter of width 1.

Parameters:: bg_img (Img) – the background image object used for plume background modelling (modes 1 - 6 in PlumeBackgroundModel)

set_bg_list(lst, always_reload=False)[source]

Assign background image list to this list.

Assigns and links an image list containing background images to this list. Similar to other linked lists, the index of the current BG image is automatically updated such that the current BG image is closest in time to the current image in this list. Please note also, that a single master BG image can be assigned using bg_img.

Parameters:

lst (ImgList) – image list containing background images. Note that the input can also be a string specifying the list_id of an image list that is already linked to this list.
always_reload (bool) – if True, the current BG image is always reloaded, whenever the index in this list is changed (not recommended since it is slow). If False, the state of the background list is only changed, if the actual background image index is altered.

set_flow_images()[source]

Update images for optical flow determination.

The images are updated in optflow (OptflowFarneback object) using method set_images()

Raises:: IndexError – object, i.e. self.loaded_images[“this”] and self.loaded_images[“next”]

set_optical_flow(optflow)[source]

Set the current optical flow object.

Currently only support for type OptflowFarneback

Parameters:: optflow (OptflowFarneback) – the optical flow engine

set_darkcorr_mode(mode)[source]

Update dark correction mode.

Parameters:: (1) (int mode) – new mode

add_master_dark_image(dark, acq_time=datetime.datetime(1900, 1, 1, 0, 0), texp=0.0, read_gain=0)[source]

Add a (master) dark image data to list.

Sets a dark image, which is used for dark correction in case, no dark / offset image lists are linked to this object or the data extraction from these lists does not work for some reason.

Parameters:

dark ((Img, ndarray)) – dark image data
acq_time (datetime) – image acquisition time (only updated if input image is numpy array or if acqtime in Img object is default), default: (1900, 1, 1)
texp (float) – optional input for exposure time in units of s (i.e. is used if img input is ndarray or if exposure time is not set in the input img)

The image is stored at:

stored at self.master_dark

add_master_offset_image(offset, acq_time=datetime.datetime(1900, 1, 1, 0, 0), texp=0.0, read_gain=0)[source]

Add a (master) offset image to list.

Sets a offset image, which is used for dark correction in case, no dark / offset image lists are linked to this object or the data extraction from these lists does not work for some reason.

Parameters:

offset ((Img, ndarray)) – offset image data
acq_time (datetime) – image acquisition time (only used if input image is numpy array or if acqtime in Img object is default)
texp (float) – optional input for exposure time in units of s (i.e. is used if img input is ndarray or if exposure time is not set in the input img)

The image is stored at:

self.master_offset

set_closest_dark_offset()[source]

Update the index of the current dark and offset images.

The index is updated in all existing dark and offset lists.

link_imglist(other_list, list_id=None, always_reload=True)[source]

Link another image list to this list.

Parameters:

other_list (ImgList) – image list object that is supposed to be linked to this one
always_reload (bool) – if True, the current image in the linked list is always reloaded, whenever the index in this list is changed. This is useful in case an offband list is linked to an onband list, not so much if a list containing BG images is linked to an oband list (see also set_bg_list())

disconnect_linked_imglist(list_id)[source]

Disconnect a linked list from this object.

Parameters:: list_id (str) – string id of linked list

link_dark_offset_lists(*lists)[source]

Assign dark and offset image lists to this object.

Assign dark and offset image lists: get “closest-in-time” indices of dark list with respect to the capture times of the images in this list. Then get “closest-in-time” indices of offset list with respect to dark list. The latter is done to ensure, that dark and offset set used for image correction are recorded subsequently and not individual from each other (i.e. only closest in time to the current image)

change_index_linked_lists()[source]: Update current index in all linked lists based on cfn.

load()[source]: Try load current and next image.

goto_next()[source]: Load next image in list.

optflow_histo_analysis(lines=None, start_idx=0, stop_idx=None, intensity_thresh=0, **optflow_settings)[source]

Perform optical flow histogram analysis for list images.

The analysis is performed for all list images within the specified index (or time) range and for an arbitraty number of PCS lines.

Parameters:

lines (list) – list containing LineOnImage instances
start_idx (int or datetime) – index or timestamp of first considered image. Note that the timestamp option only works if acq. times can be accessed from filenames for all files in the list (using method timestamp_to_index())
stop_idx (int or datetime, optional) – index of last considered image (if None, the last image in this list is used). Note that the timestamp option only works if acq. times can be accessed from filenames for all files in the list (using method timestamp_to_index())
intensity_thresh (float) – additional intensity threshold that may, e.g. be used to identify plume pixels (e.g. if list is in tau_mode).
**optflow_settings – additional keyword args passed to OptflowFarneback

Returns:

list containing the computed time series of optical flow histogram parameters (LocalPlumeProperties instances) for each of the provided input LineOnImage objects.

Return type:

get_thresh_mask(thresh=None, this_and_next=True)[source]

Get bool mask based on intensity threshold.

Parameters:

thresh (float, optional) – intensity threshold
this_and_next (bool) – if True, uses the current AND next image to determine mask

Returns:

mask specifying pixels that exceed the threshold

Return type:

array

det_vign_mask_from_bg_img()[source]

Determine vignetting mask from current background image.

The mask is determined using a blurred ( $\sigma = 3$ ) background image which is normalised to one.

The mask is stored in self.vign_mask

Returns:: vignetting mask
Return type:: Img

calc_sky_background_mask(lower_thresh=None, apply_movement_search=True, **settings_movement_search)[source]

Retrieve and set background mask for 2D poly surface fit.

Calculates mask specifying sky radiance pixels for background modelling mode 0. The mask is updated in the background model (class attribute bg_model).

Parameters:

lower_thresh (float, optional) – lower intensity threshold. If provided, this value is used, else, the minimum value is derived from the minimum intensity in the plume image within the current 3 sky reference rectangles
**settings_movement_search – additional keyword arguments passed to find_movement(). Note that these may include settings for the optical flow calculation which are further passed to the initiation of the FarnebackSettings class

Returns:

2D-numpy boolean numpy array specifying sky background pixels

Return type:

array

calc_plumepix_mask(od_img, tau_thresh=0.05, erosion_kernel_size=0, dilation_kernel_size=0)[source]

Calculate plume pixel mask from an OD image using a OD thrshold.

The method further allows to close gaps using a suitable combination of an erosion

correct_dilution(img, plume_bg_vigncorr=None, plume_pix_mask=None, plume_dists=None, ext_coeff=None, tau_thresh=0.05, vigncorr_mask=None, erosion_kernel_size=0, dilation_kernel_size=0, img_check_plumemask=True)[source]

Correct a plume image for the signal dilution effect.

The provided plume image needs to be in intensity space, meaning the pixel values need to be intensities and not optical densities or calibrated gas-CDs. The correction is based on Campion et al., 2015 and requires knowledge of the atmospheric scattering extinction coefficients (ext_coeff) in the viewing direction of the camera. These can be provided using the corresponding input parameter ext_coeff or can be assigned to the list beforehand (up to you). See example script no. 11 to check out how you can retrieve the extinction coefficients using dark terrain features in the plume image. The correction furthermore requires knowledge of the plume distance (in the best case on the pixel-level) and a binary mask specifying plume image pixels. If the latter is not provided on input, it is computed within this function by calculating an OD (tau or AA) image (based on current list state) and by applying a specified OD threshold. Thus, in case no mask is provided, it must be possible to compute optical density images in this list, hence the bg_model (instance of PlumeBackgroundModel) needs to be ready for tau image computation. In addition, a vignetting correction mask must be available.

Parameters:

img (Img) – the plume image object
plume_bg_vigncorr (Img, optional) – vignetting corrected plume background image used for dilution correction
plume_pix_mask (Img, optional) – binary mask specifying plume pixels in the image, is retrieved automatically if input is None
plume_dists (ndarray or Img, optional) – 2D array containing pixel based plume distances. If None, this mask will be attempted to be retrieved from the MeasGeometry instance assigned to this list
ext_coeff (float, optional) – atmospheric extinction coefficient. If unspecified, try access via ext_coeff which returns the current extinction coefficient and raises AttributeError in case, no coeffs are assigned to this list
tau_thresh (float) – OD (tau) threshold to compute plume pixel mask (irrelevant if next :param:`plume_pix_mask` is provided)
vigncorr_mask (ndarray or Img, optional) – mask used for vignetting correction
erosion_kernel_size (int) – if not zero, the morphological operation erosion is applied to the plume pixel mask (e.g. to remove noise outliers) using an appropriate quadratic kernel corresponding to the input size
dilation_kernel_size (int) – if not zero, the morphological operation dilation is applied to the plume pixel mask (e.g. to slightly extend the borders of the detected plume) using an appropriate quadratic kernel corresponding to the input size
img_check_plumemask (bool) – if True, the current dark and vignetting correction states of plume and BG images are checked before computation of the plume background and, if applicable, the plume pixel mask

Returns:

3-element tuple containing

Img, dilution corrected input image (vignetting corrected)
Img, vignetting corrected plume background used for the correction (is computed within this function body if not provided on input
array, mask specifying plume pixels

Return type:

correct_dilution_all(tau_thresh=0.05, ext_on=None, ext_off=None, add_off_list=True, save_dir=None, save_masks=False, save_bg_imgs=False, save_tau_prev=False, vmin_tau_prev=None, vmax_tau_prev=None, **kwargs)[source]

Correct all images for signal dilution.

Correct and save all images in this list for the signal dilution effect. See correct_dilution() and prep_data_dilutioncorr() for details about requirements and additional input options.

Note

The vignetting and dilution corrected images are stored with all additional image preparation settings applied (e.g. dark correction, blurring)

Parameters:

tau_thresh (float, optional) – tau threshold applied to determine plume pixel mask (retrieved using tau_mode, not aa_mode)
ext_on (float, optional) – atmospheric extinction coefficient at on-band wavelength, if None (default), try access via ext_coeff
ext_off (float, optional) – atmospheric extinction coefficient at off-band wavelength. Only relevant if input param add_off_list is True. If None (default) and add_off_list=True try access via ext_coeff in off band list.
add_off_list (bool) – if True, also the images in a linked off-band image list (using get_off_list()) are corrected as well. For the correction of the off-band images, the current plume pixel mask of this list is used.
save_dir (str, optional) – base directory for saving the corrected images. If None (default), then a new directory dilcorr is created at the storage location of the first image in this list
save_masks (bool) – if True, a folder plume_pix_masks is created within :param:`save_dir` in which all plume pixel masks are stored as FITS
save_bg_imgs (bool) – if True, a folder bg_imgs is created which is used to store modelled plume background images for each image in this list. This folder can be used on re-import of the data in order to save background modelling time using background modelling mode 99.
save_tau_prev (bool) – if True, png previews of dilution corrected tau images are saved
vmin_tau_prev (float, optional) – lower tau value for tau image preview plots
vmax_tau_prev (float, optional) – upper tau value for tau image preview plots
**kwargs – additional keyword args for dilution correction functions correct_dilution() and prep_data_dilutioncorr()

import_ext_coeffs_csv(file_path, header_id=None, **kwargs)[source]

Import extinction coefficients from csv.

The text file requires datetime information in the first column and a header which can be used to identify the column. The import is performed using pandas.read_csv()

Parameters:

file_path (str) – the csv data file
header_id (str) – header string for column containing ext. coeffs
**kwargs – additionald keyword args passed to pandas.read_csv()

Returns:

pandas Series containing extinction coeffs

Return type:

Series

Todo

This is a Beta version, insert try / except block after testing

has_bg_img()[source]: Return boolean whether or not background image is available.

update_index_dark_offset_lists()[source]: Check and update current dark image (if possible / applicable).

class pyplis.imagelists.CellImgList(files=None, list_id=None, list_type=None, camera=None, geometry=None, cell_id='', gas_cd=0.0, gas_cd_err=0.0)[source]

Image list object for cell images.

Whenever cell calibration is performed, one calibration cell is put in front of the lense for a certain time and the camera takes one (or ideally) a certain amount of images.

This image list corresponds to such a list of images with one specific cell in the camera FOV. It is a BaseImgList only extended by the variable self.gas_cd specifying the amount of gas (column density) in this cell.

__init__(files=None, list_id=None, list_type=None, camera=None, geometry=None, cell_id='', gas_cd=0.0, gas_cd_err=0.0)[source]

update_cell_info(cell_id, gas_cd, gas_cd_err)[source]: Update cell_id and gas_cd amount.

class pyplis.imagelists.ImgListLayered(files=None, meta=None, list_id=None, list_type=None, camera=None, geometry=None, init=True)[source]

Image list object able to deal with multi layered fits files.

Additional features:

Indexing using double index: Filename and image layer

Function which returns a DataFrame of all available data

Parameters:

files (list) – list containing image file paths, defaults to [] (i.e. empty list)
meta (DataFrame) – meta data from a previous load of the same image list. Can be used alternatively for a faster initialisation
list_id (str, optional) – string ID of this list, defaults to None
list_type (str, optional) – string specifying type of image data in this list (e.g. on, off)
camera (Camera, optional) – camera specifications, defaults to None
geometry (MeasGeometry, optional) – measurement geometry
init (bool) – if True, the first two images in list files are loaded

Note

Initialise with a list of n files each containing a (variable) number of image layers) m_n. The file header needs to be read in for every file in order to get the right amount of total images. The attribute self.files will contain m_n copies of the file n. If the list has been loaded before, the ImgListLayered can also be initialised with a DataFrame containing all meta information.

__init__(files=None, meta=None, list_id=None, list_type=None, camera=None, geometry=None, init=True)[source]

get_img_meta_from_filename(file_path)[source]

Load and prepare img meta input dict for Img object.

Note

Convenience method only rewritten in order to not break the code. Loads meta data of first image plane in fits file_path

Parameters:: file_path (str) – file path of image
Returns:: dictionary containing retrieved values for start_acq and texp
Return type:: dict

get_img_meta_all_filenames()[source]

Return the same data as ImgList.get_img_meta_all_filenames.

Note

Convenience method only rewritten in order to not break the code

Returns:

2-element tuple containing

list, list containing all retrieved acq. time stamps
list, containing all retrieved exposure times

Return type:

get_img_meta_one_fitsfile(file_path)[source]

Load all meta data from all image layers of one fits file.

In this form it is custom for the comtessa files TODO: Make general for multilayered fits

get_img_meta_all()[source]

Load all available meta data from fits files.

Returns:: containing all metadata
Return type:: dataFrame

Plume background analysis

Pyplis module containing features related to plume background analysis.

class pyplis.plumebackground.PlumeBackgroundModel(bg_raw=None, plume_init=None, init_surf_fit_mask=True, **kwargs)[source]

Class for plume background modelling and tau image determination.

Parameters:

bg_raw (Img) – sky background radiance raw image data
plume_init (Img) – initial plume image data (is used to estimate default clear sky areas for bg modelling)
**kwargs – additional class attributes (e.g. for modelling, valid keys are all keys in self.__dict__.keys())

__init__(bg_raw=None, plume_init=None, init_surf_fit_mask=True, **kwargs)[source]

scale_rect: Rectangle for scaline of background image corr modes: 1 - 6

ygrad_rect: Rectangle for linear based correction of vertical gradient corr modes: 2, 4

ygrad_line_colnum: Settings for quadratic correction of vertical gradient (along line) corr modes: 3, 5, 6

xgrad_rect: Rectangle for linear based correction of horizontal gradient (applied before ygradient correction is performed) corr modes: 4, 5

xgrad_line_rownum: Settings for quadratic correction of horizontal gradient (along line) corr modes: 6

property all_modes: List containing valid modelling modes.

property mode: Return current modelling mode.

property CORR_MODE: Return current background modelling mode.

property surface_fit_mask

fit 2D polynomial.

Type:: Mask for retrieval mode 0

check_settings()[source]: Check if any of the modelling settings is not specified.

mean_in_rects(img)[source]

Determine (mean, min, max) intensity in reference rectangles.

Parameters:: img (array) – image data array (can also be Img)
Returns:: 2-element tuple containing mean value and error
Return type:: tuple

update(**kwargs)[source]

Update class attributes.

Parameters:: **kwargs –

set_missing_ref_areas(plume_img: Img)[source]

Find and set missing default sky reference areas for modelling.

Based on the input plume image, the clear sky reference areas for sky radiance image based tau modelling are estimated, i.e.:

The rectangle areas for scaling and linear gradient corrections:
self.scale_rect, self.ygrad_rect, self.xgrad_rect

2. Coordinates of horizontal and vertical profile lines for quadratic gradient corrections: self.ygrad_line_colnum, self.xgrad_line_rownum (i.e. positions and start / stop pixel coordinates)

The estimation is performed based on a brightness analysis for left and right image area.

Parameters:: plume_img (Img) – the plume image for which the sky background areas are retrieved.

calc_sky_background_mask(plume_img, next_img=None, lower_thresh=None, apply_movement_search=True, **settings_movement_search)[source]

Retrieve and set background mask for 2D poly surface fit.

Wrapper for method find_sky_background()

Calculates mask specifying sky radiance pixels for modelling mode 0 (plume background retrieval directly from plume image without an additional I0-image, using a 2D polynomial surface fit). The mask is stored in surface_fit_mask.

Parameters:

plume_img (Img) – the plume image for which the sky background pixels are supposed to be detected
next_img (Img, optional) – second image used to compute the optical flow in :param:`plume_img`
lower_thresh (float, optional) – lower intensity threshold. If provided, this value is used, else, the minimum value is derived from the minimum intensity in the plume image within the current 3 sky reference rectangles
**settings_movement_search – additional keyword arguments passed to find_movement(). Note that these may include settings for the optical flow calculation which are further passed to the initiation of the FarnebackSettings class

Returns:

2D-numpy boolean numpy array specifying sky background pixels

Return type:

array

bg_from_poly_surface_fit(plume, mask=None, polyorder=2, pyrlevel=4)[source]

Apply poly surface fit to plume image for bg retrieval.

Parameters:

plume (Img) – plume image
mask (ndarray) – mask specifying gas free areas (if None, use all pixels). Note that the mask needs to be computed within the same ROI and at the same pyrlevel as the input plume image
polyorder (int) – order of polynomial used for fit, defaults to 4
pyrlevel (int) – pyramid level in which fit is performed (e.g. 4 => image size for fit is reduced by factor 2^4 = 16). Note that the

:param : second: PolySurfaceFit object :type : return tuple: 1st entry: fitted background image

Returns:: fitted sky background
Return type:: ndarray

Note

The PolySurfaceFit object used to retrieve the background is stored in the _last_surffit.

get_tau_image(plume_img, bg_img=None, check_state=True, **kwargs)[source]

Determine current tau image for input plume image.

Parameters:

plume_img (Img) – plume image in intensity space
bg_img (Img, optional) – sky radiance image (for self.CORR_MODE = 1 - 6)
check_state (bool) – if True and current mode != 0, it is checked whether the input images (plume and bg) have the same darkcorrection and vignetting state
**kwargs – additional keyword arguments for updating current settings (valid input keywords (strings): mode, ygrad_rect, ygrad_line_colnum, ygrad_line_startrow, ygrad_line_stoprow

Returns:

plume tau image

Return type:

Raises:

AttributeError – if input image is already a tau or AA image or if input plume image and the current background image have different states with regard to vignetting or dark correction.

get_aa_image(plume_on, plume_off, bg_on=None, bg_off=None, check_state=True, **kwargs)[source]

Retrieve apparent absorbance image from on and off imgs.

Determines an initial AA image based on input plume and background images and

Parameters:

plume_on (Img) – on-band plume image
plume_off (Img) – off-band plume image
bg_on (Img, optional) – on-band sky radiance image (for self.CORR_MODE = 1 - 6)
bg_off (Img, optional) – off-band sky radiance image (for self.CORR_MODE = 1 - 6)
check_state (bool) – if True and current mode != 0, it is checked whether the input images (plume and bg) have the same darkcorrection and vignetting state
**kwargs – additional keyword arguments for updating current settings (valid input keywords (strings), e.g. surface_fit_mask if mode == 0

Returns:

plume AA image

Return type:

correct_tau_curvature_ref_areas(tau_init)[source]

Scale and correct curvature in initial tau image.

The method used is depends on the current CORR_MODE. This method only applies for correction modes 1-6.

Parameters:: tau_init (array, Img) – inital tau image
Returns:: modelled tau image
Return type:: array

plot_sky_reference_areas(plume)[source]: Plot the current sky ref areas into a plume image.

plot_tau_result(tau_img=None, tau_min=None, tau_max=None, edit_profile_labels=True, legend_loc=3, figheight=8, add_mode_info=False, fsize_legend=12, fsize_labels=16, **add_lines)[source]

Plot current tau image including all reference areas.

Parameters:

tau_img (Img) – the tau image to be displayed
tau_min (float, optional) – lower tau boundary to be displayed
tau_max (float, optional) – upper tau boundary for colormap
edit_profile_labels (bool) – beta version of smart layout for axis labels from profile subplots
legend_loc (int) – number ID for specifying legend position
figheight (int) – figure height in inches (dpi=matplotlib default)
add_mode_info (bool) – if True, information about the used correction mode is included in the plot
**kwargs –

additional lines to be plotted, e.g.::
pcs = [300, 400, 500, 600]

settings_dict()[source]: Write current sky reference areas and masks into dictionary.

property mode_info_dict: Return information on available bg modelling modes.

mode_info(mode_num)[source]

Return short information about one of the available modelling modes.

Parameters:: mode_num (int) – the background modelling mode for which information is required
Returns:: short description of mode
Return type:: str

print_mode_info()[source]: Print information about the different correction modes.

pyplis.plumebackground.scale_tau_img(tau, rect)[source]: Scale tau image such that it fulfills tau==0 in reference area.

pyplis.plumebackground.scale_bg_img(bg, plume, rect)[source]

Normalise background image to plume image intensity in input rect.

Parameters:

bg (ndarray) – background image
plume (ndarray) – plume image
rect (list) – list containing rectangle coordinates

Returns:

the scaled background image

Return type:

ndarray

pyplis.plumebackground.corr_tau_curvature_vert_two_rects(tau0, r0, r1)[source]

Apply vertical linear background curvature correction to tau img.

Retrieves pixel mean value from two rectangular areas and determines linear offset function based on the vertical positions of the rectangle center coordinates. The corresponding offset for each image row is then subtracted from the input tau image

Parameters:

tau0 ((ndarray, Img)) – inital tau image
r0 (list) – 1st rectanglular area ``[x0, y0, x1, y1]`
r1 (list) – 2nd rectanglular area ``[x0, y0, x1, y1]`

Return ndarray:

modified tau image

pyplis.plumebackground.corr_tau_curvature_hor_two_rects(tau0, r0, r1)[source]

Apply horizonzal linear background curvature correction to tau img.

Retrieves pixel mean values from two rectangular areas and determines linear offset function based on the horizontal positions of the rectangle center coordinates. The corresponding offset for each image row is then subtracted from the input tau image.

Parameters:

tau0 ((ndarray, Img)) – inital tau image
r0 (list) – 1st rectanglular area ``[x0, y0, x1, y1]`
r1 (list) – 2nd rectanglular area ``[x0, y0, x1, y1]`

Return ndarray:

modified tau image

pyplis.plumebackground.corr_tau_curvature_vert_line(tau0, pos_x, start_y=0, stop_y=None, row_mask=None, polyorder=2)[source]

Correct vertical tau curvature using selected row indices of vertical line.

Parameters:

tau0 ((ndarray, Img)) – inital tau image
pos_x (int) – x position of line (column number)
start_y (int) – first considered vertical index for fit (0)
stop_y (int) – last considered vertical index for fit (is set to last row number if unspecified)
row_mask (ndarray) – boolean mask specifying considered row indices (if valid, params start_y, stop_y are not considered)
polyorder (int) – order of polynomial to fit curvature

return tuple: 1st entry: modified tau image, second: fitted polynomial

pyplis.plumebackground.corr_tau_curvature_hor_line(tau0, pos_y, start_x=0, stop_x=None, col_mask=None, polyorder=2)[source]

Correct vertical tau curvature using selected row indices of vertical line.

Parameters:

tau0 ((ndarray, Img)) – inital tau image
pos_y (int) – y position of line (row number)
start_x (int) – first considered horizontal index for fit (0)
stop_y (int) – last considered horizontal index for fit (is set to last col number if unspecified)
col_mask (ndarray) – boolean mask specifying considered column indices (if valid, params start_x, stop_x are not considered)
polyorder (int) – order of polynomial to fit curvature

return tuple: 1st entry: modified tau image, second: fitted polynomial

pyplis.plumebackground.find_sky_reference_areas(plume_img, sigma_blur=2, plot=False)[source]: Take an input plume image and identify suitable sky reference areas.

pyplis.plumebackground.plot_sky_reference_areas(plume_img, settings_dict, ax=None)[source]

Plot provided sky reference areas into a plume image.

Parameters:

plume_img ((ndarray, Img)) – plume image data
settings_dict (dict) – dictionary containing settings (e.g. retrieved using find_sky_reference_areas())

pyplis.plumebackground.find_sky_background(plume_img, next_img=None, bgmodel_settings_dict=None, lower_thresh=None, apply_movement_search=True, **settings_movement_search)[source]

Prepare mask for background fit based on analysis of current image.

The mask is determined by applying an intensity threshold to a plume image based on the intensities in 3 sky reference rectangles of an instance of the PlumeBackgroundModel object. If not specified on input from an exisiting instance of the class (using :param:`bgmodel_settings_dict`), the 3 required reference areas are calculated automatically using find_sky_reference_areas(). Alternatively, the lower threshold can be provided on input using :param:`lower_thresh`. Furthermore, pixels showing movement between the input image :param:`plume_img`and a second provided image (i.e. :param:`next_img`) can be excluded. The detection of movement between the two frames is performed using the movement detection algorithm find_movement() (see plumespeed).

Note

This is a Beta version
The method requires images in radiances space (i.e. plume and
terrain pixels appear darker than the sky background).
The input plume image should not contain clouds. If it does, it is
highly recommended to make use of the movement detection algorithm

Parameters:

plume_img (Img) – the plume image for which the sky background pixels are supposed to be detected
next_img (Img, optional) – second image used to compute the optical flow in :param:`plume_img`
bgmodel_settings_dict (dict) – dictionary containing information about sky reference areas (e.g. created using settings_dict() from an existing instance of the PlumeBackgroundModel). If not specified, the required reference rectangles (scale_rect, ygrad_rect, xgrad_rect) are determined automatically using find_sky_reference_areas().
lower_thresh (float, optional) – lower intensity threshold. If provided, this value is used rather than the value derived from the 3 sky reference rectangles (see :param:`bgmodel_settings_dict`)
**settings_movement_search – additional keyword arguments passed to find_movement(). Note that these may include settings for the optical flow calculation which are further passed to the initiation of the FarnebackSettings class

Returns:

2D-numpy boolean numpy array specifying sky background pixels

Return type:

array

Plume velocity analysis

Pyplis module containing features related to plume velocity analysis.

pyplis.plumespeed.get_veff(normal_vec, dir_mu, dir_sigma, len_mu, len_sigma, pix_dist_m=1.0, del_t=1.0, sigma_tol=2)[source]

Calculate effective velocity through line element with normal n.

The velocity is estimated based on a provided displacement angle and magnitude which is converted into dx and dy displacement and projected to n using the dot product. Unecertainties are estimated

Parameters:

normal_vec (array) – 2D normal vector relative to which the effective velocity is retrieved
dir_mu (float) – expectation value of displacement orientation angle in degrees (e.g. retrieved using histogram analysis)
dir_sigma (float) – uncertainty of prev. angle
len_mu (float) – expectation value of displacement magnitude in units of pixels (e.g. retrieved using histogram analysis)
len_sigma (float) – uncertainty of prev. magnitude
pix_dist_m (float) – pixel-to-pixel distance in m
del_t (float) – time difference corresponding to above displacement information
sigma_tol (int) – sigma tolerance factor for uncertainty estimate, defaults to 2

Returns:

2-element tuple containing effective velocity and corresponding error

Return type:

pyplis.plumespeed.find_signal_correlation(first_data_vec, next_data_vec, time_stamps=None, reg_grid_tres=None, freq_unit='S', itp_method='linear', max_shift_percent=20, sigma_smooth=1, plot=False, **kwargs)[source]

Determine cross correlation from two ICA time series.

Parameters:

first_data_vec (array) – first data vector (i.e. left or before next_data_vec)
next_data_vec (array) – second data vector (i.e. behind first_data_vec)
time_stamps (array) – array containing time stamps of the two data vectors. If default (None), then the two vectors are assumed to be sampled on a regular grid and the returned lag corresponds to the index shift with highest correlation. If len(time_stamps) == len(first_data_vec) and if entries are datetime objects, then the two input time series are resampled and interpolated onto a regular grid, for resampling and interpolation settings, see following 3 parameters.
reg_grid_tres (int) – sampling resolution of resampled time series data in units specified by input parameter freq_unit. If None, then the resolution is determined automatically based on the mean time resolution of the data
freq_unit (str) – pandas frequency unit (use S for seconds, L for ms)
itp_method (str) – interpolation method, choose from ["linear", "quadratic", "cubic"]
max_shift_percent (float) – percentage maximum shift applied to index of :arg:`first_data_vec` to find pearson correlation with :arg:`next_data_vec`.
sigma_smooth (int) – specify width of gaussian blurring kernel applied to data before correlation analysis (default=1)
plot (bool) – if True, result is plotted

Returns:

5-element tuple containing

float: lag (in units of s or the index, see input specs)
array: retrieved correlation coefficients for all shifts
Series: analysis signal 1. data vector
Series: analysis signal 2. data vector
Series: analysis signal 2. data vector shifted using ``lag`

Return type:

pyplis.plumespeed.find_signal_correlation_old(first_data_vec, next_data_vec, time_stamps=None, reg_grid_tres=None, freq_unit='S', itp_method='linear', cut_border_idx=0, sigma_smooth=1, plot=False, **kwargs)[source]

Determine cross correlation from two ICA time series.

This is

Parameters:

first_data_vec (array) – first data vector (i.e. left or before next_data_vec)
next_data_vec (array) – second data vector (i.e. behind first_data_vec)
time_stamps (array) – array containing time stamps of the two data vectors. If default (None), then the two vectors are assumed to be sampled on a regular grid and the returned lag corresponds to the index shift with highest correlation. If len(time_stamps) == len(first_data_vec) and if entries are datetime objects, then the two input time series are resampled and interpolated onto a regular grid, for resampling and interpolation settings, see following 3 parameters.
reg_grid_tres (int) – sampling resolution of resampled time series data in units specified by input parameter freq_unit. If None, then the resolution is determined automatically based on the mean time resolution of the data
freq_unit (str) – pandas frequency unit (use S for seconds, L for ms)
itp_method (str) – interpolation method, choose from ["linear", "quadratic", "cubic"]
cut_border_idx (int) – number of indices to be removed from both ends of the input arrays (excluded datapoints for cross correlation analysis)
sigma_smooth (int) – specify width of gaussian blurring kernel applied to data before correlation analysis (default=1)
plot (bool) – if True, result is plotted

Returns:

5-element tuple containing

float: lag (in units of s or the index, see input specs)
array: retrieved correlation coefficients for all shifts
Series: analysis signal 1. data vector
Series: analysis signal 2. data vector
Series: analysis signal 2. data vector shifted using ``lag`

Return type:

class pyplis.plumespeed.VeloCrossCorrEngine(pcs: LineOnImage, pcs_offset: LineOnImage | None = None, meas_geometry: MeasGeometry | None = None, imglist: BaseImgList | None = None, **settings)[source]

Class for plume velocity retrieval using cross-correlation method.

This class can be used to calculate the plume velocity based on a cross-correlation analysis of two ICA time-series retrieved from a set of plume images between two (ideally parallel) plume intersection lines.

profile_images

dictionary containing PCS profile images, which are ProfileTimeSeriesImg and where the x-axis corresponds to the image index (time) and the y-axis the corresponding line profiles for each of the two PCS lines. These images can be saved as FITS and reload, which can accelarate a reanalysis process (the bottleneck of the cross correlation analysis is loading all images in the list and retrieving the actual PCS profiles along both lines). Valid keys: pcs and pcs_offset.

Type:: dict

results

results of cross-correlation analysis, will be filled in get_velocity().

Type:: dict

Parameters:

imglist – Image list used to retrieve time series of integrated column amounts along 2 suitable plume intersections used for velocity retrieval
pcs (LineOnImage) – Plume cross section line used for velocity retrieval
pcs_offset (LineOnImage) – Second (shifted to pcs) PCS line used for velocity retrieval
meas_geometry – optional: MeasGeometry object used to calculate in-plume pix-to-pix distances. If None, then the MeasGeometry object of the assigned ImgList (imglist) is used.
**settings – optional keyword args passed to find_signal_correlation() (used in class method get_velocity()).

__init__(pcs: LineOnImage, pcs_offset: LineOnImage | None = None, meas_geometry: MeasGeometry | None = None, imglist: BaseImgList | None = None, **settings)[source]

update_settings(settings_dict)[source]

Update settings for cross correlation retrieval.

Parameters:: settings_dict (dict) – dictionary containing new settings

property velocity

Retrieve plume velocity.

Raises:: ValueError – if velocity is nan (default).
Returns:: plume velocity in m/s.
Return type:: float

property correlation_lag

Time lag showing highest correlation between two ICA time-series.

Raises:: ValueError – if velocity is nan (default).
Returns:: time lag in seconds (or indices, see input specs).
Return type:: float

property pcs: Return the PCS line used for the velocity retrieval.

property pcs_offset: Return the PCS offset line used for the velocity retrieval.

property pcs_profile_pics: Check and, if applicable, return current PCS profile images.

get_pcs_tseries_from_imgstack(stack, start_idx=0, stop_idx=None)[source]

Load PCS profile time series pictures from image stack.

Parameters:

stack (ImgStack) – stack containing OD or AA images
start_idx (int) – index of first considered image in list
stop_idx (int) – last considered index in image list

Returns:

2-element tuple containing ProfileTimeSeriesImg for both PCS lines

Return type:

get_pcs_tseries_from_list(start_idx=0, stop_idx=None)[source]

Load profile time series pictures from AA img list.

Loop over images in image list and extract cross section profiles for each of the 2 provided plume cross section lines. The profiles are written into a ProfileTimeSeriesImg which can be stored as FITS file.

Parameters:

start_idx (int) – index of first considered image in list
stop_idx (int) – last considered index in image list

Returns:

2-element tuple containing ProfileTimeSeriesImg for both PCS lines

Return type:

run(**settings)[source]

Apply correlation algorithm to ICA time series of both lines.

Parameters:: **settings – optional keyword args passed to find_signal_correlation()

create_parallel_pcs_offset(offset_pix=50, color='lime', linestyle='--')[source]

Create an offset line to the current PCS used for retrieval.

Parameters:: offset_pix (int) – Distance of new line to current PCS line (in normal direction). The distance is calculated in detector coordinates on pyramid level 0.
Returns:: Translated PCS line
Return type:: LineOnImage

check_list(lst)[source]

Check if imglist is ready for velocity analysis.

Parameters:: lst (BaseImgList) – the image list object supposed to be checked
Returns:: True, if list is okay, False if not
Return type:: bool

get_pix_dist_img(pyrlevel=0)[source]

Image specifying pix-to-pix distances for each pixel.

The image is loaded from the current MeasGeometry object assigned to the image list.

load_pcs_profile_img(file_path: str, line_id: str)[source]

Try to load ICA profile time series image from FITS file.

Parameters:

file_path (ProfileTimeSeriesImg) – valid file path to profile time-series image
line_id (str) – specify to which line the image belongs

save_pcs_profile_images(save_dir: str, fname1: str | None = None, fname2: str | None = None)[source]

Save current ICA profile time series images as FITS file.

Note

Existing files will be overwritten without warning

Parameters:

save_dir (str) – Directory where images are saved (if None, use current directory)
fname1 (str) – name of first profile image
fname2 (str) – name of second profile image

plot_pcs_lines(img=None, **kwargs)[source]

Plot current PCS retrieval lines into image.

Parameters:

img – optional: example plume image (Img object). If None, then the current image of imglist is used
**kwargs – additional keyword arguments passed to show() of Img object. This can also be used to pass an axes instance using keyword ax, for instance if this is supposed to be plotted into a subplot.

Returns:

matplotlib axes instance

Return type:

ax

plot_ica_tseries_overlay(ylabel=None, ax=None)[source]: Plot the ICA time-series of the analysed signals.

Note

Only works after cross-correlation analysis is performed

plot_corrcoeff_tseries(add_lag=True, ax=None, **kwargs)[source]

Plot time series of correlation coefficients.

Parameters:

add_lag (bool) – if True, a vertical line is added at x-position showing maximum correlation
ax – matplotlib axes object

class pyplis.plumespeed.LocalPlumeProperties(roi_id=None, **kwargs)[source]

Class to store local properties of plume displacement.

This class represents statistical (local) plume (gas) displacement information (e.g. retrieved using an optical flow algorithm). These include the predominant local displacement direction (orientation of displacement vectors) and the corresponding displacement length both including uncertainties (e.g. retrieved from Gauss fits applied to histogram distribution). Further, the time difference between the two frames used to estimate the displacement parameters is stored. This class is for instance used for plume displacement properties derived using local_flow_params() from OptflowFarneback which is based on a statistical analysis of histograms derived from a dense optical flow algorithm.

__init__(roi_id=None, **kwargs)[source]

property start: Acquisistion time of first image.

property stop: Start acqusition time of last image.

property len_mu: Array containing displacement lengths (unit [pix/del_t]).

property len_sigma: Array with errors of displacement lengths (unit [pix/del_t]).

property len_mu_norm: Array containing normalised displacement lengths (unit [pix/s]).

property len_sigma_norm: Array with errors of normalised displ. lens (unit [pix/s]).

property dir_mu: Return current displacement orientation vector.

property dir_sigma: Return current displacement orientation std vector.

property significance

Significancy of data point.

This array is filled in get_and_append_from_farneback(), which calls local_flow_params() of OptflowFarneback object. The number corresponds to the fraction of pixels used to determine the displacement parameters, relative to the total number of pixels available in the corresponding ROI used. The latter can, for instance, be a rotated ROI around a retrieval line (LineOnImage class).

property fit_success: Array containing flags whether or not multi-gauss fit was successful.

property pyrlevel: Array containing pyramid levels used to determine displ. params.

property del_t

Return current del_t vector.

Corresponds to the difference between frames for time series

property start_acq

Return current displacement length std vector.

Corresponds to the start acquisition times of the time series

property displacement_vectors: All displacement vectors (unit [pix / del_t]).

displacement_vector(idx=-1)[source]

Get displacement vector for given index.

The vector is returned in unit [pix / del_t].

Parameters:: idx (int) – index
Returns:: 2-element array containing displacement in x and y direction, i.e. (dx, dy)
Return type:: array

to_pyrlevel(pyrlevel=0)[source]: Convert data to a given pyramid level.

apply_significance_thresh(thresh=0.5)[source]

Remove all datapoints with significance val below thresh.

Datapoints with significance lower than the provided threshold are converted into NaN. Can be combined with interpolation and clean up.

Parameters:: thresh (float) – significance threshold supposed to be applied to data
Returns:: new object excluding nan values in any of the data arrays
Return type:: LocalPlumeProperties

dropna(**kwargs)[source]

Drop all indices containing nans.

Remove all indices for which any of the data arrays len_mu, len_sigma, dir_mu, dir_sigma, del_t contains NaN values using the method dropna() of pandas DataFrame object.

Parameters:: **kwargs – additional keyword arguments passed to dropna() of pandas DataFrame object.
Returns:: new object excluding nan values in any of the data arrays
Return type:: LocalPlumeProperties

interpolate(time_stamps=None, **kwargs)[source]

Interpolate missing.

Remove all indices for which any of the data arrays len_mu, len_sigma, dir_mu, dir_sigma, del_t contains NaN values using the method dropna() of pandas DataFrame object.

Parameters:

time_stamps (array) – array containing datetime indices supposed to be used for interpolation
**kwargs – additional keyword arguments passed to dropna() of pandas DataFrame object.

Returns:

new object excluding nan values in any of the data arrays

Return type:

LocalPlumeProperties

apply_median_filter(width=5)[source]

Apply median filter to data.

The filter is only applied to len_mu and dir_mu, and the corresponding uncertainty arrays len_sigma and dir_sigma

Note

Creates and returns new LocalPlumeProperties instance, the data in this object remains unchanged

Parameters:: width (int) – width of 1D median filter
Returns:: new data object
Return type:: LocalPlumeProperties

apply_gauss_filter(width=5)[source]

Apply Gaussian blurring filter to data.

The filter is only applied to len_mu and dir_mu, and the corresponding uncertainty arrays len_sigma and dir_sigma

Note

Creates and returns new LocalPlumeProperties instance, the data in this object remains unchanged

Parameters:: width (int) – width of Gaussian blurring kernel
Returns:: new data object
Return type:: LocalPlumeProperties

get_and_append_from_farneback(optflow_farneback, **kwargs)[source]

Retrieve main flow field parameters from Farneback engine.

Calls local_flow_params() from OptflowFarneback engine and appends the results to the current data

Parameters:

optflow_farneback (OptflowFarneback) – optical flow engine used for analysis
**kwargs – additional keyword args passed to local_flow_params()

get_velocity(idx=-1, pix_dist_m=1.0, pix_dist_m_err=None, normal_vec=None, sigma_tol=2)[source]

Determine plume velocity from displacements.

Parameters:

idx (int) – index of results for which velocity is determined
pix_dist_m (float) – pixel to pixel distance in m (default is 1.0), e.g. determined using MeasGeometry object
pix_dist_m_err (float, optional) – uncertainty in pixel distance, if None (default), then 5% of the actual pixel distance is assumed
normal_vec (tuple, optional) – normal vector used for scalar product to retrieve effective velocity (e.g. normal_vector of a LineOnImage) object. If None (default), the normal direction is assumed to be aligned with the displacement direction, i.e. the absolute magnitude of the velocity is retrieved
sigma_tol (int) – sigma tolerance level for expectation intervals of orientation angle and displ. magnitude

Returns:

2-element tuple containing

float: magnitude of effective velocity
float: uncertainty of effective velocity

Return type:

get_orientation_tseries()[source]

Get time series (and uncertainties) of movement direction.

Returns:

3-element tuple containing

Series: time series of orientation angles
Series: time series of lower vals (using dir_sigma)
Series: time series of upper vals (using dir_sigma)

Return type:

get_magnitude_tseries(normalised=True)[source]

Get time series (and uncertainties) of displacement lengths.

Note

The time series are absolute magnitudes of the retrived displacement lengths and are not considered relative to a certain normal direction.

Parameters:

normalised (bool) – if True, the lengths are normalised to a time difference of 1s

Returns:

3-element tuple containing

Series: time series of displacement lengths
Series: time series of lower vals (using len_sigma)
Series: time series of upper vals (using len_sigma)

Return type:

plot_directions(ax=None, date_fmt=None, yerr=True, ls=None, **kwargs)[source]

Plot time series of displacement orientation.

Parameters:

ax – optional, matplotlib axes object
date_fmt (str) – optional, x label datetime formatting string, passed to DateFormatter (e.g. “%H:%M”)
**kwargs – additional keyword args passed to plot function of Series object

Returns:

matplotlib axes object

Return type:

Axes

plot_magnitudes(normalised=True, ax=None, date_fmt=None, yerr=True, ls=None, **kwargs)[source]

Plot time series of displacement magnitudes.

Parameters:

normalised (bool) – normalise magnitudes to time difference intervals of 1s
ax – optional, matplotlib axes object
date_fmt (str) – optional, x label datetime formatting string, passed to DateFormatter (e.g. “%H:%M”)
**kwargs – additional keyword args passed to plot function of Series object

Returns:

matplotlib axes object

Return type:

Axes

plot(date_fmt=None, fig=None, **kwargs)[source]

Plot showing detailed information about this time series.

Parameters:

date_fmt (str) – date string formatting for x-axis
fig (figure) – matplotlib figure containing 3 subplots

plot_velocities(pix_dist_m=None, pix_dist_m_err=None, ax=None, normal_vec=None, date_fmt=None, **kwargs)[source]

Plot time series of velocity evolution.

Parameters:

pix_dist_m – detector pixel distance in m, if unspecified, then velocities are plotted in units of pix/s
pix_dist_m_err – uncertainty in pixel to pixel distance in m

to_dict()[source]

Write all data attributes into dictionary.

Keys of the dictionary are the private class names

Returns:: Dictionary containing results
Return type:: OrderedDict

from_dict(d)[source]

Read valid attributes from dictionary.

Parameters:: d (dict) – dictionary containing data
Returns:: this object
Return type:: LocalPlumeProperties

to_pandas_dataframe()[source]

Convert object into pandas dataframe.

This can, for instance be used to store the data as csv (cf. from_pandas_dataframe())

from_pandas_dataframe(df)[source]

Import results from pandas DataFrame object.

Parameters:: df (DataFrame) – pandas dataframe containing emisison rate results
Returns:: this object
Return type:: LocalPlumeProperties

property default_save_name: Return default name for txt export.

save_txt(path=None)[source]: Save this object as text file.

load_txt(path)[source]

class pyplis.plumespeed.FarnebackSettings(**settings)[source]

Settings for optical flow Farneback calculations and visualisation.

Todo

Finish docs

This object contains settings for the opencv implementation of the optical flow Farneback algorithm calcOpticalFlowFarneback(). For a detailed description of the input parameters see OpenCV docs (last access: 07.03.2017).

Furthermore, it includes attributes for image preparation which are applied to the input images before calcOpticalFlowFarneback() is called. Currently, these include contrast changes specified by i_min and i_max which can be used to specify the range of intensities to be considered.

In addition, post analysis settings of the flow field can be specified, which are relevant, e.g. for a histogram analysis of the retrieved flow field:

roi_abs: specifiy ROI for post analysis of flow field (abs indicates that the input is assumed to be in absolute image coordinates and not in coordinates set based on a cropped or size reduced image). Default corresponds to whole image.

min_length: minimum length of optical flow vectors to be considered for statistical analysis, default is 1 (pix)

hist_sigma_tol: parameter for retrieval of mean flow field parameters. It specifies the range of considered orientation angles based on mu and sigma of the main peak of flow field orientation histogram. All vectors falling into this angular range are considered to determine the flow length histogram used to estimate the average displacement length.

hist_dir_gnum_max: maximum allowed number of gaussians for multi gauss fit of orientation histogram (default = 5).

Parameters:

**settings –

valid keyword arguments for class attributes, e.g.:

stp = FarnebackSettings(i_min=0, i_max=3500,
                                   iterations=8)

__init__(**settings)[source]

update(**settings)[source]

Update current settings.

Parameters:: **settings – keyword args specifying new settings (only valid keys are considered, i.e. class attributes)

property i_min: Lower intensity limit for image contrast preparation.

property i_max: Upper intensity limit for image contrast preparation.

property roi_rad_abs

ROI used for measuring min / max intensities for contrast settings.

ROI (in absolute image coords) for updating the intensity range i_min / i_max (only relevant if auto_update is True).

property auto_update

Contrast is automatically updated based on min / max intensities.

If active, then i_min and i_max are updated automativally whenever new images are assigned to a OptflowFarneback using method set_images(). The update is performed based on min / max intensities of the images in the current ROI

property pyr_scale

scale space parameter for pyramid levels.

pyplis default = 0.5

Type:: Farneback algo input

property levels

number of pyramid levels.

pyplis default = 4

Type:: Farneback algo input

property winsize

width of averaging kernel.

The larger, the more stable the results are, but also more smoothed

pyplis default = 20

Type:: Farneback algo input

property iterations

number of iterations.

pyplis default = 5

Type:: Farneback algo input

property poly_n

size of pixel neighbourhood for poly exp.

default = 5

Type:: Farneback algo input

property poly_sigma

std of Gaussian to smooth poly derivatives.

pyplis default = 1.1

Type:: Farneback algo input

property roi_abs: Get ROI for analysis of flow field (in absolute image coords).

property min_length: Get / set minimum flow vector length for post analysis.

property min_count_frac: Minimum fraction of significant vectors required for histo analysis.

property hist_dir_sigma: Old name of hist_sigma_tol.

property hist_sigma_tol: Sigma tolerance value for mean flow analysis.

property hist_dir_gnum_max: Max number of gaussians for multigauss fit of orientation histo.

property hist_dir_binres: Angular resolution of orientation histo (bin width, in deg).

property disp_skip: Return current pixel skip value for displaying flow field.

property disp_len_thresh: Return current pixel skip value for displaying flow field.

duplicate()[source]: Return deepcopy of this object.

class pyplis.plumespeed.OptflowFarneback(first_img=None, next_img=None, **settings)[source]

Implementation of Optical flow Farneback algorithm of OpenCV library.

Engine for autmatic optical flow calculation, for settings see FarnebackSettings. The calculation of the flow field is performed for two consecutive images.

Includes features for histogram based post analysis of flow field which can be used to estimate flow vectors in low contrast image regions.

Parameters:

first_img (Img, optional) – first of two consecutive images
next_img (Img, optional) – second of two consecutive images

images_input

Dictionary containing the current images used to determine flow field. The images can be updated using set_images(). Keys: this, next

Type:: dict

images_prep

Dictionary containing modified input images prepared for determining the optical field using calcOpticalFlowFarneback() (e.g. contrast changed, converted to 8 bit). Keys: this, next

Type:: dict

flow

this attribute contains the flow field (i.e. raw output of calcOpticalFlowFarneback()).

Type:: array

settings

settings class including input specifications for flow calculation (i.e. input args for calcOpticalFlowFarneback()) and further, settings for image preparation (before the flow field is calculated, cf. images_prep) as well as settings for post analysis of the optical flow field (e.g. for histogram analysis).

Type:: FarnebackSettings

__init__(first_img=None, next_img=None, **settings)[source]

property auto_update_contrast

Get / set mode for automatically update contrast range.

If True, the contrast parameters self.settings.i_min and self.settings.i_max are updated when set_images`() is called, based on the min / max intensity of the two images. The latter intensities are retrieved within the current ROI for the flow field analysis (self.roi_abs)

reset_flow()[source]: Reset flow field.

property roi_abs: Get / set current ROI (in absolute image coordinates).

property roi: Get ROI converted to current image preparation settings.

property pyrlevel: Return pyramid level of current image.

property del_t: Return time difference in s between both images.

property current_time: Return acquisition time of current image.

set_mode_auto_update_contrast_range(value=True)[source]

Activate auto update of image contrast range.

If this mode is active (the actual parameter is stored in self._img_prep_modes["update_contrast"]), then, whenever the optical flow is calculated, the input contrast range is updated based on minimum / maxium intensity of the first input image within the current ROI.

Parameters:: (True) (bool value) – new mode

check_contrast_range(img_data)[source]: Check input contrast settings for optical flow calculation.

current_contrast_range()[source]: Get min / max intensity values for image preparation.

property has_images: Boolean specifying whether image data is available for flow comp

update_contrast_range()[source]: Update contrast range using min/max vals of current images in ROI.

set_images(this_img, next_img)[source]

Update the current image objects.

Parameters:

this_img (ndarray) – the current image
next_img (ndarray) – the next image

prep_images()[source]: Prepare images for optical flow input.

calc_flow(this_img=None, next_img=None)[source]

Calculate the optical flow field.

Uses cv2.calcOpticalFlowFarneback() to calculate optical flow field between two images using the input settings specified in self.settings.

Parameters:

this_img (Img) – the first of two successive images (if unspecified, the current images in self.images_prep are used, else, they are updated)
next_img (Img) – the second of two successive images (if unspecified, the current images in self.images_prep are used, else, they are updated)

Returns:

3D numpy array containing flow displacement field (is also assigned to flow)

Return type:

array

get_flow_in_roi(roi_rel=None)[source]

Get the flow field within in a ROI.

Parameters:

roi_rel (list) –

rectangular ROI aligned with image axis ([x0, y0, x1, y1]).

Note

The ROI is used as is, i.e. it needs to be defined for current Gauss pyramid level.

Returns:

3D numpy array containing flow displacement field in ROI

Return type:

array

prep_flow_for_analysis(mask=None)[source]

Get flow field data from all pixels in a certain ROI.

This function provides access to the flow field in a certain region of interest. In the default case the currently set roi roi is used (which is a rectangle aligned with the image x / y axis). Alternatively, a pixel access mask can be provided (e.g. specifying pixels in a rotated rectangle) which is then be used.

Parameters:

mask (array) – boolean mask specifying all pixels used to retrieve displacement information (True pixels in mask)

Returns:

2-element tuple containing

array, vector containing all x displacement lengths
array, vector containing all y displacement lenghts

Return type:

to_plume_speed(col_dist_img, row_dist_img=None)[source]

Convert the current flow field to plume speed array.

Parameters:

col_dist_img (Img) – image, where each pixel corresponds to horizontal pixel distance in m
row_dist_img – optional, image where each pixel corresponds to vertical pixel distance in m (if None, col_dist_img is also used for vertical pixel distances)

get_flow_orientation_img(in_roi=False, roi_rel=None)[source]

Return flow angle image.

The pixel values correspond to the orientation angles of the vectors of the current flow field, where the values correspond to:

0 -> upwards (-y direction)

90 -> to the right (+x direction)

-90 -> to the left (-x direction)

-180, 180 -> down (+y direction)

Parameters:

in_roi (bool) – get the image for a certain ROI
roi_rel (list, optional,) – the ROI supposed to be used if in_roi is True. If None (default) then the current ROI is used (roi).

Returns:

2D numpy array corresponding to flow orientation image

Return type:

array

get_flow_vector_length_img(in_roi=False, roi=None)[source]

Return flow vector length image.

The pixel values correspond to the magnitude of the vectors of the current flow field.

Parameters:

in_roi (bool) – get the image for a certain ROI
roi (list, optional,) – the ROI supposed to be used if in_roi is True. If None (default) then the current ROI is used (roi).

Returns:

2D numpy array corresponding to flow orientation image

Return type:

array

all_len_angle_vecs_roi(mask=None)[source]

Get lengths and angles for all pixels in a ROI.

Parameters:

mask (array, optional) – boolean mask specifying all pixels supposed to be used for data access, defaults to None, in which case the current ROI is used (i.e. roi)

Returns:

2-element tuple containing

array, vector with all displacement lengths in ROI / mask
array, vector with all displacement angles in ROI / mask

Return type:

flow_orientation_histo(pix_mask=None, bin_res_degrees=None, min_length=1.0, **kwargs)[source]

Get histogram of orientation distribution of current flow field.

Parameters:

pix_mask (array, optional) –
boolean mask specifying image pixels supposed to be considered for the analysis. Is passed to all_len_angle_vecs_roi(), i.e. if this mask is unspecified the histogram data is retrieved using the current ROI (roi) for specifying the considered image region.

Note

This is ignored if two arrays containing lengths and angles are provided using **kwargs (for details see below)
bin_res_degrees (int) – bin width of histogram (is rounded to nearest integer if not devisor of 360), if unspecified use hist_dir_binres of settings class
min_length (float) – minimum length of vectors in order to be considered for histogram, defaults to 1.0
**kwargs – additional key word args that can be used to pass lens and angles arrays (see e.g. local_flow_params()). Use keywords lens and angles to pass this information.

Returns:

3-element tuple containing

array: histogram counts
array: histogram bins
array: all angles used to determine the histogram

Return type:

flow_length_histo(pix_mask=None, bin_res_pix=1, min_length=1.0, **kwargs)[source]

Get histogram of displacement length distribution of flow field.

Parameters:

pix_mask (array, optional) –
boolean mask specifying image pixels supposed to be considered for the analysis. Is passed to all_len_angle_vecs_roi(), i.e. if this mask is unspecified the histogram data is retrieved using the current ROI (roi) for specifying the considered image region.

Note

This is ignored if two arrays containing lengths and angles are provided using **kwargs (for details see below)
bin_res_pix (int) – bin width in units of pixels, defaults to 2
min_length (float) – minimum length of vectors in order to be considered for histogram, defaults to 1.0
**kwargs – additional key word args that can be used to pass lens and angles arrays (see e.g. local_flow_params()). Use keyword lens to pass this information.

Returns:

3-element tuple containing

array: histogram counts
array: histogram bins
array: all lengths used to determine the histogram

Return type:

fit_multigauss_to_histo(count, bins, noise_amp=None, max_num_gaussians=None)[source]

Fit multi gauss distribution to histogram.

Parameters:

count (array) – array containing histogram counts
bins (array) – array containing bins corresponding to counts
noise_amp (float) – noise amplitude of the histogram data (you don’t want to fit all the noise peaks). If None, then it is estimated automatically within MultiGaussFit.
max_num_gaussians (int) – Maximum allowed number of Gaussians for MultiGaussFit, if None, then default of MultiGaussFit is used

Returns:

2-element tuple containing

MultiGaussFit: fit object
bool: success True / False

Return type:

fit_orientation_histo(count, bins, noise_amp=None, max_num_gaussians=None, **kwargs)[source]

Fit multi gauss distribution to flow orientation histogram.

Parameters:

count (array) – histogram counts (see flow_orientation_histo())
bins (array) – histogram bins (see flow_orientation_histo())
noise_amp (float, optional) – minimum amplitude required for peaks in histogram in order to be considered for multi gauss fit, if None (default) use 5% of max count
max_num_gaussians (int, optional) – maximum number of Gaussians fitted to the distributions, if None (default) then use self.settings.hist_dir_gnum_max

Returns:

2-element tuple containing

MultiGaussFit, the fit object
bool, fit success

Return type:

mu_sigma_from_moments(count, bins)[source]

Get mean and sigma of histogram distr. using 1. and 2nd moment.

Parameters:

count (array) – array with counts per bin
bins (array) – array containing bins

Returns:

2-element tuple, containing

float: expectation value mu
float: corresponding standard deviation

Return type:

fit_length_histo(count, bins, noise_amp=None, max_num_gaussians=4, **kwargs)[source]

Apply multi gauss fit to length distribution histogram.

Parameters:

count (array) – histogram counts (see flow_orientation_histo())
bins (array) – histogram bins (see flow_orientation_histo())
noise_amp (float, optional) – minimum amplitude required for peaks in histogram in order to be considered for multi gauss fit, if None (default) use 5% of max count
max_num_gaussians (int, optional) – maximum number of Gaussians fitted to the distributions, if None (default) then use self.settings.hist_dir_gnum_max

Returns:

2-element tuple containing

MultiGaussFit, the fit object
bool, fit success

Return type:

local_flow_params(line=None, pix_mask=None, noise_amp=None, min_count_frac=None, min_length=None, dir_multi_gauss=True)[source]

Histogram based statistical analysis of flow field in current ROI.

This function analyses histograms of the current flow field within a ROI in order to find the predominant movement direction (within the ROI) and the corresponding predominant displacement length.

Parameters:

line (LineOnImage, optional) – if provided, then the ROI corresponding to the line orientation is used (see get_rotated_roi_mask() in LineOnImage objects). If unspecified the current roi (roi) is used.
pix_mask (array, optional) – boolean mask specifying image pixels supposed to be considered for the analysis, e.g. only plume pixels (determined applying a tau threshold to a tau image).
noise_amp (float, optional) – this number specifies the minimum amplitude for individual peaks in the histograms (for multiple Gaussian fit). If unspecified here it will be set automatically in the corresponding methods fit_length_histo() and fit_orientation_histo().
min_count_frac (float, optional) – determines the minimum required number of significant vectors in current ROI for histogram analysis (i.e. if ROI is NxM pixels and min_count_frac=0.1, then at least (MxN)*0.1 pixels need to remain after applying cond_mask_flat and exclusion of vectors shorter than current minimum length self.settings.min_length)
min_length (float, optional) – minimum length of vectors required in order to be considered for historgram analysis
dir_multi_gauss (bool) – if True, a multi Gauss analysis (see MultiGaussFit) is applied to orientation histogram to separate the main peak from potential other peaks. Note that the optimisation slows down the analysis a bit.

Returns:

dictionary containing results of the analysis

Return type:

dict

apply_median_filter(shape=(3, 3))[source]

Apply median filter to flow field, i.e. to both flow images individually.

dx, dy is stored in self.flow.

Parameters:: (3,3) (tuple shape) – size of the filter

replace_trash_vecs(displ_vec=(0.0, 0.0), min_len=1.0, dir_low=-180.0, dir_high=180.0)[source]

Replace all vectors that do not match certain constraints.

Returns a new OptflowFarneback object with all vectors in attr. flow replaced by provided displacement vector.

Parameters:

displ_vec (iterable) – 2-element vector (list, tuple, array) containing diplacement information (dx, dy) supposed to be used to replace vectors not matching provided constraints related to minimum length and expectation direction range
min_len (float) – minimum required length of vectors to be considered reliable
dir_low (float) – lower end of accepted displacement direction in order to be considered reliable
dir_high (float) – upper end of accepted displacement direction in order to be considered reliable

Returns:

duplicate of this class with flow containing displ_vec at indices not matching constraints

Return type:

OptflowFarneback

get_img_acq_times()[source]

Return acquisition times of current input images.

Returns:

2-element tuple, containing

datetime: acquisition time of first image
datetime: acquisition time of next image

Return type:

plot_orientation_histo(pix_mask=None, min_length=None, bin_res_degrees=None, apply_fit=True, ax=None, tit='Orientation histo', color='b', label='Histo data', bar_plot=True, **fit_settings)[source]

Plot flow orientation histogram.

Plots a histogram of the orientation angles of the flow vectors w within a certain ROI. By default, vectors shorter then self.settings.min_length are excluded from the histogram, if you want a histogram including the short vectors, provide input parameter min_length=0.0.

Todo

Finish docs …

plot_length_histo(pix_mask=None, dir_low=-180, dir_high=180, min_length=None, bin_res_pix=1, apply_fit=False, apply_stats=True, ax=None, tit='Length histo', label='Histo', color='b', bar_plot=True, **fit_settings)[source]: Plot flow vector length histogram including some options.

Todo

Write docs …

plot_flow_histograms(line=None, pix_mask=None, dir_multi_gauss=True)[source]

Plot detailed information about optical flow histograms.

Parameters:

line (LineOnImage, optional) – retrieval line used to calculate historgrams only in line specific ROI
pix_mask (ndarray, optional) – 2D numpy array specifying pixels for histogram retrieval, if unspecified, all image pixels are used, if specified and :param:`line` is specified too, then the union of valid pixels between both parameters is used
dir_multi_gauss (bool) – if True, then the orientation direction histogram is fitted using MultiGauss regression

Return type:

figure

calc_flow_lines(in_roi=True, roi=None, extend_len_fac=1.0, include_short_vecs=False)[source]

Determine line objects for visualisation of current flow field.

Parameters:

in_roi (bool) – if True (default), then the lines are calculated for pixels within ROI (either specified by 2. input param and else roi_abs is used).
roi (list) – Region of interest supposed to be displayed
extend_len_fac (float) – factor by which length of vectors are extended
include_short_vecs (bool) – if True, lines for short vectors are calculated as well

Returns:

the line coordinates

Return type:

plot(**kwargs)[source]

Draw current flow field onto image.

Wrapper for draw_flow()

Parameters:

**kwargs –

key word args (see draw_flow())

draw_flow(in_roi=False, roi_abs=None, add_cbar=False, include_short_vecs=False, extend_len_fac=1.0, linewidth=1, color=None, ax=None)[source]

Draw the current optical flow field.

Parameters:

in_roi (bool) – if True, the flow field is plotted in a cropped image area else, the whole image is drawn
roi_abs (list, optional) – region of interest for which the flow field is drawn (in absolute image coordinates, i.e. is converted to current pyrlevel). If None, then the roi_abs is used.
add_cbar (bool) – if True, a colorbar is added to the plot (note that the images are converted into 8 bit before the flow is calculated, therefore the intensity range of the displayed image is between 0 and 256).
include_short_vecs (bool) – if True, also vectors shorter than self.settings.min_length are drawn
extend_len_fac (float) – factor by which length of vectors are extended
linewidth (int) – with of flow vector lines
color – Color of vectors if flow field is plotted onto an already plotted image.
ax (Axes) – matplotlib axes object

Returns:

the plot axes

Return type:

Axes

live_example()[source]: Show live example using webcam.

connect_histo(canvasWidget)[source]

pyplis.plumespeed.find_movement(first_img, next_img, pyrlevel=2, num_contrast_ivals=8, ival_overlap=0.05, imin=None, imax=None, apply_erosion=True, erosion_kernel_size=20, apply_dilation=True, dilation_kernel_size=20, verbose=False, **optflow_settings)[source]

Search for movement using an iterative optical flow algorithm.

This algorithm searches for pixels containing movement between two consecutive images. This is done by using an optical flow algorithm which computes the optical flow field between the two images for a series of different input contrast intervals (imin, imax).

Note

This is a Beta version

Parameters:

first_img (Img) – first image for computation of optical flow
next_img (Img) – next image for computation of optical flow
pyrlevel (int) – pyramid level for iterative analysis, default: 2
num_contrast_ivals (int) – number of iterations (contrast intervals). The lower and upper values for each interval are determined based on the brightness range of the first image (or alternatively, the specified total considered brightness range using input parameters :param:ìmin` and :param:`imax`) divided by the number of specified intervals and the desired overlap between each interval (see :param:`ival_overlap`).
ival_overlap (float) – percentage overlap between each of the intervals used to calculate the optical flow, default is 0.05 (corresponding to 5%)
imin (float, optional) – lower limit for considered intensity range, if not specified, the minimum intensity of the first input image is used (at the specified pyramid level)
imax (float, optional) – upper limit for considered intensity range, if not specified, the maximum intensity of the first input image is used (at the specified pyramid level)
apply_erosion (bool) – if True, the OpenCV erosion algorithm is applied to the computed mask specifying pixels containing movement
erosion_kernel_size (int) – size of the erosion kernel applied to movement mask if :param:`apply_erosion` is True. Note that the erosion is applied to the mask at the specified input pyramid level (if e.g. a size of 20 pixels is used at pyramid level 2, this corresponds to 80 pixels in the original image resolution)
apply_dilation (bool) – if True, the OpenCV dilation algorithm is applied to the computed mask specifying pixels containing movement (this is done after the erosion is applied)
dilation_kernel_size (int) – size of the dilation kernel applied to movement mask if :param:`apply_dilation` is True. Note that the dilation is applied to the mask at the specified input pyramid level (if e.g. a size of 20 pixels is used at pyramid level 2, this corresponds to 80 pixels in the original image resolution)
verbose (bool) – print search information
**optflow_settings – additional keyword arguments specifying settings for optical flow computation

Returns:

2D-numpy boolean numpy array specifying pixels where movement was detected during the iterative search in the different brightness ranges. The pyramid level of the mask corresponds to the pyramid level of the input images and not the the pyramid level, where the computation was performed

Return type:

ndarray

class pyplis.plumespeed.OpticalFlowFarnebackSettings(*args, **kwargs)[source]

Old name of FarnebackSettings.

__init__(*args, **kwargs)[source]

class pyplis.plumespeed.OpticalFlowFarneback(*args, **kwargs)[source]

Old name of OptflowFarneback.

__init__(*args, **kwargs)[source]

Camera calibration base class

Pyplis module containing the CalibData.

This is the base class for storing calibration data, fitting calibration curves, and corresponding I/O routines (e.g storage as FITS or text file).

class pyplis.calib_base.CalibData(tau_vec=None, cd_vec=None, cd_vec_err=None, time_stamps=None, calib_fun=None, calib_coeffs=None, senscorr_mask=None, polyorder=1, calib_id=None, camera=None)[source]

Base class representing calibration data and optimisation parameters.

The default calibration curve is a polynomial of first order. Calibration data is represneted by two arrays cd_vec and tau_vec and optionally, a vector containing errors in the column densities cd_vec_err (note that errors in the optical densities are not supported). Furthermore, an array of time_stamps can be provided and If you want to use a custom calibration function you can provide the function using :param:`calib_fun`.

Parameters:

tau_vec (ndarray) – tau data vector for calibration data
cd_vec (ndarray) – DOAS-CD data vector for calibration data
cd_vec_err (ndarray) – Fit errors of DOAS-CDs
time_stamps (ndarray) – array with datetime objects containing time stamps (e.g. start acquisition) of calibration data
calib_fun (function) – optimisation function used for fitting of calibration data
calib_coeffs (;obj:list, optional) – optimisation parameters for calibration curve.
senscorr_mask (Img, optional) – sensitivity correction mask that was normalised relative to the pixel position where the calibration data was retrieved (i.e. position of DOAS FOV in case of DOAS calibration data, or image pixel position, where cell calibration data was retrieved)
calib_id (str) – calibration ID (e.g. “aa”, “tau_on”, “tau_off”)
camera (Camera) – camera object (not necessarily required). A camera can be assigned in order to convert the FOV extend from pixel coordinates into decimal degrees

__init__(tau_vec=None, cd_vec=None, cd_vec_err=None, time_stamps=None, calib_fun=None, calib_coeffs=None, senscorr_mask=None, polyorder=1, calib_id=None, camera=None)[source]

num_optargs_fun(fun)[source]: Return number of optimisation args of a function.

property senscorr_mask: Get current sensitivity correction mask (Img instance).

property calib_coeffs: List containing calibration coefficients for calib_fun.

property calib_fun: Mathematical function used for retrieval of calibration curve.

Note

The function can be defined on class initiation and may be updated using the setter method. If not explicitely specified, a polynomial is used with order polyorder.

property start: Start time of calibration data (datetime).

property stop: Stop time of calibration data (datetime).

property polyorder: Get current order of fit polynomial.

property cov: Get covariance matrix of calibration polynomial.

property y_offset: Y-axis offset of calib curve.

property cd_tseries: Pandas Series object of doas data.

property tau_tseries: Pandas Series object of tau data.

property tau_range

Range of tau values extended by 5%.

Returns:

2-element tuple, containing

float, tau_min: lower end of tau range
float, tau_max: upper end of tau range

Return type:

property cd_range: Range of DOAS cd values extended by 5%.

has_calib_data()[source]: Check if calibration data is available.

fit_calib_data(calib_fun=None, guess=None, polyorder=None, weighted=True, weights_how='abs', through_origin=False, param_bounds=None, normalise_cds=False, plot=False)[source]

Fit calibration polynomial to current data.

The calibration data is fitted using a least squares optimisation. Be careful with cusomised optimisation functions that are not linear in all their optimisation parameters (especially, with using input argument :arg:`normalise_cds`).

Parameters:

calib_fun (function, optional) – if specified, the current calibration function is updated
guess (list, optional) – initial guess for optimisation (is only considerd)
polyorder (int, optional) – if specified, the current polyorder is updated (only relevant for polynomial optimisation functions, i.e. if no custom calibration function has been provided)
weighted (bool) – performs weighted fit based on DOAS errors in cd_vec_err (if available), defaults to True
weights_how (str) – use “rel” if relative errors are supposed to be used (i.e. w=CD_sigma / CD) or “abs” if absolute error is supposed to be used (i.e. w=CD_sigma).
through_origin (bool) – only relevant for polynomial fits (i.e. if no custom fit function has been provided). If True, the polynomial fit is forced to cross the coordinate origin
param_bounds (tuple) – 2-element tuple containing two lists (or tuples) specifying lower (param_borders[0]) and upper (param_borders[1]) borders for the fit parameters. If unspecified (None), the borders will automatically be set to -/+ infinity
normalise_cds (bool) – if True, the CD vector is normalised by its exponential magnitude before applying the fit.
plot (bool) – If True, the calibration curve and the polynomial are plotted

Returns:

list containing optimised parameters

Return type:

save_as_fits(save_dir=None, save_name=None, overwrite_existing=True)[source]

Save calibration data as FITS file.

Save all relevant information in an HDU list as FITS. The first HDU (PrimaryHDU) contains the sensitivity correction mask (senscorr_mask) and the second HDU is of type BinTableHDU and contains the calibration data, which contains the following 4 columns in the specified order:

time_stamps (as strings, format: %Y%m%d%H%M%S%f)

tau_vec

cd_vec

cd_vec_err

Parameters:

save_dir (str) – save directory, if None, the current working directory is used
save_name (str) – filename of the FITS file (if None, use pyplis default naming)
overwrite_existing (bool) – if True, an existing calibration file with the same name will be overwritten

load_from_fits(file_path: str) → astropy.io.fits.HDUList | None[source]

Load calibration data from FITS file

Parameters:

file_path – Absolute or relative file path of the calibration data

Returns:

None if run from this class directly, else (i.e. child class with type != “base”) FITS HDUList object
that can be used to extract further information.

plot(add_label_str='', ax=None, **kwargs)[source]

Plot calibration data and fit result.

Parameters:

add_label_str (str) – additional string added to label of plots for legend
ax – matplotlib axes object, if None, a new one is created

plot_calib_fun(add_label_str='', shift_yoffset=False, ax=None, **kwargs)[source]

Plot calibration fit result.

Parameters:

add_label_str (str) – additional string added to label of plots for legend
shift_yoffset (bool) – if True, the data is plotted without y-offset
ax – matplotlib axes object, if None, a new one is created

err()[source]: Return standard deviation of fit residual.

calibrate(value)[source]

Apply calibration to input.

Parameters:: value – optical density (can be float, n-dimensional numpy array, Img, ImgStack)
Return type:: calibrated input

Cell calibration

Pyplis module containing features related to cell calibration.

class pyplis.cellcalib.CellSearchInfo(filter_id, add_id, y_max)[source]

Class for for storage cell search from automatic cell search engine.

Parameters:

filter_id (str) – string ID of filter / Image type
add_id (str) – additional identifier (e.g. “bg”, “cell1”)
y_max (float) – a reference intensity

__init__(filter_id, add_id, y_max)[source]

property start

Get time stamp of first detected image.

Returns:: First time stamp, i.e. start_acq[0]
Return type:: datetime
Raises:: IndexError – if start_acq is empty

property stop

Get time stamp of last detected image.

Returns:: Last time stamp, i.e. self.start_acq[-1]
Return type:: datetime
Raises:: IndexError – if start_acq is empty

property tot_num

Get total number of detected images.

Returns:: length of self.mean_vals
Return type:: int

from_img_list(img_list)[source]

Fill values using all images from a specific image list.

Note

Old beta version, not tested, currently not in use

Parameters:: img_list (ImgList) – image list from which pixel mean value time series is supposed to be determined

property mean_err

Return average std of mean value time series.

Returns:: Error of mean value
Return type:: float

property mid_point_val

Get mean value of middle image of the time series.

Returns:: Mean intensity of middle image
Return type:: float

point_ok(idx)[source]

Check data point at given index.

Checks if intensity value at given index is within acceptance intensity range with respect to the middle intensity value of the time series

Parameters:: idx (int) – index of datapoint
Returns:: True, if ok, False if not
Return type:: bool

create_image_list(camera)[source]

Create image list containing all valid cell images.

Creates a CellImgList which includes all detected data points that fulfill condition point_ok().

Note

If successful, the list is assigned to img_list

Parameters:: camera (Camera) – the camera used
Returns:: image list containing all (valid) cell images
Return type:: CellImgList

property offs

Get array containing offset values.

The offset values are determined from mean_vals` with respect to y_max.

Returns:: array containing offset values for each intensity in mean_vals
Return type:: ndarray

class pyplis.cellcalib.CellAutoSearchResults[source]

Helper class collecting results from auto-cell detection algorithm.

This object is included in CellCalibEngine object and will be filled with CellSearchInfo objects if the cell autodetection is used (find_cells())

Note

This class is normally not intended to be used directly

cell_info

Ordered dictionary containing dictionaries for all filter_ids for which cell search was performed (e.g. on, off). These dictionaries contain CellSearchInfo ordered based on the acq. time of the detected cell dip

Type:: OrderedDict

bg_info

Ordered dictionary containing CellSearchInfo objects that include detected background images for each filter (e.g. on off)

Type:: OrderedDict

rest_info

Ordered dictionary containing all images for each filter (e.g. on off) that could not be identified as Cell or BG image

Type:: OrderedDict

__init__()[source]

add_cell_search_result(filter_id, cell_info, bg_info, rest_info)[source]

Add a collection of CellSearchInfo objects.

Parameters:

filter_id (str) – image type ID (e.g. on, off)
cell_info (dictlike) – dictonary containing CellSearchInfo objects containing information about images belonging to one cell
bg_info (CellSearchInfo) – object containing information about detected background images for image type specified by filter_id
rest_info (CellSearchInfo) – object containing information about images that could not be assigned to a detected cell nor to the background images

class pyplis.cellcalib.CellCalibData(tau_vec=None, cd_vec=None, cd_vec_err=None, time_stamps=None, calib_fun=None, calib_coeffs=None, senscorr_mask=None, polyorder=1, calib_id=None, camera=None, pos_x_abs=None, pos_y_abs=None)[source]

Class representing cell calibration data.

This class inherits from the CalibData base class.

Parameters:

tau_vec (ndarray) – tau data vector for calibration data
cd_vec (ndarray) – DOAS-CD data vector for calibration data
cd_vec_err (ndarray) – Fit errors of DOAS-CDs
time_stamps (ndarray) – array with datetime objects containing time stamps (e.g. start acquisition) of calibration data
calib_fun (function) – optimisation function used for fitting of calibration data
calib_coeffs (list, optional) – optimisation parameters for calibration curve.
senscorr_mask (ndarray`or :obj:`Img, optional) – sensitivity correction mask that was normalised relative to the pixel position where the calibration data was retrieved (i.e. position of DOAS FOV in case of DOAS calibration data, or image pixel position, where cell calibration data was retrieved)
calib_id (str) – calibration ID (e.g. “aa”, “tau_on”, “tau_off”)
camera (Camera) – camera object (not necessarily required). A camera can be assigned in order to convert the FOV extend from pixel coordinates into decimal degrees
pos_x_abs (int) – x-position of image pixel for which the data was retrieved
pos_y_abs (int) – y-position of image pixel for which the data was retrieved

__init__(tau_vec=None, cd_vec=None, cd_vec_err=None, time_stamps=None, calib_fun=None, calib_coeffs=None, senscorr_mask=None, polyorder=1, calib_id=None, camera=None, pos_x_abs=None, pos_y_abs=None)[source]

load_from_fits(file_path)[source]

Load calibration data from FITS file.

Note

See methods of base class pyplis.calib_base.CalibData.save_as_fits() and pyplis.calib_base.CalibData.load_from_fits() for more details

file_pathstr: path of FITS file

class pyplis.cellcalib.CellCalibEngine(setup=None, init=True)[source]

Class for performing automatic cell calibration.

This class is designed to define datasets related to time windows, where cell calibration was performed, i.e. the camera pointing into a gas (and cloud) free area of the sky with a number of calibration cells are put in front of the lense consecutively (ideally, the cells should cover the whole FOV of the camera in order to be able to retrieve calibration polynomials for each image pixel individually). Individual time windows for each cell are extracted by analysing the time series of pixel mean intensities for all images that fall into the start / stop interval. Cells can be identified by dips of decreased intensities in the time series. The individual cells are then assigned automatically based on the depth of each dip (in the on band) and the column densities of the cells used (the latter need to be provided).

Is initialised as pyplis.Datasets.Dataset object, i.e. normal setup is like plume data using a MeasSetup object (make sure that cell_info_dict is set in the setup class).

Parameters:

setup (MeasSetup) – see Dataset for details
init (bool) – if True, the image lists are initiated and filled (if possible)

__init__(setup=None, init=True)[source]

property cell_lists_ready: Call check_all_lists`().

set_cell_images(img_paths, cell_gas_cd, cell_id, filter_id, img_import_method=None)[source]

Add cell images corresponding to one cell and image type.

Creates CellImgList containing input cell images and adds them calling add_cell_img_list()

Parameters:

img_paths (list) – list containing image file paths (can also be a single image path)
cell_gas_cd (float) – column amount of gas in cell
cell_id (str) – string identification of cell
filter_id (str) – filter ID for images (e.g. “on”, “off”)

set_bg_images(img_paths, filter_id)[source]

Set background images for a certain filter type.

Creates CellImgList containing input background images and adds them calling add_bg_img_list()

Parameters:

img_paths (list) – list containing image file paths of bg images (can also be a single image file path)
filter_id (str) – image type (e.g. “on”, “off”)

add_cell_img_list(lst)[source]

Add a cell image list for calibration.

Parameters:: lst (CellImgList) – if, valid, the list is added to cell_lists using it’s ID (lst.list_id) as first key and lst.cell_id as second, e.g. self.cell_lists["on"]["a53"]

add_bg_img_list(lst)[source]

Add an image list containing background images for calibration.

Parameters:: lst (CellImgList) – if valid input, the list is added to dictionary self.bg_lists using lst.list_id as key

det_bg_mean_pix_timeseries(filter_id)[source]

Determine (or get) pixel mean values of background image list.

Gets the average pixel intenisty (considering the whole image) for all images in specified background image list and stores it within a PixelMeanTimeSeries object. The latter is then stored in bg_tseries and can be used to interpolate background intensities for cell image time stamps (this might be important for large SZA measurements where the background radiance changes fastly, cf. prepare_tau_calib()).

Parameters:: filter_id (str) – ID of background image list (must be valid key of dict bg_lists
Returns:: time series object containing background mean intensities
Return type:: PixelMeanTimeSeries

find_cells(filter_id='on', threshold=0.1, accept_last_in_dip=False)[source]

Autodetection of cell images and bg images using mean value series.

This algorithm tries to separate individual cell images and background images by analysing the 1st derivative of the mean pixel intensity of each image in the time span specified in this object (self.start, self.stop).

The separation of the individual cell images is performed by identifying dips in the mean intensity evolution and assignment of all image files belonging to each dip.

Parameters:

filter_id (str) – filter ID (e.g. on, off, uses get_list() with filter_id as input)
threshold (float) – threshold in percent by which intensity decreases are identified
accept_last_in_dip (bool) – if True, also the last image in one of the Cell intensity dips is considered a valid cell image (by default, the first and the last images of a dip are not considered)

add_search_results()[source]

Add results from automatic cell detection to calibration.

This method analyses self.search_results for valid cell image lists (i.e. lists that contain images and have the gas column assigned)

set_bg_closest(cell_id=None)[source]

Set the current background image closest to one of the cells.

Parameters:: cell_id (str) – cell ID supposed to be used, if None, then the first cell list in cell_lists is used

find_and_assign_cells_all_filter_lists(threshold=0.1)[source]

High level function for automatic cell and BG image search.

This method basically calls the following functions:

find_cells() (for all filter IDs, e.g. on/off)

_assign_calib_specs()

add_search_results()

check_all_lists()

and sets flag cell_search_performed=True.

Parameters:: threshold (float) – percentage threshold for identification of regions of decreased intensity in time series

bg_img_available(filter_id)[source]

Check if a background image is available.

Parameters:: filter_id (str) – filter ID of image list (e.g. on / off)

check_image_list(lst)[source]

Check if image list contains files and has images ready (loaded).

Parameters:

lst (ImgList) – image list object

Raises:

IndexError – If list does not contain images
Exception – If images cannot be loaded in list (unexpected error) or if lst.gas_cd is not a float

check_all_lists()[source]

Check if all image lists are ready for analysis.

Returns:: True (if it makes it to the return statement)
Return type:: bool

check_cell_info_dict_autosearch(cell_info_dict)[source]

Check if dict including cell gas column info is right format.

Parameters:: cell_info_dict (dict) – keys: cell ids (e.g. “a57”), values: list of gas column density and uncertainty in cm-2, format: [value, error]
Raises:: Exception – If any of the specs in cell_info_dict is invalid

set_cell_info_dict_autosearch(cell_info_dict)[source]

Set attribute self._cell_info_auto_search (dictionary).

Parameters:: cell_info_dict (dict) – dictionary containing cell information

prep_tau_stacks(on_id='on', off_id='off', darkcorr=True, blurring=2)[source]

Prepare image stacks for on, off and AA calibration data.

Parameters:

on_id (str) – ID of onband filter
off_id (str) – ID of offband filter
darkcorr (bool) – Use dark corrected images
blurring (int) – sigma of Gaussian blurring kernel
pyrlevel (int) – pyramid level of calibration stack

prepare_calib_data(pos_x_abs=None, pos_y_abs=None, radius_abs=1, on_id='on', off_id='off', darkcorr=True, blurring=1, **kwargs)[source]

Prepare calib data for onband, offband and AA.

This function creates 3 CellCalibData objects for each OD type (on, off and from that, AA). If not differently specified using the input parameters pos_x_abs and pos_y_abs the corresponding cell optical densities are retrieved at the image center coordinate.

The 3 CellCalibData instances for each type (on, off, AA) can be accessed via the calib_data attribute of this class.

Parameters:

pos_x_abs (int, optional) – x-position for which the calibration data is retrieved
pos_y_abs (int, optional) – y-position for which the calibration data is retrieved
radius_abs (int) – radius specifying the disk size around pos_x_abs and pos_y_abs used to retrieve the cell-ODs
on_id (str) – ID of onband filter used to determine calib curve
off_id (str) – ID of offband filter used for calibration
darkcorr (bool) – perform dark correction before determining cell tau images
blurring (int) – apply gaussian blurring to cell tau images
pyrlevel (int) – downscale factor (Gauss pyramid)

get_sensitivity_corr_mask(calib_id='aa', pos_x_abs=None, pos_y_abs=None, radius_abs=1, cell_cd_closest=0, surface_fit_pyrlevel=2)[source]

Get sensitivity correction mask.

Prepares a sensitivity correction mask to correct for filter transmission shifts. These shifts result in increasing optical densities towards the image edges for a given gas column density.

The mask is determined for original image resolution, i.e. pyramid level 0 and for a specific cell optical density image (aa, tau_on, tau_off). The latter is normalised with respect to the input pixel position (e.g. center position of DOAS FOV or pixel position where cell calibration data was retrieved).

Plume AA (or tau_on, tau_off) images can then be corrected for sensitivity variations by division with the mask. If DOAS calibration is used, the calibration function can then be used for all image pixels. If only cell calibration is used, the mask is normalised with respect to the image center, the corresponding cell calibration polynomial should then be retrieved in the center coordinate which is the default calibration position when using creating calibration data if not explicitely specified. You may then calibrate a given aa image (aa_img) as follows with using a CellCalibData object (denoted with cellcalib):

mask = cellcalib.get_sensitivity_corr_mask()
aa_corr = aa_img.duplicate()
aa_corr.img = aa_img.img / mask
#this is retrieved in the image center if not other specified
gas_cd_img = cellcalib(aa_corr)
gas_cd_img.show()

Parameters:

calib_id (str) – the mask is determined from the corresponding calib data (e.g. “on”, “off”, “aa”)
pos_x_abs (int) – x-pixel position of normalisation mask, if None the image center position is used (which is also the default pixel used to retrieve the vector of calibration optical densities from the cell OD images)
pos_y_abs (int) – y-pixel position of normalisation mask, if None the image center position is used (which is also the default pixel used to retrieve the vector of calibration optical densities from the cell OD images)
radius_abs (int) – radius specifying the disk size around pos_x_abs and pos_y_abs used to normalise the mask (i.e. uses average OD of cell image in this OD)
filter_id (str) – mask is determined from the corresponding calib data (e.g. “on”, “off”, “aa”)
cell_cd_closest (float) – use the cell which is closest to the provided column density
surface_fit_pyrlevel (int) – additional downscaling factor for 2D polynomial surface fit

Raises:

ValueError – if the corresponding ImgStack is cropped, from which the cell OD image is supposed to be retrieved

Returns:

the sensitivity correction mask

Return type:

Note

This function was only tested for AA images and not for on / off cell tau images

get_list(list_id, cell_id=None)[source]

Expand functionality of this method from Dataset.

Parameters:

list_id (str) – filter ID of list (e.g. on, off). If parameter cell_id is None, then this function returns the initial Dataset list (containing all images, not the ones separated by cells / background).
cell_id (str) – if input is specified (type str) and valid (available cell img list), then the corresponding list is returned which only contains images from this cell. The string “bg” might be used to access the background image list of the filter specified with parameter list_id

Returns:

the actual list object

Return type:

ImgList

plot_cell_search_result(filter_id='on', for_app=False, include_tit=True, cell_cmap='Oranges', ax=None)[source]

High level plotting function for results from auto-cell search.

Parameters:

filter_id (str) – filter ID (e.g. “on”, “off”)
for_app (bool) – currently irrelevant (default is False)
include_tit (bool) – if True, include default title
cell_cmap (str) – string specifying matplotlib colormap used to plot cell time windows
ax – matplotlib axes object

Returns:

matplotlib axes object

Return type:

axes

plot_calib_curve(calib_id, **kwargs)[source]

Plot calibration curve.

Parameters:

filter_id (str) – image type ID (e.g. “aa”)
**kwargs – additional keyword arguments for plot passed to plot() of corresponding CellCalibData object

Returns:

matplotlib axes object

Return type:

axes

plot_all_calib_curves(ax=None, **kwargs)[source]

Plot all available calibration curves in a certain pixel region.

Parameters:

ax (axes) – matplotlib axes instance
**kwargs – additional keyword arguments passed to get_calibration_polynomial() of corresponding CellCalibData objects

Returns:

matplotlib axes object

Return type:

axes

DOAS calibration

Pyplis module for DOAS calibration including FOV search engines.

class pyplis.doascalib.DoasCalibData(tau_vec=None, cd_vec=None, cd_vec_err=None, time_stamps=None, calib_fun=None, calib_coeffs=None, senscorr_mask=None, polyorder=1, calib_id=None, camera=None, fov=None)[source]

Class containing DOAS calibration data.

Parameters:

tau_vec (ndarray) – tau data vector for calibration data
cd_vec (ndarray) – DOAS-CD data vector for calibration data
cd_vec_err (ndarray) – Fit errors of DOAS-CDs
time_stamps (ndarray) – array with datetime objects containing time stamps (e.g. start acquisition) of calibration data
calib_fun (function) – optimisation function used for fitting of calibration data
calib_coeffs (;obj:list, optional) – optimisation parameters for calibration curve.
senscorr_mask (ndarray`or :obj:`Img, optional) – sensitivity correction mask that was normalised relative to the pixel position where the calibration data was retrieved (i.e. position of DOAS FOV in case of DOAS calibration data, or image pixel position, where cell calibration data was retrieved)
calib_id (str) – calibration ID (e.g. “aa”, “tau_on”, “tau_off”)
camera (Camera) – camera object (not necessarily required). A camera can be assigned in order to convert the FOV extend from pixel coordinates into decimal degrees
fov (DoasFOV) – information about position and shape of the FOV of the DOAS within the camera images

__init__(tau_vec=None, cd_vec=None, cd_vec_err=None, time_stamps=None, calib_fun=None, calib_coeffs=None, senscorr_mask=None, polyorder=1, calib_id=None, camera=None, fov=None)[source]

save_as_fits(save_dir=None, save_name=None, overwrite_existing=True) → str[source]

Save calibration data as FITS file.

Parameters:

save_dir (str, optional) – Directory to save the FITS file. If None, the current working directory is used.
save_name (str, optional) – Filename of the FITS file. If None, pyplis default naming is used.
overwrite_existing (bool, optional) – If True, overwrite existing.

Returns:

Path to the saved FITS file.

load_from_fits(file_path)[source]

Load stack object (fits).

Parameters:: file_path (str) – Path to the FITS file.

plot_data_tseries_overlay(date_fmt=None, ax=None)[source]: Plot overlay of tau and DOAS time series.

class pyplis.doascalib.DoasFOV(camera=None)[source]

Class for storage of FOV information.

__init__(camera=None)[source]

property method: Return search method.

property pyrlevel: Return pyramide level at which FOV search was performed.

property cx_rel: Return center x coordinate of FOV (in relative coords).

property cy_rel: Return center x coordinate of FOV (in relative coords).

property radius_rel

Return radius of FOV (in relative coords).

Raises:: TypeError if method == “ifr”

property popt

Return super gauss optimisation parameters (in relative coords).

Raises:: TypeError if method == “pearson”

property x_abs

property y_abs

property sigma_x_abs

property sigma_y_abs

property pos_abs: Return center coordinates of FOV (in absolute detector coords).

pixel_extend(abs_coords=True)[source]

Return pixel extend of FOV on image.

Parameters:: abs_coords (bool) – return value in absolute or relative coordinates (considering pyrlevel and roi)

pixel_position_center(abs_coords=False)[source]

Return pixel position of center of FOV.

Parameters:

abs_coords (bool) – return position in absolute or relative coordinates (considering pyrlevel and roi)

Returns:

tuple, (cx, cy)

fov_mask_abs(img_shape_orig=(), cam_id='')[source]

Convert the FOV mask to absolute detector coordinates.

The shape of the FOV mask (and the represented pixel coordinates) depends on the image preparation settings of the ImgStack object which was used to identify the FOV.

Parameters:

img_shape_orig (tuple) – image shape of original image data (can be extracted from an unedited image)
cam_id (str) – string ID of pyplis default camera (e.g. “ecII”)

import_from_hdulist(hdu, first_idx=0)[source]

Import FOV information from FITS HDU list.

Parameters:

hdu (HDUList) – HDU list containing a list of HDUs created using prep_hdulist() starting at index :param:`first_idx` (e.g. first_idx==2 if the method save_as_fits() from the DoasCalibData class is used, since the first 2 indices are used for saving the acutal calibration data)
first_idx (int) – index specifying the first entry of the FOV info in the provided HDU list

prep_hdulist()[source]: Prepare and return HDUList object for saving as FITS.

save_as_fits(**kwargs)[source]

Save the fov as fits file.

Saves this object as DoasCalibData:

d = DoasCalibData(fov = self)
d.save_as_fits(**kwargs)

plot(ax=None)[source]: Draw the current FOV position into the current correlation img.

class pyplis.doascalib.DoasFOVEngine(img_stack: ImgStack = None, doas_series: DoasResults = None, method='pearson', **settings)[source]

Engine to perform DOAS FOV search.

__init__(img_stack: ImgStack = None, doas_series: DoasResults = None, method='pearson', **settings)[source]

property maxrad

maximum expected disk radius of FOV.

Note

this radius is considered independent of the current pyramid level of the image stack, hence, if it is set 20 and the pyramid level of the stack is 2, then, the FOV disk radius (in detector coords) may be 80.

Type:: For Pearson method

property ifrlbda

allow asymmetric 2d gauss fit.

Type:: For IFR method

property g2dasym

allow asymmetric 2d gauss fit.

Type:: For IFR method

property g2dsuper

use supergauss parametrisation.

Type:: For IFR method

property g2dcrop

crop gaussian FOV parametrisation at sigma.

Type:: For IFR method

property g2dtilt

allow supergauss-fit to be tilted.

Type:: For IFR method

property blur

Sigma of gaussian blurring filter applied to correlation image.

The filter is applied to the correlation image before finding the position of the maximum correlation. This is only relevant for method IFR, since this method parameterises the FOV by fitting a 2D Gaussian to the correlation image. Defaults to 4.

property mergeopt

Option for temporal merging of stack and DOAS vector.

Choose from average, nearest, interpolation

update_search_settings(**settings)[source]

Update current search settings.

Parameters:

**settings –

keyword args to be updated (only valid keys will be updated)

property doas_data_vec: Return DOAS CD vector (values of self.doas_series).

property method: Return current FOV search method.

perform_fov_search(**settings)[source]

High level method for automatic FOV search.

Uses the current settings (self._settings) to perform the following steps:

1. Call merge_data(): Time merging of stack and DOAS vector. This step is skipped if data was already merged within this engine, i.e. if self.data_merged == True

#. Call det_correlation_image(): Determination of correlation image using self.method (‘ifr’ or ‘pearson’)

#. Call get_fov_shape(): Identification of FOV shape / extend on image detector either using circular disk approach (if self.method == 'pearson') or 2D (super) Gauss fit (if ``self.method == ‘ifr’).

All relevant results are written into self.calib_data (which includes DoasFOV object)

run_fov_fine_search(img_list: BaseImgList, doas_series: DoasResults, extend_fac=3, **settings)[source]

Get FOV position in full resolution.

Note

1. Only works if FOV search (i.e. perform_fov_search()) was already performed. #. This method requires some time as it needs to recompute a cropped image stack in full resolution from the provided img_list. #. This method deletes the current image stack in this object. #. Uses the same search settings as set in this class (i.e. method, etc.)

Parameters:

img_list (BaseImgList) – image list used to calculate cropped stack
doas_series (DoasResults) – original DOAS time series (i.e. not merged in time with image data, needs to be provided since the one stored within this class is modified during the first FOV search)
extend_fac (int) – factor determining crop ROI based on the current pixel extend of the FOV

Returns:

new instance containing results from fine search

Return type:

DoasFOVEngine

merge_data(merge_type=None)[source]

Merge stack data and DOAS vector in time.

Wrapper for merge_with_time_series() of ImgStack

Parameters:: merge_type (str) – choose between ``average, interpolation,

nearest``

Note

Current data (i.e. self.img_stack and self.doas_series) will be overwritten if merging succeeds.

Parameters:: merge_type (str, optional,) – one of the available merge types, see mergeopt for valid options
Raises:: RuntimeError – if merging of data fails

det_correlation_image(search_type='pearson', **kwargs)[source]

Determine correlation image.

Determines correlation image either using IFR or Pearson method. Results are written into self.calib_data.fov (DoasFOV)

Parameters:: search_type (str) – updates current search type, available types ["pearson", "ifr"]

get_fov_shape()[source]

Find shape of FOV based on correlation image.

Search pixel coordinate of highest correlation in self.calib_data.fov.corr_img (using get_img_maximum()) and based on that finds FOV shape either using disk approach (if self.method == 'pearson') calling fov_radius_search() or using 2D Gauss fit (if self.method == 'ifr') calling fov_gauss_fit(). Results are written into self.calib_data.fov (DoasFOV object)

fov_radius_search(cx: int, cy: int) → Tuple[int, Series, ndarray, ndarray, ndarray][source]

Search the FOV disk radius around center coordinate.

The search varies the radius around the center coordinate and extracts image data time series from average values of all pixels falling into the current disk. These time series are correlated with spectrometer data to find the radius showing highest correlation.

Parameters:

cx – pixel x coordinate of center position
cy – pixel y coordinate of center position

Returns:

radius of FOV - Series: correlation curve (radius vs. correlation coeff) - ndarray: vector of optical densities within FOV - ndarray: vector of DOAS data - ndarray: mask of FOV (1 inside, 0 outside)

Return type:

int

Raises:

ValueError – if the length of the DOAS data vector does not match the number of images in the stack

convolve_stack_fov(fov_mask)[source]

Normalize fov image and convolve stack.

Returns:

stack time series vector within FOV

Emission rate retrieval

Pyplis module containing methods and classes for emission-rate retrievals.

class pyplis.fluxcalc.EmissionRateSettings(pcs_lines=None, velo_glob=nan, velo_glob_err=nan, bg_roi_abs=None, ref_check_lower_lim=None, ref_check_upper_lim=None, **settings)[source]

Class for management of settings for emission rate retrievals.

Parameters:

pcs_lines – LineOnImage object or list containing LineOnImage objects along which emission rates are retrieved.
velo_glob (float) – optional, global velocity estimate (e.g. retrieved from cross correlation analysis). Please note, that global velocities can also be assigned directly to LineOnImage objects (see prev. inp. param), hence, this input velocity is only used for lines, which do not have an explicit global velocity assigned. In any case, these velocities (whether assigned in LineOnImage`objects or here) are only used if ``self.velo_mode["glob"] is True`.
velo_glob_err (float) – optional, error on prev. parameter
bg_roi_abs (list) – background region of interest used for logging of retrieved CDs in an area out of the plume (can later be used for an assessment of the performance of the plume background retrieval for each image) since the CDs are expected to be zero.
ref_check_lower_lim (float) – lower required limit for CDs in bg_roi_abs area in case ref_check_mode is active. All images which show average CDs lower than this thresh within bg_roi_abs are disregarded for the analysis
ref_check_upper_lim (float) – upper required limit for CDs in bg_roi_abs area in case ref_check_mode is active. All images which show average CDs larger than this thresh within bg_roi_abs are disregarded for the analysis

__init__(pcs_lines=None, velo_glob=nan, velo_glob_err=nan, bg_roi_abs=None, ref_check_lower_lim=None, ref_check_upper_lim=None, **settings)[source]

property bg_roi_abs: Return current background reference ROI.

property ref_check_mode: Activate / deactivate reference area control mode.

property velo_mode_glob: Attribute velo_glob for velocity analysis retrieval.

property velo_mode_flow_raw: Attribute velo_glob for velocity analysis retrieval.

property velo_mode_flow_histo: Attribute for velocity analysis retrieval.

property velo_mode_flow_hybrid: Attribute for velocity analysis retrieval.

property velo_glob

Global velocity in m/s, assigned to this line.

Raises:: AttributeError – if current value is not of type float

property velo_glob_err: Error of global velocity in m/s, assigned to this line.

add_pcs_line(line)[source]

Add one analysis line to this list.

Parameters:: line (LineOnImage) – emission rate retrieval line

class pyplis.fluxcalc.EmissionRates(pcs_id, velo_mode='glob', settings=None, color='b')[source]

Class to store results from emission rate analysis.

__init__(pcs_id, velo_mode='glob', settings=None, color='b')[source]

property start: Acquisistion time of first image.

property stop: Start acqusition time of last image.

property start_acq: Array containing acquisition time stamps.

property phi: Array containing emission rates.

property phi_err: Array containing emission rate errors.

property velo_eff: Array containing effective plume velocities.

property velo_eff_err: Array containing effective plume velocitie errors.

property as_series: Emission rates as pandas Series.

property meta_header

Return string containing available meta information.

Returns:: string containing relevant meta information (e.g. for txt export)
Return type:: str

property default_save_name: Return default name for txt export.

mean()[source]: Mean of emission rate time series.

nanmean()[source]: Mean of emission rate time series excluding NaNs.

std()[source]: Mean of emission rate time series.

nanstd()[source]: Mean of emission rate time series excluding NaNs.

min()[source]: Minimum value of emission rate time series.

nanmin()[source]: Minimum value of emission rate time series excluding NaNs.

max()[source]: Maximum value of emission rate time series.

nanmax()[source]: Maximum value of emission rate time series excluding NaNs.

get_date_time_strings()[source]

Return string reprentations of date and start / stop times.

Returns:

3-element tuple containing

date string
start acq. time string
stop acq. time string

Return type:

to_dict()[source]

Write all data attributes into dictionary.

Keys of the dictionary are the private class names

Returns:: Dictionary containing results
Return type:: dict

to_pandas_dataframe()[source]

Convert object into pandas dataframe.

This can, for instance be used to store the data as csv (cf. from_pandas_dataframe())

from_pandas_dataframe(df)[source]

Import results from pandas DataFrame object.

Parameters:: df (DataFrame) – pandas dataframe containing emisison rate results
Returns:: this object
Return type:: EmissionRates

plot_velo_eff(yerr=True, label=None, ax=None, date_fmt=None, **kwargs)[source]

Plot emission rate time series.

Parameters:

yerr (bool) – Include uncertainties
label (str) – optional, string argument specifying label
ax – optional, matplotlib axes object
date_fmt (str) – optional, x label datetime formatting string, passed to DateFormatter (e.g. “%H:%M”)
**kwargs – additional keyword args passed to plot function of Series object

Returns:

matplotlib axes object

Return type:

axes

plot(yerr=True, label=None, ax=None, date_fmt=None, ymin=None, ymax=None, alpha_err=0.1, in_kg=True, **kwargs)[source]

Plot emission rate time series.

Parameters:

yerr (bool) – Include uncertainties
label (str) – optional, string argument specifying label
ax – optional, matplotlib axes object
date_fmt (str) – optional, x label datetime formatting string, passed to DateFormatter (e.g. “%H:%M”)
ymin (float, optional) – lower limit of y-axis
ymax (float, optional) – upper limit of y-axis
alpha_err (float) – transparency of uncertainty range
in_kg (bool) – if True, emission rates are plotted in units of kg / s
**kwargs – additional keyword args passed to plot call

Returns:

matplotlib axes object

Return type:

axes

save_txt(path=None)[source]: Save this object as text file.

load_txt(path)[source]

Load results from text file.

Parameters:: path (str) – valid file location
Returns:: loaded result data class
Return type:: EmissionRates

class pyplis.fluxcalc.EmissionRateRatio(*args, **kwargs)[source]

Time series ratio of two emission rates.

This class is new and still in Beta status

__init__(*args, **kwargs)[source]

property dphi: Return attr. phi, as this class represents ratios.

property dphi_err: Return for attr. phi_err, as this class represents ratios.

plot(yerr=False, label=None, ax=None, date_fmt=None, ymin=None, ymax=None, alpha_err=0.1, **kwargs)[source]

Plot emission rate time series.

Parameters:

yerr (bool) – Include uncertainties
label (str) – optional, string argument specifying label
ax – optional, matplotlib axes object
date_fmt (str) – optional, x label datetime formatting string, passed to DateFormatter (e.g. “%H:%M”)
ymin (float, optional) – lower limit of y-axis
ymax (float, optional) – upper limit of y-axis
alpha_err (float) – transparency of uncertainty range
in_kg (bool) – if True, emission rates are plotted in units of kg / s
**kwargs – additional keyword args passed to plot call

Returns:

matplotlib axes object

Return type:

axes

class pyplis.fluxcalc.EmissionRateAnalysis(imglist, **settings)[source]

Class to perform emission rate analysis.

The analysis is performed by looping over images in an image list which is in calib_mode, i.e. which loads images as gas CD images. Emission rates can be retrieved for an arbitrary amount of plume cross sections (defined by a list of LineOnImage objects which can be provided on init or added later). The image list needs to include a valid measurement geometry (MeasGeometry) object which is used to determine pixel to pixel distances (on a pixel column basis) and corresponding uncertainties.

Parameters:

imglist (ImgList) – onband image list prepared such, that at least aa_mode and calib_mode can be activated. If emission rate retrieval is supposed to be performed using optical flow, then also optflow_mode needs to work. Apart from setting these modes, no further changes are applied to the list (e.g. dark correction, blurring or choosing the pyramid level) and should therefore be set before. A warning is given, in case dark correction is not activated.
pcs_lines (list) – python list containing LineOnImage objects supposed to be used for retrieval of emission rates (can also be a LineOnImage object directly)
velo_glob (float) – global plume velocity in m/s (e.g. retrieved using cross correlation algorithm)
velo_glob_err (float) – uncertainty in global plume speed estimate
bg_roi (list) – region of interest specifying gas free area in the images. It is used to extract mean, max, min values from each of the calibrated images during the analysis as a quality check for the performance of the plume background retrieval or to detect disturbances in this region (e.g. due to clouds). If unspecified, the scale_rect of the plume background modelling class is used (i.e. self.imglist.bg_model.scale_rect).
**settings – analysis settings (passed to EmissionRateSettings)

Todo

1. Include light dilution correction - automatic correction for light dilution is currently not supported in this object. If you wish to perform light dilution, for now, please calculate dilution corrected on and offband images first (see example script ex11) and save them locally. The new set of images can then be used normally for the analysis by creating a Dataset object and an AA image list from that (see example scripts 1 and 4).

__init__(imglist, **settings)[source]

property imglist_optflow

Image list supposed to be used for optical flow retrieval.

Is required to have the same number of images than analysis list. If this list is not set explicitely, then the optical flow is calculated from the analysis list (default setting).

This feature was introduced, since it was empirically found, that images that are dilution corrected, often cause problems with the optical flow retrieval, due to the applied threshold

property pcs_lines: Return dict containing PCS retrieval lines assigned to settings class.

property velo_glob: Global velocity.

property velo_glob_err: Return error of current global velocity.

property flow_required: Check if current velocity mode settings require flow algo.

get_results(line_id=None, velo_mode=None)[source]

Return emission rate results (if available).

Parameters:

line_id (str) – ID of PCS line
velo_mode (str) – velocity retrieval mode (see also EmissionRateSettings)

Returns:

EmissionRateResults, class containing emission rate

results for specified line and velocity retrieval

Raises:

KeyError, if result for the input constellation cannot be

found

check_and_init_list()[source]: Check if image list is ready and include all relevant info.

get_pix_dist_info_all_lines()[source]

Retrieve pixel distances and uncertainty for all pcs lines.

Returns:

2-element tuple containing

dict, keys are line ids, vals are arrays with pixel dists
dict, keys are line ids, vals are distance uncertainties

Return type:

init_results()[source]

Reset results.

Returns:

2-element tuple containing

dict, keys are line ids, vals are empty result classes
dict, keys are line ids, vals are empty
LocalPlumeProperties objects

Return type:

check_pcs_plume_props()[source]

Check if plume displacement information is available for all PCS.

Tries to access LocalPlumeProperties objects in each of the assigned plume cross section retrieval lines (pcs_lines). If so and if a considerable datetime index overlap is given in the corresponding object (with datetime indices in imglist), then the object is interpolated onto the time stamps of the list and the corresponding displacement information is used (and not re-calculated) while performing emission rate retrieval when using velo_mode = flow_histo. If no significant overlap can be detected, the LocalPlumeProperties object in the corresponding LineOnImage object is initiated and filled while performing the analysis.

calc_emission_rate(**kwargs)[source]: Old name of run_retrieval().

run_retrieval(start_index=0, stop_index=None, check_list=True)[source]

Calculate emission rates of image list.

Performs emission rate analysis for each line in self.pcs_lines and for all plume velocity retrievals activated in self.settings.velo_modes. The results for each line and velocity mode are stored within EmissionRates objects which are saved in self.results[line_id][velo_mode], e.g.:

res = self.results["bla"]["flow_histo"]

would yield emission rate results for line with ID “bla” using histogram based plume speed analysis.

The results can also be easily accessed using get_results().

Parameters:

start_index (int) – index of first considered image in self.imglist, defaults to 0
stop_index (int) – index of last considered image in self.imglist, defaults to last image in list
check_list (bool) – if True, check_and_init_list() is called before analysis

Returns:

2-element tuple containing

dict, keys are line ids, vals are corresponding results
dict, keys are line ids, vals are
LocalPlumeProperties objects

Return type:

add_pcs_line(line)[source]

Add one analysis line to this list.

Parameters:: line (LineOnImage) – the line object

plot_pcs_lines(ax=None, **kwargs)[source]: Plot all current PCS lines onto current list image.

plot_bg_roi_rect(ax=None, to_pyrlevel=0)[source]: Plot rectangular area used for background check.

plot_bg_roi_vals(ax=None, date_fmt=None, labelsize=None, **kwargs)[source]

Plot emission rate time series.

Parameters:

ax – optional, matplotlib axes object
date_fmt (str) – optional, x label datetime formatting string, passed to DateFormatter (e.g. “%H:%M”)
**kwargs – additional keyword args passed to plot function of Series object

Returns:

ax, matplotlib axes object

Return type:

axes

pyplis.fluxcalc.det_emission_rate(cds, velo, pix_dists, cds_err=None, velo_err=None, pix_dists_err=None, mmol=64.0638)[source]

Determine emission rate.

Parameters:

cds – column density in units cm-2 (float or ndarray)
velo – effective plume velocity in units of m/s (float or ndarray) Effective means, that it is with respect to the direction of the normal vector of the plume cross section used (e.g. by performing a scalar product of 2D velocity vectors with normal vector of the PCS)
pix_dists – pixel to pixel distances in units of m (float or ndarray)

Signal dilution correction

Pyplis module for image based correction of the signal dilution effect.

class pyplis.dilutioncorr.DilutionCorrFitResult(ext: float, i0: float, dists: ndarray, rads: ndarray, input_img: Img, fit_result: OptimizeResult)[source]

Class to bundle the results of the dilution fit.

ext: float: Extinction coefficient.

i0: float: Retrieved undiluted intensity of terrain

dists: ndarray: Distances to topographic features used as input to the fit.

rads: ndarray: Radiances of topographic features used as input to the fit

input_img: Img: Input image used to retrieve the measured radiances.

fit_result: OptimizeResult: Result of the fit.

__init__(ext: float, i0: float, dists: ndarray, rads: ndarray, input_img: Img, fit_result: OptimizeResult) → None

class pyplis.dilutioncorr.DilutionCorr(lines=None, meas_geometry=None, **settings)[source]

Class for management of dilution correction.

The class provides functionality to retrieve topographic distances from meas geometry, to manage lines in the image used for the retrieval, to perform the actual dilution fit (i.e. retrieval of atmospheric scattering coefficients) and to apply the dilution correction.

This class does not store any results related to individual images.

Parameters:

lines (list) – optional, list containing LineOnImage objects used to retrieve terrain distances for the dilution fit
meas_geometry (MeasGeometry) – optional, measurement geometry (required for terrain distance retrieval)
**settings –
settings for terrain distance retrieval:
- skip_pix: specify pixel step on line for which topo intersections are searched
- min_slope_angle: minimum slope of topography in order to be considered for topo distance retrieval
- topo_res_m: interpolation resolution applied to ElevationProfile objects used to find intersections of pixel viewing direction with topography

__init__(lines=None, meas_geometry=None, **settings)[source]

property line_ids: Get IDs of all LineOnImage objects for distance retrieval.

update_settings(**settings)[source]: Update settings dict for topo distance retrieval.

add_retrieval_line(line)[source]: Add one topography retrieval line.

add_retrieval_point(pos_x_abs, pos_y_abs, dist=None)[source]

Add a distinct pixel with known distance to image.

Parameters:

pos_x_abs (int) – x-pixel position of point in image in absolute coordinate (i.e. pyramid level 0 and not cropped)
pos_y_abs (int) – y-pixel position of point in image in absolute coordinate (i.e. pyramid level 0 and not cropped)
dist (float, optional) – distance to feature in image in m. If None (default), the distance will be estimated

det_topo_dists_all_lines(**settings)[source]

Estimate distances to topo distances to all assigned lines.

Parameters:: **settings – keyword args passed to update search settings (settings) and passed to get_topo_distances_line() in MeasGeometry

det_topo_dists_line(line_id, **settings)[source]

Estimate distances to pixels on current lines.

Retrieves distances to all LineOnImage objects in self.lines using self.meas_geometry (i.e. camera position and viewing direction).

Parameters:

line_id (str) – ID of line
**settings – additional key word args used to update search settings (passed to get_topo_distances_line() in MeasGeometry)

Returns:

retrieved distances

Return type:

array

get_radiances(img, line_ids=None)[source]

Get radiances for dilution fit along terrain lines.

The data is only extracted along specified input lines. The terrain distance retrieval det_topo_dists_lines_line() must have been performed for that.

Parameters:

img (Img) – vignetting corrected plume image from which the radiances are extracted
line_ids (list) – if desired, the data can also be accessed for specified line ids, which have to be provided in a list. If empty (default), all lines assigned to this class are considered

fit(img: Img, rad_ambient: float, i0_guess: float | None = None, i0_min: float = 0.0, i0_max: float | None = None, ext_guess: float = 0.0001, ext_min: float = 0.0, ext_max: float = 0.001, line_ids=None) → DilutionCorrFitResult[source]

Perform dilution correction fit to retrieve extinction coefficient.

Uses dilution_corr_fit() of optimisation which is a bounded least square fit based on the following model function

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

Parameters:

img (Img) – vignetting corrected image for radiance extraction
rad_ambient (float) – ambient intensity ( $I_A$ in model)
i0_guess (float) – optional: guess value for initial intensity of topographic features, i.e. the reflected radiation before entering scattering medium ( $I_0$ in model, if None, then it is set 5% of the ambient intensity rad_ambient)
i0_min (float) – optional: minimum initial intensity of topographic features
i0_max (float) – optional: maximum initial intensity of topographic features
ext_guess (float) – guess value for atm. extinction coefficient ( $\epsilon$ in model)
ext_min (float) – minimum value for atm. extinction coefficient
ext_max (float) – maximum value for atm. extinction coefficient
line_ids (list) – if desired, the data can also be accessed for specified line ids, which have to be provided in a list. If empty (default), all lines are considered
plot (bool) – if True, the result is plotted
**kwargs – additional keyword args passed to plotting function (e.g. to pass an axes object)

Returns:

4-element tuple containing

retrieved extinction coefficient
retrieved initial intensity
fit result object
axes instance or None (dependent on :param:`plot`)

Return type:

apply_dilution_fit(img, rad_ambient, i0_guess=None, i0_min=0, i0_max=None, ext_guess=0.0001, ext_min=0, ext_max=0.001, line_ids=None, plot=True, **kwargs)[source]

Perform dilution correction fit to retrieve extinction coefficient.

Note

DEPRECATED: please use method fit() instead.

Uses dilution_corr_fit() of optimisation which is a bounded least square fit based on the following model function

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

Parameters:

img (Img) – vignetting corrected image for radiance extraction
rad_ambient (float) – ambient intensity ( $I_A$ in model)
i0_guess (float) – optional: guess value for initial intensity of topographic features, i.e. the reflected radiation before entering scattering medium ( $I_0$ in model, if None, then it is set 5% of the ambient intensity rad_ambient)
i0_min (float) – optional: minimum initial intensity of topographic features
i0_max (float) – optional: maximum initial intensity of topographic features
ext_guess (float) – guess value for atm. extinction coefficient ( $\epsilon$ in model)
ext_min (float) – minimum value for atm. extinction coefficient
ext_max (float) – maximum value for atm. extinction coefficient
line_ids (list) – if desired, the data can also be accessed for specified line ids, which have to be provided in a list. If empty (default), all lines are considered
plot (bool) – if True, the result is plotted
**kwargs – additional keyword args passed to plotting function (e.g. to pass an axes object)

Returns:

4-element tuple containing

retrieved extinction coefficient
retrieved initial intensity
fit result object
axes instance or None (dependent on :param:`plot`)

Return type:

get_ext_coeffs_imglist(lst, roi_ambient=None, apply_median=5, **kwargs)[source]

Apply dilution fit to all images in an ImgList.

Parameters:

lst (ImgList) – image list for which the coefficients are supposed to be retrieved
roi_ambient (list) – region of interest used to estimage ambient intensity, if None (default), usd scale_rect of PlumeBackgroundModel of the input list
apply_median (int) – if > 0, then a median filter of provided width is applied to the result time series (ext. coeffs and initial intensities)
**kwargs – additional keyword args passed to dilution fit method apply_dilution_fit().

Returns:

pandas data frame containing time series of retrieved extinction coefficients and initial intensities as well as the ambient intensities used, access keys are:

coeffs: retrieved extinction coefficients

i0: retrieved initial intensities

ia: retrieved ambient intensities

Return type:

DataFrame

correct_img(plume_img, ext, plume_bg_img, plume_dists, plume_pix_mask)[source]

Perform dilution correction for a plume image.

Note

See correct_img() for description

Returns:: dilution corrected image
Return type:: Img

plot_fit_result(dists, rads, rad_ambient, i0, ext, ax=None)[source]: Plot result of dilution fit.

get_extinction_coeffs_imglist(imglist, ambient_roi_abs, darkcorr=True, line_ids=None, **fit_settings)[source]: Retrieve extinction coefficients for all imags in list.

Note

Alpha version: not yet tested

plot_distances_3d(draw_cam=1, draw_source=1, draw_plume=0, draw_fov=0, cmap_topo='Oranges', contour_color='#708090', contour_antialiased=True, contour_lw=0.2, axis_off=True, line_ids=None, **kwargs)[source]

Draw 3D map of scene including geopoints of distance retrievals.

Parameters:

draw_cam (bool) – insert camera position into map
draw_source (bool) – insert source position into map
draw_plume (bool) – insert plume vector into map
draw_fov (bool) – insert camera FOV (az range) into map
cmap_topo (str) – string specifying colormap for topography surface plot defaults to “Oranges”
contour_color (str) – string specifying color of contour lines colors of topo contour lines (default: “#708090”)
contour_antialiased (bool) – apply antialiasing to surface plot of topography, defaults to False
contour_lw – width of drawn contour lines, defaults to 0.5, use 0 if you do not want contour lines inserted
axis_off (bool) – if True, then the rendering of axes is excluded
line_ids (list) – if desired, the data can also be accessed for specified line ids, which have to be provided in a list. If empty (default), all topo lines are drawn

Returns:

plotted map instance (is of type Basemap)

Return type:

Map

pyplis.dilutioncorr.correct_img(plume_img, ext, plume_bg_img, plume_dists, plume_pix_mask)[source]

Perform dilution correction for a plume image.

Corresponds to Eq. 4 in in Campion et al., 2015.

Parameters:

plume_img (Img) – vignetting corrected plume image
ext (float) – atmospheric extinction coefficient
plume_bg_img (Img) – vignetting corrected plume background image (can be, for instance, retrieved using plumebackground)
plume_dists (array, Img, float) – plume distance(s) in m. If input is numpy array or Img then, it must have the same shape as :param:`plume_img`
plume_pix_mask (ndarray) – mask specifying plume pixels (only those are corrected), can also be type Img

Returns:

dilution corrected image

Return type:

pyplis.dilutioncorr.get_topo_dists_lines(lines, geom, img=None, skip_pix=5, topo_res_m=5.0, min_slope_angle=5.0, plot=False, line_color='lime')[source]

pyplis.dilutioncorr.perform_dilution_correction(plume_img, ext, plume_bg_img, plume_dist_img, plume_pix_mask)[source]

pyplis.dilutioncorr.get_extinction_coeff(rads, dists, rad_ambient, plot=True, **kwargs)[source]

Perform dilution correction fit to retrieve extinction coefficient.

Parameters:

rads (ndarray) – radiances retrieved for topographic features
dists (ndarray) – distances corresponding to rads
rad_ambient – ambient sky intensity
plot (bool) – if True, the result is plotted
**kwargs –
additional keyword arguments for fit settings (passed to dilution_corr_fit() of module optimisation)

Low level utils

Pyplis module containing low level utilitiy methods and classes.

pyplis.utils.identify_camera_from_filename(filepath)[source]

Identify camera based on image filepath convention.

Parameters:: filepath (str) – valid image file path
Returns:: ID of Camera that matches best
Return type:: str
Raises:: IOError – Exception is raised if no match can be found

class pyplis.utils.LineOnImage(x0=0, y0=0, x1=1, y1=1, normal_orientation='right', roi_abs_def=[0, 0, 9999, 9999], pyrlevel_def=0, line_id='', color='lime', linestyle='-')[source]

Class representing a line on an image

Main purpose is data extraction along this line on a discrete image grid. This is done using spline interpolation.

Parameters:

x0 (int) – start x coordinate
y0 (int) – start y coordinate
x1 (int) – stop x coordinate
y1 (int) – stop y coordinate
normal_orientation (str) – orientation of normal vector, choose from left or right (left means in negative x direction for a vertical line)
roi_abs_def (list) – ROI specifying image sub coordinate system in which the line coordinates are defined (is used to convert to other image shape settings)
pyrlevel_def (int) – pyramid level of image for which start /stop coordinates are defined
line_id (str) – string for identification (optional)

Note

The input coordinates correspond to relative image coordinates with respect to the input ROI (roi_def) and pyramid level (pyrlevel_def)

__init__(x0=0, y0=0, x1=1, y1=1, normal_orientation='right', roi_abs_def=[0, 0, 9999, 9999], pyrlevel_def=0, line_id='', color='lime', linestyle='-')[source]

property start: x, y coordinates of start point ([x0, y0]).

property stop: x, y coordinates of stop point ([x1, y1]).

property center_pix: Return coordinate of center pixel.

property normal_orientation: Get / set value for orientation of normal vector.

property line_frame: ROI framing the line (in line coordinate system).

property line_frame_abs: ROI framing the line (in absolute coordinate system).

property roi_def: ROI in which line is defined (at current pyrlevel).

property roi_abs_def: Return current ROI (in absolute detector coordinates).

property pyrlevel: Pyramid level at which line coords are defined.

property roi_abs: Return current ROI (in absolute detector coordinates).

property pyrlevel_def: Pyramid level at which line coords are defined.

property coords: Return coordinates as ROI list.

property rect_roi_rot: Rectangle specifying coordinates of ROI aligned with line normal.

property velo_glob

Global velocity in m/s, assigned to this line.

Raises:: AttributeError – if current value is not of type float

property velo_glob_err

Error of global velocity in m/s, assigned to this line.

Raises:: AttributeError – if current value is not of type float

property plume_props: LocalPlumeProperties object assigned to this list.

dist_other(other)[source]

Determine the distance to another line.

Note

1. The offset is applied in relative coordinates, i.e. it does not consider the pyramide level or ROI.

The two lines need to be parallel

Parameters:: other (LineOnImage) – the line to which the distance is retrieved
Returns:: retrieved distance in pixel coordinates
Return type:: float
Raises:: ValueError – if the two lines are not parallel

offset(pixel_num=20, line_id=None)[source]

Return a new line shifted within normal direction.

Note

The offset is applied in relative coordinates, i.e. it does not
consider the pyramide level or ROI
The determined required displacement (dx, dy) is converted into
integers

Parameters:

pixel_num (int) – shift length in pixels
line_id (str) – string ID of new line, if None (default) it is set automatically

Returns:

shifted line

Return type:

LineOnImage

convert(to_pyrlevel=0, to_roi_abs=[0, 0, 9999, 9999])[source]: Convert to other image preparation settings.

check_coordinates()[source]

Check line coordinates.

Checks if coordinates are in the right order and exchanges start / stop points if not

Raises:: ValueError – if any of the current coordinates is smaller than zero

in_image(img_array)[source]

Check if this line is within the coordinates of an image array.

Parameters:: img_array (array) – image data
Returns:: True if point is in image, False if not
Return type:: bool

point_in_image(x, y, img_array)[source]

Check if a given coordinate is within image.

Parameters:

x (int) – x coordinate of point
y (int) – y coordinate of point
img_array (array) – image data

Returns:

True if point is in image, False if not

Return type:

bool

get_roi_abs_coords(img_array, add_left=5, add_right=5, add_bottom=5, add_top=5)[source]

Get a rectangular ROI covering this line.

Parameters:

add_left (int) – expand range to left of line (in pix)
add_right (int) – expand range to right of line (in pix)
add_bottom (int) – expand range to bottom of line (in pix)
add_top (int) – expand range to top of line (in pix)

Returns:

ROI around this line

Return type:

integrate_profile(input_img, pix_step_length=None)[source]

Integrate the line profile on input image.

Parameters:: input_img (Img) – input image data for

set_rect_roi_rot(depth=None)[source]

Get rectangle for rotated ROI based on current tilting.

Note

This function also changes the current roi_abs attribute

Parameters:: depth (int) – depth of rotated ROI (in normal direction of line) in pixels
Returns:: rectangle coordinates
Return type:: list

get_rotated_roi_mask(shape)[source]

Return pixel access mask for rotated ROI.

Parameters:: shape (tuple) – shape of image for which the mask is supposed to be used
Returns:: bool array that can be used to access pixels within the ROI
Return type:: array

check_roi_borders(roi, img_array)[source]

Check if all points of ROI are within image borders.

Parameters:

roi (list) – ROI rectangle [x0,y0,x1,y1]
img_array (array) – exemplary image data for which the ROI is checked

Returns:

roi within image coordinates (unchanged, if input is ok, else image borders)

Return type:

prepare_coords()[source]: Prepare the analysis mesh.

Note

The number of analysis points on this object correponds to the physical length of this line in pixel coordinates.

length()[source]: Determine the length in pixel coordinates.

get_line_profile(array, order=1, **kwargs)[source]

Retrieve the line profile along pixels in input array.

Parameters:

array (array) – 2D data array (e.g. image data). Color images are converted into gray scale using cv2.cvtColor().
order (int) – order of spline interpolation used to retrieve the values along input coordinates (passed to map_coordinates())
**kwargs – additional keword args passed to interpolation method map_coordinates()

Returns:

profile

Return type:

array

plot_line_on_grid(img_arr=None, ax=None, include_normal=False, include_roi_rot=False, include_roi=False, annotate_normal=False, **kwargs)[source]

Draw this line on the image.

Parameters:

img_arr (ndarray) – if specified, the array is plotted using imshow() and onto that axes, the line is drawn
ax – matplotlib axes object. Is created if unspecified. Leave :param:`img_arr` empty if you want the line to be drawn onto an already existing image (plotted in ax)
include_normal (bool) – if True, the line normal vector is drawn
include_roi_rot (bool) – if True, a line-orientation specific ROI is drawn
include_roi (bool) – if True, an ROI is drawn which spans the i,j range of the image covered by the line
annotate_normal (bool) – if True, the normal vector is annotated (only if include_normal is set True)
**kwargs – additional keyword arguments for plotting of line (please use following keys: marker for marker style, mec for marker edge color, c for line color and ls for line style)

Returns:

matplotlib axes instance

Return type:

Axes

plot_rotated_roi(color=None, ax=None)[source]

Plot current rotated ROI into axes.

Parameters:

color – optional, color information. If None (default) then the current line color is used
ax (Axes, optional) – matplotlib axes object, if None, a figure with one subplot will be created

Returns:

axes instance

Return type:

Axes

plot_line_profile(img_arr, ax=None)[source]: Plot the line profile.

plot(img_arr)[source]

Create two subplots showing line on image and corresponding profile.

Parameters:: img_arr (array) – the image data
Returns:: figure containing the supblots
Return type:: Figure

property norm: Return length of line in pixels.

det_normal_vecs()[source]: Get both normal vectors.

property normal_vector: Get normal vector corresponding to current orientation setting.

property complex_normal: Return current normal vector as complex number.

property normal_theta

Return orientation of normal vector in degrees.

The angles correspond to:

0 => to the top (neg. y direction)

90 => to the right (pos. x direction)

180 => to the bottom (pos. y direction)

270 => to the left (neg. x direction)

to_list()[source]: Return line coordinates as 4-list.

to_dict()[source]: Write relevant parameters to dictionary.

from_dict(settings_dict)[source]

Load line parameters from dictionary.

Parameters:: settings_dict (dict) – dictionary containing line parameters (cf. to_dict())

property orientation_info: Return string about orientation of line and normal.

class pyplis.utils.Filter(id=None, type='on', acronym='default', meas_type_acro=None, center_wavelength=nan)[source]

Object representing an interference filter.

A low level helper class to store information of interference filters.

__init__(id=None, type='on', acronym='default', meas_type_acro=None, center_wavelength=nan)[source]

Initialize of object.

Parameters:

("on") (str type) – string identification of this object for working environment
("on") – Type of object (choose from “on” and “off”)
("") (str meas_type_acro) – acronym for identification in filename
("") – acronym for meastype identification in filename
(nan) (str center_wavelength) – center transmission wavelength of filter

to_list()[source]: Return filter info as list.

set_trans_curve(data, wavelengths=None)[source]

Assign transmission curve to this filter.

Parameters:

data (ndarray) – transmission data
wavelengths (ndarray) – corresponding wavelength array

Returns:

pandas.Series object

Note

Also accepts pandas.Series as input using input param data and leaving wavelength empty, in this case, the Series index is assumed to be the wavelenght data

print_specs()[source]: Print __str__.

class pyplis.utils.DarkOffsetInfo(id='dark', type='dark', acronym='', meas_type_acro=None, read_gain=0)[source]

Base class for storage of dark offset information.

Similar to Filter. This object can be used to store relevant information of different types of dark and offset images. The attribute “read_gain” is set 0 by default. For some camera types (e.g. Hamamatsu c8484 16c as used in the ECII SO2 camera), the signal can be enhancened with an electronic read_gain (measured in dB) on read. This can be helpful in low light conditions. However, it significantly increases the noise in the images and therefore also the dark image signal.

__init__(id='dark', type='dark', acronym='', meas_type_acro=None, read_gain=0)[source]

Initialize object.

Parameters:

id (str) – string identification of this object for working environment (default: “dark”)
type (str) – Type of object (e.g. dark or offset, default: “dark”)
acronym (str) – acronym for identification in filename
meas_type_acro (str) – acronym for meastype identification in filename
read_gain (str) – string specifying read_gain mode of this object (use 0 or 1, default is 0)

to_list()[source]: Return parameters as list.

Further processing classes

Pyplis module contains the following processing classes and methods.

ImgStack: Object for storage of 3D image data

#. PixelMeanTimeSeries: storage and post analysis of timeseries of average pixel intensities

class pyplis.processing.ImgStack(height=0, width=0, img_num=0, dtype=<class 'numpy.float32'>, stack_id=None, img_prep=None, camera=None, **stack_data)[source]

Image stack object.

The images are stacked into a 3D numpy array, note, that for large datasets this may cause MemoryErrors. This object is for instance used to perform a DOAS field of view search (see also doascalib).

It provides basic image processing functionality, for instance changing the pyramid level, time merging with other time series data (e.g. DOAS CD time series vector).

The most important attributes (data objects) are:

1. self.stack: 3D numpy array containing stacked images. The first axis corresponds to the time axis, allowing for easy image access, e.g. self.stack[10] would yield the 11th image in the time series.

2. self.start_acq: 1D array containing acquisition time stamps (datetime objects)

3. self.texps: 1D array conaining exposure times in s for each image

4. self.add_data: 1D array which can be used to store additional data for each image (e.g. DOAS CD vector)

Todo

Include optical flow routine for emission rate retrieval

Parameters:

height (int) – height of images to be stacked
width (int) – width of images to be stacked
num (int) – number of images to be stacked
dtype –

numerical data type (e.g. uint8, makes the necessary space smaller,
default: float32)
stack_id (str) – string ID of this object (“”)
img_prep (dict) – additional information about the preparation state of the images (e.g. roi, gauss pyramid level, dark corrected?, blurred?)
**stack_data – can be used to pass stack data directly

__init__(height=0, width=0, img_num=0, dtype=<class 'numpy.float32'>, stack_id=None, img_prep=None, camera=None, **stack_data)[source]

init_stack_array(height=0, width=0, img_num=0)[source]

Initialize the actual stack data array.

Note

All current data stored in stack, start_acq, texps, add_data will be deleted.

Parameters:

height (int) – height of images to be stacked
width (int) – width of images to be stacked
num (int) – number of images to be stacked

property last_index: Return last index.

property start: Return start time stamp of first image.

property stop: Return start time stamp of first image.

property time_stamps: Acq. time stamps of all images.

property pyrlevel: Gauss pyramid level of images in stack.

property camera: Camera object assigned to stack.

property num_of_imgs: Depth of stack.

check_index(idx=0)[source]

insert_img(pos, img_arr, start_acq=datetime.datetime(1900, 1, 1, 0, 0), texp=0.0, add_data=0.0)[source]

Insert an image into the stack at provided index.

Parameters:

pos (int) – Insert position of img in stack
img_arr (array) – image data (must have same dimension than self.stack.shape[:2], can also be of type Img)
start_acq (datetime) – acquisition time stamp of image, defaults to datetime(1900, 1, 1)
texp (float) – exposure time of image (in units of s), defaults to 0.0
add_data – arbitrary additional data appended to list add_data

add_img(img_arr, start_acq=datetime.datetime(1900, 1, 1, 0, 0), texp=0.0, add_data=0.0)[source]

Add image at current index position.

The image is inserted at the current index position current_index which is increased by 1 afterwards. If the latter exceeds the dimension of the actual stack data array stack, the stack shape will be extended by 1.

Parameters:

img_arr (array) – image data (must have same dimension than self.stack.shape[:2])
start_acq (datetime) – acquisition time stamp of image, defaults to datetime(1900, 1, 1)
texp (float) – exposure time of image (in units of s), defaults to 0.0
add_data – arbitrary additional data appended to list add_data

make_circular_access_mask(cx, cy, radius)[source]

Create a circular mask for stack.

Parameters:

cx (int) – x position of centre
cy (nint) – y position of centre
radius (int) – radius

Returns:

circular mask (use e.g. like img[mask] which will return a 1D vector containing all pixel values of img that fall into the mask)

Return type:

array

set_stack_data(stack, start_acq=None, texps=None)[source]

Set the current data based on input.

Parameters:

stack (array) – 3D numpy array containing the image stack data
start_acq (array, optional) – array containing acquisition time stamps
texps (obj:array, optional) – array containing exposure times

get_data()[source]

Get stack data (containing of stack, acq. and exp. times).

Returns:

3-element tuple containing

array: stack data
array: acq. time stamps
array: exposure times

Return type:

apply_mask(mask)[source]

Convolves the stack data with a input mask along time axis.

Parameter

maskarray: 2D bool mask for image pixel access

returns:

3-element tuple containing

array: 3D numpy array containing convolved stack data
array: acq. time stamps
array: exposure times

rtype:

tuple

get_time_series(pos_x=None, pos_y=None, radius=1, mask=None)[source]

Get time series in a ROI.

Retrieve time series at a given pixel position in stack coordinates in a circular pixel neighbourhood.

Parameters:

pos_x (int) – x position of center pixel on detector
pos_y (int) – y position of center pixel on detector
radius (float) – radius of pixel disk on detector (centered around pos_x, pos_y, default: 1)
mask (array) – mask for image pixel access, default is None, if the mask is specified and valid (i.e. same shape than images in stack) then the other three input parameter are ignored

Returns:

2-element tuple containing

Series: time series data
array: pixel access mask used to convolve stack images

Return type:

merge_with_time_series(time_series, method='average', **kwargs)[source]

High level wrapper for data merging.

Choose from either of three methods to perform an index merging based on time stamps of stack and of other time series data (provided on input).

Parameters:

time_series (Series) – time series data supposed to be merged with stack data
method (str) –
merge method, currently available methods are:
- average: determine new stack containing images averaged based on start / stop time stamps of each datapoint in input time_series (requires corresponding data to be available in input, i.e. time_series must be of type DoasResults of pydoas library).
- nearest: perform merging based on nearest datapoint per image
- interpolation: perform cross interpolation onto unified time index array from stack and time series data
**kwargs – additional keyword args specifying additional merge settings (e.g. itp_type=quadratic in case method=interpolation is used)

Returns:

2-element tuple containing

ImgStack: new stack containing merged data
Series: merged time series data

Return type:

crop_other_tseries(time_series: DoasResults) → DoasResults[source]: Crops other time series object based on start / stop time stamps.

total_time_period_in_seconds()[source]: Return start time stamp of first image.

get_nearest_indices(tstamps_other)[source]

Find indices of time stamps nearest to img acq. time stamps.

Parameters:: tstamps_other – datetime, or datetime array of other time series for which closest index / indices are searched

has_data()[source]: Return bool.

sum(*args, **kwargs)[source]

Sum over all pixels of stack.

Parameters:

*args – non-keyword arguments passed to sum() of numpy array
**kwargs – keyword arguments passed to sum() of numpy array

Returns:

result of summation operation

Return type:

mean(*args, **kwargs)[source]

Apply numpy.mean function to stack data.

Parameters:

*args –
non keyword arguments passed to numpy.mean() applied to stack data
**kwargs –
keyword arguments passed to numpy.mean() applied to stack data

std(*args, **kwargs)[source]

Apply numpy.std function to stack data.

Parameters:

*args –
non keyword arguments passed to numpy.std() applied to stack data
**kwargs –
keyword arguments passed to numpy.std() applied to stack data

property shape: Return stack shape.

property ndim: Return stack dimension.

show_img(index=0)[source]

Show image at input index.

Parameters:: index (int) – index of image in stack

pyr_down(steps=0)[source]

Reduce the stack image size using gaussian pyramid.

Parameters:: steps (int) – steps down in the pyramide
Returns:: new, downscaled image stack object
Return type:: ImgStack

pyr_up(steps)[source]

Increasing the image size using gaussian pyramide.

Parameters:: steps (int) – steps down in the pyramide

Algorithm used: cv2.pyrUp()

to_pyrlevel(final_state=0)[source]: Down / upscale image to a given pyramide level.

duplicate()[source]: Return deepcopy of this object.

load_stack_fits(file_path)[source]

Load stack object (fits).

Note

FITS stores in Big-endian and needs to be converted into little-endian (see this issue). We follow the suggested fix and use:

byteswap().newbyteorder()

on any loaded data array.

Parameters:: file_path (str) – file path of stack

save_as_fits(save_dir, save_name=None, overwrite_existing=True) → str[source]

Save stack as FITS file.

Parameters:

save_dir (str) – directory to save the FITS file
save_name (str) – name of the FITS file (optional)
overwrite_existing (bool) – whether to overwrite existing files (default: True)

Returns:

output path

pyplis.processing.find_registration_shift_optflow(on_img, off_img, roi_abs=[0, 0, 9999, 9999], **flow_settings)[source]

Search average shift between two images using optical flow.

Computes optical flow between two input images and determines the registration shift based on peaks in two histograms of the orientation angle distribution and vector magnitued distribution of the retrieved flow field. The histogram analysis may be reduced to a certain ROI in the images.

The default settings used here correspond to the settings suggested by Peters et al., Use of motion estimation algorithms for improved flux measurements using SO2 cameras, JVGR, 2015.

Parameters:

on_img (Img) – onband image containing (preferably fixed) objects in the scene that can be tracked
off_img (Img) – corresponding offband image (ideally recorded at the same time)
roi_abs (list) – if specified, the optical flow histogram parameters are retrieved from the flow field within this ROI (else, the whole image is used)
**flow_settings – additional keyword args specifying the optical flow computation and post analysis settings (see pyplis.plumespeed.FarnebackSettings for details)

Returns:

2-element tuple containing

float: shift in x-direction
float: shift in y-direction

Return type:

class pyplis.processing.PixelMeanTimeSeries(data, start_acq, std=None, texps=None, roi_abs=None, img_prep=None, **kwargs)[source]

A time series of mean pixel values.

This class implements a pandas.Series object with extended functionality representing time series data of pixel mean values in a certain image region.

Note

This object is only used to store results of a mean series analysis in a certain ROI, it does not include any algorithms for actually calculating the series

poly_model = None

__init__(data, start_acq, std=None, texps=None, roi_abs=None, img_prep=None, **kwargs)[source]

Initialize pixel mean time series.

Parameters:

data (ndarray) – data array (is passed into pandas Series init -> self.values)
start_acq (ndarray) – array containing acquisition time stamps (is passed into pandas Series init -> self.index)
std (ndarray) – array containing standard deviations
texps (ndarray) – array containing exposure times
roi_abs (list) – image area from which data was extracted, list of shape: [x0, y0, x1, y1]
img_prep (dict) – dictionary containing information about image preparation settings (e.g. blurring, etc..) or other important information which may need to be stored
**kwargs –
additional keyword parameters which are passed to the initiation of the pandas.Series object

texps = None

std = None

img_prep = {}

roi_abs = None

property start

property stop

get_data_normalised(texp=None)[source]

Normalise the mean value to a given exposure time.

Parameters:: (None) (float texp) – the exposure time to which all deviating times will be normalised. If None, the values will be normalised to the largest available exposure time
Returns:: A new :class:`PixelMeanTimeSeries`instance with normalised data

fit_polynomial(order=2)[source]

Fit polynomial to data series.

Parameters:

order (int) – order of polynomial

Returns:

poly1d, the fitted polynomial

includes_timestamp(time_stamp, ext_border_secs=0.0)[source]

Check if input time stamp is included in this dataset.

Parameters:

time_stamp (datetime) – the time stamp to be checked
ext_border_secs (float) – extend start / stop range (default 0 s)

Returns:

bool, True / False (timestamp is within interval)

get_poly_vals(time_stamps, ext_border_secs=0.0)[source]

Get value of polynomial at input time stamp.

Parameters:: time_stamp (datetime) – poly input value

estimate_noise_amplitude(sigma_gauss=1, median_size=3, plot=0)[source]

Estimate the amplitude of the noise in the data.

Steps:

Determines high frequency variations by applying binomial
filter (sigma = 3) to data and subtract this from data, resulting in a residual

Median filtering of residual signal to get rid of narrow peaks
(i.e. where the original data shows abrupt changes)

subtract both signals and determine std

..note:

Beta version: no guarantee it works for all cases

plot(include_tit=True, date_fmt=None, **kwargs)[source]

Plot time series.

Parameters:

include_tit (bool) – Include a title
date_fmt (str) – Date / time formatting string for x labels, passed to DateFormatter instance (optional)
**kwargs – Additional keyword arguments passed to pandas Series plot method

Returns:

matplotlib axes instance

Return type:

axes

Fitting / Optimisation algorithms

Module containing optimisation routines.

pyplis.optimisation.dilution_corr_fit(rads: ndarray, dists: ndarray, rad_ambient: float, i0_guess: float | None = None, i0_min: float = 0.0, i0_max: float | None = None, ext_guess: float = 0.0001, ext_min: float = 0.0, ext_max: float = 0.001) → ndarray[source]

Retrieve ambient atmospheric extinction coefficients

The retrieval is done based on the methodology introduced by Campion et al., 2015 (https://doi.org/10.1016/j.jvolgeores.2015.01.004)

The extinction coefficients are retrieved by fitting the suggested model to a set of measured intensities of dark terrain features in the images, which are located different distances within the scene.

Parameters:

rads – vector containing measured radiances of terrain features
dists – vector containing corresponding dictances to the camera
rad_ambient – ambient intensity
i0_guess – guess value for initial intensity of topographic features i.e. the reflected radiation before entering scattering medium (if None, then it is set 5% of the ambient intensity rad_ambient)
i0_min – minimum initial intensity of topographic features
i0_max – maximum initial intensity of topographic features
ext_guess – guess value for atm. extinction coefficient
ext_min – minimum value for atm. extinction coefficient
ext_max – maximum value for atm. extinction coefficient

Returns:

pyplis.optimisation.gauss_fit_2d(img_arr, cx, cy, g2d_asym=True, g2d_super_gauss=True, g2d_crop=True, g2d_tilt=False)[source]

Apply 2D gauss fit to input image at its maximum pixel coordinate.

Parameters:

corr_img (array) – correlation image
cx (float) – x-position of peak in image (used for initial guess)
cy (float) – y-position of peak in image (used for initial guess)
g2d_asym (bool) – allow for assymetric shape (sigmax != sigmay), True
g2d_super_gauss (bool) – allow for supergauss fit, True
g2d_crop (bool) – if True, set outside (1/e amplitude) datapoints = 0, True
g2d_tilt (bool) – allow gauss to be tilted with respect to x/y axis

Returns:

3-element tuple containing

array (popt): optimised multi-gauss parameters
2d array (pcov): estimated covariance of popt
2d array: correlation image

Return type:

pyplis.optimisation.gauss_fit(data, idx=None, has_offset=False, plot=False)[source]

Fit Gaussian function to data.

Parameters:

data (array) – data array
idx (array, optional) – indices of data (e.g. angles)
has_offset (bool) – if True, the fitted Gauss is allowed to have a constant offset

Returns:

optimised parameters of gauss

Return type:

array

class pyplis.optimisation.MultiGaussFit(data=None, index=None, noise_amp=None, noise_amp_thresh_fac=2.0, sigma_smooth=3, sigma_tol_overlaps=3, max_num_gaussians=20, max_iter=None, auto_bounds=True, do_fit=True)[source]

Environment to fit an unkown number of Gaussians to noisy 1D (x,y) data.

It was initally desinged and developed for histogram data and aims to find a solution based on a minimum of required superimposed Gaussians to describe the distribution. Therefore, the fit is performed in a controlled way (i.e. allowed Gaussians are required to be within certain parameter bounds, details below) starting with a noise analysis (if noise level is not provided on class initialisation). Based on the noise level, and the x-range of the data, the boundaries for accepted gauss parameters are set. These are:

self.gauss_bounds["amp"][0] = 2*self.noise_amp
self.gauss_bounds["amp"][1] = (self.y_range - self.offset) * 1.5
self.gauss_bounds["mu"][0] = self.index[0]
self.gauss_bounds["mu"][1] = self.index[-1]
self.gauss_bounds["sigma"][0] = self.x_resolution/2.
self.gauss_bounds["sigma"][1] = self.x_range/2.

i.e. the amplitude of each of the superimposed Gaussians must be positive and larger then 2 times the noise amplitude. The max allowed amplitude is set 1.5 times the min / max difference of the data. The mean of each Gaussian must be within the index range of the data and the standard deviation must at least be half the x resolution (the smallest allowed peak must be at least have a of FWHM = 1 index) and the max FHWM must not exceed the covered x-range. The fit boundaries can also be set manually using set_gauss_bounds() but this might have a strong impact on the quality of the result.

Parameters:

data (array) – data array
index (array, otional) – x-coordinates
noise_amp (float, optional,) – amplitude of noise in the signal. Defines the minimum required amplitude for fitted Gaussians (you don’t want to fit all the noise peaks). If None, it will be estimated automatically on data import using estimate_noise_amp()
noise_amp_thresh_fac (float) – factor multiplied with noise_amp in order to determine the minimum amplitude threshold required for detecting additional peaks in residual (see find_additional_peaks())
sigma_smooth (int) – width of Gaussian kernel to determine smoothed analysis signal (is used to determine data baseline offset)
sigma_tol_overlaps (int) – sigma range considered to find overlapping Gauss functions (after fit was applied). This is, for instance used in analyse_fit_result() in order to find the main peak parameters
max_num_gaussians (int) – max number of superimposed, defaults to 20 Gaussians for data
max_iter (int) – max number of iterations for optimisation, if None (default), use max_num_gaussians + 1
auto_bounds (bool) – if True, bounds will be set automatically from data ranges whenever data is updated, defaults to True
do_fit (bool) – if True and input data available & ok, then run_optimisation() will be called on initialisation, defaults to True

__init__(data=None, index=None, noise_amp=None, noise_amp_thresh_fac=2.0, sigma_smooth=3, sigma_tol_overlaps=3, max_num_gaussians=20, max_iter=None, auto_bounds=True, do_fit=True)[source]

property residual: Get and return residual.

property data_grad: Gradient of analysis signal.

property data_grad_smooth: Smoothed gradient of analysis signal.

property data_smooth: Smooth data using Gaussian kernel of width self.sigma_smooth.

property min_amp: Minimum required amplitude to idenitify significant peaks.

init_results()[source]: Initialize all result parameters.

set_data(data, index=None)[source]

Set x and y data.

Parameters:

data (array) – data array which is fitted
index (:array) – optional, x index array of data, if None, the array index of data is used

init_data()[source]: Initialize the input data and set constraints for Gaussians.

set_gauss_bounds(amp_range=None, mu_range=None, sigma_range=None)[source]

Manually set boundaries for gauss parameters.

Parameters:

amp_range (array) – accepted amplitude range, defaults to [0, inf]
mu_range (array) – accepted mu range, defaults to [-inf, inf]
sigma_range (array) – accepted range of standard deveiations, defaults to [-inf, inf]

init_gauss_bounds_auto()[source]: Set parameter bounds for individual Gaussians.

estimate_main_peak_params()[source]: Get rough estimate and position of main peak.

find_additional_peaks()[source]

Search for significant peaks in the current residual.

Returns:: list containing additional peak parameters (for optimisation), or empty list if no additional peaks can be found
Return type:: list

estimate_peak_width(dat, idx)[source]

Estimate width of a peak at given index.

The peak width is estimated by finding the closest datapoint smaller than 0.5 the amplitude of data at index position

Parameters:

dat (array) – data (with baseline zero)
idx (int) – index position of peak

Returns:

Estimated peak width in index units

Return type:

int

prepare_fit_boundaries(guess)[source]

Prepare the boundaries tuple.

For details see used least squares solver)

Prepare fit boundary tuple for a multi-gauss parameter array supposed to be optimised (e.g. for two Gaussians this could look like params=[300, 10, 2, 150, 15, 1] using the boundaries specified in self.gauss_bounds.

Note

If any of the parameters in params is out of the acceptance borders specified in self.gauss_bounds, the corresponding parameters will be updated to the corresponding boundary value.

Parameters:

params (list) – list of gauss parameters (e.g. self.params)

Returns:

2-element tuple, containing

list: new parameter list (only those matching boundaries)
tuple: corresponding lower and upper boundaries

Return type:

do_fit(x, y, guess)[source]

Perform a least squares minimisation.

Perform least squares optimisiation for initial set of parameters and input data (includes determination of fit boundary array for all initial peak guesses of input array).

Parameters:

x (array) – x-argument for model function (index of data)
y (array) – y-argument for input function (data)
guess (list) – initial guess of fit parameters

Returns:

True, if optimisation was successful, False if not

Return type:

bool

opt_iter(add_params=None)[source]

Search additional peaks in residual and apply fit.

Extends current optimisation parameters by additional peaks (either provided on input or automatically searched in residual) and performs multi gauss fit.

Parameter

add_paramslist: list containing additional gauss parameters which are supposed to be added to self.params before the fit is applied

returns:

False: Optimisation failed
True: Optimisation was successful

rtype:

bool

run_optimisation()[source]: Run optimisation.

result_ok()[source]

Compare current peak to peak residual (ppr) with noise amplitude.

Returns bool:: 1 if 2*self.noise_amp > ppr, else 0

find_overlaps(sigma_tol=None)[source]

Find overlapping Gaussians for current optimisation params.

Loops over all current Gaussians (self.gaussians) and for each of them, finds all which fall into $3\\sigma$ range.

Parameters:

sigma_tol (float, optional) – sigma tolerance level for finding overlapping Gaussians, if None, use sigma_tol_overlaps.

Returns:

2-element tuple containing

list, contains all Gaussians overlapping with Gaussian (within
sigma tolerance range defined by sigma_tol) at index k in list returned by gaussians().
list, integral values of each of the overlapping sub regions

Return type:

analyse_fit_result(sigma_tol_overlaps=None)[source]

Analyse result of optimisation.

Find main peak (can be overlap of single Gaussians) and potential other peaks.

Parameters:

sigma_tol (float, optional) – sigma tolerance level for finding overlapping Gaussians, if None, use sigma_tol_overlaps.

Returns:

4-element tuple containing

float: center position ( $\\mu$ ) of predominant peak
float: corresponding standard deviation
float: integral value of predominant peak
list: additional Gaussians (from fit result) that are
not lying within specified tolerance interval of main peak

Return type:

normalise_params(params=None)[source]: Get normalised distribution of Gaussians.

gaussians()[source]: Get list containing fitted parameters for each Gaussian.

integrate_gauss(amp, mu, sigma, start=-inf, stop=inf)[source]

Return integral value of one Gaussian.

Parameters:

amp (float) – amplitude of Gaussian
mu (float) – mean of Gaussian
sigma (float) – standard deviation
start – left integral border, defaults to $-\infty$
stop – right integral border, defaults to $\infty$

integrate_all_gaussians(params: list[float] | None = None) → ndarray[source]

Determine the integral values of all parameterised Gaussians.

Parameters:: params – parameters of all gaussians, if None, use self.params
Returns:: array containing the integral values for each of the parameterised Gaussians.

det_moment(index: ndarray, data: ndarray, center: int, n: int) → float[source]

Determine n-th moment of distribution.

This method calculates the n-th moment of a distribution. The n-th moment is defined as the expected value of the n-th power of the deviation from the center (mean) of the distribution.

It can be a good indicator of the shape of the distribution, such as skewness or kurtosis and in particular, the 1st and 2nd moments can be used to determine the mean and variance of the distribution.

Parameters:

index – x coordinates of the data points.
data – y values of the distribution.
center – the center (mean) of the distribution.
n – the order of the moment to be calculated (e.g., 1 for mean, 2 for variance).

Returns:

the value of the n-th moment of the distribution.

apply_binomial_filter(data: ndarray | None = None, sigma: int = 1) → ndarray[source]

Return filtered data using 1D gauss filter.

Parameters:

data – data to be smoothed, if None, use self.data
sigma – width of smoothing kernel, defaults to 1

Returns:

smoothed data

first_derivative(data: ndarray | None = None) → ndarray[source]

Determine and return first derivative of data.

The derivative is determined using the numpy method gradient()

Parameters:: data – data for which the gradient is to be determined, if None, use self.data
Returns:: array containing the gradient of the data

estimate_noise_amp(sigma_gauss: int = 3, sigma_tol: int = 3, cut_out_width: int | None = None) → Tuple[float, ndarray, ndarray][source]

Estimate the noise amplitude of the current data.

Parameters:

sigma_gauss (int) – width of smoothing kernel applied to data in order to determine analysis signal
sigma_tol (int) – factor by which noise signal standard deviation is multiplied in order to estimate noise amplitude
cut_out_width (Optional[int]) – specifyies the width of index neighbourhood around narrow peaks which is to be disregarded for statistics of noise amplitude. Such narrow peaks can remain in the analysis signal. If None, it is set 3 times the width of the smoothing kernel used to determine the analysis signal (that is input param sigma_gauss x 3).

Returns:

3-element tuple containing

float: the analysis signal
array: mask specifying indices used to determine the ampl.
array: inital index array

Return type:

max()[source]: Return max value and x position of current parameters (not of data).

property num_of_gaussians

Get the current number of Gaussians, which is the length.

Returns:

float, len(self.params) // 3

property max_amp: Get the max amplitude of the current fit results.

property y_range: Range of y values.

property x_range: Range of x values.

property x_resolution: Return resolution of x data array.

get_sub_intervals_bool_array(bool_arr)[source]: Get all subintervals of the input bool array.

Note

Currently not in use, but might be helpful at any later stage

get_residual(params=None, mask=None)[source]

Get the current residual.

Parameters:

params (list) – Multi gauss parameters, if None, use self.params
mask (logical) – use only certain indices

get_peak_to_peak_residual(params=None)[source]

Return peak to peak difference of fit residual.

Parameters:: params (list) – mutligauss optimisation parameters, if default (None), use self.params

cut_sigma_range(x, y, params, n_sigma=4)[source]

Cut out a N x sigma environment around Gaussian from data.

Parameters:

x (array) – x-data array
y (array) – y-data array
params (list) – Gaussian fit parameters [ampl, mu, sigma]
n_sigma (int) – N (e.g. 3 => 3* sigma environment will be cutted)

check_peak_bounds(params)[source]

Check if gauss params fulfill current boundary conditions.

Parameters:: params – parameters of a single gauss [amp, mu, sigma]

get_all_gaussians_within_sigma_range(mu, sigma, sigma_tol=None)[source]

Find all current Gaussians within sigma range of a Gaussian.

Parameters:

mu (float) – mean (x pos) of considered Gaussian
sigma (float) – corresponding standard deviation
sigma_tol (float, optional) – sigma tolerance factor for finding overlaps, if None, use sigma_tol_overlaps

Returns:

list containing parameter lists [amp, mu, sigma] for all Gaussians of the current fit result having their mu values within the specified sigma interval of the input Gaussian

Return type:

get_all_gaussians_out_of_sigma_range(mu, sigma, sigma_tol=None)[source]

Find all current Gaussians out of sigma range of a Gaussian.

Parameters:

mu (float) – mean (x pos) of considered Gaussian
sigma (float) – corresponding standard deviation
sigma_tol (float, optional) – sigma tolerance factor for finding overlaps, if None, use sigma_tol_overlaps

Returns:

list containing parameter lists [amp, mu, sigma] for all Gaussians of the current fit result having their mu values within the specified sigma interval of the input Gaussian

Return type:

plot_signal_details()[source]

Plot signal and derivatives both in original and smoothed version.

Returns:: axes of two subplots
Return type:: array

plot_data(ax=None, sub_min=False)[source]

Plot the input data.

Parameters:

ax – matplotlib axes object (default = None)
sub_min (bool) – if true, self.offset will be subtracted from data, (default = False)

get_value(x: float) → float[source]

Get value of multi gauss at x position.

Parameters:: x – x position at which the value is to be determined
Returns:: value of multi gauss at x position
Return type:: float

plot_multi_gaussian(x=None, params=None, ax=None, color=None, lw=2, **kwargs)[source]

Plot multi gauss.

Parameters:

x (array) – x data array, if None, use self.index (default = None)
params (list) – multi gauss parameter list if None, use self.params (default = None)
ax (axes) – matplotlib axes object (default = None)
**kwargs –
additional keyword args passed to matplotlib plot method

plot_gaussian(x, params, ax=None, **kwargs)[source]

Plot gaussian.

Parameters:

x (array) – x data array
params (list) – single gauss parameter list
ax (axes) – matplotlib axes object (default = None)
**kwargs –
additional keyword args passed to matplotlib plot method

plot_result(add_single_gaussians: bool = False, figsize: Tuple[int, int] | None = None)[source]

Plot the current fit result.

Parameters:

add_single_gaussians (bool) – if True, plot all individual Gaussians in addition to the multi Gaussian fit result (default = False)
figsize (tuple) – size of figure to be created (default = (16, 10))
analyse_fit_result (bool) – if True, analyse the fit result and display main peak position and width in plot title

print_gauss(ind)[source]

Print gauss string.

Parameters:: ind (int) – index of gauss in self.params

gauss_str(g)[source]

Return string representation of a Gaussian.

Parameters:: g (list) – gauss parameter list [amp, mu, sigma]

info()[source]: Print string representation.

property has_data: Return True, if data available, else False.

has_results()[source]: Check if fit results are available.

class pyplis.optimisation.PolySurfaceFit(data_arr, mask=None, polyorder=3, pyrlevel=4, do_fit=1)[source]

Fit a 2D polynomial to data (e.g. a blue sky background image).

This class can be used to fit 2D polynomials to image data. It includes specifying pixels supposed to be used for the fit which have to be provided using a mask. The fit can be performed at arbitrary Gauss pyramid levels which can dramatically increase the performance.

Note

The fit result image can be accessed via the attribute model

Parameters:

data_arr (array) – image data to be fitted (NxM matrix)
mask (array) – mask specifying pixels considered for the fit (if None, then all pixels of the image data are considered
polyorder (int) – order of polynomial for fit (default=3)
pyrlevel (int) – level of Gauss pyramid at which the fit is performed (relative to Gauss pyramid level of input data)
do_fit (bool) – if True, and if input data is valid, then the fit is performed on intialisation of the class

__init__(data_arr, mask=None, polyorder=3, pyrlevel=4, do_fit=1)[source]

set_data(data_arr, mask=None)[source]

Set the data array (must be dimension 2).

Create self.mask for array shape which can be used to exclude picxel areas from the image

Parameters:

data_arr (array) – image data (can also be Img)
mask (array) – boolean mask specifying pixels considered for fit, if None, all pixels are considered

Returns:

True if data is valid, False if not

Return type:

bool

activate_auto_update(val=1)[source]

Activate or deactivate auto update mode.

If active, the fit is reapplied each time some input parameter is changed

Parameters:: val (bool) – new value for auto_update

change_pyrlevel(newlevel)[source]: Change the level in the Gaussian pyramide where the fit is applied.

change_polyorder(new_order)[source]

Change the order of the polynomial which is fitted.

Sets new poly order and re-applies fit in case auto_update == True

Parameters:: new_order (int) – new order of poly fit

exclude_pix_range_rect(x0, x1, y0, y1)[source]

Add a rectangular pixel area which will be excluded from the fit.

Parameters:

x0 (int) – start x coordinate (original image resolution)
x1 (int) – stop x coordinate (original image resolution)
y0 (int) – start y coordinate (original image resolution)
y1 (int) – stop y coordinate (original image resolution)

exclude_pix_range_circ(x0, y0, r)[source]

Add a circular pixel area which will be excluded from the fit.

Parameters:

x0 (int) – centre x coordinate (original image resolution)
y0 (int) – centre y coordinate (original image resolution)
r (int) – radius in pixel coordinates (original image resolution)

pyr_down(arr, steps)[source]

Reduce the image size using Gaussian pyramide.

Parameters:: steps (int) – steps down in the pyramide

Algorithm used: cv2.pyrDown()

pyr_up(arr, steps)[source]

Increase the image size using Gaussian pyramide.

Parameters:: steps (int) – steps down in the pyramide

Algorithm used: cv2.pyrUp()

make_weights_mask()[source]: Make a mask for pixel fit weights based on values in self.mask.

do_fit()[source]: Apply the fit to the data and write results.

get_residual()[source]: Get the current residual image array.

plot_result()[source]

Plot the fit result.

Plots the results, the original data and the residual in two versions (2 different intensity ranges)

Mathematical model functions

Pyplis module containing mathematical model functions.

pyplis.model_functions.cfun_kern2015(x, a0, a1)[source]

pyplis.model_functions.cfun_kern2015_offs(x, a0, a1, a2)[source]

class pyplis.model_functions.CalibFuns[source]

Class containing functions for fit of calibration curve.

__init__()[source]

available_poly_orders(through_origin=False)[source]

Return the available polynomial orders.

Parameter

through_originbool: polys without offset

returns:: list containing available polyorders
rtype:: list

print_poly_info()[source]: Print information about available polynomials.

print_custom_funs_info()[source]: Print information about available curtom calib functions.

get_custom_fun(key='kern2015')[source]

Return an available custom calibration function.

Parameters:: key (str) – access key of custom function (call print_custom_funs_info() for info about available functions)
Return type:: the function object

get_poly(order=1, through_origin=False)[source]

Get a polynomial of certain order.

Parameters:

order (int) – order of polynomial (choose from 1-3)
through_origin (bool) – if True, the polynomial will have no offset term

Returns:

the polynomial function object (callable)

Return type:

function

pyplis.model_functions.dilutioncorr_model(dist, rad_ambient, i0, ext)[source]

Model function for light dilution correction.

This model is based on the findings of Campion et al., 2015.

Parameters:

dist (float) – distance of dark (black) object in m
rad_ambient (float) – intensity of ambient atmosphere at position of dark object
i0 (float) – initial intensity of dark object before it enters the scattering medium. It is determined from the illumination intensity and the albedo of the dark object.
atm_ext (float) – atmospheric scattering extincion coefficient $\epsilon$ (in Campion et al., 2015 denoted with $\sigma$ ).

pyplis.model_functions.gaussian_no_offset(x, ampl, mu, sigma)[source]

1D gauss with baseline zero.

Parameters:

x (float) – x position of evaluation
ampl (float) – Amplitude of gaussian
mu (float) – center poistion
sigma (float) – standard deviation

Returns float:

value at position x

pyplis.model_functions.gaussian(x, ampl, mu, sigma, offset)[source]

1D gauss with arbitrary baseline.

Parameters:

x (float) – x position of evaluation
ampl (float) – Amplitude of gaussian
mu (float) – center poistion
sigma (float) – standard deviation
offset (float) – baseline of gaussian

Returns float:

value at position x

pyplis.model_functions.multi_gaussian_no_offset(x, *params)[source]

Superimposed 1D gauss functions with baseline zero.

Parameters:

x (array) – x array used for evaluation
*params (list) –
List of length L = 3xN were N corresponds to the number of gaussians e.g.:
```
[100,10,3,50,15,6]
```
would correspond to 2 gaussians with the following characteristics:
1. Peak amplitude: 100, Mu: 10, sigma: 3
2. Peak amplitude: 50, Mu: 15, sigma: 6

pyplis.model_functions.multi_gaussian_same_offset(x, offset, *params)[source]

Superimposed 1D gauss functions with baseline (offset).

See multi_gaussian_no_offset() for instructions

pyplis.model_functions.supergauss_2d(position, amplitude, xm, ym, sigma, asym, shape, offset)[source]

2D super gaussian without tilt.

Parameters:

position (tuple) – position (x, y) of Gauss
amplitude (float) – amplitude of peak
xm (float) – x position of maximum
ym (float) – y position of maximum
asym (float) – assymetry in y direction (1 is circle, smaller means dillated in y direction)
shape (float) – super gaussian shape parameter (1 is gaussian)
offset (float) – base level of gaussian

pyplis.model_functions.supergauss_2d_tilt(position, amplitude, xm, ym, sigma, asym, shape, offset, theta)[source]

2D super gaussian without tilt.

Parameters:

position (tuple) – position (x, y) of Gauss
amplitude (float) – amplitude of peak
xm (float) – x position of maximum
ym (float) – y position of maximum
asym (float) – assymetry in y direction (1 is circle, smaller means dillated in y direction)
shape (float) – super gaussian shape parameter (2 is gaussian)
offset (float) – base level of gaussian
theta (float) – tilt angle (rad) of super gaussian

I/O routines

Module containing all sorts of I/O-routines (e.g. test data access).

pyplis.inout.data_search_dirs()[source]

Get basic search directories for package data files.

Data files are searched for in ~/my_pyplis, ./data and, if set, in the PYPLIS_DATADIR environment variable.

pyplis.inout.zip_example_scripts(repo_base)[source]

pyplis.inout.get_all_files_in_dir(directory, file_type=None, include_sub_dirs=False)[source]

Find all files in a certain directory.

Parameters:

directory (str) – path to directory
file_type (str, optional) – specify file type (e.g. “png”, “fts”). If unspecified, then all files are considered
include_sub_dirs (bool) – if True, also all files from all sub-directories are extracted

Returns:

sorted list containing paths of all files detected

Return type:

pyplis.inout.create_temporary_copy(path)[source]

pyplis.inout.download_test_data(save_path=None)[source]

Download pyplis test data.

Parameters:: save_path – location where path is supposed to be stored

Code for progress bar was “stolen” here (last access date: 11/01/2017) -progress-bar-in-python

pyplis.inout.find_test_data()[source]: Search location of test data folder.

pyplis.inout.all_test_data_paths()[source]: Return list of all search paths for test data.

pyplis.inout.set_test_data_path(save_path)[source]: Set local path where test data is stored.

pyplis.inout.get_camera_info(cam_id, cam_info_file: Path | None = None)[source]

Try access camera information from file “cam_info.txt” (package data).

Parameters:: cam_id (str) – string ID of camera (e.g. “ecII”)

pyplis.inout.save_new_default_camera(info_dict, cam_info_file: Path | None = None)[source]

Save new default camera to data file cam_info.txt.

Parameters:

info_dict (dict) – dictionary containing camera default information
cam_info_file (dict) – text file where camera should be stored in. If None, check and use pyplis default locations (libdir/data or ~/my_pyplis)

pyplis.inout.save_default_source(info_dict)[source]: Add a new default source to file source_info.txt.

pyplis.inout.get_all_valid_cam_ids()[source]

Load all valid camera string ids.

Reads info from file cam_info.txt which is part of package data

pyplis.inout.get_cam_ids()[source]

Load all default camera string ids.

Reads info from file cam_info.txt which is part of package data

pyplis.inout.get_source_ids()[source]

Get all existing source IDs.

Reads info from file my_sources.txt which is part of package data

pyplis.inout.get_source_info(source_id, try_online=True)[source]

Try access source information from file “my_sources.txt”.

File is part of package data

Parameters:

source_id (str) – string ID of source (e.g. Etna)
try_online (bool) – if True and local access fails, try to find source ID in online database

pyplis.inout.get_source_info_online(source_id)[source]

Try to load source info from online database (@ www.ngdc.noaa.gov).

Parameters:: source_id (str) – ID of source

pyplis.inout.normalise_keys(dict)[source]

Convert the names from the NOAA data to be consistent with pyplis naming conventions

Parameters:: dict – Dict with volcano information

pyplis.inout.get_icon(name, color=None)[source]

Try to find icon in lib icon folder.

Parameters:

name (str) – name of icon (i.e. filename is <name>.png)
(None) (color) – color of the icon (“r”, “k”, “g”)

Returns icon image filepath if valid

Custom image import methods

Custom image load methods for different camera standards.

Note

This file can be used to include cusotmised image import method. Please re-install pyplis after defining your customised import method here. The method requires the following input / output:

Input: str, file_path -> full file path of the image

Optional input: dict, dictionary specifying image meta information
(e.g. extracted from file name before image load)

Two return parameters

ndarray, the image data (2D numpy array)

dict, additional meta information (is required as return value

, if no meta data is imported from your custom method, then simply return an empty dictionary. Please also make sure to use valid pyplis image meta data keys (listed below)

Valid keys for import of image meta information:

‘start_acq’, ‘stop_acq’, ‘texp’, ‘focal_length’, ‘pix_width’, ‘pix_height’, ‘bit_depth’, ‘f_num’, ‘read_gain’, ‘filter’, ‘path’, ‘file_name’, ‘file_type’, ‘device_id’, ‘ser_no’, ‘wvlngth’, ‘fits_idx’, ‘temperature’, ‘user_param1’, ‘user_param2’, ‘user_param3’

pyplis.custom_image_import.load_ecII_fits(file_path, meta=None, **kwargs)[source]: Load NILU ECII camera FITS file and import meta information.

pyplis.custom_image_import.load_hd_custom(file_path, meta=None, **kwargs)[source]

Load image from HD custom camera.

The camera specs can be found in Kern et al. 2015, Intercomparison of SO2 camera systems for imaging volcanic gas plumes

Images recorded with this camera type are stored as .tiff files and are

Parameters:

file_path – image file path
meta (dict) – optional, meta info dictionary to which additional meta information is suppose to be appended

Returns:

ndarray, image data
dict, dictionary containing meta information

pyplis.custom_image_import.load_hd_new(file_path, meta=None, **kwargs)[source]

Load new format from Heidelberg group.

This format contains IPTC information

Parameters:

file_path – image file path
meta (dict) – optional, meta info dictionary to which additional meta information is supposed to be appended

Returns:

ndarray, image data
dict, dictionary containing meta information

pyplis.custom_image_import.load_qsi_lmv(file_path, meta=None, **kwargs)[source]

Load images for QSI cam from LMV.

Laboratoire Magmas et Volcans, Université Clermont Auvergne - CNRS - IRD, OPGC

This format contains IPTC information

Parameters:

file_path (str) – image file path
meta (dict) – optional, meta info dictionary to which additional meta information is supposed to be appended

Returns:

2-element tuple, containing:

ndarray, image data

dict, dictionary containing meta information

Return type: