Difference

Draft: written, not yet checked by a person Operation · difference

Removes from each feature of a layer the parts covered by a mask layer, keeping what lies outside it.

Pitfall. Functions that work per pair of geometries (SQL, Shapely) subtract one mask feature at a time; union the mask first, or a feature is returned once per mask feature.

Pitfall. Attributes such as lengths and areas are copied, not recalculated, for the remaining parts.

About this operation
Also called	Erase, Pairwise Erase, overlay difference, cut out
Group	`vector/overlay`
Checks	`crs.agreement, geometry.valid, extent.plausible`
Pitfalls	2 listed above
Columbus tool	Not stated
Notes	Not stated
Status	active
Broader	Not stated
Narrower	Not stated
Related	`clip` `intersect`

Parameters

Not stated

Inputs and outputs

Direction	Name	Type	Geometry	Note
Input	`layer`	vector	Not stated	Not stated
Input	`mask`	vector	polygon	Not stated
Output	`output`	vector	Not stated	Not stated

In each engine

Engine	Tool	Parameters	Differences
`apache-sedona`	`sedona.sql.ST_Difference`	`layer` → `a` `mask` → `b`	Per pair of geometries: union the mask first to subtract all of it. A Spark SQL function: arguments are columns or column names, run over a Spark DataFrame.
`gdal`	`gdal vector layer-algebra`	`layer` → `input` `mask` → `method` `output` → `output`	None noted Preset: `{"operation":"erase"}`
`geopandas`	`geopandas.GeoSeries.difference`	`mask` → `other`	Element-wise against another GeoSeries (aligned on the index), or against one geometry; union the mask first to subtract all of it. geopandas.overlay(how='difference') works on whole layers.
`grass`	`v.overlay`	`layer` → `ainput` `mask` → `binput` `output` → `output`	The b input must be areas. Preset: `{"operator":"not"}`
`postgis`	`st_difference`	`layer` → `geom1` `mask` → `geom2`	Per pair of geometries: union the mask first to subtract all of it.
`qgis`	`native:difference`	`layer` → `INPUT` `mask` → `OVERLAY` `output` → `OUTPUT`	None noted
`sf`	`sf::st_difference`	`layer` → `x` `mask` → `y`	With several features in y, returns one result per pair; union y first (st_union) to subtract all of it.
`shapely`	`shapely.difference`	`layer` → `a` `mask` → `b`	Per pair of geometries: union the mask first to subtract all of it.
`terra`	`terra::erase`	`layer` → `x` `mask` → `y`	None noted
`whiteboxtools`	`Erase`	`layer` → `input` `mask` → `erase` `output` → `output`	None noted