GDAL-VECTOR-CLEAN-COVERAGE(1)

📦

version 3.13.3 · 4 versions

3.13.3 · alpine 3.24, arch rolling, ubuntu stonking (latest)
3.12.4 · fedora 44
3.12.3 · fedora 44
3.12.2 · ubuntu resolute

, in alpine 3.24, arch rolling, ubuntu stonking

👑 GDAL-VECTOR-CLEAN-COVERAGE(1) 👑

okay bestie, welcome to GDAL-VECTOR-CLEAN-COVERAGE(1), straight out of the GDAL section-1 manual 💅 This page is long so it's split into parts — this is part 1, and there's more coming, so don't go anywhere.

🌸 NAME 🌸

gdal-vector-clean-coverage — Remove gaps and overlaps from a polygon dataset 🌈

Added in version 3.12.

✨ SYNOPSIS ✨

Here's the whole lineup, the way the tool itself spits it out, untouched and unmessed-with 🫶:

Usage: gdal vector clean-coverage [OPTIONS] <INPUT> <OUTPUT>

Alter polygon boundaries to make shared edges identical, removing gaps and overlaps

Positional arguments:
  -i, --input <INPUT>                                  Input vector datasets [required] [not available in pipelines]
  -o, --output <OUTPUT>                                Output vector dataset [required] [not available in pipelines]

Common Options:
  -h, --help                                           Display help message and exit
  --json-usage                                         Display usage as JSON document and exit
  --config <KEY>=<VALUE>                               Configuration option [may be repeated]
  -q, --quiet                                          Quiet mode (no progress bar or warning message) [not available in pipelines]

Options:
  -l, --layer, --input-layer <INPUT-LAYER>             Input layer name(s) [may be repeated] [not available in pipelines]
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed) [not available in pipelines]
  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated] [not available in pipelines]
  --lco, --layer-creation-option <KEY>=<VALUE>         Layer creation option [may be repeated] [not available in pipelines]
  --overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
  --update                                             Whether to open existing dataset in update mode [not available in pipelines]
  --overwrite-layer                                    Whether overwriting existing output layer is allowed [not available in pipelines]
  --append                                             Whether appending to existing layer is allowed [not available in pipelines]
                                                       Mutually exclusive with --upsert
  --output-layer <OUTPUT-LAYER>                        Output layer name [not available in pipelines]
  --skip-errors                                        Skip errors when writing features [not available in pipelines]
  --active-layer <ACTIVE-LAYER>                        Set active layer (if not specified, all)
  --snapping-distance <SNAPPING-DISTANCE>              Distance tolerance for snapping nodes
  --merge-strategy <MERGE-STRATEGY>                    Algorithm to assign overlaps to neighboring polygons. MERGE-STRATEGY=longest-border|max-area|min-area|min-index
  --maximum-gap-width <MAXIMUM-GAP-WIDTH>              Maximum width of a gap to be closed

Advanced Options:
  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated] [not available in pipelines]
  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated] [not available in pipelines]
  --output-oo, --output-open-option <KEY>=<VALUE>      Output open options [may be repeated] [not available in pipelines]
  --upsert                                             Upsert features (implies 'append') [not available in pipelines]
                                                       Mutually exclusive with --append

slay. now let's actually read the little menu, because every one of these matters 🔥

🔹 Positional arguments

-i, --input <INPUT> — the input vector datasets. Required, and not available in pipelines.
-o, --output <OUTPUT> — the output vector dataset. Also required, also not available in pipelines.

🔹 Common Options

-h, --help — shows you the help message and peaces out 🙈
--json-usage — dumps the usage as a JSON document and exits, for my structured-data girlies
--config <KEY>=<VALUE> — a configuration option. May be repeated as many times as you need.
-q, --quiet — quiet mode, no progress bar, no warning message. Not available in pipelines.

🔹 Options

