[GH-2799] Add ST_OffsetCurve function

Author: jiayuasu

common/src/main/java/org/apache/sedona/common/Functions.java

@@ -54,6 +54,7 @@
 import org.locationtech.jts.linearref.LengthIndexedLine;
 import org.locationtech.jts.operation.buffer.BufferOp;
 import org.locationtech.jts.operation.buffer.BufferParameters;
+import org.locationtech.jts.operation.buffer.OffsetCurve;
 import org.locationtech.jts.operation.distance.DistanceOp;
 import org.locationtech.jts.operation.distance3d.Distance3DOp;
 import org.locationtech.jts.operation.linemerge.LineMerger;
@@ -424,6 +425,20 @@ else if (singleParam[0].equalsIgnoreCase(listBufferParameters[5])) {
     return bufferParameters;
   }
 
+  public static Geometry offsetCurve(Geometry geometry, double distance) {
+    return offsetCurve(geometry, distance, BufferParameters.DEFAULT_QUADRANT_SEGMENTS);
+  }
+
+  public static Geometry offsetCurve(Geometry geometry, double distance, int quadrantSegments) {
+    if (geometry.isEmpty()) {
+      return null;
+    }
+    BufferParameters bufferParameters = new BufferParameters();
+    bufferParameters.setQuadrantSegments(quadrantSegments);
+    OffsetCurve oc = new OffsetCurve(geometry, distance, bufferParameters);
+    return oc.getCurve();
+  }
+
   public static int bestSRID(Geometry geometry) throws IllegalArgumentException {
     // Shift longitudes if geometry crosses dateline
     if (crossesDateLine(geometry)) {

common/src/test/java/org/apache/sedona/common/FunctionsTest.java

@@ -4250,6 +4250,52 @@ public void shortestLineSameGeometry() {
     assertEquals(0.0, result.getLength(), 1e-6);
   }
 
+  @Test
+  public void offsetCurvePositiveDistance() throws ParseException {
+    // Offset to the left of a horizontal line
+    Geometry line = Constructors.geomFromWKT("LINESTRING (0 0, 10 0)", 0);
+    Geometry result = Functions.offsetCurve(line, 5.0);
+    String actual = Functions.asWKT(result);
+    assertEquals("LINESTRING (0 5, 10 5)", actual);
+  }
+
+  @Test
+  public void offsetCurveNegativeDistance() throws ParseException {
+    // Offset to the right of a horizontal line
+    Geometry line = Constructors.geomFromWKT("LINESTRING (0 0, 10 0)", 0);
+    Geometry result = Functions.offsetCurve(line, -5.0);
+    String actual = Functions.asWKT(result);
+    assertEquals("LINESTRING (0 -5, 10 -5)", actual);
+  }
+
+  @Test
+  public void offsetCurveZeroDistance() throws ParseException {
+    // Zero distance returns a copy of the input
+    Geometry line = Constructors.geomFromWKT("LINESTRING (0 0, 10 0)", 0);
+    Geometry result = Functions.offsetCurve(line, 0.0);
+    String actual = Functions.asWKT(result);
+    assertEquals("LINESTRING (0 0, 10 0)", actual);
+  }
+
+  @Test
+  public void offsetCurveEmptyGeometry() throws ParseException {
+    // Empty geometry returns null
+    Geometry empty = Constructors.geomFromWKT("LINESTRING EMPTY", 0);
+    Geometry result = Functions.offsetCurve(empty, 5.0);
+    assertNull(result);
+  }
+
+  @Test
+  public void offsetCurveWithQuadrantSegments() throws ParseException {
+    // Test with custom quadrant segments
+    Geometry line = Constructors.geomFromWKT("LINESTRING (0 0, 10 0)", 0);
+    Geometry result = Functions.offsetCurve(line, 5.0, 4);
+    assertNotNull(result);
+    // The result should still be a simple offset for a straight line
+    String actual = Functions.asWKT(result);
+    assertEquals("LINESTRING (0 5, 10 5)", actual);
+  }
+
   @Test
   public void testZmFlag() throws ParseException {
     int _2D = 0, _3DM = 1, _3DZ = 2, _4D = 3;

docs/api/flink/Geometry-Functions.md

@@ -221,6 +221,7 @@ These functions compute geometric constructions, or alter geometry size or shape
 | [ST_LabelPoint](Geometry-Processing/ST_LabelPoint.md) | Geometry | `ST_LabelPoint` computes and returns a label point for a given polygon or geometry collection. The label point is chosen to be sufficiently far from boundaries of the geometry. For a regular Polygo... | v1.7.1 |
 | [ST_MinimumBoundingCircle](Geometry-Processing/ST_MinimumBoundingCircle.md) | Geometry | Returns the smallest circle polygon that contains a geometry. The optional quadrantSegments parameter determines how many segments to use per quadrant and the default number of segments is 48. | v1.5.0 |
 | [ST_MinimumBoundingRadius](Geometry-Processing/ST_MinimumBoundingRadius.md) | Struct | Returns a struct containing the center point and radius of the smallest circle that contains a geometry. | v1.5.0 |
+| [ST_OffsetCurve](Geometry-Processing/ST_OffsetCurve.md) | Geometry | Returns a line at a given offset distance from a linear geometry. Positive distance offsets to the left, negative to the right. | v1.9.0 |
 | [ST_OrientedEnvelope](Geometry-Processing/ST_OrientedEnvelope.md) | Geometry | Returns the minimum-area rotated rectangle enclosing a geometry. The rectangle may be rotated relative to the coordinate axes. Degenerate inputs may result in a Point or LineString being returned. | v1.8.1 |
 | [ST_PointOnSurface](Geometry-Processing/ST_PointOnSurface.md) | Geometry | Returns a POINT guaranteed to lie on the surface. | v1.2.1 |
 | [ST_Polygonize](Geometry-Processing/ST_Polygonize.md) | Geometry | Generates a GeometryCollection composed of polygons that are formed from the linework of an input GeometryCollection. When the input does not contain any linework that forms a polygon, the function... | v1.6.0 |

docs/api/flink/Geometry-Processing/ST_OffsetCurve.md

@@ -0,0 +1,52 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# ST_OffsetCurve
+
+Introduction: Returns a line at a given offset distance from a linear geometry. If the distance is positive, the offset is on the left side of the input line; if it is negative, it is on the right side. Returns null for empty geometries.
+
+The optional third parameter `quadrantSegments` controls the number of line segments used to approximate a quarter circle at round joins. The default value is 8.
+
+Format: `ST_OffsetCurve(geometry: Geometry, distance: Double, quadrantSegments: Integer)`
+
+Format: `ST_OffsetCurve(geometry: Geometry, distance: Double)`
+
+Return type: `Geometry`
+
+Since: `v1.9.0`
+
+SQL Example
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), 5.0))
+```
+
+Output: `LINESTRING (0 5, 10 5)`
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), -5.0))
+```
+
+Output: `LINESTRING (0 -5, 10 -5)`
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), 5.0, 4))
+```
+
+Output: `LINESTRING (0 5, 10 5)`

docs/api/snowflake/vector-data/Geometry-Functions.md

@@ -214,6 +214,7 @@ These functions compute geometric constructions, or alter geometry size or shape
 | [ST_MaximumInscribedCircle](Geometry-Processing/ST_MaximumInscribedCircle.md) | Finds the largest circle that is contained within a (multi)polygon, or which does not overlap any lines and points. Returns a row with fields: |
 | [ST_MinimumBoundingCircle](Geometry-Processing/ST_MinimumBoundingCircle.md) | Returns the smallest circle polygon that contains a geometry. |
 | [ST_MinimumBoundingRadius](Geometry-Processing/ST_MinimumBoundingRadius.md) | Returns two columns containing the center point and radius of the smallest circle that contains a geometry. |
+| [ST_OffsetCurve](Geometry-Processing/ST_OffsetCurve.md) | Returns a line at a given offset distance from a linear geometry. Positive distance offsets to the left, negative to the right. |
 | [ST_OrientedEnvelope](Geometry-Processing/ST_OrientedEnvelope.md) | Returns the minimum-area rotated rectangle enclosing a geometry. The rectangle may be rotated relative to the coordinate axes. Degenerate inputs may result in a Point or LineString being returned. |
 | [ST_PointOnSurface](Geometry-Processing/ST_PointOnSurface.md) | Returns a POINT guaranteed to lie on the surface. |
 | [ST_Polygonize](Geometry-Processing/ST_Polygonize.md) | Generates a GeometryCollection composed of polygons that are formed from the linework of an input GeometryCollection. When the input does not contain any linework that forms a polygon, the function... |

docs/api/snowflake/vector-data/Geometry-Processing/ST_OffsetCurve.md

@@ -0,0 +1,50 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# ST_OffsetCurve
+
+Introduction: Returns a line at a given offset distance from a linear geometry. If the distance is positive, the offset is on the left side of the input line; if it is negative, it is on the right side. Returns null for empty geometries.
+
+The optional third parameter `quadrantSegments` controls the number of line segments used to approximate a quarter circle at round joins. The default value is 8.
+
+Format: `ST_OffsetCurve(geometry: Geometry, distance: Double, quadrantSegments: Integer)`
+
+Format: `ST_OffsetCurve(geometry: Geometry, distance: Double)`
+
+Return type: `Geometry`
+
+SQL Example
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), 5.0))
+```
+
+Output: `LINESTRING (0 5, 10 5)`
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), -5.0))
+```
+
+Output: `LINESTRING (0 -5, 10 -5)`
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), 5.0, 4))
+```
+
+Output: `LINESTRING (0 5, 10 5)`

