raster-footprint#

A Python package for creating GeoJSON geometries that bound valid data in geospatial rasters.

What is a raster footprint?#

A raster footprint is one or more polygons that surround valid data in a raster, or a single polygon surrounding the entire raster grid. For example, a single polygon that surrounds the entire raster grid of an ESA WorldCover tile:

ESA WorldCover tile

The raster footprint (red polygon) for an ESA WorldCover tile#

The raster-footprint package generates a GeoJSON representation of the polygon:

{
   "type": "Polygon",
   "coordinates": [
      [
         [120.0, -30.0],
         [120.0, -33.0],
         [123.0, -33.0],
         [123.0, -30.0],
         [120.0, -30.0]
      ]
   ]
}

What are the challenges?#

By definition, GeoJSON geometries contain point sequences with coordinates referenced to the WGS84 (EPSG:4326) datum. However, unlike the ESA WorldCover example above, most geospatial raster products exist in a projected coordinate system that is distorted with respect to WGS84. This leads to gaps between the raster data and the GeoJSON polygons. For exampe, MODIS tiles are in a sinusoidal projection and are distorted when transformed to WGS84. A simple four-corner polygon at the tile corners results in gaps and gores:

A MODIS tile and footprint in WGS84

A MODIS tile and footprint in WGS84#

One way to remove these gaps is to insert additional vertices into the polygon(s) prior to transformation to WGS84. Raster-footprint provides options for densifying by “factor” and by “distance”.

Footprint densified at a 10 km interval ("distance" densification)

Footprint densified at a 10 km interval (“distance” densification)#

Another challege results from the fact that many geospatial rasters contain pixels that do not contain data, commonly termed “nodata” pixels. These nodata pixels are black in our MODIS example. We can exclude them from the footprint:

Footprint excluding nodata pixels

Footprint excluding nodata pixels#

However, this increases the number and complexity of the polygons in the footprint. Our example footprint now contains over 150 polygons and almost 9000 coordinate pairs, resulting in a GeoJSON text file approaching 1 MB in size. Raster-footprint provides options for reducing complexity by removing polygon holes, simplifying the polygons up to an error tolerance, and/or applying a convex hull to the footprint. For our current MODIS example, simplifying with an error tolerance roughly equal to 1 pixel of ground distance reduces the footprint coordinate pair count to under 2000. For a very simple footprint, applying a convex hull along with the same simplification tolerance produces a single polygon with only 25 coordinate pairs:

Convex hull applied to the footprint

Convex hull applied to the footprint#

The challenge is to balance the competing interests of maximizing footprint fidelity to the raster data while limiting footprint complexity by reducing the number of coordinates to a reasonable number. This balance is specific to the application and user preference.

How does the raster-footprint package help?#

The raster-footprint package provides an API for creating footprints with options to tune acceptable projection error and to reduce footprint complexity. With raster-footprint you can:

Use a variety of data sources:

Mitigate projection distortion effects:

  • insert additional polygon vertices via a densification factor or densification distance

Reduce footprint complexity:

  • use the entire raster grid, i.e., include nodata pixels

  • discard polygon holes

  • simplify the polygons with the Douglas-Peucker algorithm

  • apply a convex hull to the footprint

Be selective:

  • choose one or more bands from a multiband raster for footprint creation

Specify a CRS:

  • specify a CRS other than WGS84 for the footprint (caution - invalid GeoJSON!)

Contents:

Indices and tables#