API¶
Note
The code documentation is currently in the process of being changed to the NumPy standard.
Setup classes¶
Setup classes to specify relevant parameters for the emission-rate analysis.
The most important ones are:
-
class
pyplis.setupclasses.
Source
(name='', info_dict=None, **kwargs)[source]¶ Object containing information about emission source.
-
suppl_info
¶ dictionary containing supplementary information (e.g. source type, region, country)
Type: dict
Parameters: Note
If input param
name
is a valid default ID (e.g. “Etna”) then the source information is extracted from the database and the parameterinfo_dict
is ignored.-
__init__
(name='', info_dict=None, **kwargs)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
info_available
¶ Check if main information is available.
-
geo_data
¶ Return dictionary containing lon, lat and altitude.
-
to_dict
()[source]¶ Return dictionary of all parameters.
Returns: dictionary representation of class Return type: dict
-
load_source_info
(name=None, try_online=True)[source]¶ Try to load source info from external database.
Try to find source info in pyplis database file my_sources.txt and if it cannot be found there, try online, if applicable.
Parameters:
-
save_to_database
()[source]¶ Save the current information as a new source.
The information is stored in the my_sources.txt file that can be found in the pyplis installation folder my_pyplis
-
get_info
(name=None, try_online=True)[source]¶ Load source info from database.
Looks if desired source (specified by argument name) can be found in the my_sources.txt file and if not, tries to find information about the source online (if :param:`try_online` is True)
Parameters: Returns: Dictionary containing source information
Return type:
-
-
class
pyplis.setupclasses.
FilterSetup
(filter_list=None, default_key_on=None, default_key_off=None, **filters)[source]¶ A collection of
pyplis.utils.Filter
objects.This collection specifies a filter setup for a camera. A typical setup would be one on and one off band filter. An instance of this class is created automatically as an attribute of
Camera
objects.Parameters: - filters (list) – list of
pyplis.utils.Filter
objects specifying camera filter setup - default_key_on (str) – string ID of default on band filter (only relevant if collection contains more than one on band filter)
- default_key_off (str) – string ID of default off band filter (only relevant if collection contains more than one off band filter)
-
__init__
(filter_list=None, default_key_on=None, default_key_off=None, **filters)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
filters
¶ Get dict containing filters (only getter, for backwards compat).
-
on_band
¶ Return default on band filter.
-
off_band
¶ Return default on band filter.
-
ids_off
¶ List with all offband filter ids.
-
ids_on
¶ List with all onband filter ids.
-
default_key_on
¶ Return default onband key.
-
default_key_off
¶ Return default offband key.
-
has_on
¶ Check if collection contains an onband filter.
-
has_off
¶ Check if collection contains an onband filter.
-
number_of_filters
¶ Return the current number of filters in this collection.
-
init_filters
(filter_list=None, **filters)[source]¶ Initialize the filter collection (old settings will be deleted).
The filters will be written into the dictionary
self._filters
in the list order, keys are the filter idsParameters: - filters (list) – list of
pyplis.utils.Filter
objects specifying camera filter setup - **filters – pairs of filter IDs and instances of
Filter
that may be used instead of (or in addition to) input filter_list
- filters (list) – list of
-
update_filters_from_dict
(filter_dict)[source]¶ Add filter objects from a dictionary.
Parameters: filter_dict (dict) – dictionary, containing filter information
- filters (list) – list of
-
class
pyplis.setupclasses.
Camera
(cam_id=None, filter_list=None, default_filter_on=None, default_filter_off=None, ser_no=9999, **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 paramcam_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
- **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=None, filter_list=None, default_filter_on=None, default_filter_off=None, ser_no=9999, **geom_info)[source]¶ Init object.
Parameters: Note
if input cam_id is valid (i.e. can be found in database) then any additional input using
info_dict
is ignored.
-
lon
¶ Camera longitude.
-
lat
¶ Camera latitude.
-
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 usingalt_offset
.
-
elev
¶ Return viewing elevation angle (center pixel) in degrees.
0 refers to horizon, 90 to zenith
-
elev_err
¶ Uncertainty in viewing elevation angle in degrees.
-
azim
¶ Return viewing azimuth angle in deg relative to north (center pixel).
-
azim_err
¶ Uncertainty in viewing azimuth angle in degrees.
-
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
-
update
(**settings)[source]¶ Update camera parameters.
Parameters: settings (dict) – dictionary containing camera parametrs (valid keys are all keys of self.__dict__
and from dictionaryself.geom_data
)
-
prepare_filter_setup
(filter_list=None, default_key_on=None, default_key_off=None)[source]¶ Create
FilterSetup
object.This method defines the camera filter setup based on an input list of
Filter
instances.Parameters: - filter_list (list) – list containing
pyplis.utils.Filter
objects - default_filter_on (str) – 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_filter_off (str) – 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.
- filter_list (list) – list containing
-
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:
-
class
pyplis.setupclasses.
FormSetup
(line_dict=None, rect_dict=None)[source]¶ Setup class for all forms (lines, rectangles etc.) used for evaluation.
-
class
pyplis.setupclasses.
BaseSetup
(base_dir, start, stop, **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:
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, start, stop, **opts)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
start
¶ Start time of setup.
-
stop
¶ Stop time of setup.
-
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)
-
SEPARATE_FILTERS
¶ File import option (boolean).
If true, files are separated by filter type (e.g. “on”, “off”)
-
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)
-
INCLUDE_SUB_DIRS
¶ File import option (boolean).
If True, sub directories are included into image search
-
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 attributelist_id
which is passed using the keyfilter_id
to the respective customised image import method that has to be defined in thecustom_image_import
file of the pyplis installation and linked to your Camera settings in thecam_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()
incustom_image_import
.
-
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.
-
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 thereg_shift_off
attribute of theCamera
instance.
-
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 forpyplis.dataset.Dataset
objects (i.e. alsopyplis.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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
source
¶ Emission source.
-
camera
¶ Camera.
-
update_wind_info
(info_dict)[source]¶ Update wind info dict using valid entries from input dict.
Parameters: info_dict (dict) – dictionary containing wind information
-
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
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.-
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
includesMeasSetup
instance or a valid image directory.input
is passed toload_input()
. - lst_type (object) – default type of image list objects (e.g.
ImgList
,CellImgList
), defaults toImgList
. - init (bool) – init
-
__init__
(input=None, lst_type=<class 'pyplis.imagelists.ImgList'>, init=1)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
camera
¶ Return camera base info object.
-
source
¶ Get / set current Source.
-
cam_id
¶ Return current camera ID.
-
base_dir
¶ Getter / setter of current image base_dir.
-
USE_ALL_FILES
¶ Return USE_ALL_FILES boolen from setup.
-
USE_ALL_FILE_TYPES
¶ Return USE_ALL_FILE_TYPES option from setup.
-
INCLUDE_SUB_DIRS
¶ Return boolean sub directory inclusion option.
-
LINK_OFF_TO_ON
¶ I/O option defined in
BaseSetup
.
-
start
¶ Getter / setter for current start time stamp.
-
stop
¶ Getter / setter for current stop time stamp.
-
file_type
¶ Return current image file type.
-
meas_geometry
¶ Return current measurement geometry.
-
filters
¶ Return the current filter setup.
-
filter_acronyms
¶ Make a dictionary of filter IDs and corresponding acronyms.
-
num_of_filters
¶ Return the number of filters in
self.filters
.
-
rects
¶ Return rectangle collection.
-
lines
¶ Return rectangle collection.
-
load_input
(input)[source]¶ Extract information from input and set / update self.setup.
Parameters: input – Usable input
includesMeasSetup
instance or a valid image directory.Returns: True
, if input could be utilised,False
if notReturn type: bool
-
set_setup
(stp)[source]¶ Set the current measurement setup.
Parameters: stp (MeasSetup) – Class containing information about measurement setup
-
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 setupParameters: filepath (str) – valid file path of an example image Returns: Dictionary containing information about which meta inforamtion 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
-
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: into_list (None) (ImgList) – optional input, if specified, the dark assignment is performed only in the input list
-
dark_lists
¶ Call and return
get_all_dark_offset_lists()
.
-
dark_lists_with_data
¶ Return all dark/offset lists that include image data.
-
filter_ids
¶ Get all dark IDs.
-
img_lists
¶ Wrap
get_all_image_lists()
.
-
img_lists_with_data
¶ Wrap
get_all_image_lists()
.
-
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
-
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()
ofself.meas_geometry
.
-
draw_map_3d
(*args, **kwargs)[source]¶ Call and return
draw_map_3d()
ofself.meas_geometry
.
-
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 classespyplis.Camera
andpyplis.Source
. If you want to change these parameters, it is recommended to use the correpdonding update methodsupdate_cam_specs()
,update_source_specs()
andupdate_wind_specs()
or use the provided getter / setter methods for each parameter (e.g.,cam_elev
for keyelev
of_cam
dictionary,cam_azim
for keyazim
of_cam
dictionary,cam_lon
for keylon
of_cam
dictionary,cam_lat
for keylat
of_cam
dictionary,source_lon
for keylon
of_source
dictionary,source_lat
for keylat
of_source
dictionary,wind_dir
for keydir
of_dir
dictionary.Note that in the dictionary based update methods
update_cam_specs()
,update_source_specs()
andupdate_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 thegeonum.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 altitude_offs
Type: dict
Parameters: -
__init__
(source_info=None, cam_info=None, wind_info=None, auto_topo_access=True)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
cam_id
¶ ID of current camera (string).
-
cam_serno
¶ Return serial number of camera.
-
cam_lon
¶ Longitude position of camera.
-
cam_lat
¶ Latitude position of camera.
-
cam_altitude
¶ Altitude of camera position.
-
cam_elev
¶ Elevation angle of camera viewing direction (CFOV).
-
cam_elev_err
¶ Elevation angle error of camera viewing direction (CFOV).
-
cam_azim
¶ Azimuth of camera viewing direction (CFOV).
-
cam_azim_err
¶ Azimuth error of camera viewing direction (CFOV).
-
cam_focal_length
¶ Focal length of camera.
-
cam_pix_width
¶ Pixel width of camera detector (horizonzal pix-to-pix distance).
-
cam_pix_height
¶ Pixel height of camera detector (vertical pix-to-pix distance).
-
cam_pixnum_x
¶ Return Number of camera detector pixels in x-direction (horizontal).
-
cam_pixnum_y
¶ Return Number of camera detector pixels in y-direction (vertical).
-
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).
-
source_lon
¶ Longitude position of source.
-
source_lat
¶ Latitude position of source.
-
source_altitude
¶ Altitude of source position.
-
wind_dir
¶ Azimuth of wind direction.
-
wind_dir_err
¶ Azimuth error of wind direction.
-
update_cam_specs
(info_dict=None, update_geosetup=True, **kwargs)[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 - **kwargs – can be used to directly pass valid key / value pairs
- info_dict (dict) – dictionary containing camera information (see
-
update_source_specs
(info_dict=None, update_geosetup=True, **kwargs)[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 - **kwargs – alternative way to update the source dictionary using valid keywords directly
- info_dict (dict) – dictionary containing source information (see
-
update_wind_specs
(info_dict=None, update_geosetup=True, **kwargs)[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 - **kwargs – alternative way to update the wind dictionary using valid keywords directly
- info_dict (dict) – dictionary containing meterology information (see
-
update_geosetup
()[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
-
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)[source]¶ Determine viewing direction coords for a line in an image.
Parameters: line (LineOnImage) – line on image object Returns: 4-element tuple containing - 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: tuple
-
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 beLineOnImage
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
- line (list) – list with line coordinates:
-
get_angular_displacement_pix_to_cfov
(pos_x, pos_y)[source]¶ Get the angular difference between pixel and detector center.
Parameters:
-
get_azim_elev
(pos_x, pos_y)[source]¶ Get values of azimuth and elevation in pixel (x|y).
Parameters:
-
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
inself.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: 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: 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 andheight are equal)
Img
: image where each pixel corresponds to plume- distance in m
Return type:
-
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: 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”)
-
plume_dir
¶ Return current plume direction angle.
-
plume_dir_err
¶ Return uncertainty in current plume direction angle.
-
cam
¶ Camera location (
geonum.GeoPoint
).
-
source
¶ Return camera Geopoint.
-
intersect_pos
¶ Return camera Geopoint.
-
plume_vec
¶ Return the plume center vector.
-
source2cam
¶ Return vector pointing camera to source.
-
cam_view_vec
¶ Return vector corresponding to CFOV azimuth of camera view dir.
-
haversine
(lon0, lat0, lon1, lat1, radius=6371.0)[source]¶ Haversine formula.
Approximate horizontal distance between 2 points assuming a spherical earth
Parameters:
-
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 setupReturns: float, distance between source and camera
-
del_az
(pixcol1=0, pixcol2=1)[source]¶ Determine the difference in azimuth angle between 2 pixel columns.
Parameters: 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: 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: Returns: plume distance(s) in m for input azimuth(s) and elevations
Return type:
-
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
-
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 - See also
-
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¶
Classes 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 asnumpy.ndarray
objects and the is stored in the attributeself.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 usingprint_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()
andtexp()
).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 usingcv2.pyrDown(img.img)
for resizing orimg.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
-
__init__
(input=None, import_method=None, dtype=None, **meta_info)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
img
¶ Get / set image data.
-
start_acq
¶ Get image acquisition time.
Returns: acquisition time if available (i.e. it deviates from the default 1/1/1900), else, raises ImgMetaError
-
stop_acq
¶ Return stop time of acquisition (if available).
-
texp
¶ Get image acquisition time.
Returns: acquisition time if available (i.e. it deviates from the default 1/1/1900), else, raises ImgMetaError
-
gain
¶ Return read gain value from meta info.
-
shape
¶ Return shape of image data.
-
xy_aspect
¶ Aspect ratio (delx / dely).
-
pyr_up_factor
¶ Return coordinates conversion factor.
This factor is used to convert coordinates at current pyramid level into original size coordinates.
-
is_darkcorr
¶ Boolean specifying whether image is dark corrected.
-
is_tau
¶ Return boolean whether image is a tau image or not.
-
is_aa
¶ Return boolean whether current image is AA image.
-
is_calibrated
¶ Flag for image calibration status.
-
is_vignetting_corrected
¶ Boolean stating whether image is vignetting corrected or not.
-
is_gray
¶ Check if image is gray image.
-
is_binary
¶ Attribute specifying whether image is binary image.
-
is_inverted
¶ Flag specifying whether image was inverted or not.
-
is_vigncorr
¶ Bool specifying whether or not image is vignetting corrected.
-
is_dilcorr
¶ Return whether this image is corrected for signal dilution.
-
is_cropped
¶ Boolean specifying whether image is cropped.
-
is_resized
¶ Boolean specifying whether image pyramid level unequals 0.
-
is_shifted
¶ Boolean specifying whether image was shifted.
This may be e.g. the case for stereo imaging
-
modified
¶ Check if this image was already modified.
-
pyrlevel
¶ Return current gauss pyramid level (stored in
self.edit_log
).
-
roi
¶ Return current roi in consideration of current pyrlevel.
-
roi_abs
¶ Get / set current ROI in absolute image coordinates.
Note
use
roi()
to get ROI for current pyrlevel
-
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: 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: Returns: - Img, cropped image
-
correct_dark_offset
(dark, offset)[source]¶ Perform dark frame subtraction, 3 different modi possible.
Parameters: Return Img: modelled dark image
Uses
model_dark_image()
(inProcessing
) 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)
-
apply_median_filter
(size_final=3)[source]¶ Apply a median filter.
Parameters: shape (3,3) (tuple) – 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
-
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 usedNote
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 kernelReturns: 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 usedNote
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 kernelReturns: 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 usingParameters: Returns: new Img object containing tau image data (this object remains unchanged)
Return type:
-
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:
-
set_val_below_thresh
(val, threshold)[source]¶ Set value in all pixels with intensities below threshold.
Note
Modifies this Img object
Parameters:
-
set_val_above_thresh
(val, threshold)[source]¶ Set value in all pixels with intensities above threshold.
Note
Modifies this Img object
Parameters:
-
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_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).
-
save_as_fits
(save_dir=None, save_name=None)[source]¶ Save this image as FITS file.
Parameters: Returns: name of saved file
Return type:
-
get_cmap
(vmin=None, vmax=None, **kwargs)[source]¶ Determine and return default cmap for current image.
-
show_img
(zlabel=None, tit=None, cbar=True, ax=None, zlabel_size=18, **kwargs)[source]¶ Show image using matplotlib method imshow.
-
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:
Parameters: Returns: Img
, modelled dark image
-
class
pyplis.image.
ProfileTimeSeriesImg
(img_data=None, time_stamps=array([], dtype=float64), img_id='', dtype=<type '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=<type 'numpy.float32'>, profile_info_dict=None, **meta_info)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
img
¶ Get / set image data.
-
start
¶ Return first datetime from
self.time_stamps
.
-
stop
¶ Return first datetime from
self.time_stamps
.
-
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.
BaseImgList
(files=None, list_id=None, list_type=None, camera=None, geometry=None, init=True, **img_prep_settings)[source]¶ Basic image list object.
Basic class for image list objects providing indexing and image loading functionality
In this class, only the current image is loaded at a time while
ImgList
loads current and next image whenever the index is changed (e.g. required foroptflow_mode
)This object and all objects inheriting from this are fundamentally based on a list of image file paths, which are dynamically loaded and processed during usage.
Parameters: - files (list, optional) – list with image file paths
- list_id (str, optional) – a string used to identify this list (e.g. “second_onband”)
- list_type (str, optional) – type of images in list (please use “on” or “off”)
- camera (Camera, optional) – camera specifications
- init (bool) – if True, list will be initiated and files loaded (given that image files are provided on input)
- **img_prep_settings – additional keyword args specifying image preparation settings applied on image load
-
__init__
(files=None, list_id=None, list_type=None, camera=None, geometry=None, init=True, **img_prep_settings)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
start
¶ Acquisistion time of first image.
-
stop
¶ Start acqusition time of last image.
-
this
¶ Return current image.
-
edit_active
¶ Define whether images are edited on image load or not.
If False, images will be loaded as raw, i.e. without any editing or further calculations (e.g. determination of optical flow, or updates of linked image lists). Images will be reloaded.
-
skip_files
¶ Integer specifying the image iter step in the file list.
Defaults to 1: every file is used, 2 means, that every second file is used.
-
meas_geometry
¶ Return measurement geometry.
-
update_cam_geodata
¶ Update measurement geometry whenever list index is changed.
-
plume_dists
¶ Distance to plume.
Can be an image were each pixel value corresponds to the plume distance at each pixel position (e.g. computed using the MeasGeometry) or can also be a single value, which may be appropriate under certain measurement setups (e.g. distant plume perpendicular to CFOV of camera)
Note
This method checks if a value is accessible in
_plume_dists
and if not tries to compute plume distances by callingcompute_all_integration_step_lengths()
of theMeasGeometry
object assigned to this ImgList. If this fails, then an AttributeError is raisedReturns: Plume distances in m. If plume distances are accessible per image pixel. Note that the corresponding data is converted to pyramid level 0 (required for dilution correction). Return type: float or Img or ndarray
-
vign_mask
¶ Return current vignetting correction mask.
-
sky_mask
¶ Return sky access mask.
0 for sky, 1 for non-sky (=invalid) (in masked arrays, entries marked with 1 are invalid)
-
integration_step_length
¶ Return integration step length for emission-rate analyses.
The intgration step length corresponds to the physical distance in m between two pixels within the plume and is central for computing emission-rate. It may be an image were each pixel value corresponds to the integreation step length at each pixel position (e.g. computed using the MeasGeometry) or it can also be a single value, which may be appropriate under certain measurement setups (e.g. distant plume perpendicular to CFOV of camera).
Note
This method checks if a value is accessible in
_integration_step_lengths
and if not tries to compute them by callingcompute_all_integration_step_lengths()
of theMeasGeometry
object assigned to this ImgList. If this fails, an AttributeError is raisedReturns: Integration step lengths in m. If plume distances are accessible per image pixel, then the corresponding data IS converted to the current pyramid level Return type: float or Img or ndarray
-
auto_reload
¶ Activate / deactivate automatic reload of images.
-
crop
¶ Activate / deactivate crop mode.
-
pyrlevel
¶ Return current Gauss pyramid level.
Note
images are reloaded on change
-
gaussian_blurring
¶ Return current blurring level.
Note
images are reloaded on change
-
roi
¶ Return current ROI (in relative coordinates).
The ROI is returned with respect to the current
pyrlevel
-
cfn
¶ Return current index (file number in
files
).
-
nof
¶ Return number of files in this list.
-
last_index
¶ Return index of last image.
-
data_available
¶ Return wrapper for
has_files()
.
-
has_images
¶ Return wrapper for
has_files()
.
-
start_acq
¶ Array containing all image acq. time stamps of this list.
Note
The time stamps are extracted from the file names
-
timestamp_to_index
(val=datetime.datetime(1900, 1, 1, 0, 0))[source]¶ Convert a datetime to the list index.
Returns the list index that is closest in time to the input time stamp.
Parameters: val (datetime) – time stamp Raises: AttributeError – if time stamps of images in list cannot be accessed from their file names Returns: corresponding list index Return type: int
-
index_to_timestamp
(val=0)[source]¶ Get timestamp of input list index.
Parameters: val (index) – time stamp Raises: AttributeError – if time stamps of images in list cannot be accessed from their file names Returns: corresponding list index Return type: int
-
add_files
(files, load=True)[source]¶ Add images to this list.
Parameters: file_list (list) – list with file paths Returns: success / failed Return type: bool
-
init_filelist
(at_index=0)[source]¶ Initialize the filelist.
Sets current list index and resets loaded images
Parameters: at_index (int) – desired image index, defaults to 0
-
iter_indices
(to_index)[source]¶ Change the current image indices for previous, this and next img.
Note
This method only updates the actual list indices and does not perform a reload.
-
load
()[source]¶ Load current image.
Try to load the current file
self.files[self.cfn]
and if remove the file from the list if the import failsReturns: if True, image was loaded, if False not Return type: bool
-
goto_img
(to_index, reload_here=False)[source]¶ Change the index of the list, load and prepare images at new index.
Parameters: - to_index (float) – new list index
- reload_here (bool) – applies only if :param:`to_index` is the current list index. If True, then the current images are reloaded, if False, nothing is done.
-
update_img_prep
(**settings)[source]¶ Update image preparation settings and reload.
Parameters: **settings – key word args specifying settings to be updated (see keys of img_prep
dictionary)
-
separate_by_substr_filename
(sub_str, sub_str_pos, delim='_')[source]¶ Separate this list by filename specifications.
The function checks all current filenames, and keeps those, which have a certain sub string at a certain position in the file name after splitting using a provided delimiter. All other files are added to a new image list which is returned.
Parameters: Returns: 2-element tuple containing
Return type:
-
set_camera
(camera=None, cam_id=None)[source]¶ Set the current camera.
Two options:
- set
Camera
directly - provide one of the default camera IDs (e.g. “ecII”, “hdcam”)
Parameters: - camera (Camera) – the camera used
- cam_id (str) – one of the default cameras (use
pyplis.inout.get_all_valid_cam_ids()
to get the default camera IDs)
- set
-
get_img_meta_from_filename
(file_path)[source]¶ Load and prepare img meta input dict for Img object.
Parameters: file_path (str) – file path of image Returns: dictionary containing retrieved values for start_acq
andtexp
Return type: dict
-
get_img_meta_all_filenames
()[source]¶ Try to load acquisition and exposure times from filenames.
Note
Only works if relevant information is specified in
self.camera
and can be accessed from the file namesReturns: 2-element tuple containing - list, list containing all retrieved acq. time stamps
- list, containing all retrieved exposure times
Return type: tuple
-
assign_indices_linked_list
(lst)[source]¶ Create a look up table for fast indexing between image lists.
Parameters: lst (BaseImgList) – image list supposed to be linked Returns: array contining linked indices Return type: array
-
same_preedit_settings
(settings_dict)[source]¶ Compare input settings dictionary with self.img_prep.
Parameters: **settings_dict – keyword args specifying settings to be compared Returns: False if not the same, True else Return type: bool
-
make_stack
(stack_id=None, pyrlevel=None, roi_abs=None, start_idx=0, stop_idx=None, ref_check_roi_abs=None, ref_check_min_val=None, ref_check_max_val=None, dtype=<type 'numpy.float32'>)[source]¶ Stack all images in this list.
The stacking is performed using the current image preparation settings (blurring, dark correction etc). Only stack ROI and pyrlevel can be set explicitely.
Note
In case of
MemoryError
try stacking less images (specifying start / stop index) or reduce the size setting a different Gauss pyramid level.Parameters: - stack_id (
str
, optional) – identification string of the image stack - pyrlevel (
int
, optional) – Gauss pyramid level of stack - roi_abs (list) – build stack of images cropped in ROI
- start_idx (
int
ordatetime
) – 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 methodtimestamp_to_index()
) - stop_idx (
int
ordatetime
, 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 methodtimestamp_to_index()
) - ref_check_roi_abs (
list
, optional) – rectangular area specifying a reference area which can be specified in combination with the following 2 parameters in order to include only images in the stack that are within a certain intensity range within this ROI (Note that this ROI needs to be specified in absolute coordinate, i.e. corresponding to pyrlevel 0). - ref_check_min_val (
float
, optional) – if attributeroi_ref_check
is a valid ROI, then only images are included in the stack that exceed the specified intensity value (can e.g. be optical density or minimum gas CD in calib mode) - ref_check_max_val (
float
, optional) – if attributeroi_ref_check
is a valid ROI, then only images are included in the stack that are smaller than the specified intensity value (can e.g. be optical density or minimum gas CD in calib mode) - dtype – data type of stack
Returns: image stack containing stacked images
Return type: - stack_id (
-
get_mean_img
(start_idx=0, stop_idx=None)[source]¶ Determine an average image from a number of list images.
Parameters: - start_idx (
int
ordatetime
) – 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 methodtimestamp_to_index()
) - stop_idx (
int
ordatetime
, 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 methodtimestamp_to_index()
)
Returns: average image
Return type: - start_idx (
-
get_mean_tseries_rects
(start_idx, stop_idx, *rois)[source]¶ Similar to
get_mean_value()
but for multiple rects.Parameters: - start_idx (
int
ordatetime
) – 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 methodtimestamp_to_index()
) - stop_idx (
int
ordatetime
) – 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 methodtimestamp_to_index()
) - *rois – non keyword args specifying rectangles for data access
Returns: N-element tuple containing
PixelMeanTimeSeries
objects (one for each ROI specified on input)Return type: - start_idx (
-
get_mean_value
(start_idx=0, stop_idx=None, roi=[0, 0, 9999, 9999], apply_img_prep=True)[source]¶ Determine pixel mean value time series in ROI.
Determines the mean pixel value (and standard deviation) for all images in this list. Default ROI is the whole image and can be set via input param roi, image preparation can be turned on or off.
Parameters: - start_idx (
int
ordatetime
) – 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 methodtimestamp_to_index()
) - stop_idx (
int
ordatetime
) – 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 methodtimestamp_to_index()
) - roi (list) – rectangular region of interest
[x0, y0, x1, y1]
, defaults to [0, 0, 9999, 9999] (i.e. whole image) - apply_img_prep (bool) – if True, img preparation is performed as specified in
self.img_prep
dictionary, defaults to True
Returns: time series of retrieved values
Return type: - start_idx (
-
add_gaussian_blurring
(sigma=1)[source]¶ Increase amount of gaussian blurring on image load.
Parameters: sigma (1) (int) – Add width gaussian blurring kernel
-
current_time
()[source]¶ Get the acquisition time of the current image from image meta data.
Raises: IndexError – if list does not contain images Returns: start acquisition time of currently loaded image Return type: datetime
-
current_img
(key='this')[source]¶ Get the current image object.
Parameters: key (str) – this” or “next” Returns: currently loaded image in list Return type: Img
-
plot_mean_value
(roi=[0, 0, 9999, 9999], yerr=False, ax=None)[source]¶ Plot mean value of image time series.
Parameters: Returns: matplotlib axes object
Return type: Axes
-
plot_tseries_vert_profile
(pos_x, start_y=0, stop_y=None, step_size=0.1, blur=4)[source]¶ Plot the temporal evolution of a line profile.
Parameters: - pos_x (int) – number of pixel column
- start_y (int) – Start row of profile (y coordinate, default: 10)
- stop_y (int) – Stop row of profile (is set to rownum - 10pix if input is None)
- step_size (float) – stretch between different line profiles of the evolution (0.1)
- blur (int) – blurring of individual profiles (4)
Returns: figure containing result plot
Return type: Figure
-
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 theedit_active
.
-
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.
-
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()
ofImgList
)Type: PlumeBackgroundModel
Parameters: -
-
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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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
-
darkcorr_mode
¶ Return current list darkcorr mode.
-
optflow_mode
¶ Activate / deactivate optical flow calc on image load.
-
vigncorr_mode
¶ Activate / deactivate vignetting correction on image load.
-
dilcorr_mode
¶ Activate / deactivate dilution correction on image load.
-
sensitivity_corr_mode
¶ Activate / deactivate AA sensitivity correction mode.
-
tau_mode
¶ Return current list tau mode.
-
shift_mode
¶ Return current list registration shift mode.
-
aa_mode
¶ Return current list AA mode.
-
calib_mode
¶ Acitivate / deactivate current list gas calibration mode.
-
ext_coeff
¶ Return current extinction coefficient.
-
ext_coeffs
¶ Dilution extinction coefficients.
-
bg_img
¶ Return background image based on current vignetting corr setting.
-
dark_img
¶ Return current dark image.
-
bg_list
¶ Return background image list (if assigned).
-
senscorr_mask
¶ Get / set AA correction mask.
-
calib_data
¶ Get set object to perform calibration.
-
doas_fov
¶ Try access DOAS FOV info (in case cailbration data is available).
-
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 whichself.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:
1. 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 listParameters: val (bool) – Activate / deactivate AA 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:
-
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
andself.offset_lists
(so these must exist). If this fails for some reason, setself.darkcorr_opt = 2
, else model dark image usingmodel_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 inself.darkImg
(which can be set manually usingset_dark_image()
). If this also fails, setself.darkcorr_opt = 0
and return False. If a dark image could be found and the exposure time differs by more than 20%, setself.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 methodset_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
-
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: - ndarray) dark ((Img,) – 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: - ndarray) offset ((Img,) – 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)
-
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
ordatetime
) – 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 methodtimestamp_to_index()
) - stop_idx (
int
ordatetime
, 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 methodtimestamp_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 inputLineOnImage
objects.Return type: - lines (list) – list containing
-
get_thresh_mask
(thresh=None, this_and_next=True)[source]¶ Get bool mask based on intensity threshold.
Parameters: 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 () 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 theFarnebackSettings
class
Returns: 2D-numpy boolean numpy array specifying sky background pixels
Return type: array
- lower_thresh (
-
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 parameterext_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 thebg_model
(instance ofPlumeBackgroundModel
) 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
orImg
, optional) – 2D array containing pixel based plume distances. If None, this mask will be attempted to be retrieved from theMeasGeometry
instance assigned to this list - ext_coeff (
float
, optional) – atmospheric extinction coefficient. If unspecified, try access viaext_coeff
which returns the current extinction coefficient and raisesAttributeError
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
orImg
, 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 providedon input -
array
, mask specifying plume pixelsReturn 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()
andprep_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 usingtau_mode
, notaa_mode
) - ext_on (
float
, optional) – atmospheric extinction coefficient at on-band wavelength, if None (default), try access viaext_coeff
- ext_off (
float
, optional) – atmospheric extinction coefficient at off-band wavelength. Only relevant if input paramadd_off_list
is True. If None (default) andadd_off_list=True
try access viaext_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 directorydilcorr
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()
andprep_data_dilutioncorr()
- tau_thresh (
-
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: Returns: pandas Series containing extinction coeffs
Return type: Series
Todo
This is a Beta version, insert try / except block after testing
-
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 variableself.gas_cd
specifying the amount of gas (column density) in this cell.
-
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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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
andtexp
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: tuple
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: -
__init__
(bg_raw=None, plume_init=None, init_surf_fit_mask=True, **kwargs)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
scale_rect
= None¶ Rectangle for scaline of background image corr modes: 1 - 6
-
ygrad_rect
= None¶ Rectangle for linear based correction of vertical gradient corr modes: 2, 4
-
ygrad_line_colnum
= None¶ Settings for quadratic correction of vertical gradient (along line) corr modes: 3, 5, 6
-
xgrad_rect
= None¶ Rectangle for linear based correction of horizontal gradient (applied before ygradient correction is performed) corr modes: 4, 5
-
xgrad_line_rownum
= None¶ Settings for quadratic correction of horizontal gradient (along line) corr modes: 6
-
all_modes
¶ List containing valid modelling modes.
-
mode
¶ Return current modelling mode.
-
CORR_MODE
¶ Return current background modelling mode.
-
surface_fit_mask
¶ fit 2D polynomial.
Type: Mask for retrieval mode 0
-
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
-
guess_missing_settings
(plume_img)[source]¶ Call and return
set_missing_ref_areas()
.Note
This is the previous name of the method
set_missing_ref_areas()
-
set_missing_ref_areas
(plume_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) – exemplary plume image (should be representative for a whole dataset)
-
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 theFarnebackSettings
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 imageReturns: 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 (forself.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 (forself.CORR_MODE = 1 - 6
) - bg_off (
Img
, optional) – off-band sky radiance image (forself.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
ifmode == 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 imageReturns: modelled tau image Return type: array
-
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]
-
mode_info_dict
¶ Return information on available bg modelling 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: 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: 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: - Img) tau0 ((ndarray,) – 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: - Img) tau0 ((ndarray,) – 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: - Img) plume_img ((ndarray,) – 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 usingfind_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 algorithmfind_movement()
(seeplumespeed
).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 thePlumeBackgroundModel
). If not specified, the required reference rectangles (scale_rect
,ygrad_rect
,xgrad_rect
) are determined automatically usingfind_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 theFarnebackSettings
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: - first_data_vec (array) – first data vector (i.e. left or before
-
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: - first_data_vec (array) – first data vector (i.e. left or before
-
class
pyplis.plumespeed.
VeloCrossCorrEngine
(imglist=None, pcs=None, pcs_offset=None, meas_geometry=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
andpcs_offset
.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 theMeasGeometry
object of the assignedImgList
(imglist
) is used. - **settings – optional keyword args passed to
find_signal_correlation()
(used in class methodget_velocity()
).
-
__init__
(imglist=None, pcs=None, pcs_offset=None, meas_geometry=None, **settings)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
update_settings
(settings_dict)[source]¶ Update valid settings for cross correlation retrieval.
Parameters: settings_dict (dict) – dictionary containing new settings
-
velocity
¶ Retrieve plume velocity.
Raises: ValueError – if velocity is nan (default).
-
correlation_lag
¶ Time lag showing highest correlation between two ICA time-series.
Raises: ValueError – if velocity is nan (default).
-
pcs
¶ Return the PCS line used for the velocity retrieval.
-
pcs_offset
¶ Return the PCS offset line used for the velocity retrieval.
-
imglist
¶ Return the image list supposed to be used for the analysis.
-
meas_geometry
¶ Return measurement geometry from image list.
-
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: Returns: 2-element tuple containing
ProfileTimeSeriesImg
for both PCS linesReturn 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: Returns: 2-element tuple containing
ProfileTimeSeriesImg
for both PCS linesReturn 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, line_id='pcs')[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=None, fname1='profile_tseries_pcs.fts', fname2='profile_tseries_offset.fts')[source]¶ Save current ICA profile time series images as FITS file.
Note
Existing files will be overwritten without warning
Parameters:
-
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 ofimglist
is used - **kwargs – additional keyword arguments passed to
show()
ofImg
object. This can also be used to pass an axes instance using keywordax
, for instance if this is supposed to be plotted into a subplot.
Returns: matplotlib axes instance
Return type: ax
- img – optional: example plume image (
-
-
class
pyplis.plumespeed.
LocalPlumeProperties
(roi_id='', **kwargs)[source]¶ Class to store results about 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()
fromOptflowFarneback
which is based on a statistical analysis of histograms derived from a dense optical flow algorithm.-
start
¶ Acquisistion time of first image.
-
stop
¶ Start acqusition time of last image.
-
len_mu
¶ Array containing displacement lengths (unit [pix/del_t]).
-
len_sigma
¶ Array with errors of displacement lengths (unit [pix/del_t]).
-
len_mu_norm
¶ Array containing normalised displacement lengths (unit [pix/s]).
-
len_sigma_norm
¶ Array with errors of normalised displ. lens (unit [pix/s]).
-
dir_mu
¶ Return current displacement orientation vector.
-
dir_sigma
¶ Return current displacement orientation std vector.
-
significance
¶ Significancy of data point.
This array is filled in
get_and_append_from_farneback()
, which callslocal_flow_params()
ofOptflowFarneback
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).
-
fit_success
¶ Array containing flags whether or not multi-gauss fit was successful.
-
pyrlevel
¶ Array containing pyramid levels used to determine displ. params.
-
del_t
¶ Return current del_t vector.
Corresponds to the difference between frames for time series
-
start_acq
¶ Return current displacement length std vector.
Corresponds to the start acquisition times of the time series
-
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
-
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 methoddropna()
of pandasDataFrame
object.Parameters: **kwargs – additional keyword arguments passed to dropna()
of pandasDataFrame
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 methoddropna()
of pandasDataFrame
object.Parameters: - time_stamps (array) – array containing datetime indices supposed to be used for interpolation
- **kwargs – additional keyword arguments passed to
dropna()
of pandasDataFrame
object.
Returns: new object excluding nan values in any of the data arrays
Return type:
-
apply_median_filter
(width=5)[source]¶ Apply median filter to data.
The filter is only applied to
len_mu
anddir_mu
, and the corresponding uncertainty arrayslen_sigma
anddir_sigma
Note
Creates and returns new
LocalPlumeProperties
instance, the data in this object remains unchangedParameters: 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
anddir_mu
, and the corresponding uncertainty arrayslen_sigma
anddir_sigma
Note
Creates and returns new
LocalPlumeProperties
instance, the data in this object remains unchangedParameters: 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()
fromOptflowFarneback
engine and appends the results to the current dataParameters: - 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 aLineOnImage
) 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
Return type:
-
get_orientation_tseries
()[source]¶ Get time series (and uncertainties) of movement direction.
Returns: 3-element tuple containing Series
: time series of orientation anglesSeries
: time series of lower vals (usingdir_sigma
)Series
: time series of upper vals (usingdir_sigma
)
Return type: tuple
-
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 lengthsSeries
: time series of lower vals (usinglen_sigma
)Series
: time series of upper vals (usinglen_sigma
)
Return type: tuple
-
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: 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
-
default_save_name
¶ Return default name for txt export.
-
-
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 byi_min
andi_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)
-
update
(**settings)[source]¶ Update current settings.
Parameters: **settings – keyword args specifying new settings (only valid keys are considered, i.e. class attributes)
-
i_min
¶ Lower intensity limit for image contrast preparation.
-
i_max
¶ Upper intensity limit for image contrast preparation.
-
roi_rad
¶ Old name of
roi_rad_abs
.
-
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 ifauto_update
is True).
-
auto_update
¶ Contrast is automatically updated based on min / max intensities.
If active, then
i_min
andi_max
are updated automativally whenever new images are assigned to aOptflowFarneback
using methodset_images()
. The update is performed based on min / max intensities of the images in the current ROI
-
pyr_scale
¶ scale space parameter for pyramid levels.
pyplis default = 0.5
Type: Farneback algo input
-
levels
¶ number of pyramid levels.
pyplis default = 4
Type: Farneback algo input
-
winsize
¶ width of averaging kernel.
The larger, the more stable the results are, but also more smoothed
pyplis default = 20
Type: Farneback algo input
-
iterations
¶ number of iterations.
pyplis default = 5
Type: Farneback algo input
-
poly_n
¶ size of pixel neighbourhood for poly exp.
default = 5
Type: Farneback algo input
-
poly_sigma
¶ std of Gaussian to smooth poly derivatives.
pyplis default = 1.1
Type: Farneback algo input
-
roi_abs
¶ Get ROI for analysis of flow field (in absolute image coords).
-
min_length
¶ Get / set minimum flow vector length for post analysis.
-
min_count_frac
¶ Minimum fraction of significant vectors required for histo analysis.
-
hist_dir_sigma
¶ Old name of
hist_sigma_tol
.
-
hist_sigma_tol
¶ Sigma tolerance value for mean flow analysis.
-
hist_dir_gnum_max
¶ Max number of gaussians for multigauss fit of orientation histo.
-
hist_dir_binres
¶ Angular resolution of orientation histo (bin width, in deg).
-
disp_skip
¶ Return current pixel skip value for displaying flow field.
-
disp_len_thresh
¶ Return current pixel skip value for displaying flow field.
-
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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
auto_update_contrast
¶ Get / set mode for automatically update contrast range.
If True, the contrast parameters
self.settings.i_min
andself.settings.i_max
are updated whenset_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
)
-
roi_abs
¶ Get / set current ROI (in absolute image coordinates).
-
roi
¶ Get ROI converted to current image preparation settings.
-
pyrlevel
¶ Return pyramid level of current image.
-
del_t
¶ Return time difference in s between both images.
-
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: value (True) (bool) – new mode
-
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
-
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 inself.settings
.Parameters: 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 Return type: tuple
-
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: 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: 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 Return type: tuple
-
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 keywordslens
andangles
to pass this information.
Returns: 3-element tuple containing
Return type: - pix_mask (
-
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 keywordlens
to pass this information.
Returns: 3-element tuple containing
Return type: - pix_mask (
-
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 ofMultiGaussFit
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 useself.settings.hist_dir_gnum_max
Returns: 2-element tuple containing
MultiGaussFit
, the fit object- bool, fit success
Return type: - count (array) – histogram counts (see
-
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
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 useself.settings.hist_dir_gnum_max
Returns: 2-element tuple containing
MultiGaussFit
, the fit object- bool, fit success
Return type: - count (array) – histogram counts (see
-
get_main_flow_field_params
(**kwargs)[source]¶ Old name of
local_flow_params()
.
-
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 (seeget_rotated_roi_mask()
inLineOnImage
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 methodsfit_length_histo()
andfit_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 andmin_count_frac=0.1
, then at least (MxN)*0.1 pixels need to remain after applyingcond_mask_flat
and exclusion of vectors shorter than current minimum lengthself.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: - line (
-
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: shape (3,3) (tuple) – 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
containingdispl_vec
at indices not matching constraintsReturn type: - displ_vec (iterable) – 2-element vector (list, tuple, array) containing diplacement
information
-
get_img_acq_times
()[source]¶ Return acquisition times of current input images.
Returns: 2-element tuple, containing Return type: tuple
-
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 parametermin_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
Returns: Return type: figure
- line (
-
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: - in_roi (bool) – if True (default), then the lines are calculated for pixels
within ROI (either specified by 2. input param and else
-
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 theroi_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
- first_img (
-
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
.
-
class
pyplis.plumespeed.
OpticalFlowFarneback
(*args, **kwargs)[source]¶ Old name of
OptflowFarneback
.
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='', 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
andtau_vec
and optionally, a vector containing errors in the column densitiescd_vec_err
(note that errors in the optical densities are not supported). Furthermore, an array oftime_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='', camera=None)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
senscorr_mask
¶ Get current sensitivity correction mask (
Img
instance).
-
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
.
-
start
¶ Start time of calibration data (datetime).
-
stop
¶ Stop time of calibration data (datetime).
-
polyorder
¶ Get current order of fit polynomial.
-
cov
¶ Get covariance matrix of calibration polynomial.
-
y_offset
¶ Y-axis offset of calib curve.
-
cd_tseries
¶ Pandas Series object of doas data.
-
tau_tseries
¶ Pandas Series object of tau data.
-
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: tuple
-
cd_range
¶ Range of DOAS cd values extended by 5%.
-
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: - calib_fun (
-
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 typeBinTableHDU
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:
-
load_from_fits
(file_path)[source]¶ Load stack object (fits).
Parameters: file_path (str) – file path of calibration data Returns: opened HDU object (e.g. to access potential further data in a function that is calling this method) Return type: HDUList
-
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
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: -
__init__
(filter_id, add_id, y_max)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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
-
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
-
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
-
mean_err
¶ Return average std of mean value time series.
Returns: Error of mean value Return type: float
-
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 conditionpoint_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
-
offs
¶ Get array containing offset values.
The offset values are determined from
mean_vals`
with respect toy_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 withCellSearchInfo
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 dipType: 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
-
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='', 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 (;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
- 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='', camera=None, pos_x_abs=None, pos_y_abs=None)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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()
andpyplis.calib_base.CalibData.load_from_fits()
for more details- file_path : str
- 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 aMeasSetup
object (make sure thatcell_info_dict
is set in the setup class).Parameters: -
__init__
(setup=None, init=True)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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 callingadd_cell_img_list()
Parameters:
-
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 callingadd_bg_img_list()
Parameters:
-
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 andlst.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
usinglst.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 inbg_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()
withfilter_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)
- filter_id (str) – filter ID (e.g. on, off, uses
-
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:
-
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 parameterspos_x_abs
andpos_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 thecalib_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
andpos_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)
- pos_x_abs (
-
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 aCellCalibData
object (denoted withcellcalib
):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
andpos_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 retrievedReturns: 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: - list_id (str) – filter ID of list (e.g. on, off). If parameter
-
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: 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 correspondingCellCalibData
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 correspondingCellCalibData
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='', 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='', camera=None, fov=None)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
save_as_fits
(save_dir=None, save_name=None, overwrite_existing=True)[source]¶ Save calibration data as FITS file.
Parameters:
-
class
pyplis.doascalib.
DoasFOV
(camera=None)[source]¶ Class for storage of FOV information.
-
method
¶ Return search method.
-
pyrlevel
¶ Return pyramide level at which FOV search was performed.
-
cx_rel
¶ Return center x coordinate of FOV (in relative coords).
-
cy_rel
¶ Return center x coordinate of FOV (in relative coords).
-
radius_rel
¶ Return radius of FOV (in relative coords).
Raises: TypeError if method == “ifr”
-
popt
¶ Return super gauss optimisation parameters (in relative coords).
Raises: TypeError if method == “pearson”
-
x_abs
¶
-
y_abs
¶
-
sigma_x_abs
¶
-
sigma_y_abs
¶
-
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)
- tuple,
-
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:
-
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 methodsave_as_fits()
from theDoasCalibData
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
- hdu (HDUList) – HDU list containing a list of HDUs created using
-
-
class
pyplis.doascalib.
DoasFOVEngine
(img_stack=None, doas_series=None, method='pearson', **settings)[source]¶ Engine to perform DOAS FOV search.
-
__init__
(img_stack=None, doas_series=None, method='pearson', **settings)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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
-
ifrlbda
¶ allow asymmetric 2d gauss fit.
Type: For IFR method
-
g2dasym
¶ allow asymmetric 2d gauss fit.
Type: For IFR method
-
g2dsuper
¶ use supergauss parametrisation.
Type: For IFR method
-
g2dcrop
¶ crop gaussian FOV parametrisation at sigma.
Type: For IFR method
-
g2dtilt
¶ allow supergauss-fit to be tilted.
Type: For IFR method
-
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.
-
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)
-
doas_data_vec
¶ Return DOAS CD vector (values of
self.doas_series
).
-
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. ifself.data_merged == True
#. Call
det_correlation_image()
: Determination of correlation image usingself.method
(‘ifr’ or ‘pearson’)#. Call
get_fov_shape()
: Identification of FOV shape / extend on image detector either using circular disk approach (ifself.method == 'pearson'
) or 2D (super) Gauss fit (if ``self.method == ‘ifr’).All relevant results are written into
self.calib_data
(which includesDoasFOV
object)
-
run_fov_fine_search
(img_list, doas_series, 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 objects. #. 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:
-
merge_data
(merge_type=None)[source]¶ Merge stack data and DOAS vector in time.
Wrapper for
merge_with_time_series()
ofImgStack
Parameters: merge_type (str) – choose between ``average, interpolation, nearest``
Note
Current data (i.e.
self.img_stack
andself.doas_series
) will be overwritten if merging succeeds.Parameters: merge_type ( str
, optional,) – one of the available merge types, seemergeopt
for valid optionsRaises: 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
(**settings)[source]¶ Find shape of FOV based on correlation image.
Search pixel coordinate of highest correlation in
self.calib_data.fov.corr_img
(usingget_img_maximum()
) and based on that finds FOV shape either using disk approach (ifself.method == 'pearson'
) callingfov_radius_search()
or using 2D Gauss fit (ifself.method == 'ifr'
) callingfov_gauss_fit()
. Results are written intoself.calib_data.fov
(DoasFOV
object)Parameters: **settings – update current settings (keyword args passed to
update_search_settings()
)
-
fov_radius_search
(cx, cy)[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:
-
Emission rate retrieval¶
Pyplis module containing methods and classes for emission-rate retrievals.
-
class
pyplis.fluxcalc.
OutputERA
(out_dir=None, overlay_optflow=True, img_vmin=None, img_vmax=None)[source]¶ Class for specifying default output for emission rate analyses.
Note
This class is under development and not intended to be used currently
-
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 containingLineOnImage
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 inLineOnImage`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 caseref_check_mode
is active. All images which show average CDs lower than this thresh withinbg_roi_abs
are disregarded for the analysis - ref_check_upper_lim (float) – upper required limit for CDs in
bg_roi_abs
area in caseref_check_mode
is active. All images which show average CDs larger than this thresh withinbg_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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
bg_roi_abs
¶ Return current background reference ROI.
-
ref_check_mode
¶ Activate / deactivate reference area control mode.
-
velo_mode_glob
¶ Attribute velo_glob for velocity analysis retrieval.
-
velo_mode_flow_raw
¶ Attribute velo_glob for velocity analysis retrieval.
-
velo_mode_flow_histo
¶ Attribute for velocity analysis retrieval.
-
velo_mode_flow_hybrid
¶ Attribute for velocity analysis retrieval.
-
velo_glob
¶ Global velocity in m/s, assigned to this line.
Raises: AttributeError – if current value is not of type float
-
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
- pcs_lines –
-
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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
start
¶ Acquisistion time of first image.
-
stop
¶ Start acqusition time of last image.
-
start_acq
¶ Array containing acquisition time stamps.
-
phi
¶ Array containing emission rates.
-
phi_err
¶ Array containing emission rate errors.
-
velo_eff
¶ Array containing effective plume velocities.
-
velo_eff_err
¶ Array containing effective plume velocitie errors.
-
as_series
¶ Emission rates as pandas Series.
-
meta_header
¶ Return string containing available meta information.
Returns: string containing relevant meta information (e.g. for txt export) Return type: str
-
default_save_name
¶ Return default name for txt export.
-
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: tuple
-
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
-
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
-
dphi
¶ Return attr. phi, as this class represents ratios.
-
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 ofLineOnImage
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
andcalib_mode
can be activated. If emission rate retrieval is supposed to be performed using optical flow, then alsooptflow_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 aLineOnImage
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).-
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
-
pcs_lines
¶ Return dict containing PCS retrieval lines assigned to settings class.
-
velo_glob
¶ Global velocity.
-
velo_glob_err
¶ Return error of current global velocity.
-
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
-
get_pix_dist_info_all_lines
()[source]¶ Retrieve pixel distances and uncertainty for all pcs lines.
Returns: 2-element tuple containing Return type: tuple
-
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 inimglist
), 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 usingvelo_mode = flow_histo
. If no significant overlap can be detected, theLocalPlumeProperties
object in the correspondingLineOnImage
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 inself.settings.velo_modes
. The results for each line and velocity mode are stored withinEmissionRates
objects which are saved inself.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
Return type: - start_index (int) – index of first considered image in
-
add_pcs_line
(line)[source]¶ Add one analysis line to this list.
Parameters: line (LineOnImage) – the line object
-
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
- imglist (ImgList) – onband image list prepared such, that at least
-
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.
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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
line_ids
¶ Get IDs of all
LineOnImage
objects for distance retrieval.
-
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 toget_topo_distances_line()
inMeasGeometry
-
det_topo_dists_line
(line_id, **settings)[source]¶ Estimate distances to pixels on current lines.
Retrieves distances to all
LineOnImage
objects inself.lines
usingself.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()
inMeasGeometry
)
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:
-
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.
Uses
dilution_corr_fit()
ofoptimisation
which is a bounded least square fit based on the following model functionParameters: - img (Img) – vignetting corrected image for radiance extraction
- rad_ambient (float) – ambient intensity ( in model)
- i0_guess (float) – optional: guess value for initial intensity of topographic
features, i.e. the reflected radiation before entering scattering
medium ( 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 ( 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
ofPlumeBackgroundModel
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 coefficientsi0
: retrieved initial intensitiesia
: 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 descriptionReturns: dilution corrected image Return type: Img
-
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
- lines (list) – optional, list containing
-
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 orImg
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 moduleoptimisation
)
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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
start
¶ x, y coordinates of start point (
[x0, y0]
).
-
stop
¶ x, y coordinates of stop point (
[x1, y1]
).
-
center_pix
¶ Return coordinate of center pixel.
-
normal_orientation
¶ Get / set value for orientation of normal vector.
-
line_frame
¶ ROI framing the line (in line coordinate system).
-
line_frame_abs
¶ ROI framing the line (in absolute coordinate system).
-
roi_def
¶ ROI in which line is defined (at current
pyrlevel
).
-
roi_abs_def
¶ Return current ROI (in absolute detector coordinates).
-
pyrlevel
¶ Pyramid level at which line coords are defined.
-
roi_abs
¶ Return current ROI (in absolute detector coordinates).
-
pyrlevel_def
¶ Pyramid level at which line coords are defined.
-
coords
¶ Return coordinates as ROI list.
-
rect_roi_rot
¶ Rectangle specifying coordinates of ROI aligned with line normal.
-
velo_glob
¶ Global velocity in m/s, assigned to this line.
Raises: AttributeError – if current value is not of type float
-
velo_glob_err
¶ Error of global velocity in m/s, assigned to this line.
Raises: AttributeError – if current value is not of type float
-
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: Returns: shifted line
Return type:
-
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: Returns: True if point is in image, False if not
Return type:
-
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: 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
attributeParameters: 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: - roi (list) – ROI rectangle
-
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.
-
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
- array (array) – 2D data array (e.g. image data). Color images are converted into
gray scale using
-
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
- img_arr (ndarray) – if specified, the array is plotted using
-
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
(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
-
norm
¶ Return length of line in pixels.
-
normal_vector
¶ Get normal vector corresponding to current orientation setting.
-
complex_normal
¶ Return current normal vector as complex number.
-
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)
-
from_dict
(settings_dict)[source]¶ Load line parameters from dictionary.
Parameters: settings_dict (dict) – dictionary containing line parameters (cf. to_dict()
)
-
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: - id ("on") (str) – string identification of this object for working environment
- type ("on") (str) – Type of object (choose from “on” and “off”)
- acronym ("") (str) – acronym for identification in filename
- meas_type_acro ("") (str) – acronym for meastype identification in filename
- center_wavelength (nan) (str) – center transmission wavelength of filter
-
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
objectNote
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
-
-
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)
-
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=<type 'numpy.float32'>, stack_id='', 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 image4.
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=<type 'numpy.float32'>, stack_id='', img_prep=None, camera=None, **stack_data)[source]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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:
-
last_index
¶ Return last index.
-
start
¶ Return start time stamp of first image.
-
stop
¶ Return start time stamp of first image.
-
time_stamps
¶ Acq. time stamps of all images.
-
pyrlevel
¶ Gauss pyramid level of images in stack.
-
camera
¶ Camera object assigned to stack.
-
num_of_imgs
¶ Depth of stack.
-
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 typeImg
) - 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 arraystack
, 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
- img_arr (array) – image data (must have same dimension than
-
make_circular_access_mask
(cx, cy, radius)[source]¶ Create a circular mask for stack.
Parameters: Returns: circular mask (use e.g. like
img[mask]
which will return a 1D vector containing all pixel values ofimg
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 Return type: tuple
-
apply_mask
(mask)[source]¶ Convolves the stack data with a input mask along time axis.
- mask : array
- 2D bool mask for image pixel access
Returns: 3-element tuple containing Return type: 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 dataarray
: 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 typeDoasResults
ofpydoas
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
- average: determine new stack containing images averaged based
on start / stop time stamps of each datapoint in input
- **kwargs – additional keyword args specifying additional merge settings (e.g.
itp_type=quadratic
in casemethod=interpolation
is used)
Returns: 2-element tuple containing
ImgStack
: new stack containing merged dataSeries
: merged time series data
Return type:
-
crop_other_tseries
(time_series)[source]¶ Crops other time series object based on start / stop time stamps.
-
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
-
get_nearest_img
(time_stamp)[source]¶ Return stack image which is nearest to input timestamp.
Searches the nearest image(s) with respect to input datetime(s)
Parameters: ndarray) time_stamps ((datetime,) – the actual time stamp(s) (for instance from another time series object)
-
sum
(*args, **kwargs)[source]¶ Sum over all pixels of stack.
Parameters: 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
- *args –
-
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
- *args –
-
shape
¶ Return stack shape.
-
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()
-
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
-
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
- data (ndarray) – data array
(is passed into pandas Series init ->
-
texps
= None¶
-
std
= None¶
-
img_prep
= {}¶
-
roi_abs
= None¶
-
start
¶
-
stop
¶
-
get_data_normalised
(texp=None)[source]¶ Normalise the mean value to a given exposure time.
Parameters: texp (None) (float) – 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
-
Fitting / Optimisation algorithms¶
Module containing optimisation routines.
-
pyplis.optimisation.
dilution_corr_fit
(rads, dists, rad_ambient, i0_guess=None, i0_min=0.0, i0_max=None, ext_guess=0.0001, ext_min=0.0, ext_max=0.001)[source]¶ Perform least square fit on data.
Parameters: - rads (ndarray) – vector containing measured radiances
- dists (ndarray) – vector containing corresponding dictances
- rad_ambient (float) – 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 (float) – minimum initial intensity of topographic features
- i0_max (float) – maximum initial intensity of topographic features
- ext_guess (float) – guess value for atm. extinction coefficient
- ext_min (float) – minimum value for atm. extinction coefficient
- ext_max (float) – maximum value for atm. extinction coefficient
-
pyplis.optimisation.
gauss_fit_2d
(img_arr, cx, cy, g2d_asym=True, g2d_super_gauss=True, g2d_crop=True, g2d_tilt=False, **kwargs)[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: Returns: optimised parameters of gauss
Return type: array
-
pyplis.optimisation.
get_histo_data
(data, **kwargs)[source]¶ Determine histogram of data and set bin array to center of bins.
-
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 arbitrary amounts 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 usingestimate_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 (seefind_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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
residual
¶ Get and return residual.
-
data_grad
¶ Gradient of analysis signal.
-
data_grad_smooth
¶ Smoothed gradient of analysis signal.
-
data_smooth
¶ Smooth data using Gaussian kernel of width
self.sigma_smooth
.
-
min_amp
¶ Minimum required amplitude to idenitify significant peaks.
-
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
-
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]
- amp_range (array) – accepted amplitude range, defaults to
-
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:
-
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 inself.gauss_bounds
.Note
If any of the parameters in
params
is out of the acceptance borders specified inself.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 Return type: tuple
-
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:
-
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.
- add_params : list
- 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
Return type: bool
-
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 range.Parameters: sigma_tol ( float
, optional) – sigma tolerance level for finding overlapping Gaussians, if None, usesigma_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 bygaussians()
.
- list, integral values of each of the overlapping sub regions
Return type: tuple
-
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, usesigma_tol_overlaps
.Returns: 4-element tuple containing Return type: tuple
-
analyse_fit_result_old
(sigma_tol=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, usesigma_tol_overlaps
.Returns: 4-element tuple containing Return type: tuple
-
integrate_gauss
(amp, mu, sigma, start=-inf, stop=inf)[source]¶ Return integral value of one Gaussian.
Parameters:
-
integrate_all_gaussians
(params=None)[source]¶ Determine the integral values of all Gaussians in
self.gaussians
.Returns list: integral values for each Gaussian
-
create_test_data_singlegauss
(add_noise=True, noise_frac=0.05)[source]¶ Make a test data set containing a single Gaussian (without offset).
The parameters of the Gaussian are
[300, 150, 20]
Parameters:
-
create_test_data_multigauss
(add_noise=True, noise_frac=0.03)[source]¶ Create test data set containing 5 overlapping Gaussians.
Parameters:
-
create_test_data_multigauss2
(add_noise=True, noise_frac=0.03)[source]¶ Create test data set containing 5 overlapping Gaussians.
Parameters:
-
apply_binomial_filter
(data=None, sigma=1)[source]¶ Return filtered data using 1D gauss filter.
Parameters: Returns: smoothed data array
Return type: array
-
first_derivative
(data=None)[source]¶ Determine and return first derivatieve of data.
The derivative is determined using the numpy method
gradient()
Parameters: data ( array
, optional) – data to be smoothed, if None, useself.data
Returns: array containing gradients Return type: array
-
set_noise_amp
(ampl)[source]¶ Set the current fit amplitude threshold.
Parameters: ampl (float) – amplitude of noise level
-
estimate_noise_amp
(sigma_gauss=3, sigma_tol=3, cut_out_width=None)[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 (float) – factor by which noise signal standard deviation is multiplied in order to estimate noise amplitude
- cut_out_width – 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.
Returns: 3-element tuple containing
Return type:
-
num_of_gaussians
¶ Get the current number of Gaussians, which is the length.
Returns: - float,
len(self.params) // 3
- float,
-
max_amp
¶ Get the max amplitude of the current fit results.
-
y_range
¶ Range of y values.
-
x_range
¶ Range of x values.
-
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
- params (list) – Multi gauss parameters, if None, use
-
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:
-
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: 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 GaussianReturn 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: 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 GaussianReturn 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)
-
plot_multi_gaussian
(x=None, params=None, ax=None, color='r', 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
- x (array) – x data array, if None, use
-
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=False, figsize=(16, 10))[source]¶ Plot the current fit result.
Parameters: add_single_gaussians (bool) – if True, all individual Gaussians are plotted
-
gauss_str
(g)[source]¶ Return string representation of a Gaussian.
Parameters: g (list) – gauss parameter list [amp, mu, sigma]
-
has_data
¶ Return True, if data available, else False.
-
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]¶ x.__init__(…) initializes x; see help(type(x)) for signature
-
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 imageParameters: - 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: - data_arr (array) – image data (can also be
-
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:
-
exclude_pix_range_circ
(x0, y0, r)[source]¶ Add a circular pixel area which will be excluded from the fit.
Parameters:
-
pyr_down
(arr, steps)[source]¶ Reduce the image size using Gaussian pyramide.
Parameters: steps (int) – steps down in the pyramide Algorithm used:
cv2.pyrDown()
Mathematical model functions¶
Pyplis module containing mathematical model functions.
-
class
pyplis.model_functions.
CalibFuns
[source]¶ Class containing functions for fit of calibration curve.
-
available_poly_orders
(through_origin=False)[source]¶ Return the available polynomial orders.
- through_origin : bool
- polys without offset
Returns: list containing available polyorders Return type: list
-
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)Returns: Return type: the function object
-
-
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 (in Campion et al., 2015 denoted with ).
-
pyplis.model_functions.
gaussian_no_offset
(x, ampl, mu, sigma)[source]¶ 1D gauss with baseline zero.
Parameters: Returns float: value at position x
-
pyplis.model_functions.
gaussian
(x, ampl, mu, sigma, offset)[source]¶ 1D gauss with arbitrary baseline.
Parameters: 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:
- Peak amplitude: 100, Mu: 10, sigma: 3
- 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.
get_all_files_in_dir
(directory, file_type=None, include_sub_dirs=False)[source]¶ Find all files in a certain directory.
Parameters: Returns: sorted list containing paths of all files detected
Return type:
-
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.
get_camera_info
(cam_id)[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)[source]¶ Save new default camera to data file cam_info.txt.
Parameters: info_dict (dict) – dictionary containing camera default information Only valid keys will be added to the
-
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:
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: Returns: 2-element tuple, containing:
- ndarray, image data
- dict, dictionary containing meta information
Return type:
-
pyplis.custom_image_import.
load_comtessa
(file_path, meta=None)[source]¶ Load image from a multi-layered fits file (several images in one file).
Meta data is available only inside the header.
This corresponds to image data from the COMTESSA project at Norwegian Institute for Air Research.
Note
The comtessa *.fits files have several timestamps: 1) Filename –> minute in which the image was saved. 2) Meta information in the image header –> computer time when the image was saved. 3) First 14 image pixels contain a binary timestamp –> time when exposure was finished. Here nr 3) is saved as meta[‘stop_acq’]. meta[‘start_acq’] is calculated from meta[‘stop_acq’] and meta[‘texp’]. meta[‘user_param1’] is the gain (float type).
Parameters: - file_path (string) – image file path
- meta (dictionary) – optional, meta info dictionary to which additional meta information is appended. The image index should be provided with key “fits_idx”.
Returns: - ndarray – image data
- dict – dictionary containing meta information
Helper functions¶
Pyplis module containing all sorts of helper methods.
-
pyplis.helpers.
get_pyr_factor_rel
(img1, img2)[source]¶ Get difference in pyramid level between two input images.
Parameters: - img1 (
Img
orndarray
) – First image - img2 (
Img
orndarray
) – Second image
Raises: ValueError – if image shapes can not be matched by changinf the pyramid level of either of the 2 images
Returns: Difference in Gauss pyramid level of img2 relative to img1, i.e. a negative number means, that :param:`img2` is larger than :param:`img1`
Return type: - img1 (
-
pyplis.helpers.
nth_moment
(index, data, center=0.0, n=0)[source]¶ Determine n-th moment of distribution.
Parameters:
-
pyplis.helpers.
set_ax_lim_roi
(roi, ax, xy_aspect=None)[source]¶ Update axes limits to ROI coords (for image disp).
Note
Hard coded in a rush, probably easier solution to it ;)
Parameters: - roi (list) –
[x0, y0, x1, y1]
- ax (Axes) – the Axes showing the image
Returns: trivial
Return type: Axes
- roi (list) –
-
pyplis.helpers.
closest_index
(time_stamp, time_stamps)[source]¶ Find index of time stamp in array to other time stamp.
Parameters: - time_stamp (datetime) – time stamp for which closest match is searched
- time_stamps (iterable) – ordered list of time stamps to be searched (i.e. first index is earliest, last is latest)
Returns: index of best match
Return type:
-
pyplis.helpers.
to_datetime
(value)[source]¶ Evaluate time and / or date input and convert to datetime.
-
pyplis.helpers.
isnum
(val)[source]¶ Check if input is number (int or float) and not nan.
Returns: bool, True or False
-
pyplis.helpers.
mesh_from_img
(img_arr)[source]¶ Create a mesh from an 2D numpy array (e.g. image).
Parameters: img_arr (ndarray) – 2D numpy array Returns: mesh
-
pyplis.helpers.
make_circular_mask
(h, w, cx, cy, radius, inner=True)[source]¶ Create a circular access mask for accessing certain pixels in an image.
Parameters: Returns: the pixel access mask
Return type: ndarray
-
pyplis.helpers.
get_img_maximum
(img_arr, add_blur=0)[source]¶ Get coordinates of maximum in image.
Parameters: - img_arr (array) – numpy array with image data data
- gaussian_blur (int) – apply gaussian filter before max search
-
pyplis.helpers.
sub_img_to_detector_coords
(img_arr, shape_orig, pyrlevel, roi_abs=None)[source]¶ Convert a shape manipulated image to original detecor coords.
Parameters: Note
Regions outside the ROI are set to 0
-
pyplis.helpers.
check_roi
(roi, shape=None)[source]¶ Check if input fulfills all criteria for a valid ROI.
Parameters: - roi – the ROI candidate to be checked
- shape (tuple) – dimension of image for which the ROI is supposed to be checked (optional)
-
pyplis.helpers.
subimg_shape
(img_shape=None, roi=None, pyrlevel=0)[source]¶ Get shape of subimg after cropping and size reduction.
Parameters: Returns: - tuple, (height, width) of (cropped and) size reduced image
-
pyplis.helpers.
roi2rect
(roi, inverse=False)[source]¶ Convert ROI to rectangle coordinates or vice versa.
Parameters: Returns: - tuple, (x0, y0, w, h) if param
inverse == False
- tuple, (x0, y0, x1, y1) if param
inverse == True
- tuple, (x0, y0, w, h) if param
-
pyplis.helpers.
map_coordinates_sub_img
(pos_x_abs, pos_y_abs, roi_abs=None, pyrlevel=0, inverse=False)[source]¶ Map absolute pixel coordinate to cropped and / or downscaled image.
Parameters: - pos_x_abs (int) – x coordinate in absolute image coords (can also be an array of coordinates)
- pos_y_abs (int) – y coordinate in absolute image coords (can also be an array of coordinates)
- roi_abs (list) – list specifying rectangular ROI in absolute image
coordinates (i.e.
[x0, y0, x1, y1]
) - pyrlevel (list) – level of gauss pyramid
- inverse (bool) – if True, do inverse transformation (False)
-
pyplis.helpers.
map_roi
(roi_abs, pyrlevel_rel=0, inverse=False)[source]¶ Map a list containing start / stop coords onto size reduced image.
Parameters: Returns: - roi coordinates for size reduced image
-
pyplis.helpers.
shifted_color_map
(vmin, vmax, cmap=None)[source]¶ Shift center of a diverging colormap to value 0.
Function to offset the “center” of a colormap. Useful for data with a negative min and positive max and if you want the middle of the colormap’s dynamic range to be at zero level
Parameters: - vmin – lower end of data value range
- vmax – upper end of data value range
- cmap – colormap (if None, use default cmap: seismic)
Returns: - shifted colormap
-
pyplis.helpers.
rotate_xtick_labels
(ax, deg=30, ha='right')[source]¶ Rotate xtick labels in matplotlib axes object.
-
pyplis.helpers.
rotate_ytick_labels
(ax, deg=30, va='bottom')[source]¶ Rotate xtick labels in matplotlib axes object.
-
pyplis.helpers.
bytescale
(data, cmin=None, cmax=None, high=255, low=0)[source]¶ Bytescale an image array.
Byte scales an array (image).
Note
This function was copied from the Python Imaging Library module pilutil in order to ensure stability due to re-occuring problems with the PIL installation / import.
Byte scaling means converting the input image to uint8 dtype and scaling the range to
(low, high)
(default 0-255). If the input image already has dtype uint8, no scaling is done.Parameters: - data (ndarray) – image data array
- cmin – optional, bias scaling of small values. Default is
data.min()
- cmin – optional, bias scaling of large values. Default is
data.max()
- high – optional, scale max value to high. Default is 255
- low – optional, scale min value to low. Default is 0
Returns: - uint8, byte-scaled 2D numpy array
Examples
>>> from pyplis.helpers import bytescale >>> img = np.array([[ 91.06794177, 3.39058326, 84.4221549 ], ... [ 73.88003259, 80.91433048, 4.88878881], ... [ 51.53875334, 34.45808177, 27.5873488 ]]) >>> bytescale(img) array([[255, 0, 236], [205, 225, 4], [140, 90, 70]], dtype=uint8) >>> bytescale(img, high=200, low=100) array([[200, 100, 192], [180, 188, 102], [155, 135, 128]], dtype=uint8) >>> bytescale(img, cmin=0, cmax=255) array([[91, 3, 84], [74, 81, 5], [52, 34, 28]], dtype=uint8)
Forms and geometrical objects¶
-
class
pyplis.forms.
FormCollectionBase
(forms_dict=None)[source]¶ Abtract base class representing collection of geometrical forms.
Abstract class providing basic functionality for object collections. Note that the basic management functions for adding / deleting forms
add()
,remove()
create the objects based on start (x,y) and stop (x,y) points, i.e. [x0, y0, x1, y1]This class and classes inheriting from it show large similarities to dictionaries
-
tot_num
¶ Return current number of forms in collection.
-
remove
(id)[source]¶ Remove one form from collection.
Parameters: id (str) – string id of the form to be deleted
-
-
class
pyplis.forms.
LineCollection
(forms_dict=None)[source]¶ Class specifying line objects on images.