docs/api/sql/Geometry-Functions.md

@@ -223,6 +223,7 @@ These functions compute geometric constructions, or alter geometry size or shape
 | [ST_MaximumInscribedCircle](Geometry-Processing/ST_MaximumInscribedCircle.md) | Struct | Finds the largest circle that is contained within a (multi)polygon, or which does not overlap any lines and points. Returns a row with fields: | v1.6.1 |
 | [ST_MinimumBoundingCircle](Geometry-Processing/ST_MinimumBoundingCircle.md) | Geometry | Returns the smallest circle polygon that contains a geometry. The optional quadrantSegments parameter determines how many segments to use per quadrant and the default number of segments has been ch... | v1.0.1 |
 | [ST_MinimumBoundingRadius](Geometry-Processing/ST_MinimumBoundingRadius.md) | Struct | Returns a struct containing the center point and radius of the smallest circle that contains a geometry. | v1.0.1 |
+| [ST_OffsetCurve](Geometry-Processing/ST_OffsetCurve.md) | Geometry | Returns a line at a given offset distance from a linear geometry. Positive distance offsets to the left, negative to the right. | v1.9.0 |
 | [ST_OrientedEnvelope](Geometry-Processing/ST_OrientedEnvelope.md) | Geometry | Returns the minimum-area rotated rectangle enclosing a geometry. The rectangle may be rotated relative to the coordinate axes. Degenerate inputs may result in a Point or LineString being returned. | v1.8.1 |
 | [ST_PointOnSurface](Geometry-Processing/ST_PointOnSurface.md) | Geometry | Returns a POINT guaranteed to lie on the surface. | v1.2.1 |
 | [ST_Polygonize](Geometry-Processing/ST_Polygonize.md) | Geometry | Generates a GeometryCollection composed of polygons that are formed from the linework of an input GeometryCollection. When the input does not contain any linework that forms a polygon, the function... | v1.6.0 |

