Overview
A distance map is a raster layer containing the distance to the nearest vector geometry. They are an elemental transforms from rasters to vectors with a range of useful properties.
Creation
For a Vector v read from a shapefile:
# Read Vector from shape file
vec = shapefileToVector("linestring.shp")
A Raster distance map called distance can be created using the mapDistance function:
# Create distance map
distance = vec.mapDistance(0.001)
# Set Raster name
distance.name = 'distance'where the parameter 0.001 is the spatial resolution of the required raster. The shape file here is in the EPSG:4326 projection and to keep the example simple the distance is mapped in decimal degrees. The second line to set the name of the Raster is required for the script operations below.
The resulting distance map is shown below. Yellow areas are furthest from the lines and black is nearest:
Uses
Distance maps are calculated using exact distance formula in Geostack, rather than an iterative method (such as fast marching). As such they provide low error distance values suitable for a wide range of geospatial operations.
A distance map can be used to give a contour a certain distance away from any geometry:
# Create contour
contour = distance.vectorise(0.02)where the parameter 0.02 is the isovalue for the contour, shown as the black line below:
Similarly, the distance raster can be masked to give areas within a certain distance of the lines. The following code evaluates whether the distance map is less than 0.02 and converts the value to a floating-point 0 or 1.
# Apply threshold
threshold = runScript("output = distance < 0.02;", [distance])The resulting threshold raster is shown below:
The gradient of a distance map gives a vector pointing away from the nearest geometry. This property can be used to build a vector in each Raster cell pointing to the nearest geometry, such as with the following script:
// Calculate local gradient
REAL dx = (distance_NE + 2.0*distance_E + distance_SE) -
(distance_NW + 2.0*distance_W + distance_SW);
REAL dy = (distance_SW + 2.0*distance_S + distance_SE) -
(distance_NW + 2.0*distance_N + distance_NE);
// Calculate distance vector
REALVEC2 d = -distance*normalize((REALVEC2)(dx, dy));The vector d calculated in the above script points from the centre of each Raster cell to the nearest geometry:
Signed distance
If a feature thickness is specified for points or line strings, or if polygons are mapped the distance value is signed. Within the polygon or feature the distance is negative, outside the feature the distance is positive. The following shows a distance map from a square polygon with a square hole. Outside the polygon and within the hole the distance is positive, inside the polygon the distance is negative:
Imports
The following imports are required for the examples above:
from geostack.raster import Raster
from geostack.vector import Vector
from geostack.io import shapefileToVector
from geostack.runner import runScript
from geostack.gs_enums import RasterNullValueType, GeometryType