XQuery geo:region-relate

MarkLogic 9 Product Documentation
geo.regionRelate

geo.regionRelate(
   region-1 as cts.region,
   operation as String,
   region-2 as cts.region,
   [options as String[]]
) as Boolean

Summary

Compares geospatial regions based on a specified relationship. For example, determine if two regions overlap.

Parameters
region-1 The first geospatial region to compare. This region is the left operand of $operation.
operation The operation to apply between the region specified in the $region-1 and $region-2 parameters. Allowed values: contains, covered-by, covers, crosses, disjoint, equals, intersects, overlaps, touches, within. See the Usage Notes for details.
region-2 The second geospatial region to compare. This region is the right operand of $operation.
options Options to this operation. The default is (). Available options:
"coordinate-system=string"
Use the given coordinate system. Valid values are:
wgs84
The WGS84 coordinate system.
wgs84/double
The WGS84 coordinate system at double precision.
etrs89
The ETRS89 coordinate system.
etrs89/double
The ETRS89 coordinate system at double precision.
raw
The raw (unmapped) coordinate system.
raw/double
The raw coordinate system at double precision.
"precision=value"
Use the coordinate system at the given precision. Allowed values: float and double.
"units=value"
Measure distance, radii of circles, and tolerance in the specified units. Allowed values: miles (default), km, feet, meters.
"tolerance=distance"
Tolerance is the largest allowable variation in geometry calculations. If the distance between two points is less than tolerance, then the two points are considered equal. For the raw coordinate system, use the units of the coordinates. For geographic coordinate systems, use the units specified by the units option.

Usage Notes

This function determines whether the two regions R1=$region-1 and R2=$region-2 satisfy the relationship R1 op R2, where op=$operation.

The operations are defined by the Dimensionally Extended nine-Intersection Model (DE-9IM) of spatial relations. They have the following semantics:

"contains"
R1 contains R2 if every point of R2 is also a point of R1, and their interiors intersect.
"covered-by"
R1 is covered-by R2 if every point of R1 is also a point of R2.
"covers"
R1 covers R2 if every point of R2 is also a point of R1.
"crosses"
R1 crosses R2 if their interiors intersect and the dimension of the intersection is less than that of at least one of the regions.
"disjoint"
R1 is disjoint from R2 if they have no points in common.
"equals"
R1 equals R2 if every point of R1 is a point of R2, and every point of R2 is a point of R1. That is, the regions are topologically equal.
"intersects"
R1 intersects R2 if the two regions have at least one point in common.
"overlaps"
R1 overlaps R2 if the two regions partially intersect -- that is, they have some but not all points in common -- and the intersection of R1 and R2 has the same dimension as R1 and R2.
"touches"
R1 touches R2 if they have a boundary point in common but no interior points in common.
"within"
R1 is within R2 if every point of R1 is also a point of R2, and their interiors intersect.

The operations in this function are the same as those used in cts.geospatialRegionQuery. For example, geo.regionRelate($r1,$op,$r2) returns true if and only if a document containing the region $r1 would match the geospatial region query cts.geospatialRegionQuery($index,$op,$r2). (Where $index is a geospatial region path index configured on the same coordinate system and units used in geo.regionRelate.)

Note: the operation covers differs from contains only in that covers does not distinguish between points in the boundary and the interior of geometries. In general, covers should be used in preference to contains. Similarly, covered-by should generally be used in preference to within.

The DE9-IM operators are defined in terms of the underlying intersection matrix between the two regions. To calculate this matrix for two regions, use geo.regionDe9im.

The value of the precision option takes precedence over that implied by the governing coordinate system name, including the value of the coordinate-system option. For example, if the governing coordinate system is "wgs84/double" and the precision option is "float", then the operation uses single precision.

See Also

Example

const r1 = cts.polygon('POLYGON((-122.427520751953 37.6555576956251,-122.459106445313 37.5658069549294,-122.289505004883 37.5946477878735,-122.427520751953 37.6555576956251))');
const r2 = cts.linestring('LINESTRING(-122.571029663086 37.5728821555562,-122.400054931641 37.6077041124284,-122.161102294922 37.5696167618573)');
geo.regionRelate(r1,'crosses',r2,['coordinate-system=wgs84','precision=double'])

// returns true
Powered by MarkLogic Server | Terms of Use | Privacy Policy