Skip to main content

An object-oriented toolset for calculating velocities, surface areas and distances from oblique imagery of glacial environments

Project description

PyTrx

Documentation Status
PyTrx (short for 'Python Tracking') is a Python object-oriented toolbox created for the purpose of calculating real-world measurements from oblique images and time-lapse image series. Its primary purpose is to obtain velocities, surface areas, and distances from imagery of glacial environments.

This branch contains the PyTrx toolset along with the distribution setup for sharing documentation with PyTrx's readthedocs webpages, and the pip package installer.

Authors: Penelope How (how@asiaq.gl), Nick Hulton, and Lynne Buie (née Addison)


PyTrx citations

We are happy for others to use and adapt PyTrx for their own processing needs. If used, please cite the following key publication and Digital Object Identifier:

How et al. (2020) PyTrx: a Python-based monoscopic terrestrial photogrammetry toolset for glaciology. Frontiers in Earth Science, doi:10.3389/feart.2020.00021


PyTrx has been used in the following publications. In addition to the publication above, please cite any that are applicable where possible:

PyTrx used for georectification of glacier calving event locations
How et al. (2019) Calving controlled by melt-undercutting: detailed mechanisms revealed through time-lapse observations. Annals of Glaciology 60 (78), 20-31, doi:10.1017/aog.2018.28

PhD thesis by Penelope How, for which PyTrx was developed primarily
How (2018) Dynamical change at tidewater glaciers examined using time-lapse photogrammetry. PhD thesis, University of Edinburgh, UK, https://hdl.handle.net/1842/31103

PyTrx used for detection of supraglacial lakes and meltwater plumes
How et al. (2017) Rapidly changing subglacial hydrological pathways at a tidewater glacier revealed through simultaneous observations of water pressure, supraglacial lakes, meltwater plumes and surface velocities. The Cryosphere 11, 2691-2710, doi:10.5194/tc-11-2691-2017

MSc thesis by Lynne Buie, where PyTrx was created in its earliest form
Addison (2015) PyTrx: feature tracking software for automated production of glacier velocity. MSc thesis, University of Edinburgh, UK, https://hdl.handle.net/1842/11794


Permissions and acknowledgements

Example image sets distributed with PyTrx were collected as part of CRIOS (Calving Rates and Impact On Sea level), and are used here with permission.

The DEM of the Kongsfjorden area provided as an example dataset for PyTrx originates from the freely available DEM dataset provided by the Norwegian Polar Institute, data product 'S0 Terrengmodell - Delmodell_5m_2009_13822_33 (GeoTIFF)' doi:10.21334/npolar.2014.dce53a47. This data is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.

The DEM of the Tempelfjorden area provided as an example dataset for PyTrx originates from ArcticDEM, Scene ID WV01_20130714_1020010 (July 14, 2013). There is no license for the ArcticDEM data and it can be used and distributed freely. The DEM was created from DigitalGlobe, Inc., imagery and funded under National Science Foundation awards 1043681, 1559691, and 1542736.

Refer to the readme document in the Examples folder of this repository for more information on the DEMs provided and distributed with PyTrx.

Parts of the georectification functions in the PyTrx toolbox were inspired and translated from ImGRAFT, a photogrammetry toolbox for Matlab (Messerli and Grinsted, 2015). Where possible, ImGRAFT has been credited for in the corresponding PyTrx scripts (primarily some passages in the CamEnv.py script) and cited in relevant PyTrx publications.

PyTrx scripts

Detailed documentation is available on the PyTrx readthedocs page. Each script contains classes and functions for handling each aspect needed for photogrammetric processing:

CamEnv.py
Handles the associated data with the camera environment.
The GCPs class handles the Ground Control Points (GCPs) and their correspondence to the associated DEM and CamImage object.
The CamCalib class handles information concerning the camera calibration, i.e. the intrinsic camera matrix and lens distortion coefficients. This class contains functionality for reading in calibration files from .txt and .mat formats.
The CamEnv compiles all the information about the camera environment from the GCPs and CamCalib classes, and also contains information about the camera object (pose and location). This is also where georectification functionality is held, with functions for projection and inverse projection. The class is initialised using a .txt file containing file path directories to all the associated data files.

