This is an automated email from the ASF dual-hosted git repository. jiayu pushed a commit to branch branch-1.7.1 in repository https://gitbox.apache.org/repos/asf/sedona.git
commit 57ca36ecd09b98285c2dee5df1570a8839b0407e Author: Pranav Toggi <[email protected]> AuthorDate: Sun Mar 30 21:52:43 2025 -0700 [SEDONA-727] Relocate ST_LabelPoint to alphabetical order in docs (#1896) * profiling1 * profiling4 * profiling... * profiling 8 * relocate docs * undo pom changes --- docs/api/flink/Function.md | 148 ++++++++++++++--------------- docs/api/snowflake/vector-data/Function.md | 144 ++++++++++++++-------------- docs/api/sql/Function.md | 148 ++++++++++++++--------------- 3 files changed, 220 insertions(+), 220 deletions(-) diff --git a/docs/api/flink/Function.md b/docs/api/flink/Function.md index 8446bc5a69..87e1b3ffbe 100644 --- a/docs/api/flink/Function.md +++ b/docs/api/flink/Function.md @@ -183,80 +183,6 @@ Input: `POLYGON ((1 0 1, 1 1 1, 2 2 2, 1 0 1))` Output: `POLYGON Z((2 3 1, 4 5 1, 7 8 2, 2 3 1))` -## ST_LabelPoint - -Introduction: `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 Polygon this will be the -centroid. - -The algorithm is derived from Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than optimal algorithms like `polylabel`. It searches for a “good enough” label point within a limited number of iterations. For geometry collections, only the largest Polygon by area is considered. While `ST_Centroid` is a fast algorithm to calculate the center of mass of a (Multi)Polygon, it may place the point outside of the Polygon or near a bounda [...] - -`ST_LabelPoint` takes up to 3 arguments, - -- `geometry`: input geometry (e.g., a Polygon or GeometryCollection) for which the anchor point is to be calculated. -- `gridResolution` (Optional, default is 16): Controls the resolution of the search grid for refining the label point. A higher resolution increases the grid density, providing a higher chance of finding a good enough result at the cost of runtime. For example, a gridResolution of 16 divides the bounding box of the polygon into a 16x16 grid. -- `goodnessThreshold` (Optional, default is 0.2): Determines the minimum acceptable “goodness” value for the anchor point. Higher thresholds prioritize points farther from boundaries but may require more computation. - -!!!note - - `ST_LabelPoint` throws an `IllegalArgumentException` if the input geometry has an area of zero or less. - - Holes within polygons are respected. Points within a hole are given a goodness of 0. - - For GeometryCollections, only the largest polygon by area is considered. - -!!!tip - - Use `ST_LabelPoint` for tasks such as label placement, identifying representative points for polygons, or other spatial analyses where an internal reference point is preferred but not required. If intersection of the point and the original geometry is required, use of an algorithm like `polylabel` should be considered. - - `ST_LabelPoint` offers a faster, approximate solution for label point generation, making it ideal for large datasets or real-time applications. - -Format: - -```sql -ST_LabelPoint(geometry: Geometry) -``` - -```sql -ST_LabelPoint(geometry: Geometry, gridResolution: Integer) -``` - -```sql -ST_LabelPoint(geometry: Geometry, gridResolution: Integer, goodnessThreshold: Double) -``` - -Since: `v1.7.1` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')) -``` - -Output: - -``` -POINT (2 2) -``` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('GEOMETRYCOLLECTION(POLYGON ((-112.840785 33.435962, -112.840785 33.708284, -112.409597 33.708284, -112.409597 33.435962, -112.840785 33.435962)), POLYGON ((-112.309264 33.398167, -112.309264 33.746007, -111.787444 33.746007, -111.787444 33.398167, -112.309264 33.398167)))')) -``` - -Output: - -``` -POINT (-112.04835399999999 33.57208699999999) -``` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON ((-112.654072 33.114485, -112.313516 33.653431, -111.63515 33.314399, -111.497829 33.874913, -111.692825 33.431378, -112.376684 33.788215, -112.654072 33.114485))', 4326)) -``` - -Output: - -``` -SRID=4326;POINT (-112.0722602222832 33.53914975012836) -``` - ## ST_Angle Introduction: Compute and return the angle between two vectors represented by the provided points or linestrings. @@ -2433,6 +2359,80 @@ Output: false ``` +## ST_LabelPoint + +Introduction: `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 Polygon this will be the +centroid. + +The algorithm is derived from Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than optimal algorithms like `polylabel`. It searches for a “good enough” label point within a limited number of iterations. For geometry collections, only the largest Polygon by area is considered. While `ST_Centroid` is a fast algorithm to calculate the center of mass of a (Multi)Polygon, it may place the point outside of the Polygon or near a bounda [...] + +`ST_LabelPoint` takes up to 3 arguments, + +- `geometry`: input geometry (e.g., a Polygon or GeometryCollection) for which the anchor point is to be calculated. +- `gridResolution` (Optional, default is 16): Controls the resolution of the search grid for refining the label point. A higher resolution increases the grid density, providing a higher chance of finding a good enough result at the cost of runtime. For example, a gridResolution of 16 divides the bounding box of the polygon into a 16x16 grid. +- `goodnessThreshold` (Optional, default is 0.2): Determines the minimum acceptable “goodness” value for the anchor point. Higher thresholds prioritize points farther from boundaries but may require more computation. + +!!!note + - `ST_LabelPoint` throws an `IllegalArgumentException` if the input geometry has an area of zero or less. + - Holes within polygons are respected. Points within a hole are given a goodness of 0. + - For GeometryCollections, only the largest polygon by area is considered. + +!!!tip + - Use `ST_LabelPoint` for tasks such as label placement, identifying representative points for polygons, or other spatial analyses where an internal reference point is preferred but not required. If intersection of the point and the original geometry is required, use of an algorithm like `polylabel` should be considered. + - `ST_LabelPoint` offers a faster, approximate solution for label point generation, making it ideal for large datasets or real-time applications. + +Format: + +```sql +ST_LabelPoint(geometry: Geometry) +``` + +```sql +ST_LabelPoint(geometry: Geometry, gridResolution: Integer) +``` + +```sql +ST_LabelPoint(geometry: Geometry, gridResolution: Integer, goodnessThreshold: Double) +``` + +Since: `v1.7.1` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')) +``` + +Output: + +``` +POINT (2 2) +``` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('GEOMETRYCOLLECTION(POLYGON ((-112.840785 33.435962, -112.840785 33.708284, -112.409597 33.708284, -112.409597 33.435962, -112.840785 33.435962)), POLYGON ((-112.309264 33.398167, -112.309264 33.746007, -111.787444 33.746007, -111.787444 33.398167, -112.309264 33.398167)))')) +``` + +Output: + +``` +POINT (-112.04835399999999 33.57208699999999) +``` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON ((-112.654072 33.114485, -112.313516 33.653431, -111.63515 33.314399, -111.497829 33.874913, -111.692825 33.431378, -112.376684 33.788215, -112.654072 33.114485))', 4326)) +``` + +Output: + +``` +SRID=4326;POINT (-112.0722602222832 33.53914975012836) +``` + ## ST_Length Introduction: Returns the perimeter of A. diff --git a/docs/api/snowflake/vector-data/Function.md b/docs/api/snowflake/vector-data/Function.md index f6b8c447f2..9b1999de88 100644 --- a/docs/api/snowflake/vector-data/Function.md +++ b/docs/api/snowflake/vector-data/Function.md @@ -146,78 +146,6 @@ Input: `POLYGON ((1 0 1, 1 1 1, 2 2 2, 1 0 1))` Output: `POLYGON Z((2 3 1, 4 5 1, 7 8 2, 2 3 1))` -## ST_LabelPoint - -Introduction: `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 Polygon this will be the -centroid. - -The algorithm is derived from Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than optimal algorithms like `polylabel`. It searches for a “good enough” label point within a limited number of iterations. For geometry collections, only the largest Polygon by area is considered. While `ST_Centroid` is a fast algorithm to calculate the center of mass of a (Multi)Polygon, it may place the point outside of the Polygon or near a bounda [...] - -`ST_LabelPoint` takes up to 3 arguments, - -- `geometry`: input geometry (e.g., a Polygon or GeometryCollection) for which the anchor point is to be calculated. -- `gridResolution` (Optional, default is 16): Controls the resolution of the search grid for refining the label point. A higher resolution increases the grid density, providing a higher chance of finding a good enough result at the cost of runtime. For example, a gridResolution of 16 divides the bounding box of the polygon into a 16x16 grid. -- `goodnessThreshold` (Optional, default is 0.2): Determines the minimum acceptable “goodness” value for the anchor point. Higher thresholds prioritize points farther from boundaries but may require more computation. - -!!!note - - `ST_LabelPoint` throws an `IllegalArgumentException` if the input geometry has an area of zero or less. - - Holes within polygons are respected. Points within a hole are given a goodness of 0. - - For GeometryCollections, only the largest polygon by area is considered. - -!!!tip - - Use `ST_LabelPoint` for tasks such as label placement, identifying representative points for polygons, or other spatial analyses where an internal reference point is preferred but not required. If intersection of the point and the original geometry is required, use of an algorithm like `polylabel` should be considered. - - `ST_LabelPoint` offers a faster, approximate solution for label point generation, making it ideal for large datasets or real-time applications. - -Format: - -```sql -ST_LabelPoint(geometry: Geometry) -``` - -```sql -ST_LabelPoint(geometry: Geometry, gridResolution: Integer) -``` - -```sql -ST_LabelPoint(geometry: Geometry, gridResolution: Integer, goodnessThreshold: Double) -``` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')) -``` - -Output: - -``` -POINT (2 2) -``` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('GEOMETRYCOLLECTION(POLYGON ((-112.840785 33.435962, -112.840785 33.708284, -112.409597 33.708284, -112.409597 33.435962, -112.840785 33.435962)), POLYGON ((-112.309264 33.398167, -112.309264 33.746007, -111.787444 33.746007, -111.787444 33.398167, -112.309264 33.398167)))')) -``` - -Output: - -``` -POINT (-112.04835399999999 33.57208699999999) -``` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON ((-112.654072 33.114485, -112.313516 33.653431, -111.63515 33.314399, -111.497829 33.874913, -111.692825 33.431378, -112.376684 33.788215, -112.654072 33.114485))', 4326)) -``` - -Output: - -``` -SRID=4326;POINT (-112.0722602222832 33.53914975012836) -``` - ## ST_Angle Introduction: Computes and returns the angle between two vectors represented by the provided points or linestrings. @@ -1793,6 +1721,78 @@ gid | validity_info ``` +## ST_LabelPoint + +Introduction: `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 Polygon this will be the +centroid. + +The algorithm is derived from Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than optimal algorithms like `polylabel`. It searches for a “good enough” label point within a limited number of iterations. For geometry collections, only the largest Polygon by area is considered. While `ST_Centroid` is a fast algorithm to calculate the center of mass of a (Multi)Polygon, it may place the point outside of the Polygon or near a bounda [...] + +`ST_LabelPoint` takes up to 3 arguments, + +- `geometry`: input geometry (e.g., a Polygon or GeometryCollection) for which the anchor point is to be calculated. +- `gridResolution` (Optional, default is 16): Controls the resolution of the search grid for refining the label point. A higher resolution increases the grid density, providing a higher chance of finding a good enough result at the cost of runtime. For example, a gridResolution of 16 divides the bounding box of the polygon into a 16x16 grid. +- `goodnessThreshold` (Optional, default is 0.2): Determines the minimum acceptable “goodness” value for the anchor point. Higher thresholds prioritize points farther from boundaries but may require more computation. + +!!!note + - `ST_LabelPoint` throws an `IllegalArgumentException` if the input geometry has an area of zero or less. + - Holes within polygons are respected. Points within a hole are given a goodness of 0. + - For GeometryCollections, only the largest polygon by area is considered. + +!!!tip + - Use `ST_LabelPoint` for tasks such as label placement, identifying representative points for polygons, or other spatial analyses where an internal reference point is preferred but not required. If intersection of the point and the original geometry is required, use of an algorithm like `polylabel` should be considered. + - `ST_LabelPoint` offers a faster, approximate solution for label point generation, making it ideal for large datasets or real-time applications. + +Format: + +```sql +ST_LabelPoint(geometry: Geometry) +``` + +```sql +ST_LabelPoint(geometry: Geometry, gridResolution: Integer) +``` + +```sql +ST_LabelPoint(geometry: Geometry, gridResolution: Integer, goodnessThreshold: Double) +``` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')) +``` + +Output: + +``` +POINT (2 2) +``` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('GEOMETRYCOLLECTION(POLYGON ((-112.840785 33.435962, -112.840785 33.708284, -112.409597 33.708284, -112.409597 33.435962, -112.840785 33.435962)), POLYGON ((-112.309264 33.398167, -112.309264 33.746007, -111.787444 33.746007, -111.787444 33.398167, -112.309264 33.398167)))')) +``` + +Output: + +``` +POINT (-112.04835399999999 33.57208699999999) +``` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON ((-112.654072 33.114485, -112.313516 33.653431, -111.63515 33.314399, -111.497829 33.874913, -111.692825 33.431378, -112.376684 33.788215, -112.654072 33.114485))', 4326)) +``` + +Output: + +``` +SRID=4326;POINT (-112.0722602222832 33.53914975012836) +``` + ## ST_Length Introduction: Returns the perimeter of A. diff --git a/docs/api/sql/Function.md b/docs/api/sql/Function.md index d4bda5c44a..584c7e7ead 100644 --- a/docs/api/sql/Function.md +++ b/docs/api/sql/Function.md @@ -179,80 +179,6 @@ Input: `POLYGON ((1 0 1, 1 1 1, 2 2 2, 1 0 1))` Output: `POLYGON Z((2 3 1, 4 5 1, 7 8 2, 2 3 1))` -## ST_LabelPoint - -Introduction: `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 Polygon this will be the -centroid. - -The algorithm is derived from Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than optimal algorithms like `polylabel`. It searches for a “good enough” label point within a limited number of iterations. For geometry collections, only the largest Polygon by area is considered. While `ST_Centroid` is a fast algorithm to calculate the center of mass of a (Multi)Polygon, it may place the point outside of the Polygon or near a bounda [...] - -`ST_LabelPoint` takes up to 3 arguments, - -- `geometry`: input geometry (e.g., a Polygon or GeometryCollection) for which the anchor point is to be calculated. -- `gridResolution` (Optional, default is 16): Controls the resolution of the search grid for refining the label point. A higher resolution increases the grid density, providing a higher chance of finding a good enough result at the cost of runtime. For example, a gridResolution of 16 divides the bounding box of the polygon into a 16x16 grid. -- `goodnessThreshold` (Optional, default is 0.2): Determines the minimum acceptable “goodness” value for the anchor point. Higher thresholds prioritize points farther from boundaries but may require more computation. - -!!!note - - `ST_LabelPoint` throws an `IllegalArgumentException` if the input geometry has an area of zero or less. - - Holes within polygons are respected. Points within a hole are given a goodness of 0. - - For GeometryCollections, only the largest polygon by area is considered. - -!!!tip - - Use `ST_LabelPoint` for tasks such as label placement, identifying representative points for polygons, or other spatial analyses where an internal reference point is preferred but not required. If intersection of the point and the original geometry is required, use of an algorithm like `polylabel` should be considered. - - `ST_LabelPoint` offers a faster, approximate solution for label point generation, making it ideal for large datasets or real-time applications. - -Format: - -```sql -ST_LabelPoint(geometry: Geometry) -``` - -```sql -ST_LabelPoint(geometry: Geometry, gridResolution: Integer) -``` - -```sql -ST_LabelPoint(geometry: Geometry, gridResolution: Integer, goodnessThreshold: Double) -``` - -Since: `v1.7.1` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')) -``` - -Output: - -``` -POINT (2 2) -``` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('GEOMETRYCOLLECTION(POLYGON ((-112.840785 33.435962, -112.840785 33.708284, -112.409597 33.708284, -112.409597 33.435962, -112.840785 33.435962)), POLYGON ((-112.309264 33.398167, -112.309264 33.746007, -111.787444 33.746007, -111.787444 33.398167, -112.309264 33.398167)))')) -``` - -Output: - -``` -POINT (-112.04835399999999 33.57208699999999) -``` - -SQL Example: - -``` -SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON ((-112.654072 33.114485, -112.313516 33.653431, -111.63515 33.314399, -111.497829 33.874913, -111.692825 33.431378, -112.376684 33.788215, -112.654072 33.114485))', 4326)) -``` - -Output: - -``` -SRID=4326;POINT (-112.0722602222832 33.53914975012836) -``` - ## ST_Angle Introduction: Computes and returns the angle between two vectors represented by the provided points or linestrings. @@ -2554,6 +2480,80 @@ Output: false ``` +## ST_LabelPoint + +Introduction: `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 Polygon this will be the +centroid. + +The algorithm is derived from Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than optimal algorithms like `polylabel`. It searches for a “good enough” label point within a limited number of iterations. For geometry collections, only the largest Polygon by area is considered. While `ST_Centroid` is a fast algorithm to calculate the center of mass of a (Multi)Polygon, it may place the point outside of the Polygon or near a bounda [...] + +`ST_LabelPoint` takes up to 3 arguments, + +- `geometry`: input geometry (e.g., a Polygon or GeometryCollection) for which the anchor point is to be calculated. +- `gridResolution` (Optional, default is 16): Controls the resolution of the search grid for refining the label point. A higher resolution increases the grid density, providing a higher chance of finding a good enough result at the cost of runtime. For example, a gridResolution of 16 divides the bounding box of the polygon into a 16x16 grid. +- `goodnessThreshold` (Optional, default is 0.2): Determines the minimum acceptable “goodness” value for the anchor point. Higher thresholds prioritize points farther from boundaries but may require more computation. + +!!!note + - `ST_LabelPoint` throws an `IllegalArgumentException` if the input geometry has an area of zero or less. + - Holes within polygons are respected. Points within a hole are given a goodness of 0. + - For GeometryCollections, only the largest polygon by area is considered. + +!!!tip + - Use `ST_LabelPoint` for tasks such as label placement, identifying representative points for polygons, or other spatial analyses where an internal reference point is preferred but not required. If intersection of the point and the original geometry is required, use of an algorithm like `polylabel` should be considered. + - `ST_LabelPoint` offers a faster, approximate solution for label point generation, making it ideal for large datasets or real-time applications. + +Format: + +```sql +ST_LabelPoint(geometry: Geometry) +``` + +```sql +ST_LabelPoint(geometry: Geometry, gridResolution: Integer) +``` + +```sql +ST_LabelPoint(geometry: Geometry, gridResolution: Integer, goodnessThreshold: Double) +``` + +Since: `v1.7.1` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON((0 0, 4 0, 4 4, 0 4, 0 0))')) +``` + +Output: + +``` +POINT (2 2) +``` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('GEOMETRYCOLLECTION(POLYGON ((-112.840785 33.435962, -112.840785 33.708284, -112.409597 33.708284, -112.409597 33.435962, -112.840785 33.435962)), POLYGON ((-112.309264 33.398167, -112.309264 33.746007, -111.787444 33.746007, -111.787444 33.398167, -112.309264 33.398167)))')) +``` + +Output: + +``` +POINT (-112.04835399999999 33.57208699999999) +``` + +SQL Example: + +``` +SELECT ST_LabelPoint(ST_GeomFromWKT('POLYGON ((-112.654072 33.114485, -112.313516 33.653431, -111.63515 33.314399, -111.497829 33.874913, -111.692825 33.431378, -112.376684 33.788215, -112.654072 33.114485))', 4326)) +``` + +Output: + +``` +SRID=4326;POINT (-112.0722602222832 33.53914975012836) +``` + ## ST_Length Introduction: Returns the perimeter of A.