-l, --layer, --input-layer <INPUT-LAYER> — input layer name(s). May be repeated. Not available in pipelines.
-f, --of, --format, --output-format <OUTPUT-FORMAT> — the output format, and yes, "GDALG" is allowed 👀 Not available in pipelines.
--co, --creation-option <KEY>=<VALUE> — creation option. May be repeated. Not available in pipelines.
--lco, --layer-creation-option <KEY>=<VALUE> — layer creation option. May be repeated. Not available in pipelines.
--overwrite — whether overwriting an existing output dataset is allowed. Not available in pipelines.
--update — whether to open the existing dataset in update mode. Not available in pipelines.
--overwrite-layer — whether overwriting an existing output layer is allowed. Not available in pipelines.
--append — whether appending to an existing layer is allowed. Not available in pipelines. Mutually exclusive with --upsert — pick a lane bestie, you literally cannot have both.
--output-layer <OUTPUT-LAYER> — the output layer name. Not available in pipelines.
--skip-errors — skip errors when writing features. Not available in pipelines.
--active-layer <ACTIVE-LAYER> — set the active layer (if you don't specify one, it's all of them).
--snapping-distance <SNAPPING-DISTANCE> — the distance tolerance for snapping nodes.
--merge-strategy <MERGE-STRATEGY> — the algorithm that assigns overlaps to neighboring polygons. MERGE-STRATEGY=longest-border|max-area|min-area|min-index.
--maximum-gap-width <MAXIMUM-GAP-WIDTH> — the maximum width of a gap that gets closed.

🔹 Advanced Options

--if, --input-format <INPUT-FORMAT> — input formats. May be repeated. Not available in pipelines.
--oo, --open-option <KEY>=<VALUE> — open options. May be repeated. Not available in pipelines.
--output-oo, --output-open-option <KEY>=<VALUE> — output open options. May be repeated. Not available in pipelines.
--upsert — upsert features (implies 'append'). Not available in pipelines. Mutually exclusive with --append — again, no double-dipping.

💖 DESCRIPTION 💖

okay so here's the vibe 👇

gdal vector clean-coverage modifies the boundaries of a polygonal dataset so that gaps and overlaps between features are removed, and shared edges are defined using the same vertices. The resulting dataset forms a polygonal coverage — and you can absolutely feed that into gdal vector simplify-coverage afterwards. chef's kiss 🎀

You can also use this command as a step of gdal vector pipeline, although it requires loading the entire dataset into memory at once. so, like, be mindful of your RAM, bestie 😭

NOTE: This command requires a GDAL build against the GEOS library (version 3.14 or greater). no GEOS, no clean-coverage, periodt 💀

🦋 GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) 🦋

This program supports serializing the command line as a JSON file using the GDALG output format ✨ The resulting file can then be opened as a vector dataset using the GDALG: GDAL Streamed Algorithm driver, applying the specified pipeline in an on-the-fly / streamed way. it's giving main character energy for real.

NOTE: However, this algorithm is not natively streaming compatible. Consequently an in-memory temporary dataset will be generated, which may cause significant processing time at opening. so the streaming is, um, a little theatrical 🙈

💅 PROGRAM-SPECIFIC OPTIONS 💅

these are the ones that actually shape your polygons, so pay attention bestie 🫶

🍓 `--input-layer`

Specifies the name of the layer to process. By default, all layers will be processed.

🍓 `--maximum-gap-width <MAXIMUM-GAP-WIDTH>`

Defines the largest area that should be considered a "gap" and merged into an adjacent polygon. Gaps will be merged unless a circle with radius larger than the specified tolerance can be inscribed within the gap. The default maximum gap width is zero, meaning that gaps are not closed.

[image] Polygon dataset before cleaning (left), after cleaning with default parameters (center), and after cleaning with --maximum-gap-width 1 (right). ..UNINDENT

🍓 `--merge-strategy <MERGE-STRATEGY>`

Method by which overlaps or gaps should be added to adjacent polygons. Options include:

