Distance

Distance computation APIs. More...

Files
file	distance.hpp
file	distance.cuh

Functions
template<class LonLatItA , class LonLatItB , class OutputIt , class T = typename cuspatial::iterator_vec_base_type<LonLatItA>>
OutputIt	cuspatial::haversine_distance (LonLatItA a_lonlat_first, LonLatItA a_lonlat_last, LonLatItB b_lonlat_first, OutputIt distance_first, T const radius=EARTH_RADIUS_KM, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Compute haversine distances between points in set A to the corresponding points in set B.
template<class PointIt , class OffsetIt , class OutputIt >
OutputIt	cuspatial::directed_hausdorff_distance (PointIt points_first, PointIt points_last, OffsetIt space_offsets_first, OffsetIt space_offsets_last, OutputIt distance_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Computes Hausdorff distances for all pairs in a collection of spaces.
template<class MultiPointArrayViewA , class MultiPointArrayViewB , class OutputIt >
OutputIt	cuspatial::pairwise_point_distance (MultiPointArrayViewA multipoints1, MultiPointArrayViewB multipoints2, OutputIt distances_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Compute pairwise (multi)point-to-(multi)point Cartesian distance.
template<class MultiPointRange , class MultiLinestringRange , class OutputIt >
OutputIt	cuspatial::pairwise_point_linestring_distance (MultiPointRange multipoints, MultiLinestringRange multilinestrings, OutputIt distances_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Compute pairwise multipoint to multilinestring distance.
template<class MultiPointRange , class MultiPolygonRange , class OutputIt >
OutputIt	cuspatial::pairwise_point_polygon_distance (MultiPointRange multipoints, MultiPolygonRange multipoiygons, OutputIt distances_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Computes pairwise multipoint to multipolygon distance.
template<class MultiLinestringRange1 , class MultiLinestringRange2 , class OutputIt >
OutputIt	cuspatial::pairwise_linestring_distance (MultiLinestringRange1 multilinestrings1, MultiLinestringRange2 multilinestrings2, OutputIt distances_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
template<class MultiLinestringRange , class MultiPolygonRange , class OutputIt >
OutputIt	cuspatial::pairwise_linestring_polygon_distance (MultiLinestringRange multilinestrings, MultiPolygonRange multipoiygons, OutputIt distances_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Computes pairwise multilinestring to multipolygon distance.
template<class MultipolygonRangeA , class MultipolygonRangeB , class OutputIt >
OutputIt	cuspatial::pairwise_polygon_distance (MultipolygonRangeA lhs, MultipolygonRangeB rhs, OutputIt distances_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Computes pairwise multipolygon to multipolygon distance.

Detailed Description

Distance computation APIs.

Function Documentation

directed_hausdorff_distance()

template<class PointIt , class OffsetIt , class OutputIt >

OutputIt cuspatial::directed_hausdorff_distance	(	PointIt	points_first,
		PointIt	points_last,
		OffsetIt	space_offsets_first,
		OffsetIt	space_offsets_last,
		OutputIt	distance_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Computes Hausdorff distances for all pairs in a collection of spaces.

https://en.wikipedia.org/wiki/Hausdorff_distance

Example in 1D (this function operates in 2D):

spaces
[0 2 5] [9] [3 7]
 
spaces represented as points per space and concatenation of all points
[0 2 5 9 3 7] [3 1 2]
 
note: the following matrices are visually separated to highlight the relationship of a pair of
points with the pair of spaces from which it is produced
 
cartesian product of all
points by pair of spaces     distance between points
+----------+----+-------+    +---------+---+------+
: 00 02 05 : 09 : 03 07 :    : 0  2  5 : 9 : 3  7 :
: 20 22 25 : 29 : 23 27 :    : 2  0  3 : 7 : 1  5 :
: 50 52 55 : 59 : 53 57 :    : 5  3  0 : 4 : 2  2 :
+----------+----+-------+    +---------+---+------+
: 90 92 95 : 99 : 93 97 :    : 9  7  4 : 0 : 6  2 :
+----------+----+-------+    +---------+---+------+
: 30 32 35 : 39 : 33 37 :    : 3  1  2 : 6 : 0  4 :
: 70 72 75 : 79 : 73 77 :    : 7  5  2 : 2 : 4  0 :
+----------+----+-------+    +---------+---+------+
 
minimum distance from
every point in one           Hausdorff distance is
space to any point in        the maximum of the
the other space              minimum distances
+----------+----+-------+    +---------+---+------+
:  0       :  9 :  3    :    : 0       : 9 : 3    :
:     0    :  7 :  1    :    :         :   :      :
:        0 :  4 :  2    :    :         :   :      :
+----------+----+-------+    +---------+---+------+
:        4 :  0 :     2 :    :       4 : 0 :    2 :
+----------+----+-------+    +---------+---+------+
:     1    :  6 :  0    :    :         : 6 : 0    :
:        2 :  2 :     0 :    :       2 :   :      :
+----------+----+-------+    +---------+---+------+
 
returned as concatenation of columns
[0 2 4 3 0 2 9 6 0]

Parameters

[in]	points_first	xs: beginning of range of (x,y) points
[in]	points_lasts	xs: end of range of (x,y) points
[in]	space_offsets_first	beginning of range of indices to each space.
[in]	space_offsets_first	end of range of indices to each space. Last index is the last
[in]	distance_first	beginning of range of output Hausdorff distance for each pair of spaces

Template Parameters

PointIt	Iterator to input points. Points must be of a type that is convertible to cuspatial::vec_2d<T>. Must meet the requirements of [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible.
OffsetIt	Iterator to space offsets. Value type must be integral. Must meet the requirements of [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible.
OutputIt	Output iterator. Must meet the requirements of [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible and mutable.

Precondition

All iterators must have the same underlying floating-point value type.

Returns

Output iterator to the element past the last distance computed.

Note

Hausdorff distances are asymmetrical

haversine_distance()

template<class LonLatItA , class LonLatItB , class OutputIt , class T = typename cuspatial::iterator_vec_base_type<LonLatItA>>

OutputIt cuspatial::haversine_distance	(	LonLatItA	a_lonlat_first,
		LonLatItA	a_lonlat_last,
		LonLatItB	b_lonlat_first,
		OutputIt	distance_first,
		T const	radius = EARTH_RADIUS_KM,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Compute haversine distances between points in set A to the corresponding points in set B.

Computes N haversine distances, where N is std::distance(a_lonlat_first, a_lonlat_last). The distance for each a_lonlat[i] and b_lonlat[i] point pair is assigned to distance_first[i]. distance_first must be an iterator to output storage allocated for N distances.

Computed distances will have the same units as radius.

https://en.wikipedia.org/wiki/Haversine_formula

Parameters

[in]	a_lonlat_first	beginning of range of (longitude, latitude) locations in set A
[in]	a_lonlat_last	end of range of (longitude, latitude) locations in set A
[in]	b_lonlat_first	beginning of range of (longitude, latitude) locations in set B
[out]	distance_first	beginning of output range of haversine distances
[in]	radius	radius of the sphere on which the points reside. default: 6371.0 (approximate radius of Earth in km)
[in]	stream	The CUDA stream on which to perform computations and allocate memory.

Template Parameters

LonLatItA	Iterator to input location set A. Must meet the requirements of LegacyRandomAccessIterator and be device-accessible.
LonLatItB	Iterator to input location set B. Must meet the requirements of LegacyRandomAccessIterator and be device-accessible.
OutputIt	Output iterator. Must meet the requirements of LegacyRandomAccessIterator and be device-accessible and mutable.
T	The underlying coordinate type. Must be a floating-point type.

Precondition

All iterators must have the same Location type, with the same underlying floating-point coordinate type (e.g. cuspatial::vec_2d<float>).

Returns

Output iterator to the element past the last distance computed.

pairwise_linestring_distance()

template<class MultiLinestringRange1 , class MultiLinestringRange2 , class OutputIt >

OutputIt cuspatial::pairwise_linestring_distance	(	MultiLinestringRange1	multilinestrings1,
		MultiLinestringRange2	multilinestrings2,
		OutputIt	distances_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

The shortest distance between two linestrings is defined as the shortest distance between all pairs of segments of the two linestrings. If any of the segments intersect, the distance is 0.

Template Parameters

MultiLinestringRange	an instance of template type multilinestring_range
OutputIt	iterator type for output array. Must meet the requirements of [LRAI](LinkLRAI) and be device writable.

Parameters

multilinestrings1	Range object of the lhs multilinestring array
multilinestrings2	Range object of the rhs multilinestring array
stream	The CUDA stream to use for device memory operations and kernel launches.

Returns

Output iterator to the element past the last distance computed.

pairwise_linestring_polygon_distance()

template<class MultiLinestringRange , class MultiPolygonRange , class OutputIt >

OutputIt cuspatial::pairwise_linestring_polygon_distance	(	MultiLinestringRange	multilinestrings,
		MultiPolygonRange	multipoiygons,
		OutputIt	distances_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Computes pairwise multilinestring to multipolygon distance.

Template Parameters

MultiLinestringRange	An instance of template type multipoint_range
MultiPolygonRange	An instance of template type multipolygon_range
OutputIt	iterator type for output array. Must meet the requirements of [LRAI](LinkLRAI). Must be an iterator to type convertible from floating points.

Parameters

multilinestrings	Range of multilinestrings, one per computed distance pair.
multipolygons	Range of multipolygons, one per computed distance pair.
stream	The CUDA stream on which to perform computations

Returns

Output Iterator past the last distance computed

pairwise_point_distance()

template<class MultiPointArrayViewA , class MultiPointArrayViewB , class OutputIt >

OutputIt cuspatial::pairwise_point_distance	(	MultiPointArrayViewA	multipoints1,
		MultiPointArrayViewB	multipoints2,
		OutputIt	distances_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Compute pairwise (multi)point-to-(multi)point Cartesian distance.

Computes the cartesian distance between each pair of multipoints.

Template Parameters

MultiPointArrayViewA	An instance of template type array_view::multipoint_array
MultiPointArrayViewB	An instance of template type array_view::multipoint_array

Parameters

multipoints1	Range of first multipoint in each distance pair.
multipoints2	Range of second multipoint in each distance pair.

Returns

Iterator past the last distance computed

pairwise_point_linestring_distance()

template<class MultiPointRange , class MultiLinestringRange , class OutputIt >

OutputIt cuspatial::pairwise_point_linestring_distance	(	MultiPointRange	multipoints,
		MultiLinestringRange	multilinestrings,
		OutputIt	distances_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Compute pairwise multipoint to multilinestring distance.

Template Parameters

MultiPointRange	an instance of template type multipoint_range
MultiLinestringRange	an instance of template type multilinestring_range
OutputIt	iterator type for output array. Must meet the requirements of [LRAI](LinkLRAI).

Parameters

multipoints	The range of multipoints, one per computed distance pair
multilinestrings	The range of multilinestrings, one per computed distance pair
stream	The CUDA stream to use for device memory operations and kernel launches.

Returns

Output iterator to the element past the last distance computed.

pairwise_point_polygon_distance()

template<class MultiPointRange , class MultiPolygonRange , class OutputIt >

OutputIt cuspatial::pairwise_point_polygon_distance	(	MultiPointRange	multipoints,
		MultiPolygonRange	multipoiygons,
		OutputIt	distances_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Computes pairwise multipoint to multipolygon distance.

Template Parameters

MultiPointRange	An instance of template type multipoint_range
MultiPolygonRange	An instance of template type multipolygon_range
OutputIt	iterator type for output array. Must meet the requirements of [LRAI](LinkLRAI). Must be an iterator to type convertible from floating points.

Parameters

multipoints	Range of multipoints, one per computed distance pair.
multipolygons	Range of multilinestrings, one per computed distance pair.
stream	The CUDA stream on which to perform computations

Returns

Output Iterator past the last distance computed

pairwise_polygon_distance()

template<class MultipolygonRangeA , class MultipolygonRangeB , class OutputIt >

OutputIt cuspatial::pairwise_polygon_distance	(	MultipolygonRangeA	lhs,
		MultipolygonRangeB	rhs,
		OutputIt	distances_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Computes pairwise multipolygon to multipolygon distance.

Template Parameters

MultiPolygonRangeA	An instance of template type multipolygon_range
MultiPolygonRangeB	An instance of template type multipolygon_range
OutputIt	iterator type for output array. Must meet the requirements of [LRAI](LinkLRAI). Must be an iterator to type convertible from floating points.

Parameters

lhs	The first multipolygon range to compute distance from
rhs	The second multipolygon range to compute distance to
stream	The CUDA stream on which to perform computations

Returns

Output Iterator past the last distance computed