Connect_matrix

syntax

connect_matrix(points, maxSqrDistPoint, features, maxSqrDistFeature)
connect_matrix(points, maxSqrDistPoint, features, maxSqrDistFeature, max_nr_matches)
connect_matrix_eq(points, pointKey, maxSqrDistPoint, features, featureKey, maxSqrDistFeature[, max_nr_matches])
connect_matrix_ne(points, pointKey, maxSqrDistPoint, features, featureKey, maxSqrDistFeature[, max_nr_matches])

definition

Since GeoDMS 20.19.2. Where Connect_info gives each feature its nearest point, connect_matrix gives every point within a maximum distance — a sparse distance matrix.

The result is a new Domain unit of (feature, point) pairs, so it is keyed by neither argument. It carries:

arc_rel: the relation towards the domain unit of the features;
point_rel: the relation towards the domain unit of the points;
dist: the distance between the point and the CutPoint on that feature;
CutPoint, InArc, InSegm, SegmID: as in Connect_info, describing the connection on that feature.

Dist_matrix is the variant without the last four; it still results in a pair domain with both relations, since without them the distances could not be interpreted.

No new geometry is built, which is why there is no separate connect / connect_info pair of names here: connect_matrix is the info variant.

the two cutoffs

Both maxSqrDistPoint and maxSqrDistFeature are required, and both are the square of a distance. A pair is in the result when

dist(point, feature) <= min(maxSqrDistPoint(point), maxSqrDistFeature(feature))

Each may be given per entry of its own domain unit or as a single [[parameter|parameters]] with a Void domain, in any combination — per point and one value for the features, one value for the points and per feature, per both, or one value for both. Giving each side its own cutoff is what the wind-turbine case needs: the norm distance follows from the turbine’s tip height, while a building may carry a limit of its own.

max_nr_matches

The optional last argument caps the number of matches per feature, keeping the max_nr_matches nearest ones. Without it every point within the cutoff is reported, and the result can grow to the product of the two domain sizes — with real datasets that bound is worth setting.

order of the result

Rows are grouped by feature, in the order of the feature domain, and within one feature the nearest point comes first (ties by the lower point index). A feature with no match within its cutoff contributes no row at all.

description

The features should contain unique geometries. Use the Unique function to make a domain unit with unique geometries.

A multi-linestring or multi-polygon is not split: it is one feature, and a point matches it once, at its nearest location.

applies to

data items points and features with fpoint or dpoint Value type
data item features with composition type arc or polygon
maxSqrDistPoint and maxSqrDistFeature with float32 or float64 value type
max_nr_matches a uint32 parameter
pointKey and featureKey with uint32 value type

conditions

The value type of points and features must match.
maxSqrDistPoint has the domain unit of the points, or a void domain; maxSqrDistFeature has the domain unit of the features, or a void domain.
For the _eq / _ne variants, each key has the domain unit of its own geometry, and the two keys share their values unit.

For _eq only points whose key equals the feature’s key are matched, for _ne only those whose key differs — the same rule as Connect_eq and Connect_ne, including that a Null pointKey waives the comparison, while a null featureKey is not a wildcard.

example

unit<uint32> pand2turbine := connect_matrix(
      turbine/geometry, sqr(turbine/norm_afstand)
    , pand/geometry,    sqr(pand/max_afstand)
    , 25);

attribute<float64> dichtstbijzijnde (pand) := min(pand2turbine/dist, pand2turbine/arc_rel);
attribute<uint32>  nr_turbines      (pand) := pcount(pand2turbine/arc_rel);