Functions for applying contour tracing to gridded data
Project description
geocontour
Utilities for masking, contour tracing, and geocontour construction for flux calculations from gridded geographic data.
Installation
pip install geocontour
or
pip install git+https://github.com/benkrichman/geocontour.git@main
To run a full test of internal functions (minus cartopy features):
geocontour.tests.full()
Example Use Case
*to reconstruct these examples use (or view)
geocontour.examples.small()
geocontour.examples.large()
mask search
Given a series of lat/lon points constituting a geographical boundary, and a set of gridded data on a lat/lon grid, find an appropriate mask to select gridded data within the boundary:
Use the 'area' approach to mask calculation, defaulting to selection of all cells for which 50% or greater falls withing the boundary. Note that boundary falls outside gridded data bounds at some points.
mask=geocontour.masksearch.area(latitudes,longitudes,boundary)
geocontour.output.plot(latitudes,longitudes,boundary=boundary,mask=mask,title='Example Mask and Boundary',outname='example_small_boundary+mask',outdpi='indep')
contour trace
Given the previously calculated mask, find the outer edge using a contour tracing algorithm:
Use the improved Pavlidis algorithm to trace the contour.
contour,contoursearch=geocontour.contourtrace.pavlidis_imp(mask,latitudes,longitudes)
geocontour.output.plot(latitudes,longitudes,mask=mask,contoursearch=contoursearch,title='Example Contour Search',outname='example_small_contoursearch',outdpi='indep')
geocontour.output.plot(latitudes,longitudes,contour=contour,cells='contour',title='Example Contour',outname='example_small_contour',outdpi='indep')
construct geocontour
Given the previously calculated contour, construct the geocontour to determine contour segment lengths and outward normal vectors:
Use the build function of geocontour to construct the geocontour. Note that the 'simplify' option is used, combining cells with multiple visits into single segments.
geocontour=geocontour.build(contour,latitudes,longitudes,simplify=True)
geocontour.output.plot(latitudes,longitudes,geocontour=geocontour,buffer='on',title='Example Geocontour',outname='example_small_geocontour',outdpi='indep')
project geocontour against map features
Given a large geocontour (in this case, the Mississippi River Basin) project against natural features and political borders (requires cartopy):
geocontour.output.plot(latitudes,longitudes,geocontour=geocontour,title='Example Geocontour\nMississippi River Basin',outname='example_large_geocontour+natfeat',features='natural')
geocontour.output.plot(latitudes,longitudes,geocontour=geocontour,title='Example Geocontour\nMississippi River Basin',outname='example_large_geocontour+bordfeat',features='borders')
Features
Masks
Selectable criteria for masks created from input boundary coordinates
- cell center
- area ratio
- node ratio
Useful mask operators
- return mask connectivity (and null connectivity)
- return mask edge cells
- return mask vertex points
Contours
Implements 4 existing algorithms for contour tracing, and two improvements on known algorithms
- square tracing [^IPP][^Toussaint]
- moore neighbor tracing [^IPP][^Toussaint]
- improved moore neighbor tracing (capturing inside corners)
- pavlidis tracing [^IPP][^Pavlidis]
- improved pavlidis tracing (capturing inside corners)
- fast representative tracing [^FRT]
Tuning of contours created from tracing input masks
- trace direction
- selectable and adjustable stopping conditions
- automatic or manual selection of starting cell
- selectable connection type (cell to cell or cell edge to cell center)
- simplification of output contour (removal of repeating cells)
- selectable contour closure
- usable for an associated lat/lon grid or on a non-specified grid
Useful contour operators
- return full search path for a contour trace
- return cell neighbors with connectivity and directional input
- return starting cell for contour tracing and check that starting cells work for a given algorithm
Geocontours
From an input contour, create a closed geospatial contour with calculated segment lengths and outward unit vectors (for example: useful in calculating flux across a bounding surface from a geospatial data set)
Options for tuning criteria of geocontours created from input contours
- selectable connection type (cell to cell or cell edge to cell center)
- optionally simplify geocontours at the cell level to shorten and improve compute times in practical applications
Visualization
Easy and semi-automated plotting function for visualization of boundaries/masks/contours/contour searches/geocontours
- buffers
- grid overlay
- mask cell visibility
- directional indicators for contours and contour searches
- outward unit vector indicators for geocontours
- automatic calculation of feature size and output resolution
- display of natural features or political boundaries (optional with cartopy installed)
- selectable marker/line/arrow/cell size/color/style
Function Overview
*to see full function documentation use
help(geocontour.module.function)
check
geocontour.check.cdim()
Checks an input dimension array for 1-dimensionality and regular spacing
geocontour.check.cboundary()
Checks a list of boundary points for 2-dimensionality and proper ordering
geocontour.check.cmask()
Checks a mask for correct data type and dimensionality, and size if optional latitudes and longitudes are provided
geocontour.check.ccontour()
Check contour for repeating cells, closure, and connectivity, and latitude/longitude range if optional latitudes and longitudes are provided
geocontour.check.cgeocontour()
Check geocontour for latitude/longitude range and dimension
grid
geocontour.grid.spacing()
Returns the grid spacing for a given input dimension
geocontour.grid.lonlens()
Returns the lengths of a degree (default) of longitude over a range of latitudes [^Osborne]
geocontour.grid.latlens()
Returns the grid lengths of a defined range of latitudes [^Osborne]
geocontour.grid.lonlen()
Returns the length of a degree of longitude at the input latitude [^Osborne]
geocontour.grid.latlen()
Returns the length of a degree of latitude at the input latitude [^Osborne]
geocontour.grid.areas()
Returns the cell areas of a grid defined by a range of latitudes and longitudes
geocontour.grid.clonrng()
Returns a descriptor for the range of a set of longitude points
- negative (-180 to 180), positive (0 to 360), or indeterminate (0 to 180) range
geocontour.grid.clatdir()
Returns a descriptor for the direction of a set of latitude points (increasing or decreasing)
geocontour.grid.switchlon()
Returns a set of longitude points switched in place between negative (-180 to 180) and positive (0 to 360)
geocontour.grid.switchind()
Returns the index where a longitude array either crosses 0 or 180 degrees
masksearch
geocontour.masksearch.center()
Returns a mask over a range of input latitudes and longitudes determined by an input boundary
- Critera for inclusion of a cell is whether the center of the cell falls within the boundary
geocontour.masksearch.center2()
Returns a mask over a range of input latitudes and longitudes determined by an input boundary
- Critera for inclusion of a cell is whether the center of the cell falls within the boundary
- Functionally matches geocontour.masksearch.center(), but utilizes matplotlib.path functions, which are probably optimized and thus is roughly 2.5*sqrt(N) faster for N points, though lacks a "precision" buffer input
geocontour.masksearch.nodes()
Returns a mask over a range of input latitudes and longitudes determined by an input boundary
- Critera for inclusion of a cell is whether a given number (default=2) of cell nodes (corners) fall within the boundary
geocontour.masksearch.nodes2()
Returns a mask over a range of input latitudes and longitudes determined by an input boundary
- Critera for inclusion of a cell is whether a given number (default=2) of cell nodes (corners) fall within the boundary
- Functionally matches geocontour.masksearch.nodes(), but utilizes matplotlib.path functions, though speed is similar to the shapely implementation
geocontour.masksearch.area()
Returns a mask over a range of input latitudes and longitudes determined by an input boundary
- Critera for inclusion of a cell is whether the area of the cell enclosed by the boundary is greater than some fraction (default=0.5)
maskutil
geocontour.maskutil.bbox()
Checks input dimensions (lat/lon) against input boundary and returns min/max indicies of bounding box
geocontour.maskutil.edge()
Returns a mask of only the edge cells, and if latitudes and longitudes are provided also returns an array of the edge cells
geocontour.maskutil.vertex()
Returns the vertex points of all cells in the input mask, and the vertex points of only the mask edge
geocontour.maskutil.neighbors()
Returns the neighbors of a cell, with selected connectivity and direction
geocontour.maskutil.conn()
Returns whether a mask or its inverse are connected
contourtrace
geocontour.contourtrace.square()
Returns the contour trace of a mask input using the square tracing algorithm [^IPP][^Toussaint]
geocontour.contourtrace.moore()
Returns the contour trace of a mask input using the Moore neighbor tracing algorithm [^IPP][^Toussaint]
geocontour.contourtrace.moore_imp()
Returns the contour trace of a mask input using an improved Moore neighbor tracing algorithm
- Captures inside corners missed by Moore neighbor tracing
geocontour.contourtrace.pavlidis()
Returns the contour trace of a mask input using the Pavlidis tracing algorithm [^IPP][^Pavlidis]
geocontour.contourtrace.pavlidis_imp()
Returns the contour trace of a mask input using an improved Pavlidis tracing algorithm
- Captures inside corners missed by Pavlidis tracing
geocontour.contourtrace.TSR()
Returns the contour trace of a mask input using two-step representative tracing [^FRT]
contourutil
geocontour.contourutil.findstart()
Returns a starting cell for a contour, given a mask and a search criteria
geocontour.contourutil.parsestart()
Checks start input for contour tracing
- Mainly used internally for contour trace functions
geocontour.contourutil.setstop()
Returns a stopping function for use in contour tracing while loop
- Mainly used internally for contour trace functions
geocontour.contourutil.clean()
Returns a cleaned contour that will pass checks
- Mainly used internally for contour trace functions
geocontour
geocontour.build()
Returns a geocontour from a contour input
output
geocontour.output.plot()
Plots any/all geocontour-created elements: boundary, mask, contour, contoursearch, geocontour, vertices
geocontour.output.save()
Saves any/all geocontour-created elements: boundary, mask, contour, contoursearch, geocontour, vertices
tests
geocontour.tests.full()
Runs all user-facing geocontour functions with test data, printing/saving results
examples
geocontour.examples.small()
Runs a small scale example of geocontour processing using mock data, saves resulting plots to run directory
- find mask using area criteria (0.5) and plot boundary/mask
- trace contour using improved pavlidis algorithm and plot resultant contour and contour search
- compute geocontour from contour and plot, using simplify option
geocontour.examples.large()
Runs a large scale example of geocontour processing using the Mississippi River Basin boundary, saves resulting plots to run directory
- find mask using area criteria (0.5) and plot boundary/mask
- trace contour using improved pavlidis algorithm and plot resultant contour and contour search
- compute geocontour from contour and plot, using simplify option
- plot geocontour with cartopy background options (borders and physical features) - will error and exit if cartopy not installed
- plots will be large (dpi is auto-calculated to create enough resolution to zoom in for diagnostic use - this setting can be changed for quick plotting)
[^IPP]:Contour Tracing Algorithms, Pattern Recognition Project [^Toussaint]:Grids Connectivity and Contour Tracing, Lesson Notes [^Pavlidis]:Algorithms for Graphics and Image Processing, doi:10.1007/978-3-642-93208-3 [^FRT]:Fast Contour-Tracing Algorithm Based on a Pixel-Following Method for Image Sensors, doi:10.3390/s16030353 [^Kovalevsky]:Other Source to Note: Vladimir Kovalevsky [^Osborne]:The Mercator Projections doi:10.5281/ZENODO.35392
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
Built Distribution
Hashes for geocontour-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 94e6b0484e2deaf86e71801f4988f3267f2003ac7e2214ab20950dec2f32ef35 |
|
MD5 | fef0171fed713719a081a91e70424735 |
|
BLAKE2b-256 | b67ed916a1af0dca14096f64d9f00ac4d2894c83abd8dcad3b5a86aeb16b1a29 |