DEM.py
Handles the DEM data. This currently supports .mat and .tif file types.
The ExplicitRaster class represents a DEM as a numeric raster with explicit XY cell referencing in each grid cell. The class includes functions for densification, calculating viewsheds, and incorporates unbound functions that import a DEM file from .mat and .tif formats.

FileHandler.py
This module contains a set of functions for reading in data from files (such as image data and calibration information) and writing out data.

Images.py
Handles the image data, and the image sequence.
The CamImage class holds information about a singular image and contains functionality for importing image data from file and passing specific image bands forward for subsequent processing.
The ImageSequence class holds information about an image sequence, i.e. a collection of CamImage objects, from which specific images and image pairs can be called.

Velocity.py
Calculates velocities and homography. This can either be achieved through the Velocity class for processing velocities and homography through a series of images, or using the functions provided within the script for processing velocities and homography between an image pair.

Area.py
Automated and manual detection of surface areas from imagery (e.g. supraglacial lakes, meltwater plume surface extent). This can either be achieved through the Area class for defining areas of interest through a series of images, or using the functions provided within the script for defining areas of interest in a single image.

Line.py
Manual detection of line features from imagery (e.g. glacier terminus position). This can either be achieved through the Line class for defining line features through a series of images, or using the functions provided within the script for defining line features in a single image.

Utilities.py
This module contains a set of functions for plotting and interpolating data.

For beginners in programming, it is advised to look at the example applications provided and adapt them accordingly for your own use. For experienced programmers... get stuck in. Feel free to contact us if you run into major problems or have constructive comments that will help us further PyTrx and its capabilities. We will not respond to minor troubleshooting or unconstructive comments.


PyTrx set-up and requirements

PyTrx has been coded with Python 3 and has been tested on Linux and Windows operating systems (it should also work on Apple operating systems too, it just hasn't been tested). PyTrx has the following key dependencies:

OpenCV (v3 and above): opencv.org
GDAL (v2 and above): gisinternals.com
Pillow (PIL) (v5 and above): pythonware.com

PyTrx can either be downloaded directly from the GitHub repository, or installed using a package manager such as conda or pip. If downloading directly from GitHub, be aware that these dependencies may not necessarily be installed with distributions of Python (e.g. PythonXY, Anaconda), so you may have to install them. These can be specified using the .yml environment file provided in this repository. PyTrx has been tried and tested with the following dependency version configuration: OpenCV=3.4.2, GDAL=2.3.2, and PIL=5.3. PyTrx also needs other packages, which are commonly included with distributions of Python: datetime, glob, imghdr, math, Matplotlib, NumPy, operator, os, pathlib, PyLab, SciPy, struct, and sys. Compatibility with all newer versions of these packages are highly likely.

If you are installing PyTrx through a package manager, we recommend using conda. Be aware that the PyTrx example scripts are not included with this distribution of PyTrx given the size of the example dataset files. PyTrx is also available through pip, although difficulties with the GDAL package on pip meant that GDAL could not be declared explicitly as a PyTrx dependency. Please ensure that GDAL is installed separately if installing PyTrx through pip. Please see our readthedocs page on setting up PyTrx for more details.


Links

There are other useful software available for terrestrial photogrammetry in glaciology:

Pointcatcher - Matlab-based GUI toolbox for feature-tracking and georectification
ImGRAFT - Matlab toolbox for feature-tracking and georectification
CIAS - IDL gui for feature-tracking
PRACTISE - Matlab toolbox for georectification


Copyright

PyTrx is licensed under a MIT License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytrx-1.1.0.tar.gz (66.1 kB view hashes)

Uploaded Source

Built Distribution

pytrx-1.1.0-py3-none-any.whl (67.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page