docs/api/sql/Geometry-Processing/ST_OffsetCurve.md

@@ -0,0 +1,54 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# ST_OffsetCurve
+
+![ST_OffsetCurve](../../../image/ST_OffsetCurve/ST_OffsetCurve.svg "ST_OffsetCurve")
+
+Introduction: Returns a line at a given offset distance from a linear geometry. If the distance is positive, the offset is on the left side of the input line; if it is negative, it is on the right side. Returns null for empty geometries.
+
+The optional third parameter `quadrantSegments` controls the number of line segments used to approximate a quarter circle at round joins. The default value is 8.
+
+Format: `ST_OffsetCurve(geometry: Geometry, distance: Double, quadrantSegments: Integer)`
+
+Format: `ST_OffsetCurve(geometry: Geometry, distance: Double)`
+
+Return type: `Geometry`
+
+Since: `v1.9.0`
+
+SQL Example
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), 5.0))
+```
+
+Output: `LINESTRING (0 5, 10 5)`
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), -5.0))
+```
+
+Output: `LINESTRING (0 -5, 10 -5)`
+
+```sql
+SELECT ST_AsText(ST_OffsetCurve(ST_GeomFromWKT('LINESTRING(0 0, 10 0)'), 5.0, 4))
+```
+
+Output: `LINESTRING (0 5, 10 5)`

docs/image/ST_OffsetCurve/ST_OffsetCurve.svg

@@ -70,6 +70,7 @@ public static UserDefinedFunction[] getFuncs() {
       new Functions.ST_BestSRID(),
       new Functions.ST_ClosestPoint(),
       new Functions.ST_ShortestLine(),
+      new Functions.ST_OffsetCurve(),
       new Functions.ST_Centroid(),
       new Functions.ST_Collect(),
       new Functions.ST_CollectionExtract(),