james-willis commented on code in PR #1712: URL: https://github.com/apache/sedona/pull/1712#discussion_r1887361616
########## docs/api/flink/Function.md: ########## @@ -164,6 +164,82 @@ 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 near the center of the polygon. +- Stay far from boundaries for optimal placement. + +The algorithm is inspired by Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than iterative algorithms like `polylabel`. It may not produce the globally optimal result, but it ensures 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 polygon, assuming uniform density, it may place the point outside the polygon or near a boundary, especially for irregular shapes or polygons with holes. + +`ST_LabelPoint` takes upto 3 arguments, + +- `geometry`: input geometry (e.g., a polygon or GeometryCollection) for which the anchor point is to be calculated. Review Comment: Polygon should be capitalized ########## docs/api/flink/Function.md: ########## @@ -164,6 +164,82 @@ 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 near the center of the polygon. +- Stay far from boundaries for optimal placement. + +The algorithm is inspired by Tippecanoe’s `polygon_to_anchor`, an approximate solution for label point generation, designed to be faster than iterative algorithms like `polylabel`. It may not produce the globally optimal result, but it ensures 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 polygon, assuming uniform density, it may place the point outside the polygon or near a boundary, especially for irregular shapes or polygons with holes. + +`ST_LabelPoint` takes upto 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 more accurate results but at the cost of additional computation. 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, and the anchor is always placed inside the outer boundary, not inside a hole. Review Comment: Im not sure this is strictly true. There are certain parameters where you will run out of iterations before finding a point not in a hole -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
