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.

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.

To find the polygon with the highest rank, the function looks at every polygon that may contain a point, not only until it finds one. The spatial index keeps each polygon at a depth that follows from its size, so that a dense set of small polygons, such as parcels or grid cells, is searched quickly; see Point_in_polygon.

A point tested against a polygon of many vertices reads only the edges near its own row, through an edge index per polygon of at least 32 vertices, which is built when there are at least 4 points per such polygon. This makes the function many times faster on polygons of thousands of vertices, such as municipalities or countries; see Point_in_polygon for how it works and what it costs.

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

see also