Merge branch 'apache:master' into master

Author: jiayuasu

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

@@ -1812,6 +1812,24 @@ private static Geometry[] convertGeometryToArray(Geometry geom) {
     return array;
   }
 
+  public static Geometry generatePoints(Geometry geom, int numPoints, long seed) {
+    RandomPointsBuilderSeed pointsBuilder = new RandomPointsBuilderSeed(geom.getFactory(), seed);
+    pointsBuilder.setExtent(geom);
+    pointsBuilder.setNumPoints(numPoints);
+    return pointsBuilder.getGeometry();
+  }
+
+  public static Geometry generatePoints(Geometry geom, int numPoints) {
+    return generatePoints(geom, numPoints, 0);
+  }
+
+  public static Geometry generatePoints(Geometry geom, int numPoints, Random random) {
+    RandomPointsBuilderSeed pointsBuilder = new RandomPointsBuilderSeed(geom.getFactory(), random);
+    pointsBuilder.setExtent(geom);
+    pointsBuilder.setNumPoints(numPoints);
+    return pointsBuilder.getGeometry();
+  }
+
   public static Integer nRings(Geometry geometry) throws Exception {
     String geometryType = geometry.getGeometryType();
     if (!(geometry instanceof Polygon || geometry instanceof MultiPolygon)) {

common/src/main/java/org/apache/sedona/common/utils/RandomPointsBuilderSeed.java

@@ -0,0 +1,48 @@
+/*
+ * 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.
+ */
+package org.apache.sedona.common.utils;
+
+import java.util.Random;
+import org.locationtech.jts.geom.*;
+import org.locationtech.jts.shape.random.RandomPointsBuilder;
+
+public class RandomPointsBuilderSeed extends RandomPointsBuilder {
+  Random rand;
+
+  public RandomPointsBuilderSeed(GeometryFactory geometryFactory, long seed) {
+    super(geometryFactory);
+    if (seed > 0) {
+      this.rand = new Random(seed);
+    } else {
+      this.rand = new Random();
+    }
+  }
+
+  public RandomPointsBuilderSeed(GeometryFactory geometryFactory, Random random) {
+    super(geometryFactory);
+    this.rand = random;
+  }
+
+  @Override
+  protected Coordinate createRandomCoord(Envelope env) {
+    double x = env.getMinX() + env.getWidth() * rand.nextDouble();
+    double y = env.getMinY() + env.getHeight() * rand.nextDouble();
+    return createCoord(x, y);
+  }
+}

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

@@ -2112,6 +2112,48 @@ public void minimumClearanceLine() throws ParseException {
     assertEquals(expected, actual);
   }
 
+  @Test
+  public void generatePoints() throws ParseException {
+    Geometry geom = Constructors.geomFromWKT("LINESTRING(50 50,10 10,10 50)", 4326);
+
+    Geometry actual =
+        Functions.generatePoints(Functions.buffer(geom, 10, false, "endcap=round join=round"), 12);
+    assertEquals(actual.getNumGeometries(), 12);
+
+    actual =
+        Functions.reducePrecision(
+            Functions.generatePoints(
+                Functions.buffer(geom, 10, false, "endcap=round join=round"), 5, 100),
+            5);
+    String expected =
+        "MULTIPOINT ((40.02957 46.70645), (37.11646 37.38582), (14.2051 29.23363), (40.82533 31.47273), (28.16839 34.16338))";
+    assertEquals(expected, actual.toString());
+    assertEquals(4326, actual.getSRID());
+
+    geom =
+        Constructors.geomFromEWKT(
+            "MULTIPOLYGON (((10 0, 10 10, 20 10, 20 0, 10 0)), ((50 0, 50 10, 70 10, 70 0, 50 0)))");
+    actual = Functions.generatePoints(geom, 30);
+    assertEquals(actual.getNumGeometries(), 30);
+
+    // Deterministic when using the same seed
+    Geometry first = Functions.generatePoints(geom, 10, 100);
+    Geometry second = Functions.generatePoints(geom, 10, 100);
+    assertEquals(first, second);
+
+    // Deterministic when using the same random number generator
+    geom = geom.buffer(10, 48);
+    Random rand = new Random(100);
+    Random rand2 = new Random(100);
+    first = Functions.generatePoints(geom, 100, rand);
+    second = Functions.generatePoints(geom, 100, rand);
+    Geometry first2 = Functions.generatePoints(geom, 100, rand2);
+    Geometry second2 = Functions.generatePoints(geom, 100, rand2);
+    assertNotEquals(first, second);
+    assertEquals(first, first2);
+    assertEquals(second, second2);
+  }
+
   @Test
   public void nRingsPolygonOnlyExternal() throws Exception {
     Polygon polygon = GEOMETRY_FACTORY.createPolygon(coordArray(1, 0, 1, 1, 2, 1, 2, 0, 1, 0));

docs/api/flink/Function.md

@@ -1552,6 +1552,35 @@ Output:
 5.0990195135927845
 ```
 
+## ST_GeneratePoints
+
+Introduction: Generates a specified quantity of pseudo-random points within the boundaries of the provided polygonal geometry. When `seed` is either zero or not defined then output will be random.
+
+Format:
+
+`ST_GeneratePoints(geom: Geometry, numPoints: Integer, seed: Long = 0)`
+
+`ST_GeneratePoints(geom: Geometry, numPoints: Integer)`
+
+Since: `v1.6.1`
+
+SQL Example:
+
+```sql
+SELECT ST_GeneratePoints(
+        ST_GeomFromWKT('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'), 4
+)
+```
+
+Output:
+
+!!!Note
+    Due to the pseudo-random nature of point generation, the output of this function will vary between executions and may not match any provided examples.
+
+```
+MULTIPOINT ((0.2393028905520183 0.9721563442837837), (0.3805848547053376 0.7546556656982678), (0.0950295778200995 0.2494334895495989), (0.4133520939987385 0.3447046312451945))
+```
+
 ## ST_GeoHash
 
 Introduction: Returns GeoHash of the geometry with given precision

docs/api/snowflake/vector-data/Function.md

@@ -1163,6 +1163,33 @@ Output:
 5.0990195135927845
 ```
 
+## ST_GeneratePoints
+
+Introduction: Generates a specified quantity of pseudo-random points within the boundaries of the provided polygonal geometry. When `seed` is either zero or not defined then output will be random.
+
+Format:
+
+`ST_GeneratePoints(geom: Geometry, numPoints: Integer, seed: Long = 0)`
+
+`ST_GeneratePoints(geom: Geometry, numPoints: Integer)`
+
+SQL Example:
+
+```sql
+SELECT ST_GeneratePoints(
+        ST_GeomFromWKT('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'), 4
+)
+```
+
+Output:
+
+!!!Note
+    Due to the pseudo-random nature of point generation, the output of this function will vary between executions and may not match any provided examples.
+
+```
+MULTIPOINT ((0.2393028905520183 0.9721563442837837), (0.3805848547053376 0.7546556656982678), (0.0950295778200995 0.2494334895495989), (0.4133520939987385 0.3447046312451945))
+```
+
 ## ST_GeoHash
 
 Introduction: Returns GeoHash of the geometry with given precision

docs/api/sql/Function.md

@@ -1557,6 +1557,35 @@ Output:
 5.0990195135927845
 ```
 
+## ST_GeneratePoints
+
+Introduction: Generates a specified quantity of pseudo-random points within the boundaries of the provided polygonal geometry. When `seed` is either zero or not defined then output will be random.
+
+Format:
+
+`ST_GeneratePoints(geom: Geometry, numPoints: Integer, seed: Long = 0)`
+
+`ST_GeneratePoints(geom: Geometry, numPoints: Integer)`
+
+Since: `v1.6.1`
+
+SQL Example:
+
+```sql
+SELECT ST_GeneratePoints(
+        ST_GeomFromWKT('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'), 4
+)
+```
+
+Output:
+
+!!!Note
+    Due to the pseudo-random nature of point generation, the output of this function will vary between executions and may not match any provided examples.
+
+```
+MULTIPOINT ((0.2393028905520183 0.9721563442837837), (0.3805848547053376 0.7546556656982678), (0.0950295778200995 0.2494334895495989), (0.4133520939987385 0.3447046312451945))
+```
+
 ## ST_GeoHash
 
 Introduction: Returns GeoHash of the geometry with given precision

docs/api/sql/Raster-operators.md

@@ -452,14 +452,14 @@ SELECT RS_GeoReferrence(ST_MakeEmptyRaster(1, 3, 4, 100.0, 200.0,2.0, -3.0, 0.1,
 
 ### RS_GeoTransform
 
-Introduction: Returns an array of parameters that represent the GeoTransformation of the raster. The array contains the following values:
+Introduction: Returns a struct of parameters that represent the GeoTransformation of the raster. The struct has the following schema:
 
-- 0: pixel width along west-east axis (x-axis)
-- 1: pixel height along north-south axis (y-axis)
-- 2: Rotation of the raster
-- 3: Angular separation between x-axis and y-axis
-- 4: X ordinate of upper-left coordinate
-- 5: Y ordinate of upper-left coordinate
+- magnitudeI: size of a pixel along the transformed i axis
+- magnitudeJ: size of a pixel along the transformed j axis
+- thetaI: angle by which the raster is rotated (Radians positive clockwise)
+- thetaIJ: angle from transformed i axis to transformed j axis (Radians positive counter-clockwise)
+- offsetX: X ordinate of the upper-left corner of the upper-left pixel
+- offsetY: Y ordinate of the upper-left corner of the upper-left pixel
 
 !!!note
     Refer to [this image](https://www.researchgate.net/figure/Relation-between-the-cartesian-axes-x-y-and-i-j-axes-of-the-pixels_fig3_313860913) for a clear understanding between i & j axis and x & y-axis.
@@ -479,7 +479,7 @@ SELECT RS_GeoTransform(
 Output:
 
 ```
-[2.23606797749979, 2.23606797749979, -1.1071487177940904, -2.214297435588181, 1.0, 2.0]
+{2.23606797749979, 2.23606797749979, -1.1071487177940904, -2.214297435588181, 1.0, 2.0}
 ```
 
 ### RS_Height
@@ -1094,7 +1094,7 @@ Output:
 
 ### RS_SummaryStatsAll
 
-Introduction: Returns summary stats consisting of count, sum, mean, stddev, min, max for a given band in raster. If band is not specified then it defaults to `1`.
+Introduction: Returns summary stats struct consisting of count, sum, mean, stddev, min, max for a given band in raster. If band is not specified then it defaults to `1`.
 
 !!!Note
     If excludeNoDataValue is set `true` then it will only count pixels with value not equal to the nodata value of the raster.
@@ -1122,7 +1122,7 @@ SELECT RS_SummaryStatsAll(RS_MakeEmptyRaster(2, 5, 5, 0, 0, 1, -1, 0, 0, 0), 1,
 Output:
 
 ```
-25.0, 204.0, 8.16, 9.4678403028357, 0.0, 25.0
+{25.0, 204.0, 8.16, 9.4678403028357, 0.0, 25.0}
 ```
 
 SQL Example
@@ -1134,7 +1134,7 @@ SELECT RS_SummaryStatsAll(RS_MakeEmptyRaster(2, 5, 5, 0, 0, 1, -1, 0, 0, 0), 1)
 Output:
 
 ```
-14.0, 204.0, 14.571428571428571, 11.509091348732502, 1.0, 25.0
+{14.0, 204.0, 14.571428571428571, 11.509091348732502, 1.0, 25.0}
 ```
 
 ### RS_ZonalStats
@@ -1207,17 +1207,17 @@ Output:
 
 ### RS_ZonalStatsAll
 
-Introduction: Returns an array of statistic values, where each statistic is computed over a region defined by the `zone` geometry. The array contains the following values:
+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:
 
-- 0: Count of the pixels.
-- 1: Sum of the pixel values.
-- 2: Arithmetic mean.
-- 3: Median.
-- 4: Mode.
-- 5: Standard deviation.
-- 6: Variance.
-- 7: Minimum value of the zone.
-- 8: Maximum value of the zone.
+- count: Count of the pixels.
+- sum: Sum of the pixel values.
+- mean: Arithmetic mean.
+- median: Median.
+- mode: Mode.
+- stddev: Standard deviation.
+- variance: Variance.
+- min: Minimum value of the zone.
+- max: Maximum value of the zone.
 
 !!!note
     If the coordinate reference system (CRS) of the input `zone` geometry differs from that of the `raster`, then `zone` will be transformed to match the CRS of the `raster` before computation.
@@ -1258,7 +1258,7 @@ RS_ZonalStatsAll(rast1, geom1, 1, false)
 Output:
 
 ```
-[184792.0, 1.0690406E7, 57.851021689230684, 0.0, 0.0, 92.13277429243035, 8488.448098819916, 0.0, 255.0]
+{184792.0, 1.0690406E7, 57.851021689230684, 0.0, 0.0, 92.13277429243035, 8488.448098819916, 0.0, 255.0}
 ```
 
 SQL Example
@@ -1270,7 +1270,7 @@ RS_ZonalStatsAll(rast2, geom2, 1, true)
 Output:
 
 ```
-[14184.0, 3213526.0, 226.55992667794473, 255.0, 255.0, 74.87605357255357, 5606.423398599913, 1.0, 255.0]
+{14184.0, 3213526.0, 226.55992667794473, 255.0, 255.0, 74.87605357255357, 5606.423398599913, 1.0, 255.0}
 ```
 
 ## Raster Predicates
@@ -1541,18 +1541,18 @@ Output (Shown as heatmap):
 
 ### RS_MetaData
 
-Introduction: Returns the metadata of the raster as an array of double. The array contains the following values:
+Introduction: Returns the metadata of the raster as a struct. The struct has the following schema:
 
-- 0: upper left x coordinate of the raster, in terms of CRS units
-- 1: upper left y coordinate of the raster, in terms of CRS units
-- 2: width of the raster, in terms of pixels
-- 3: height of the raster, in terms of pixels
-- 4: ScaleX: the scaling factor in the x direction
-- 5: ScaleY: the scaling factor in the y direction
-- 6: skew in x direction (rotation x)
-- 7: skew in y direction (rotation y)
-- 8: srid of the raster
-- 9: number of bands
+- upperLeftX: upper left x coordinate of the raster, in terms of CRS units
+- upperLeftX: upper left y coordinate of the raster, in terms of CRS units
+- gridWidth: width of the raster, in terms of pixels
+- gridHeight: height of the raster, in terms of pixels
+- scaleX: ScaleX: the scaling factor in the x direction
+- scaleY: ScaleY: the scaling factor in the y direction
+- skewX: skew in x direction (rotation x)
+- skewY: skew in y direction (rotation y)
+- srid: srid of the raster
+- numSampleDimensions: number of bands
 
 For more information about ScaleX, ScaleY, SkewX, SkewY, please refer to the [Affine Transformations](Raster-affine-transformation.md) section.
 
@@ -1569,7 +1569,7 @@ SELECT RS_MetaData(raster) FROM raster_table
 Output:
 
 ```
-[-1.3095817809482181E7, 4021262.7487925636, 512.0, 517.0, 72.32861272132695, -72.32861272132695, 0.0, 0.0, 3857.0, 1.0]
+{-1.3095817809482181E7, 4021262.7487925636, 512.0, 517.0, 72.32861272132695, -72.32861272132695, 0.0, 0.0, 3857.0, 1.0}
 ```
 
 ### RS_NormalizeAll

flink/src/main/java/org/apache/sedona/flink/Catalog.java

@@ -184,6 +184,7 @@ public static UserDefinedFunction[] getFuncs() {
       new Functions.ST_ForceCollection(),
       new Functions.ST_ForcePolygonCW(),
       new Functions.ST_ForceRHR(),
+      new Functions.ST_GeneratePoints(),
       new Functions.ST_NRings(),
       new Functions.ST_IsPolygonCCW(),
       new Functions.ST_ForcePolygonCCW(),