From 62c7c1e10a541f93465d85646465d9c6d96ccff5 Mon Sep 17 00:00:00 2001 From: Alex Iannicelli Date: Wed, 12 Aug 2026 15:58:43 -0400 Subject: [PATCH 1/7] Add bathymetry guide page documenting deeper-than coverage semantics Documents the base theme bathymetry feature type: stacked depth levels, the coverage inversion introduced in tf-data-platform#4780, grid chipping, and rendering/query guidance. Links the new page from the base guide overview and sidebar. Refs #479 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alex Iannicelli --- docs/guides/base/bathymetry.mdx | 53 +++++++++++++++++++++++++++++++++ docs/guides/base/index.mdx | 5 ++-- sidebars.js | 1 + 3 files changed, 57 insertions(+), 2 deletions(-) create mode 100644 docs/guides/base/bathymetry.mdx diff --git a/docs/guides/base/bathymetry.mdx b/docs/guides/base/bathymetry.mdx new file mode 100644 index 00000000..d6e1e641 --- /dev/null +++ b/docs/guides/base/bathymetry.mdx @@ -0,0 +1,53 @@ +--- +title: Bathymetry +description: Underwater depth features in the base theme and how their coverage is defined +pagination_label: Base Bathymetry +--- + +# Bathymetry + +The base theme's **bathymetry** feature type provides topographic representations of underwater areas, such as parts of lake beds or ocean floors. The geometries are derived from vectorized bathymetric data products built from [ETOPO1](https://www.ncei.noaa.gov/products/etopo-global-relief-model) and [GLOBathy](https://www.nature.com/articles/s41597-022-01132-9) data. + +Bathymetry features carry Polygon or MultiPolygon geometries and a single classifying property, `depth`, which gives the depth level of the feature in meters below the water surface. See the [bathymetry schema reference](/schema/reference/base/bathymetry/) for the full column definitions. + +## Stacked depth levels + +Bathymetry is delivered as a set of **stacked depth levels** rather than a partition of the seafloor into disjoint depth bands. Each depth level is a coverage polygon set: the features with `depth = d` together cover every point of the earth's surface where the water is **deeper than** `d` meters. + +Because deeper levels are subsets of shallower ones, the levels nest: + +- `depth = 0` covers all water — oceans and the lakes captured by GLOBathy. +- `depth = 200` covers only the water that is deeper than 200 m. +- `depth = 4000` covers only the water that is deeper than 4000 m. + +A point on the ocean floor at 3,500 m depth is therefore covered by every level from 0 up to the deepest level shallower than 3,500 m. Land is not covered by any level. + +To render a classic bathymetric tint map, draw the levels stacked from shallow to deep: paint `depth = 0` first in the lightest color, then paint each successively deeper level on top in a darker color. The `cartography.sort_key` property encodes this recommended drawing order — features with a lower `sort_key` should be drawn first (behind features with a higher `sort_key`). To extract a single disjoint depth *band* instead (for example, water between 200 m and 1000 m deep), subtract the deeper level's coverage from the shallower level's coverage. + +## How the coverage is built + +The raw ETOPO/GLOBathy source product expresses each depth level in the opposite orientation: the source feature for `depth = d` covers everything *shallower* than `d` — which includes all land. Delivered directly, this made the bathymetry layer blanket the entire land surface (see [schema#311](https://github.com/OvertureMaps/schema/issues/311)). + +Overture's pipeline inverts each level ([tf-data-platform#4780](https://github.com/OvertureMaps/tf-data-platform/pull/4780)) so that the published `depth = d` features cover everything *deeper* than `d`: + +1. Source coverage polygons are repaired (`ST_MakeValid`) rather than dropped — dropping a shallow-coverage feature would incorrectly mark its area as deep water. +2. A world grid (1° cells by default, matching how Overture's ocean water polygons are chipped) is intersected with each depth level's coverage. +3. Within each grid cell, the covered ("shallower-than") area is subtracted from the cell, leaving the "deeper-than" remainder. Cells with no source coverage at a level are entirely deeper than that level and pass through whole. +4. Each resulting chip gets a deterministic ID derived from its depth and geometry, and carries through the source `version`, `cartography`, and `sources` provenance. + +## What this means for consumers + +- **Land is not covered.** Bathymetry polygons only exist over water; no masking against land or water layers is needed. +- **Geometries are grid chips.** Instead of a small number of world-spanning multipolygons, each depth level is delivered as many polygons chipped to a roughly 1° grid, the same way Overture's ocean water polygons are delivered. Spatial filters (for example, `bbox` predicates) are much more effective as a result. +- **Semantics are "deeper than."** A feature with `depth = d` means "the water here is deeper than `d` meters," and levels overlap by design. Count on multiple features covering the same point — one per depth level shallower than the water at that point. + +## Data access + +Bathymetry data is available at: + +| provider | location | +| --- | --- | +| Amazon S3 | `s3://overturemaps-us-west-2/release//theme=base/type=bathymetry/*` | +| Azure Blob Storage | `https://overturemapswestus2.blob.core.windows.net/release//theme=base/type=bathymetry/*` | + +See the [base guide overview](./index.mdx) for general information about the base theme, including licensing and release cadence. diff --git a/docs/guides/base/index.mdx b/docs/guides/base/index.mdx index 0d835291..21138456 100644 --- a/docs/guides/base/index.mdx +++ b/docs/guides/base/index.mdx @@ -20,8 +20,9 @@ Some of our schema design choices include: ## In this guide -This overview covers the feature types, dataset construction, and access for the base theme. A dedicated page covers one feature type in more depth: +This overview covers the feature types, dataset construction, and access for the base theme. Dedicated pages cover some feature types in more depth: +- **[Bathymetry](./bathymetry):** Underwater depth features — how the stacked "deeper-than" depth levels work, how the coverage is built, and what it means for rendering and querying. - **[Infrastructure](./infrastructure):** Transit features such as bus stops, platforms, and stations — including how they relate to the places and transportation themes — and entities like mountains that appear in both base and places by design, with example queries. ## Dataset description @@ -31,7 +32,7 @@ This overview covers the feature types, dataset construction, and access for the There are six feature types in the base theme: #### Bathymetry -Bathymetry features provide topographic representations of underwater areas, such as parts of lake beds or ocean floors. The geometries are derived vectorized bathymetric data products from [ETOPO1](https://www.ncei.noaa.gov/products/etopo-global-relief-model) and [GLOBathy](https://www.nature.com/articles/s41597-022-01132-9) data. +Bathymetry features provide topographic representations of underwater areas, such as parts of lake beds or ocean floors. The geometries are derived vectorized bathymetric data products from [ETOPO1](https://www.ncei.noaa.gov/products/etopo-global-relief-model) and [GLOBathy](https://www.nature.com/articles/s41597-022-01132-9) data. Bathymetry is delivered as stacked depth levels, where each feature with `depth = d` covers all water deeper than `d` meters; see the [bathymetry page](./bathymetry) for details. #### Infrastructure Infrastructure features provide basic information about real-world infrastructure entities such as bridges, airports, runways, aerialways, communication towers, and power lines. All of the features are pulled from OpenStreetMap and converted to the Overture schema. See the [infrastructure page](./infrastructure) for a closer look at transit features and how the infrastructure type relates to other themes. diff --git a/sidebars.js b/sidebars.js index 18198094..2029d22d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -58,6 +58,7 @@ const sidebars = { collapsed: true, items: [ 'guides/base/index', + 'guides/base/bathymetry', 'guides/base/infrastructure', ], }, From 5d4d4ee2bc3772d2712fcea119b4acb86026d64b Mon Sep 17 00:00:00 2001 From: Alex Iannicelli Date: Wed, 12 Aug 2026 16:02:57 -0400 Subject: [PATCH 2/7] Remove pipeline implementation detail from bathymetry guide Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alex Iannicelli --- docs/guides/base/bathymetry.mdx | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/guides/base/bathymetry.mdx b/docs/guides/base/bathymetry.mdx index d6e1e641..6e977887 100644 --- a/docs/guides/base/bathymetry.mdx +++ b/docs/guides/base/bathymetry.mdx @@ -24,17 +24,6 @@ A point on the ocean floor at 3,500 m depth is therefore covered by every level To render a classic bathymetric tint map, draw the levels stacked from shallow to deep: paint `depth = 0` first in the lightest color, then paint each successively deeper level on top in a darker color. The `cartography.sort_key` property encodes this recommended drawing order — features with a lower `sort_key` should be drawn first (behind features with a higher `sort_key`). To extract a single disjoint depth *band* instead (for example, water between 200 m and 1000 m deep), subtract the deeper level's coverage from the shallower level's coverage. -## How the coverage is built - -The raw ETOPO/GLOBathy source product expresses each depth level in the opposite orientation: the source feature for `depth = d` covers everything *shallower* than `d` — which includes all land. Delivered directly, this made the bathymetry layer blanket the entire land surface (see [schema#311](https://github.com/OvertureMaps/schema/issues/311)). - -Overture's pipeline inverts each level ([tf-data-platform#4780](https://github.com/OvertureMaps/tf-data-platform/pull/4780)) so that the published `depth = d` features cover everything *deeper* than `d`: - -1. Source coverage polygons are repaired (`ST_MakeValid`) rather than dropped — dropping a shallow-coverage feature would incorrectly mark its area as deep water. -2. A world grid (1° cells by default, matching how Overture's ocean water polygons are chipped) is intersected with each depth level's coverage. -3. Within each grid cell, the covered ("shallower-than") area is subtracted from the cell, leaving the "deeper-than" remainder. Cells with no source coverage at a level are entirely deeper than that level and pass through whole. -4. Each resulting chip gets a deterministic ID derived from its depth and geometry, and carries through the source `version`, `cartography`, and `sources` provenance. - ## What this means for consumers - **Land is not covered.** Bathymetry polygons only exist over water; no masking against land or water layers is needed. From f224314e6ade5f4bbd5235d99d2f4c2c229c9079 Mon Sep 17 00:00:00 2001 From: Alex Iannicelli Date: Wed, 12 Aug 2026 16:05:13 -0400 Subject: [PATCH 3/7] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Alex Iannicelli --- docs/guides/base/bathymetry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/base/bathymetry.mdx b/docs/guides/base/bathymetry.mdx index 6e977887..86542da0 100644 --- a/docs/guides/base/bathymetry.mdx +++ b/docs/guides/base/bathymetry.mdx @@ -22,7 +22,7 @@ Because deeper levels are subsets of shallower ones, the levels nest: A point on the ocean floor at 3,500 m depth is therefore covered by every level from 0 up to the deepest level shallower than 3,500 m. Land is not covered by any level. -To render a classic bathymetric tint map, draw the levels stacked from shallow to deep: paint `depth = 0` first in the lightest color, then paint each successively deeper level on top in a darker color. The `cartography.sort_key` property encodes this recommended drawing order — features with a lower `sort_key` should be drawn first (behind features with a higher `sort_key`). To extract a single disjoint depth *band* instead (for example, water between 200 m and 1000 m deep), subtract the deeper level's coverage from the shallower level's coverage. +To render a classic bathymetric tint map, draw the levels stacked from shallow to deep: paint `depth = 0` first in the lightest color, then paint each successively deeper level on top in a darker color. The `cartography.sort_key` property encodes this recommended stacking — features with a lower `sort_key` should be drawn in front of features with a higher `sort_key`. To extract a single disjoint depth *band* instead (for example, water between 200 m and 1000 m deep), subtract the deeper level's coverage from the shallower level's coverage. ## What this means for consumers From 7143623354ae3ee03fa78face0955023be857cfc Mon Sep 17 00:00:00 2001 From: Alex Iannicelli Date: Wed, 12 Aug 2026 16:09:45 -0400 Subject: [PATCH 4/7] Exclude terminology false positives in textlint config The flagged terms appear in generated schema reference docs as field names (websites), type names (Id), or intentional prose (snake case, key/value pairs), so exclude them rather than editing generated files. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Alex Iannicelli --- .github/linters/.textlintrc.json | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/linters/.textlintrc.json b/.github/linters/.textlintrc.json index 4ef3eab6..f94386c5 100644 --- a/.github/linters/.textlintrc.json +++ b/.github/linters/.textlintrc.json @@ -4,7 +4,13 @@ }, "rules": { "terminology": { - "exclude": ["to-?do(s)?(?=[ ,.])"] + "exclude": [ + "to-?do(s)?(?=[ ,.])", + "key[/ ]?value", + "web[- ]?site(s)?", + "ID", + "snake[- ]?case" + ] } } } From 08fa0d8be91e8f14c415ab0f01fd46a8f9e3c0c1 Mon Sep 17 00:00:00 2001 From: Alex Iannicelli Date: Wed, 12 Aug 2026 16:26:27 -0400 Subject: [PATCH 5/7] Update docs/guides/base/bathymetry.mdx Co-authored-by: Adam Lastowka Signed-off-by: Alex Iannicelli --- docs/guides/base/bathymetry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/base/bathymetry.mdx b/docs/guides/base/bathymetry.mdx index 86542da0..81eaf8f6 100644 --- a/docs/guides/base/bathymetry.mdx +++ b/docs/guides/base/bathymetry.mdx @@ -12,7 +12,7 @@ Bathymetry features carry Polygon or MultiPolygon geometries and a single classi ## Stacked depth levels -Bathymetry is delivered as a set of **stacked depth levels** rather than a partition of the seafloor into disjoint depth bands. Each depth level is a coverage polygon set: the features with `depth = d` together cover every point of the earth's surface where the water is **deeper than** `d` meters. +Bathymetry is delivered as a set of **stacked depth levels**. Each depth level is a coverage polygon set: the features with `depth = d` together cover every point of the earth's surface where the water is **deeper than** `d` meters. Because deeper levels are subsets of shallower ones, the levels nest: From 710eae7dcca4d3268d411fed83a0e5af5a799102 Mon Sep 17 00:00:00 2001 From: Alex Iannicelli Date: Wed, 12 Aug 2026 16:26:55 -0400 Subject: [PATCH 6/7] Update docs/guides/base/bathymetry.mdx Co-authored-by: Adam Lastowka Signed-off-by: Alex Iannicelli --- docs/guides/base/bathymetry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/base/bathymetry.mdx b/docs/guides/base/bathymetry.mdx index 81eaf8f6..d6bc534d 100644 --- a/docs/guides/base/bathymetry.mdx +++ b/docs/guides/base/bathymetry.mdx @@ -14,7 +14,7 @@ Bathymetry features carry Polygon or MultiPolygon geometries and a single classi Bathymetry is delivered as a set of **stacked depth levels**. Each depth level is a coverage polygon set: the features with `depth = d` together cover every point of the earth's surface where the water is **deeper than** `d` meters. -Because deeper levels are subsets of shallower ones, the levels nest: +Practically, this means entities with a lower `depth` will always totally cover entities with a higher `depth`: - `depth = 0` covers all water — oceans and the lakes captured by GLOBathy. - `depth = 200` covers only the water that is deeper than 200 m. From e9d6b239d3e9ea1171e1c2ce68600059c684915e Mon Sep 17 00:00:00 2001 From: Alex Iannicelli Date: Wed, 12 Aug 2026 16:30:36 -0400 Subject: [PATCH 7/7] Update docs/guides/base/bathymetry.mdx Co-authored-by: Adam Lastowka Signed-off-by: Alex Iannicelli --- docs/guides/base/bathymetry.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/base/bathymetry.mdx b/docs/guides/base/bathymetry.mdx index d6bc534d..61e132e4 100644 --- a/docs/guides/base/bathymetry.mdx +++ b/docs/guides/base/bathymetry.mdx @@ -24,7 +24,7 @@ A point on the ocean floor at 3,500 m depth is therefore covered by every level To render a classic bathymetric tint map, draw the levels stacked from shallow to deep: paint `depth = 0` first in the lightest color, then paint each successively deeper level on top in a darker color. The `cartography.sort_key` property encodes this recommended stacking — features with a lower `sort_key` should be drawn in front of features with a higher `sort_key`. To extract a single disjoint depth *band* instead (for example, water between 200 m and 1000 m deep), subtract the deeper level's coverage from the shallower level's coverage. -## What this means for consumers +## Takeaways - **Land is not covered.** Bathymetry polygons only exist over water; no masking against land or water layers is needed. - **Geometries are grid chips.** Instead of a small number of world-spanning multipolygons, each depth level is delivered as many polygons chipped to a roughly 1° grid, the same way Overture's ocean water polygons are delivered. Spatial filters (for example, `bbox` predicates) are much more effective as a result.