longest-border (default): add areas to the polygon with which the longest border is shared
max-area: add areas to the largest adjacent polygon
min-area: add areas to the smallest adjacent polygon
min-index: add areas to the adjacent polygon that was read first

[image] Polygon dataset before cleaning (left), after cleaning with "longest-border" merge strategy (center) and --merge-strategy max-area (right). ..UNINDENT

🍓 `--output-layer`

Specifies the name of the layer to which features will be written. By default, the names of the output layers will be the same as the names of the input layers.

🍓 `--snapping-distance <SNAPPING-DISTANCE>`

Controls the node snapping step, when nearby vertices are snapped together. By default, an automatic snapping distance is determined based on an analysis of the input. Set to zero to turn off all snapping.

[image] Polygon dataset before cleaning (left), after cleaning with default snapping distance (center), and a more aggressive --snapping-distance 0.2 (right). Note the movement in the upper-left corner of the polygon on the right. ..UNINDENT

and that's part 1, bestie — part 2 is on its way, so hold that thought 💖

🌈 STANDARD OPTIONS 🌈

These are the ~glow-up~ options every gdal vector tool shares, and bestie they are load-bearing. Read them, love them, use them. 💅

--active-layer <ACTIVE-LAYER> — picks THE layer. Once you name one, only that layer gets processed and every other layer just sits there unbothered, untouched, living its best life. If you don't pass this at all, then literally every layer gets the treatment. 👑
--append — says "yes, we can totally add features onto layer(s) that already exist." Bonus: it also creates the output dataset for you if it isn't there yet. Iconic, self-sufficient behavior. ✨
--co, --creation-option <NAME>=<VALUE> — for fiddling with how the dataset itself gets made. Tons of formats have one or more optional creation options for controlling particulars about the file being created. Example: the GeoPackage driver has creation options that control the version.

You can repeat this one as many times as you want.

Which creation options exist depends entirely on the format driver, and some super simple formats have no creation options at all. You can get a list of what a format supports via the --formats command line option, but ngl the format's own documentation is the definitive source of truth on driver creation options. Go check the Vector drivers format specific documentation for the legal creation options of each format.

Heads up bestie: dataset creation options and layer creation options are different things. Don't mix them up! 🙈

--if, --input-format <format> — the format/driver name that should be attempted when opening the input file(s). Honestly you usually don't need it, but it's there for when automatic driver detection fails to pick the right driver and you need to skip past it. You can repeat this several times to line up several candidate drivers.

That said — plot twist — it does not force those drivers to open the dataset. Some drivers have requirements around file extensions, so no promises, okay? 💀

You can repeat this one.

--lco, --layer-creation-option <NAME>=<VALUE> — for fiddling with how a layer gets made. Plenty of formats have optional layer creation options controlling particulars about the layer created. Example: the GeoPackage driver's layer creation options let you control the feature identifier or the geometry column name, set the identifier or description, etc. 💖

You can repeat this one.

Available layer creation options vary by format driver, and again, some simple formats have zero layer creation options. A format's supported options can be listed with the --formats command line option, but the documentation for the format is the definitive source on driver creation options. See the Vector drivers format specific documentation for legal creation options for each format.

And yes, once more for the people in the back: layer creation options are not the same as dataset creation options. 🫶

