You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sedona.apache.org by ji...@apache.org on 2026/10/14 03:52:41 UTC
(sedona) branch master updated: [DOCS] Correct 2.0 migration and raster examples (#3452)
This is an automated email from the ASF dual-hosted git repository.
jiayuasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sedona.git
The following commit(s) were added to refs/heads/master by this push:
new 3959bd52fb8 [DOCS] Correct 2.0 migration and raster examples (#3452)
3959bd52fb8 is described below
commit 3959bd52fb82748a07a62f97451a4eeedf05b448
Author: Jia Yu <ji...@apache.org>
AuthorDate: Tue Oct 13 20:52:34 2026 -0700
[DOCS] Correct 2.0 migration and raster examples (#3452)
---
.../sedona/common/raster/RasterBandEditors.java | 7 ++++---
docs/api/flink/Overlay-Functions/ST_SharedPaths.md | 20 ++++++++++++--------
.../vector-data/Overlay-Functions/ST_SharedPaths.md | 20 ++++++++++++--------
docs/api/sql/Overlay-Functions/ST_SharedPaths.md | 20 ++++++++++++--------
docs/api/sql/Raster-Band-Accessors/RS_ZonalStats.md | 10 +++++++---
.../sql/Raster-Band-Accessors/RS_ZonalStatsAll.md | 10 +++++++---
docs/api/sql/Raster-Operators/RS_AsRaster.md | 14 +++++++++++---
docs/api/sql/Raster-Operators/RS_Clip.md | 12 +++++++++---
.../Raster-Operators/RS_ReplaceBandNoDataValue.md | 2 +-
docs/api/sql/Raster-Operators/RS_SetValues.md | 12 +++++++++---
docs/image/ST_SharedPaths/ST_SharedPaths.svg | 4 ++--
.../ST_SharedPaths/ST_SharedPaths_multipart.svg | 6 +++---
.../ST_SharedPaths_point_intersections.svg | 8 ++++----
docs/setup/migration-2.0.md | 13 ++++++++-----
docs/setup/release-notes.md | 7 +++++--
15 files changed, 106 insertions(+), 59 deletions(-)
diff --git a/common/src/main/java/org/apache/sedona/common/raster/RasterBandEditors.java b/common/src/main/java/org/apache/sedona/common/raster/RasterBandEditors.java
index f91397161bd..e810e3a2172 100644
--- a/common/src/main/java/org/apache/sedona/common/raster/RasterBandEditors.java
+++ b/common/src/main/java/org/apache/sedona/common/raster/RasterBandEditors.java
@@ -77,9 +77,10 @@ public class RasterBandEditors {
/**
* Moves a band's no-data value to {@code noDataValue}, rewriting every pixel that holds the
- * current no-data value to the new one first, so the same pixels read as no-data before and
- * after. A pixel holds the current no-data value by {@link RasterUtils#isNoData}: compared
- * numerically, with any NaN matching a NaN no-data value.
+ * current no-data value to the new one first. Pixels already equal to the new value also become
+ * no-data. To preserve the same no-data mask, choose a value exactly representable in the band's
+ * pixel type and absent from valid pixels. A pixel holds the current no-data value by {@link
+ * RasterUtils#isNoData}: compared numerically, with any NaN matching a NaN no-data value.
*
* @param raster Source raster
* @param bandIndex Band whose no-data value is replaced (1-based)
diff --git a/docs/api/flink/Overlay-Functions/ST_SharedPaths.md b/docs/api/flink/Overlay-Functions/ST_SharedPaths.md
index fe2bcda975f..f4cb9018f57 100644
--- a/docs/api/flink/Overlay-Functions/ST_SharedPaths.md
+++ b/docs/api/flink/Overlay-Functions/ST_SharedPaths.md
@@ -32,6 +32,9 @@ a `GeometryCollection` containing exactly two `MultiLineString` elements. The fi
traversed in the same direction by both inputs; the second contains paths traversed in opposite
directions. Coordinates in both elements follow the direction of `A`.
+Use `ST_GeometryN(result, 1)` to access the first element and `ST_GeometryN(result, 2)` to
+access the second.
+
For non-simple inputs that traverse the same path more than once, direction follows the first
matching source traversal. Consequently, swapping `A` and `B` can change which result element
contains a path.
@@ -50,8 +53,8 @@ are empty `MultiLineString` geometries.
### Same and opposite directions
Input `B` first follows `A`, leaves it, and later traverses another part of `A` backwards. The
-single result therefore populates both direction buckets. Notice that the path in element 1 is
-reoriented to follow `A`, even though `B` traverses it in the opposite direction.
+single result therefore populates both direction buckets. Notice that the path in the second
+element is reoriented to follow `A`, even though `B` traverses it in the opposite direction.
@@ -59,7 +62,7 @@ reoriented to follow `A`, even though `B` traverses it in the opposite direction
Input `A` can be a `MultiLineString`. In this example, `B` shares part of two different components
of `A`. The vertex at `(90 161)` belongs to `B` and splits the shared diagonal into two paths in
-element 0.
+the first element.
@@ -76,7 +79,8 @@ Wrap the result in `ST_AsText` to display its two direction buckets as WKT.
### Same direction
-The shared interval is returned in element 0 because both inputs traverse it from left to right.
+The shared interval is returned in the first element because both inputs traverse it from left
+to right.
```sql
SELECT ST_AsText(ST_SharedPaths(
@@ -93,8 +97,8 @@ GEOMETRYCOLLECTION (MULTILINESTRING ((5 0, 10 0)), MULTILINESTRING EMPTY)
### Opposite direction
-The shared interval is returned in element 1 because `B` traverses it from right to left. Its
-coordinates still follow the left-to-right direction of `A`.
+The shared interval is returned in the second element because `B` traverses it from right to
+left. Its coordinates still follow the left-to-right direction of `A`.
```sql
SELECT ST_AsText(ST_SharedPaths(
@@ -174,8 +178,8 @@ digitized consistently in two datasets from a one-way segment digitized in rever
measure how much of an inspected utility route follows its reference alignment in either
direction.
-The following query assumes that a spatial join has already paired candidate segments. Element 0
-measures consistently directed overlap, while element 1 measures reversed overlap:
+The following query assumes that a spatial join has already paired candidate segments. The first
+element measures consistently directed overlap, while the second element measures reversed overlap:
```sql
WITH compared AS (
diff --git a/docs/api/snowflake/vector-data/Overlay-Functions/ST_SharedPaths.md b/docs/api/snowflake/vector-data/Overlay-Functions/ST_SharedPaths.md
index 9a67bc3bb7f..69c3db614e1 100644
--- a/docs/api/snowflake/vector-data/Overlay-Functions/ST_SharedPaths.md
+++ b/docs/api/snowflake/vector-data/Overlay-Functions/ST_SharedPaths.md
@@ -31,6 +31,9 @@ containing exactly two `MultiLineString` elements. The first contains paths trav
direction by both inputs; the second contains paths traversed in opposite directions. Coordinates
in both elements follow the direction of `A`.
+Use `ST_GeometryN(result, 1)` to access the first element and `ST_GeometryN(result, 2)` to
+access the second.
+
For non-simple inputs that traverse the same path more than once, direction follows the first
matching source traversal. Consequently, swapping `A` and `B` can change which result element
contains a path.
@@ -51,8 +54,8 @@ are empty `MultiLineString` geometries.
### Same and opposite directions
Input `B` first follows `A`, leaves it, and later traverses another part of `A` backwards. The
-single result therefore populates both direction buckets. Notice that the path in element 1 is
-reoriented to follow `A`, even though `B` traverses it in the opposite direction.
+single result therefore populates both direction buckets. Notice that the path in the second
+element is reoriented to follow `A`, even though `B` traverses it in the opposite direction.
@@ -60,7 +63,7 @@ reoriented to follow `A`, even though `B` traverses it in the opposite direction
Input `A` can be a `MultiLineString`. In this example, `B` shares part of two different components
of `A`. The vertex at `(90 161)` belongs to `B` and splits the shared diagonal into two paths in
-element 0.
+the first element.
@@ -77,7 +80,8 @@ Wrap the result in `ST_AsText` to display its two direction buckets as WKT.
### Same direction
-The shared interval is returned in element 0 because both inputs traverse it from left to right.
+The shared interval is returned in the first element because both inputs traverse it from left
+to right.
```sql
SELECT ST_AsText(ST_SharedPaths(
@@ -94,8 +98,8 @@ GEOMETRYCOLLECTION (MULTILINESTRING ((5 0, 10 0)), MULTILINESTRING EMPTY)
### Opposite direction
-The shared interval is returned in element 1 because `B` traverses it from right to left. Its
-coordinates still follow the left-to-right direction of `A`.
+The shared interval is returned in the second element because `B` traverses it from right to
+left. Its coordinates still follow the left-to-right direction of `A`.
```sql
SELECT ST_AsText(ST_SharedPaths(
@@ -175,8 +179,8 @@ digitized consistently in two datasets from a one-way segment digitized in rever
measure how much of an inspected utility route follows its reference alignment in either
direction.
-The following query assumes that a spatial join has already paired candidate segments. Element 0
-measures consistently directed overlap, while element 1 measures reversed overlap:
+The following query assumes that a spatial join has already paired candidate segments. The first
+element measures consistently directed overlap, while the second element measures reversed overlap:
```sql
WITH compared AS (
diff --git a/docs/api/sql/Overlay-Functions/ST_SharedPaths.md b/docs/api/sql/Overlay-Functions/ST_SharedPaths.md
index fe2bcda975f..f4cb9018f57 100644
--- a/docs/api/sql/Overlay-Functions/ST_SharedPaths.md
+++ b/docs/api/sql/Overlay-Functions/ST_SharedPaths.md
@@ -32,6 +32,9 @@ a `GeometryCollection` containing exactly two `MultiLineString` elements. The fi
traversed in the same direction by both inputs; the second contains paths traversed in opposite
directions. Coordinates in both elements follow the direction of `A`.
+Use `ST_GeometryN(result, 1)` to access the first element and `ST_GeometryN(result, 2)` to
+access the second.
+
For non-simple inputs that traverse the same path more than once, direction follows the first
matching source traversal. Consequently, swapping `A` and `B` can change which result element
contains a path.
@@ -50,8 +53,8 @@ are empty `MultiLineString` geometries.
### Same and opposite directions
Input `B` first follows `A`, leaves it, and later traverses another part of `A` backwards. The
-single result therefore populates both direction buckets. Notice that the path in element 1 is
-reoriented to follow `A`, even though `B` traverses it in the opposite direction.
+single result therefore populates both direction buckets. Notice that the path in the second
+element is reoriented to follow `A`, even though `B` traverses it in the opposite direction.
@@ -59,7 +62,7 @@ reoriented to follow `A`, even though `B` traverses it in the opposite direction
Input `A` can be a `MultiLineString`. In this example, `B` shares part of two different components
of `A`. The vertex at `(90 161)` belongs to `B` and splits the shared diagonal into two paths in
-element 0.
+the first element.
@@ -76,7 +79,8 @@ Wrap the result in `ST_AsText` to display its two direction buckets as WKT.
### Same direction
-The shared interval is returned in element 0 because both inputs traverse it from left to right.
+The shared interval is returned in the first element because both inputs traverse it from left
+to right.
```sql
SELECT ST_AsText(ST_SharedPaths(
@@ -93,8 +97,8 @@ GEOMETRYCOLLECTION (MULTILINESTRING ((5 0, 10 0)), MULTILINESTRING EMPTY)
### Opposite direction
-The shared interval is returned in element 1 because `B` traverses it from right to left. Its
-coordinates still follow the left-to-right direction of `A`.
+The shared interval is returned in the second element because `B` traverses it from right to
+left. Its coordinates still follow the left-to-right direction of `A`.
```sql
SELECT ST_AsText(ST_SharedPaths(
@@ -174,8 +178,8 @@ digitized consistently in two datasets from a one-way segment digitized in rever
measure how much of an inspected utility route follows its reference alignment in either
direction.
-The following query assumes that a spatial join has already paired candidate segments. Element 0
-measures consistently directed overlap, while element 1 measures reversed overlap:
+The following query assumes that a spatial join has already paired candidate segments. The first
+element measures consistently directed overlap, while the second element measures reversed overlap:
```sql
WITH compared AS (
diff --git a/docs/api/sql/Raster-Band-Accessors/RS_ZonalStats.md b/docs/api/sql/Raster-Band-Accessors/RS_ZonalStats.md
index 42eee22a388..dfcf1a5e963 100644
--- a/docs/api/sql/Raster-Band-Accessors/RS_ZonalStats.md
+++ b/docs/api/sql/Raster-Band-Accessors/RS_ZonalStats.md
@@ -21,10 +21,14 @@
Introduction: This returns a statistic value specified by `statType` over the region of interest defined by `zone`. It computes the statistic from the pixel values within the ROI geometry and returns the result. If the `excludeNoData` parameter is not specified, it will default to `true`. This excludes NoData values from the statistic calculation. Additionally, if the `band` parameter is not provided, band 1 will be used by default for the statistic computation. The valid options for `st [...]
-The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
+For polygon geometries, the `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
-- When true, any pixel touched by the geometry will be included. As in GDAL, a pixel the geometry touches only on its boundary, along an edge or at a corner, is not included, so a geometry that ends exactly on a pixel boundary does not pull in the pixels beyond it.
-- When false (default), only pixels whose centroid intersects with the geometry will be included.
+- When true, pixel selection also includes cells entered by the polygon's boundary, following the [RS_AsRaster](../Raster-Operators/RS_AsRaster.md) rules.
+- When false (default), pixels whose centroid intersects the polygon will be included.
+
+A polygon never selects a pixel it touches only on the pixel's boundary, whichever edge that is. A polygon aligned with grid lines selects only pixels inside it.
+
+Point geometries select the single pixel containing the point under the half-open rule, regardless of `allTouched`. Line rasterization follows the cells entered by its segments rather than requiring a pixel-centre intersection. A point or line lying on an internal grid edge selects the pixel after it in pixel order; one lying on the raster's last edge selects none. A neighboring pixel contacted only at a line endpoint is not selected unless the segment enters it.
diff --git a/docs/api/sql/Raster-Band-Accessors/RS_ZonalStatsAll.md b/docs/api/sql/Raster-Band-Accessors/RS_ZonalStatsAll.md
index c1e614329b9..74e5a92b1f1 100644
--- a/docs/api/sql/Raster-Band-Accessors/RS_ZonalStatsAll.md
+++ b/docs/api/sql/Raster-Band-Accessors/RS_ZonalStatsAll.md
@@ -21,10 +21,14 @@
Introduction: Returns a struct of statistic values, where each statistic is computed over a region defined by the `zone` geometry. The struct has the following schema:
-The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
+For polygon geometries, the `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
-- When true, any pixel touched by the geometry will be included. As in GDAL, a pixel the geometry touches only on its boundary, along an edge or at a corner, is not included, so a geometry that ends exactly on a pixel boundary does not pull in the pixels beyond it.
-- When false (default), only pixels whose centroid intersects with the geometry will be included.
+- When true, pixel selection also includes cells entered by the polygon's boundary, following the [RS_AsRaster](../Raster-Operators/RS_AsRaster.md) rules.
+- When false (default), pixels whose centroid intersects the polygon will be included.
+
+A polygon never selects a pixel it touches only on the pixel's boundary, whichever edge that is. A polygon aligned with grid lines selects only pixels inside it.
+
+Point geometries select the single pixel containing the point under the half-open rule, regardless of `allTouched`. Line rasterization follows the cells entered by its segments rather than requiring a pixel-centre intersection. A point or line lying on an internal grid edge selects the pixel after it in pixel order; one lying on the raster's last edge selects none. A neighboring pixel contacted only at a line endpoint is not selected unless the segment enters it.
diff --git a/docs/api/sql/Raster-Operators/RS_AsRaster.md b/docs/api/sql/Raster-Operators/RS_AsRaster.md
index 11a81d3f0ee..c9e61c79d3b 100644
--- a/docs/api/sql/Raster-Operators/RS_AsRaster.md
+++ b/docs/api/sql/Raster-Operators/RS_AsRaster.md
@@ -24,11 +24,19 @@ Introduction: `RS_AsRaster` converts a vector geometry into a raster dataset by
* `geom`: The geometry to be rasterized.
* `raster`: The reference raster to be used for overlaying the `geom` on.
* `pixelType`: Defines data type of the output raster. This can be one of the following, D (double), F (float), I (integer), S (short), US (unsigned short) or B (byte).
-* `allTouched` (Since: `v1.7.1`): Decides the pixel selection criteria. If set to `true`, the function selects all pixels touched by the geometry, else, selects only pixels whose centroids intersect the geometry. Defaults to `false`. As in GDAL, pixels are half-open: a pixel contains its first edges in pixel order (the left and top edges on a north-up raster) but not its last, so a pixel the geometry touches only on its boundary is not selected, and a polygon whose edges lie on pixel gri [...]
+* `allTouched` (Since: `v1.7.1`): For polygons, `false` selects pixels whose centroids intersect the polygon; `true` also includes cells entered by the polygon's boundary. Defaults to `false`. Point and line selection follows the rules below.
* `value`: The value to be used for assigning pixels covered by the geometry. Defaults to using `1.0` if not provided.
* `noDataValue`: The no data value of the resultant raster. Every pixel the geometry does not cover (including interior holes) is filled with the resolved no data value, which is also recorded as the output band's no data metadata. The value must be representable in `pixelType`: an out-of-range or fractional value for an integer `pixelType`, or a value that is not exactly representable in a floating-point `pixelType` (for example `0.1` in a 32-bit float band), is rejected with an error r [...]
* `useGeometryExtent`: Defines the extent of the resultant raster. When set to `true`, it corresponds to the extent of `geom`, and when set to false, it corresponds to the extent of `raster`. Default value is `true` if not set. When set to `true` and `geom` neither burns nor overlaps any pixel of `raster`, for example a polygon that only touches its boundary or a line along its right or bottom edge, there is nothing to crop to and `RS_AsRaster` returns `null`. A polygon that overlaps a p [...]
+Pixel selection depends on the geometry type:
+
+* A polygon never selects a pixel it touches only on the pixel's boundary, whichever edge that is. A polygon whose edges lie on grid lines selects only pixels inside it.
+* A point selects its containing half-open pixel, regardless of `allTouched`. A pixel contains its first edges in pixel order (the left and top edges on a north-up raster) but not its last. A point on an internal edge or corner selects the pixel after it in pixel order; a point on the raster's last edge selects none.
+* Line rasterization follows the cells entered by its segments rather than requiring a pixel-centre intersection. A segment lying on a grid line selects the pixels after it in pixel order; one lying on the raster's last edge selects none. A neighboring pixel contacted only at a segment endpoint is not selected unless the segment enters it.
+
+For `LineString` geometries, `allTouched=true` can expand the geometry extent at grid boundaries. With `useGeometryExtent=true`, this can change both the output dimensions and the selected pixels.
+
Format:
```
@@ -71,7 +79,7 @@ SQL Example
```sql
SELECT RS_AsRaster(
ST_GeomFromWKT('POLYGON((15 15, 18 20, 15 24, 24 25, 15 15))'),
- RS_MakeEmptyRaster(2, 255, 255, 3, -215, 2, -2, 0, 0, 4326),
+ RS_MakeEmptyRaster(2, 255, 255, 3, 30, 2, -2, 0, 0, 4326),
'D', false, 255.0, 0d
)
```
@@ -89,7 +97,7 @@ With the `noDataValue` omitted, the output inherits the reference band's no data
```sql
SELECT RS_AsRaster(
ST_GeomFromWKT('POLYGON((15 15, 18 20, 15 24, 24 25, 15 15))'),
- RS_SetBandNoDataValue(RS_MakeEmptyRaster(2, 255, 255, 3, -215, 2, -2, 0, 0, 4326), 1, 0),
+ RS_SetBandNoDataValue(RS_MakeEmptyRaster(2, 255, 255, 3, 30, 2, -2, 0, 0, 4326), 1, 0),
'D'
)
```
diff --git a/docs/api/sql/Raster-Operators/RS_Clip.md b/docs/api/sql/Raster-Operators/RS_Clip.md
index 61875207a43..0c7611c6892 100644
--- a/docs/api/sql/Raster-Operators/RS_Clip.md
+++ b/docs/api/sql/Raster-Operators/RS_Clip.md
@@ -23,10 +23,16 @@ Introduction: Returns a raster that is clipped by the given geometry.
If `crop` is not specified then it will default to `true`, meaning it will make the resulting raster shrink to the geometry's extent and if `noDataValue` is not specified then the resulting raster will have the minimum possible value for the band pixel data type.
-The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
+For polygon geometries, the `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
-- When true, any pixel touched by the geometry will be included. As in GDAL, a pixel the geometry touches only on its boundary, along an edge or at a corner, is not included, so a geometry that ends exactly on a pixel boundary does not pull in the pixels beyond it.
-- When false (default), only pixels whose centroid intersects with the geometry will be included.
+- When true, pixel selection also includes cells entered by the polygon's boundary, following the [RS_AsRaster](RS_AsRaster.md) rules.
+- When false (default), pixels whose centroid intersects the polygon will be included.
+
+A polygon never selects a pixel it touches only on the pixel's boundary, whichever edge that is. A polygon aligned with grid lines selects only pixels inside it.
+
+Point geometries select the single pixel containing the point under the half-open rule, regardless of `allTouched`. Line rasterization follows the cells entered by its segments rather than requiring a pixel-centre intersection. A point or line lying on an internal grid edge selects the pixel after it in pixel order; one lying on the raster's last edge selects none. A neighboring pixel contacted only at a line endpoint is not selected unless the segment enters it.
+
+For `LineString` geometries, `allTouched` can also change the rasterization window at grid boundaries and therefore the selected pixels.
!!!Note
- Since `v1.5.1`, if the coordinate reference system (CRS) of the input `geom` geometry differs from that of the `raster`, then `geom` will be transformed to match the CRS of the `raster`. If the `raster` or `geom` doesn't have a CRS then it will default to `4326/WGS84`.
diff --git a/docs/api/sql/Raster-Operators/RS_ReplaceBandNoDataValue.md b/docs/api/sql/Raster-Operators/RS_ReplaceBandNoDataValue.md
index e19e5d5712c..2f62ff0bfe0 100644
--- a/docs/api/sql/Raster-Operators/RS_ReplaceBandNoDataValue.md
+++ b/docs/api/sql/Raster-Operators/RS_ReplaceBandNoDataValue.md
@@ -19,7 +19,7 @@
# RS_ReplaceBandNoDataValue
-Introduction: Moves the no-data value of a band to `noDataValue`, carrying the no-data pixels with it. Every pixel of the band that holds the current no-data value is rewritten to `noDataValue`, which then becomes the band's no-data value, so the same pixels read as no-data before and after the call. [RS_SetBandNoDataValue](RS_SetBandNoDataValue.md), by contrast, changes only the declared value.
+Introduction: Moves the no-data value of a band to `noDataValue`, carrying the no-data pixels with it. Every pixel of the band that holds the current no-data value is rewritten to `noDataValue`, which then becomes the band's no-data value. Pixels that already equal the new value also become no-data; choose a value exactly representable in the band's pixel type and absent from valid pixels to preserve the same no-data mask. [RS_SetBandNoDataValue](RS_SetBandNoDataValue.md), by contrast, c [...]
A pixel holds the current no-data value when it compares equal to it numerically: `-0.0` matches a `0.0` no-data value, and any `NaN` matches a `NaN` no-data value. Other bands are unchanged.
diff --git a/docs/api/sql/Raster-Operators/RS_SetValues.md b/docs/api/sql/Raster-Operators/RS_SetValues.md
index dc5ca542ebb..638cdcf2cfd 100644
--- a/docs/api/sql/Raster-Operators/RS_SetValues.md
+++ b/docs/api/sql/Raster-Operators/RS_SetValues.md
@@ -46,10 +46,16 @@ set to the corresponding value in `newValues`. The `newValues` should be provide
The geometry variant of this function accepts all types of Geometries, and it sets the `newValue` in the specified region under the `geom`.
-The `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
+For polygon geometries, the `allTouched` parameter (Since `v1.7.1`) determines how pixels are selected:
-- When true, any pixel touched by the geometry will be included. As in GDAL, a pixel the geometry touches only on its boundary, along an edge or at a corner, is not included, so a geometry that ends exactly on a pixel boundary does not pull in the pixels beyond it.
-- When false (default), only pixels whose centroid intersects with the geometry will be included.
+- When true, pixel selection also includes cells entered by the polygon's boundary, following the [RS_AsRaster](RS_AsRaster.md) rules.
+- When false (default), pixels whose centroid intersects the polygon will be included.
+
+A polygon never selects a pixel it touches only on the pixel's boundary, whichever edge that is. A polygon aligned with grid lines selects only pixels inside it.
+
+Point geometries select the single pixel containing the point under the half-open rule, regardless of `allTouched`. Line rasterization follows the cells entered by its segments rather than requiring a pixel-centre intersection. A point or line lying on an internal grid edge selects the pixel after it in pixel order; one lying on the raster's last edge selects none. A neighboring pixel contacted only at a line endpoint is not selected unless the segment enters it.
+
+For `LineString` geometries, `allTouched` can also change the rasterization window at grid boundaries and therefore the selected pixels.
!!!note
If the shape of `newValues` doesn't match with provided `width` and `height`, `IllegalArgumentException` is thrown.
diff --git a/docs/image/ST_SharedPaths/ST_SharedPaths.svg b/docs/image/ST_SharedPaths/ST_SharedPaths.svg
index 366eaa48059..7384361a69c 100644
--- a/docs/image/ST_SharedPaths/ST_SharedPaths.svg
+++ b/docs/image/ST_SharedPaths/ST_SharedPaths.svg
@@ -71,11 +71,11 @@
<rect x="710" y="282" width="365" height="270" rx="9" class="panel"/>
<text x="730" y="309" class="panel-title">4 · GeometryCollection output</text>
<rect x="730" y="333" width="325" height="89" rx="7" class="card" stroke="#007a65"/>
- <text x="746" y="357" font-size="13" font-weight="700" fill="#006b58">Element 0 · same direction</text>
+ <text x="746" y="357" font-size="13" font-weight="700" fill="#006b58">First element · same direction</text>
<path d="M765 385 L1015 385" class="same" marker-end="url(#main-arrow-same)"/>
<text x="892" y="411" text-anchor="middle" class="wkt">MULTILINESTRING ((20 0, 30 0))</text>
<rect x="730" y="442" width="325" height="89" rx="7" class="card" stroke="#6f2da8"/>
- <text x="746" y="466" font-size="13" font-weight="700" fill="#6f2da8">Element 1 · opposite direction</text>
+ <text x="746" y="466" font-size="13" font-weight="700" fill="#6f2da8">Second element · opposite direction</text>
<path d="M765 494 L1015 494" class="opposite" marker-end="url(#main-arrow-opposite)"/>
<text x="892" y="520" text-anchor="middle" class="wkt">MULTILINESTRING ((70 0, 80 0))</text>
diff --git a/docs/image/ST_SharedPaths/ST_SharedPaths_multipart.svg b/docs/image/ST_SharedPaths/ST_SharedPaths_multipart.svg
index be554d459f4..8d92c75ca8e 100644
--- a/docs/image/ST_SharedPaths/ST_SharedPaths_multipart.svg
+++ b/docs/image/ST_SharedPaths/ST_SharedPaths_multipart.svg
@@ -61,12 +61,12 @@
<text x="309" y="527" text-anchor="middle" font-size="12" font-weight="700" fill="#006b58">shared triangle edge</text>
<line x1="65" y1="606" x2="95" y2="606" class="input-a"/><text x="104" y="611" font-size="12">A</text>
<line x1="145" y1="606" x2="175" y2="606" class="input-b"/><text x="184" y="611" font-size="12">B</text>
- <line x1="225" y1="606" x2="255" y2="606" class="same"/><text x="264" y="611" font-size="12">element 0 · same</text>
+ <line x1="225" y1="606" x2="255" y2="606" class="same"/><text x="264" y="611" font-size="12">first element · same</text>
<rect x="740" y="335" width="335" height="300" rx="9" class="panel"/>
<text x="760" y="362" class="title">4 · GeometryCollection output</text>
<rect x="760" y="387" width="295" height="174" rx="7" fill="#ffffff" stroke="#007a65" stroke-width="2"/>
- <text x="776" y="412" font-size="13" font-weight="700" fill="#006b58">Element 0 · same direction</text>
+ <text x="776" y="412" font-size="13" font-weight="700" fill="#006b58">First element · same direction</text>
<path d="M800 435 L800 474" class="same" marker-end="url(#multipart-arrow-same)"/>
<text x="820" y="458" class="wkt">(126 156.25, 126 125)</text>
<path d="M1015 501 L961 478" class="same" marker-end="url(#multipart-arrow-same)"/>
@@ -75,7 +75,7 @@
<text x="907" y="525" text-anchor="middle" class="wkt">(101 150, 90 161)</text>
<text x="907" y="545" text-anchor="middle" class="wkt">(90 161, 76 175)</text>
<rect x="760" y="578" width="295" height="39" rx="7" fill="#ffffff" stroke="#6f2da8" stroke-width="2"/>
- <text x="776" y="603" font-size="12" font-weight="700" fill="#6f2da8">Element 1 · MULTILINESTRING EMPTY</text>
+ <text x="776" y="603" font-size="12" font-weight="700" fill="#6f2da8">Second element · MULTILINESTRING EMPTY</text>
<rect x="25" y="660" width="1050" height="135" rx="9" fill="#f8fafc" stroke="#b8c3d1" stroke-width="1.5"/>
<text x="45" y="687" font-size="14" font-weight="700">Exact inputs and output</text>
diff --git a/docs/image/ST_SharedPaths/ST_SharedPaths_point_intersections.svg b/docs/image/ST_SharedPaths/ST_SharedPaths_point_intersections.svg
index b539b49db4b..da4c4b7dc98 100644
--- a/docs/image/ST_SharedPaths/ST_SharedPaths_point_intersections.svg
+++ b/docs/image/ST_SharedPaths/ST_SharedPaths_point_intersections.svg
@@ -44,8 +44,8 @@
<text x="827" y="147" class="heading">4 · Output</text>
<text x="942" y="185" text-anchor="middle" class="caption">A point has no shared length.</text>
<rect x="829" y="205" width="227" height="78" rx="7" fill="#ffffff" stroke="#64748b" stroke-width="1.5"/>
- <text x="942" y="229" text-anchor="middle" class="wkt">Element 0 = MULTILINESTRING EMPTY</text>
- <text x="942" y="257" text-anchor="middle" class="wkt">Element 1 = MULTILINESTRING EMPTY</text>
+ <text x="942" y="229" text-anchor="middle" class="wkt">First = MULTILINESTRING EMPTY</text>
+ <text x="942" y="257" text-anchor="middle" class="wkt">Second = MULTILINESTRING EMPTY</text>
<rect x="25" y="346" width="1050" height="31" rx="6" fill="#e8f1fa" stroke="#91b6d5"/>
<text x="43" y="367" font-size="14" font-weight="700" fill="#234e70">Case 2 · Lines touch at one endpoint</text>
@@ -70,8 +70,8 @@
<text x="827" y="414" class="heading">4 · Output</text>
<text x="942" y="452" text-anchor="middle" class="caption">An endpoint has no shared length.</text>
<rect x="829" y="472" width="227" height="78" rx="7" fill="#ffffff" stroke="#64748b" stroke-width="1.5"/>
- <text x="942" y="496" text-anchor="middle" class="wkt">Element 0 = MULTILINESTRING EMPTY</text>
- <text x="942" y="524" text-anchor="middle" class="wkt">Element 1 = MULTILINESTRING EMPTY</text>
+ <text x="942" y="496" text-anchor="middle" class="wkt">First = MULTILINESTRING EMPTY</text>
+ <text x="942" y="524" text-anchor="middle" class="wkt">Second = MULTILINESTRING EMPTY</text>
<rect x="25" y="618" width="1050" height="128" rx="9" fill="#f8fafc" stroke="#b8c3d1" stroke-width="1.5"/>
<text x="45" y="645" font-size="14" font-weight="700">Exact result for both cases</text>
diff --git a/docs/setup/migration-2.0.md b/docs/setup/migration-2.0.md
index 9cb9272b368..c86a4e2ffc0 100644
--- a/docs/setup/migration-2.0.md
+++ b/docs/setup/migration-2.0.md
@@ -35,9 +35,11 @@ when you upgrade from 1.x. The [release notes](release-notes.md#sedona-200) list
## Element and pixel positions now count from 1
-Four functions used to count positions from 0 and now count from 1, as PostGIS does. This is
-the change most likely to affect existing queries, because the old queries still run: they
-now return the *next* element or pixel, or `NULL` past the end, rather than raising an error.
+Four functions used to count positions from 0 and now count from 1, as PostGIS does. Existing
+queries can still run but return different results: the same positive geometry or ring index
+now selects the previous element. Keeping both positive raster grid coordinates unchanged
+selects a pixel one column to the left and one row up in grid order. An element index or either
+grid coordinate of `0` returns `NULL`. Update existing calls as shown below.
| Function | Sedona 1.x | Sedona 2.0 (= PostGIS) |
|---|---|---|
@@ -48,8 +50,9 @@ now return the *next* element or pixel, or `NULL` past the end, rather than rais
In 2.0, an index of `0`, a negative index, or one past the last element returns `NULL`.
-**What to change:** add 1 to the index or grid coordinate in every call to these four
-functions, whether it's a literal or a column. For example:
+**What to change:** add 1 to the geometry or ring index, or to both the raster column and row
+coordinates (every entry of both coordinate arrays for `RS_Values`), whether they are literals
+or columns. Band arguments were already 1-based and do not change. For example:
```sql
-- Sedona 1.x
diff --git a/docs/setup/release-notes.md b/docs/setup/release-notes.md
index 57c12294ac8..2ff3af2bad8 100644
--- a/docs/setup/release-notes.md
+++ b/docs/setup/release-notes.md
@@ -25,8 +25,11 @@ See [Migrating to Sedona 2.0](migration-2.0.md) for what to check when upgrading
* **Positions count from 1, as in PostGIS**: `ST_GeometryN` and `ST_InteriorRingN` read `n`
1-based, and the grid-coordinate forms of `RS_Value` and `RS_Values` read `(1, 1)` as the
- upper-left pixel. They were 0-based, so existing queries now address the next element or pixel;
- add 1 to the index. An index of `0` or below returns `NULL`.
+ upper-left pixel. They were 0-based: an unchanged positive geometry or ring index selects
+ the previous element; unchanged positive grid coordinates select one column to the left
+ and one row up in grid order. Add 1 to the element index or to both column and row coordinates
+ (each entry of both arrays for `RS_Values`) to preserve the original result. Band arguments
+ remain unchanged. An element index or either grid coordinate of `0` or below returns `NULL`.
* **`RS_Union` and `RS_Union_Aggr` are renamed `RS_Stack` and `RS_Stack_Aggr`**: the functions
stack the bands of several rasters into one raster; they do not merge grids the way a raster
union (PostGIS `ST_Union`) does. The old names are removed, so replace them in queries. The