[GH-2798] Add ST_ShortestLine function (#2806)

Author: jiayuasu

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

@@ -1115,6 +1115,15 @@ public static Geometry closestPoint(Geometry left, Geometry right) {
     }
   }
 
+  public static Geometry shortestLine(Geometry left, Geometry right) {
+    if (left.isEmpty() || right.isEmpty()) {
+      return null;
+    }
+    DistanceOp distanceOp = new DistanceOp(left, right);
+    Coordinate[] closestPoints = distanceOp.nearestPoints();
+    return left.getFactory().createLineString(closestPoints);
+  }
+
   public static Geometry delaunayTriangle(Geometry geometry) {
     return delaunayTriangle(geometry, 0.0, 0);
   }

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

@@ -4195,6 +4195,61 @@ public void closestPointEmpty() {
     assertEquals(expected, e2.getMessage());
   }
 
+  @Test
+  public void shortestLinePointToPoint() {
+    Point point1 = GEOMETRY_FACTORY.createPoint(new Coordinate(0, 0));
+    Point point2 = GEOMETRY_FACTORY.createPoint(new Coordinate(3, 4));
+    String expected = "LINESTRING (0 0, 3 4)";
+    String actual = Functions.shortestLine(point1, point2).toText();
+    assertEquals(expected, actual);
+  }
+
+  @Test
+  public void shortestLinePointToLineString() {
+    Point point = GEOMETRY_FACTORY.createPoint(new Coordinate(160, 40));
+    LineString lineString =
+        GEOMETRY_FACTORY.createLineString(
+            coordArray(10, 30, 50, 50, 30, 110, 70, 90, 180, 140, 130, 190));
+    Geometry result = Functions.shortestLine(point, lineString);
+    assertNotNull(result);
+    assertEquals("LineString", result.getGeometryType());
+    // First point should be on the point geometry, second on the linestring
+    assertEquals(160.0, result.getCoordinates()[0].x, 1e-6);
+    assertEquals(40.0, result.getCoordinates()[0].y, 1e-6);
+  }
+
+  @Test
+  public void shortestLinePolygonToPolygon() {
+    Polygon polygonA =
+        GEOMETRY_FACTORY.createPolygon(coordArray(190, 150, 20, 10, 160, 70, 190, 150));
+    Point point = GEOMETRY_FACTORY.createPoint(new Coordinate(80, 160));
+    Geometry polygonB = Functions.buffer(point, 30);
+    Geometry result = Functions.shortestLine(polygonA, polygonB);
+    assertNotNull(result);
+    assertEquals("LineString", result.getGeometryType());
+    // The length of the shortest line should equal the distance between the polygons
+    assertEquals(Functions.distance(polygonA, polygonB), result.getLength(), 1e-6);
+  }
+
+  @Test
+  public void shortestLineEmptyGeometry() {
+    Point point = GEOMETRY_FACTORY.createPoint(new Coordinate(1, 1));
+    LineString emptyLineString = GEOMETRY_FACTORY.createLineString();
+    assertNull(Functions.shortestLine(point, emptyLineString));
+
+    Polygon emptyPolygon = GEOMETRY_FACTORY.createPolygon();
+    assertNull(Functions.shortestLine(emptyPolygon, emptyLineString));
+  }
+
+  @Test
+  public void shortestLineSameGeometry() {
+    Point point = GEOMETRY_FACTORY.createPoint(new Coordinate(5, 5));
+    Geometry result = Functions.shortestLine(point, point);
+    assertNotNull(result);
+    assertEquals("LINESTRING (5 5, 5 5)", result.toText());
+    assertEquals(0.0, result.getLength(), 1e-6);
+  }
+
   @Test
   public void testZmFlag() throws ParseException {
     int _2D = 0, _3DM = 1, _3DZ = 2, _4D = 3;

docs/api/flink/Geometry-Functions.md

@@ -201,6 +201,7 @@ These functions compute measurements of distance, area, length, and angles.
 | [ST_MinimumClearanceLine](Measurement-Functions/ST_MinimumClearanceLine.md) | Geometry | This function returns a two-point LineString geometry representing the minimum clearance distance of the input geometry. If the input geometry does not have a defined minimum clearance, such as for... | v1.6.1 |
 | [ST_Perimeter](Measurement-Functions/ST_Perimeter.md) | Double | This function calculates the 2D perimeter of a given geometry. It supports Polygon, MultiPolygon, and GeometryCollection geometries (as long as the GeometryCollection contains polygonal geometries)... | v1.7.0 |
 | [ST_Perimeter2D](Measurement-Functions/ST_Perimeter2D.md) | Double | This function calculates the 2D perimeter of a given geometry. It supports Polygon, MultiPolygon, and GeometryCollection geometries (as long as the GeometryCollection contains polygonal geometries)... | v1.7.1 |
+| [ST_ShortestLine](Measurement-Functions/ST_ShortestLine.md) | Geometry | Returns the shortest LineString between two geometries. The line starts on geom1 and ends on geom2. If either geometry is empty, returns null. | v1.9.0 |
 
 ## Geometry Processing
 

docs/api/flink/Measurement-Functions/ST_ShortestLine.md

@@ -0,0 +1,64 @@
+<!--
+ 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_ShortestLine
+
+Introduction: Returns the shortest LineString between two geometries. The line starts on geom1 and ends on geom2. If either geometry is empty, the function returns null.
+
+![ST_ShortestLine](../../../image/ST_ShortestLine/ST_ShortestLine.svg "ST_ShortestLine")
+
+Format: `ST_ShortestLine(geom1: Geometry, geom2: Geometry)`
+
+Return type: `Geometry`
+
+Since: `v1.9.0`
+
+SQL Example:
+
+![ST_ShortestLine Point to Point](../../../image/ST_ShortestLine/ST_ShortestLine_point_point.svg "ST_ShortestLine Point to Point")
+
+```sql
+SELECT ST_ShortestLine(
+        ST_GeomFromText('POINT (0 0)'),
+        ST_GeomFromText('POINT (3 4)')
+)
+```
+
+Output:
+
+```
+LINESTRING (0 0, 3 4)
+```
+
+SQL Example:
+
+![ST_ShortestLine Point to LineString](../../../image/ST_ShortestLine/ST_ShortestLine_point_linestring.svg "ST_ShortestLine Point to LineString")
+
+```sql
+SELECT ST_ShortestLine(
+        ST_GeomFromText('POINT (0 1)'),
+        ST_GeomFromText('LINESTRING (0 0, 1 0, 2 0, 3 0, 4 0, 5 0)')
+)
+```
+
+Output:
+
+```
+LINESTRING (0 1, 0 0)
+```

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

@@ -193,6 +193,7 @@ These functions compute measurements of distance, area, length, and angles.
 | [ST_MinimumClearanceLine](Measurement-Functions/ST_MinimumClearanceLine.md) | This function returns a two-point LineString geometry representing the minimum clearance distance of the input geometry. If the input geometry does not have a defined minimum clearance, such as for... |
 | [ST_Perimeter](Measurement-Functions/ST_Perimeter.md) | This function calculates the 2D perimeter of a given geometry. It supports Polygon, MultiPolygon, and GeometryCollection geometries (as long as the GeometryCollection contains polygonal geometries)... |
 | [ST_Perimeter2D](Measurement-Functions/ST_Perimeter2D.md) | This function calculates the 2D perimeter of a given geometry. It supports Polygon, MultiPolygon, and GeometryCollection geometries (as long as the GeometryCollection contains polygonal geometries)... |
+| [ST_ShortestLine](Measurement-Functions/ST_ShortestLine.md) | Returns the shortest LineString between two geometries. The line starts on geom1 and ends on geom2. If either geometry is empty, returns null. |
 
 ## Geometry Processing
 

docs/api/snowflake/vector-data/Measurement-Functions/ST_ShortestLine.md

@@ -0,0 +1,62 @@
+<!--
+ 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_ShortestLine
+
+Introduction: Returns the shortest LineString between two geometries. The line starts on geom1 and ends on geom2. If either geometry is empty, the function returns null.
+
+![ST_ShortestLine](../../../../image/ST_ShortestLine/ST_ShortestLine.svg "ST_ShortestLine")
+
+Format: `ST_ShortestLine(geom1: Geometry, geom2: Geometry)`
+
+Return type: `Geometry`
+
+SQL Example:
+
+![ST_ShortestLine Point to Point](../../../../image/ST_ShortestLine/ST_ShortestLine_point_point.svg "ST_ShortestLine Point to Point")
+
+```sql
+SELECT ST_ShortestLine(
+        ST_GeomFromText('POINT (0 0)'),
+        ST_GeomFromText('POINT (3 4)')
+)
+```
+
+Output:
+
+```
+LINESTRING (0 0, 3 4)
+```
+
+SQL Example:
+
+![ST_ShortestLine Point to LineString](../../../../image/ST_ShortestLine/ST_ShortestLine_point_linestring.svg "ST_ShortestLine Point to LineString")
+
+```sql
+SELECT ST_ShortestLine(
+        ST_GeomFromText('POINT (0 1)'),
+        ST_GeomFromText('LINESTRING (0 0, 1 0, 2 0, 3 0, 4 0, 5 0)')
+)
+```
+
+Output:
+
+```
+LINESTRING (0 1, 0 0)
+```

docs/api/sql/Geometry-Functions.md

@@ -202,6 +202,7 @@ These functions compute measurements of distance, area, length, and angles.
 | [ST_MinimumClearanceLine](Measurement-Functions/ST_MinimumClearanceLine.md) | Geometry | This function returns a two-point LineString geometry representing the minimum clearance distance of the input geometry. If the input geometry does not have a defined minimum clearance, such as for... | v1.6.1 |
 | [ST_Perimeter](Measurement-Functions/ST_Perimeter.md) | Double | This function calculates the 2D perimeter of a given geometry. It supports Polygon, MultiPolygon, and GeometryCollection geometries (as long as the GeometryCollection contains polygonal geometries)... | v1.7.0 |
 | [ST_Perimeter2D](Measurement-Functions/ST_Perimeter2D.md) | Double | This function calculates the 2D perimeter of a given geometry. It supports Polygon, MultiPolygon, and GeometryCollection geometries (as long as the GeometryCollection contains polygonal geometries)... | v1.7.1 |
+| [ST_ShortestLine](Measurement-Functions/ST_ShortestLine.md) | Geometry | Returns the shortest LineString between two geometries. The line starts on geom1 and ends on geom2. If either geometry is empty, returns null. | v1.9.0 |
 
 ## Geometry Processing
 

docs/api/sql/Measurement-Functions/ST_ShortestLine.md

@@ -0,0 +1,64 @@
+<!--
+ 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_ShortestLine
+
+Introduction: Returns the shortest LineString between two geometries. The line starts on geom1 and ends on geom2. If either geometry is empty, the function returns null.
+
+![ST_ShortestLine](../../../image/ST_ShortestLine/ST_ShortestLine.svg "ST_ShortestLine")
+
+Format: `ST_ShortestLine(geom1: Geometry, geom2: Geometry)`
+
+Return type: `Geometry`
+
+Since: `v1.9.0`
+
+SQL Example:
+
+![ST_ShortestLine Point to Point](../../../image/ST_ShortestLine/ST_ShortestLine_point_point.svg "ST_ShortestLine Point to Point")
+
+```sql
+SELECT ST_ShortestLine(
+        ST_GeomFromText('POINT (0 0)'),
+        ST_GeomFromText('POINT (3 4)')
+)
+```
+
+Output:
+
+```
+LINESTRING (0 0, 3 4)
+```
+
+SQL Example:
+
+![ST_ShortestLine Point to LineString](../../../image/ST_ShortestLine/ST_ShortestLine_point_linestring.svg "ST_ShortestLine Point to LineString")
+
+```sql
+SELECT ST_ShortestLine(
+        ST_GeomFromText('POINT (0 1)'),
+        ST_GeomFromText('LINESTRING (0 0, 1 0, 2 0, 3 0, 4 0, 5 0)')
+)
+```
+
+Output:
+
+```
+LINESTRING (0 1, 0 0)
+```