Trajectory APIs

APIs related to trajectories. More...

Files
file	trajectory.hpp
file	trajectory.cuh

Functions
template<typename IdInputIt , typename PointInputIt , typename TimestampInputIt , typename IdOutputIt , typename PointOutputIt , typename TimestampOutputIt , typename OffsetType = std::int32_t>
std::unique_ptr< rmm::device_uvector< OffsetType > >	cuspatial::derive_trajectories (IdInputIt ids_first, IdInputIt ids_last, PointInputIt points_first, TimestampInputIt timestamps_first, IdOutputIt ids_output_first, PointOutputIt points_output_first, TimestampOutputIt timestamps_output_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Derive trajectories from object ids, points, and timestamps.
template<typename IdInputIt , typename PointInputIt , typename TimestampInputIt , typename OutputIt , typename IndexT = iterator_value_type<IdInputIt>>
OutputIt	cuspatial::trajectory_distances_and_speeds (IndexT num_trajectories, IdInputIt ids_first, IdInputIt ids_last, PointInputIt points_first, TimestampInputIt timestamps_first, OutputIt distances_and_speeds_first, rmm::cuda_stream_view stream=rmm::cuda_stream_default)
	Compute the total distance (in meters) and average speed (in m/s) of objects in trajectories.
std::pair< std::unique_ptr< cudf::table >, std::unique_ptr< cudf::column > >	cuspatial::derive_trajectories (cudf::column_view const &object_id, cudf::column_view const &x, cudf::column_view const &y, cudf::column_view const &timestamp, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Derive trajectories from object ids, points, and timestamps.
std::unique_ptr< cudf::table >	cuspatial::trajectory_distances_and_speeds (cudf::size_type num_trajectories, cudf::column_view const &object_id, cudf::column_view const &x, cudf::column_view const &y, cudf::column_view const &timestamp, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Compute the distance and speed of objects in a trajectory. Groups the timestamp, x, and y, columns by object id to determine unique trajectories, then computes the average distance and speed for all routes in each trajectory.
std::unique_ptr< cudf::table >	cuspatial::trajectory_bounding_boxes (cudf::size_type num_trajectories, cudf::column_view const &object_id, cudf::column_view const &x, cudf::column_view const &y, rmm::device_async_resource_ref mr=rmm::mr::get_current_device_resource())
	Compute the spatial bounding boxes of trajectories. Groups the x, y, and timestamp columns by object id to determine unique trajectories, then computes the minimum bounding box to contain all routes in each trajectory.

Detailed Description

APIs related to trajectories.

Function Documentation

derive_trajectories() [1/2]

std::pair< std::unique_ptr< cudf::table >, std::unique_ptr< cudf::column > > cuspatial::derive_trajectories	(	cudf::column_view const &	object_id,
		cudf::column_view const &	x,
		cudf::column_view const &	y,
		cudf::column_view const &	timestamp,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource() )

Derive trajectories from object ids, points, and timestamps.

Groups the input object ids to determine unique trajectories. Returns a table with the trajectory ids, the number of objects in each trajectory, and the offset position of the first object for each trajectory in the input object ids column.

Parameters

object_id	column of object (e.g., vehicle) ids
x	coordinates (in kilometers)
y	coordinates (in kilometers)
timestamp	column of timestamps in any resolution
mr	The optional resource to use for output device memory allocations

Exceptions

cuspatial::logic_error	If object_id isn't cudf::type_id::INT32
cuspatial::logic_error	If x and y are different types
cuspatial::logic_error	If timestamp isn't a cudf::TIMESTAMP type
cuspatial::logic_error	If object_id, x, y, or timestamp contain nulls
cuspatial::logic_error	If object_id, x, y, and timestamp are different sizes

Returns

an std::pair<table, column>:

1. table of (object_id, x, y, timestamp) sorted by (object_id, timestamp)
2. int32 column of start positions for each trajectory's first object

derive_trajectories() [2/2]

template<typename IdInputIt , typename PointInputIt , typename TimestampInputIt , typename IdOutputIt , typename PointOutputIt , typename TimestampOutputIt , typename OffsetType = std::int32_t>

std::unique_ptr< rmm::device_uvector< OffsetType > > cuspatial::derive_trajectories	(	IdInputIt	ids_first,
		IdInputIt	ids_last,
		PointInputIt	points_first,
		TimestampInputIt	timestamps_first,
		IdOutputIt	ids_output_first,
		PointOutputIt	points_output_first,
		TimestampOutputIt	timestamps_output_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource() )

Derive trajectories from object ids, points, and timestamps.

Output points and timestamps are reordered to be grouped by object ID and ordered by timestamp within groups. Returns a vector containing the offset index of the first object of each trajectory in the output.

Template Parameters

IdInputIt	Iterator over object IDs. Must meet the requirements of LegacyRandomAccessIterator and be device-readable.
PointInputIt	Iterator over points. Must meet the requirements of LegacyRandomAccessIterator and be device-readable.
TimestampInputIt	Iterator over timestamps. Must meet the requirements of LegacyRandomAccessIterator and be device-readable.
IdOutputIt	Iterator over output object IDs. Must meet the requirements of LegacyRandomAccessIterator and be device-writeable.
PointOutputIt	Iterator over output points. Must meet the requirements of LegacyRandomAccessIterator and be device-writeable.
TimestampOutputIt	Iterator over output timestamps. Must meet the requirements of LegacyRandomAccessIterator and be device-writeable.

Parameters

ids_first	beginning of the range of input object ids
ids_last	end of the range of input object ids
points_first	beginning of the range of input point (x,y) coordinates
timestamps_first	beginning of the range of input timestamps
ids_out_first	beginning of the range of output object ids
points_out_first	beginning of the range of output point (x,y) coordinates
timestamps_out_first	beginning of the range of output timestamps
stream	the CUDA stream on which to perform computations and allocate memory.
mr	optional resource to use for output device memory allocations

Returns

a unique_ptr to a device_uvector containing the offset index of the first object of each trajectory in the sorted output. These offsets can be used to access the sorted output data.

Precondition

There must be no overlap between any of the input and output ranges.

The type of the object IDs and timestamps must support strict weak ordering via comparison operators.

trajectory_bounding_boxes()

std::unique_ptr< cudf::table > cuspatial::trajectory_bounding_boxes	(	cudf::size_type	num_trajectories,
		cudf::column_view const &	object_id,
		cudf::column_view const &	x,
		cudf::column_view const &	y,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource() )

Compute the spatial bounding boxes of trajectories. Groups the x, y, and timestamp columns by object id to determine unique trajectories, then computes the minimum bounding box to contain all routes in each trajectory.

Note

Assumes object_id, timestamp, x, y presorted by (object_id, timestamp).

Parameters

num_trajectories	number of trajectories (unique object ids)
object_id	column of object (e.g., vehicle) ids
x	coordinates (in kilometers)
y	coordinates (in kilometers)
mr	The optional resource to use for output device memory allocations

Exceptions

cuspatial::logic_error	If object_id isn't cudf::type_id::INT32
cuspatial::logic_error	If x and y are different types
cuspatial::logic_error	If object_id, x, or y contain nulls
cuspatial::logic_error	If object_id, x, and y are different sizes

Returns

a cudf table of bounding boxes with length num_trajectories and four columns: x_min - the minimum x-coordinate of each bounding box in kilometers y_min - the minimum y-coordinate of each bounding box in kilometers x_max - the maximum x-coordinate of each bounding box in kilometers y_max - the maximum y-coordinate of each bounding box in kilometers

trajectory_distances_and_speeds() [1/2]

std::unique_ptr< cudf::table > cuspatial::trajectory_distances_and_speeds	(	cudf::size_type	num_trajectories,
		cudf::column_view const &	object_id,
		cudf::column_view const &	x,
		cudf::column_view const &	y,
		cudf::column_view const &	timestamp,
		rmm::device_async_resource_ref	mr = rmm::mr::get_current_device_resource() )

Compute the distance and speed of objects in a trajectory. Groups the timestamp, x, and y, columns by object id to determine unique trajectories, then computes the average distance and speed for all routes in each trajectory.

Note

Assumes object_id, timestamp, x, y presorted by (object_id, timestamp).

Parameters

num_trajectories	number of trajectories (unique object ids)
object_id	column of object (e.g., vehicle) ids
x	coordinates (in kilometers)
y	coordinates (in kilometers)
timestamp	column of timestamps in any resolution
mr	The optional resource to use for output device memory allocations

Exceptions

cuspatial::logic_error	If object_id isn't cudf::type_id::INT32
cuspatial::logic_error	If x and y are different types
cuspatial::logic_error	If timestamp isn't a cudf::TIMESTAMP type
cuspatial::logic_error	If object_id, x, y, or timestamp contain nulls
cuspatial::logic_error	If object_id, x, y, and timestamp are different sizes

Returns

a cuDF table of distances (meters) and speeds (meters/second) whose length is num_trajectories, sorted by object_id.

trajectory_distances_and_speeds() [2/2]

template<typename IdInputIt , typename PointInputIt , typename TimestampInputIt , typename OutputIt , typename IndexT = iterator_value_type<IdInputIt>>

OutputIt cuspatial::trajectory_distances_and_speeds	(	IndexT	num_trajectories,
		IdInputIt	ids_first,
		IdInputIt	ids_last,
		PointInputIt	points_first,
		TimestampInputIt	timestamps_first,
		OutputIt	distances_and_speeds_first,
		rmm::cuda_stream_view	stream = rmm::cuda_stream_default )

Compute the total distance (in meters) and average speed (in m/s) of objects in trajectories.

Note

Assumes object_id, timestamp, x, y presorted by (object_id, timestamp).

Template Parameters

IdInputIt	Iterator over object IDs. Must meet the requirements of LegacyRandomAccessIterator and be device-readable.
PointInputIt	Iterator over points. Must meet the requirements of LegacyRandomAccessIterator and be device-readable.
TimestampInputIt	Iterator over timestamps. Must meet the requirements of LegacyRandomAccessIterator and be device-readable.
OutputIt	Iterator over output (distance, speed) pairs. Must meet the requirements of LegacyRandomAccessIterator and be device-writeable.
IndexT	The type of the object IDs.

Parameters

num_trajectories	number of trajectories (unique object ids)
ids_first	beginning of the range of input object ids
ids_last	end of the range of input object ids
points_first	beginning of the range of input point (x,y) coordinates
timestamps_first	beginning of the range of input timestamps
distances_and_speeds_first	beginning of the range of output (distance, speed) pairs
stream	the CUDA stream on which to perform computations and allocate memory.

Returns

An iterator to the end of the range of output (distance, speed) pairs.