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.
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