geocontour 1.0.0

Functions for applying contour tracing to gridded data

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