--oo, --open-option <NAME>=<VALUE> — dataset open option (format specific, so it depends on the driver you're vibing with).

You can repeat this one.

-f, --of, --format, --output-format <OUTPUT-FORMAT> — which output vector format we're using. If you want to know the allowed values, run:

gdal --formats | grep vector | grep rw | sort

--output-open-option, --output-oo <NAME>=<VALUE> — ✨ added in version 3.12 ✨ — dataset open option for the output dataset (format specific).

You can repeat this one.

--overwrite — lets the program overwrite an existing target file or dataset. Without it, the default behavior is that gdal just errors out the moment the target file or dataset already exists. So if you're seeing an error, bestie... this might be why. 😭
--overwrite-layer — controls whether overwriting the existing output vector layer is allowed.
--skip-errors — ✨ added in version 3.12 ✨ — whether failures to write feature(s) should just be ignored.

Lowkey important: this option sets the size of the transaction unit to one feature at a time, which may cause severe slowdown when inserting into databases. Choose wisely. 💀

--update — whether to open an existing output dataset in update mode.
--upsert — ✨ added in version 3.12 ✨ — a variant of --append where the OGRLayer::UpsertFeature() operation is used to insert or update features instead of appending with OGRLayer::CreateFeature().

Right now this is only implemented in a few drivers: GPKG — GeoPackage vector, Elasticsearch: Geographically Encoded Objects for Elasticsearch, and MongoDBv3 (drivers that implement upsert expose the GDAL_DCAP_UPSERT capability).

The upsert operation uses the FID of the input feature, whenever it's set (and the FID column name is not the empty string), as the key for updating existing features. It is crucial to make sure that the FID in the source and target layers are consistent. Like, genuinely crucial. 👑

For the GPKG driver, it's also possible to upsert features whose FID is unset or non-significant — you can use the --unset-fid option of gdal vector edit to ignore the FID from the source feature — and that works when there's a UNIQUE column that is not the integer primary key.

💯 RETURN STATUS CODE 💯

The program returns status code 0 in case of success, and non-zero in case of error. And yes, non-blocking errors that get emitted as warnings still count as a successful execution. We love a forgiving queen. 🫶

✨ EXAMPLES ✨

🎀 Example 1: Create and then simplify a polygonal coverage

$ gdal vector pipeline read ne_10m_admin_0_countries.shp ! \
                       make-valid ! \
                       clean-coverage ! \
                       simplify-coverage --tolerance 1 ! \
                       write countries.shp

Read it, make it valid, clean that coverage, simplify it with --tolerance 1, and write the whole thing out. Chained with ! like a little pipeline of destiny. Periodt. 🔥

👑 AUTHOR 👑

Dan Baston <dbaston@gmail.com>

📜 COPYRIGHT 📜

1998-2026

Okay bestie that's the whole page, you made it to the end, I'm so proud. 🦋 This came from the GDAL source/version manual page and is dated Aug 18, 2026 — go forth and clean those coverages, main character. 💖✨🌸

📦 where this page comes from

alpine 3.24: gdal-doc 3.13.3-r0 · MIT
arch rolling: gdal 3.13.3-6 · MIT
ubuntu stonking: gdal-bin 3.13.3+dfsg-1ubuntu4 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms

GDAL-VECTOR-CLEAN-COVERAGE(1)

👑 GDAL-VECTOR-CLEAN-COVERAGE(1) 👑

🌸 NAME 🌸

✨ SYNOPSIS ✨

🔹 Positional arguments

🔹 Common Options

🔹 Options

🔹 Advanced Options

💖 DESCRIPTION 💖

🦋 GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) 🦋

💅 PROGRAM-SPECIFIC OPTIONS 💅

🍓 --input-layer

🍓 --maximum-gap-width <MAXIMUM-GAP-WIDTH>

🍓 --merge-strategy <MERGE-STRATEGY>

🍓 --output-layer

🍓 --snapping-distance <SNAPPING-DISTANCE>

🌈 STANDARD OPTIONS 🌈

💯 RETURN STATUS CODE 💯

✨ EXAMPLES ✨

🎀 Example 1: Create and then simplify a polygonal coverage

👑 AUTHOR 👑

📜 COPYRIGHT 📜

🍓 `--input-layer`

🍓 `--maximum-gap-width <MAXIMUM-GAP-WIDTH>`

🍓 `--merge-strategy <MERGE-STRATEGY>`

🍓 `--output-layer`

🍓 `--snapping-distance <SNAPPING-DISTANCE>`