Point_in_ranked_polygon
Geometric functions point_in_ranked_polygon
syntax
- point_in_ranked_polygon(point_data_item, polygon_data_item, rank_data_item)
definition
point_in_ranked_polygon(point_data_item, polygon_data_item, rank_data_item) results for each point of the point_data_item in a relation towards the domain unit of the polygon_data_item in which the point is located.
The resulting Values unit is the Domain unit of the polygon_data_item.
If a point is not located in any polygon, the function results in a Null value. If a point is located in multiple polygons (the red point in the image), the function results in the polygon with the highest rank_data_item value, and of polygons with equal rank in the one with the lowest index. A polygon whose rank is Null is not considered: a point that lies only in such polygons results in null.
Since GeoDMS 20.23.1 equal ranks go to the lowest index, and a null rank is skipped for every rank type (#1289). Before, of polygons with equal rank the function took the one its spatial index found first, which followed from how that index was built, and a null integer rank could make the result null for a point that also lay in polygons with a rank. Earlier versions of this page said that the lowest rank wins; the function has always taken the highest.
description
The rank_data_item argument is used to make an explicit choice for a polygon, if a point is located in multiple polygons. Therefore the rank values need to distinguish the different polygons. If a constant is used as rank value, point_in_ranked_polygon results in the polygon with the lowest index of those that contain the point. For a point in one polygon only, that is the same value as the Point_in_polygon function gives; for a point in several, point_in_polygon gives one of them, unspecified which.
applies to
- a Data item point_data_item with Point Value type
- a data item polygon_data_item with composition type type polygon and Point value type
- a data item rank_data_item with a uint8, (u)int32, float32 or float64 value type
since version
8.036
performance
O(n log p + n * k) where n = number of points, p = number of polygons, and k = average polygon complexity. Similar to Point_in_polygon, but additionally considers ranking when multiple polygons contain a point.
Since GeoDMS 20.25.0 this function is much faster on a dense set of small polygons, such as parcels or grid cells (#1292). It looks at every polygon that may contain a point, not only until it finds one, and the spatial index kept each polygon that crossed or touched one of the lines along which it divides its area at the top, where every point’s search tested it. The index now keeps each polygon at a depth that follows from its size; see Point_in_polygon. The results are the same.
example
attribute<city> city_rel (ADomain) := point_in_ranked_polygon(Adomain/point, city/geometry, city/rank);
| point | city_rel |
|---|---|
| xy(115135; 401331) | 3 |
| xy(111803; 399476) | 2 |
| xy(114903; 399289) | 1 |
| xy(111353; 401729) | 5 |
| xy(111741; 398696) | null |
ADomain, nr of rows = 5
| City/geometry | City/rank |
|---|---|
| {21:xy(113810; 403025),{4 | 2 |
| {17:xy(113269; 400990),{4 | 1 |
| {19:xy(115099; 403128),{4 | 7 |
| {23:xy(113703; 402174),{4 | 4 |
| {30:xy(114646; 401531),{4 | 6 |
| {13:xy(114546; 402757),{4 | 5 |
| {54:xy(113562; 405282),{4 | 3 |
domain City, nr of rows = 7