Trajectory#

Functions for identifying and grouping trajectories from point data.

cuspatial.derive_trajectories(object_ids, xs, ys, timestamps)#

Derive trajectories from object ids, points, and timestamps.

Parameters

object_ids: column of object (e.g., vehicle) ids
xs: column of x-coordinates (in kilometers)
ys: column of y-coordinates (in kilometers)
timestamps: column of timestamps in any resolution

Returns

resulttuple (objects, traj_offsets)

objectscudf.DataFrame: object_ids, xs, ys, and timestamps sorted by (object_id, timestamp), used by trajectory_bounding_boxes and trajectory_distances_and_speeds
traj_offsetscudf.Series: offsets of discovered trajectories

Examples

Compute sorted objects and discovered trajectories

>>> objects, traj_offsets = cuspatial.derive_trajectories(
        [0, 1, 2, 3],  # object_id
        [0, 0, 1, 1],  # x
        [0, 0, 1, 1],  # y
        [0, 10, 0, 10] # timestamp
    )
>>> print(traj_offsets)
    0  0
    1  2
>>> print(objects)
       object_id       x       y  timestamp
    0          0       1       0          0
    1          0       0       0         10
    2          1       3       1          0
    3          1       2       1         10

cuspatial.trajectory_distances_and_speeds(num_trajectories, object_ids, xs, ys, timestamps)#

Compute the distance traveled and speed of sets of trajectories

Parameters

num_trajectories: number of trajectories (unique object ids)
object_ids: column of object (e.g., vehicle) ids
xs: column of x-coordinates (in kilometers)
ys: column of y-coordinates (in kilometers)
timestamps: column of timestamps in any resolution

Returns

resultcudf.DataFrame

meterscudf.Series: trajectory distance (in kilometers)
speedcudf.Series: trajectory speed (in meters/second)

Examples

Compute the distances and speeds of derived trajectories

>>> objects, traj_offsets = cuspatial.derive_trajectories(...)
>>> dists_and_speeds = cuspatial.trajectory_distances_and_speeds(
        len(traj_offsets)
        objects['object_id'],
        objects['x'],
        objects['y'],
        objects['timestamp']
    )
>>> print(dists_and_speeds)
                   distance          speed
    trajectory_id
    0                1000.0  100000.000000
    1                1000.0  111111.109375

cuspatial.directed_hausdorff_distance(xs, ys, space_offsets)#

Compute the directed Hausdorff distances between all pairs of spaces.

Parameters

xs: column of x-coordinates
ys: column of y-coordinates
space_offsets: beginning index of each space, plus the last space’s end offset.

Returns

resultcudf.DataFrame: The pairwise directed distance matrix with one row and one column per input space; the value at row i, column j represents the hausdorff distance from space i to space j.

Examples

The directed Hausdorff distance from one space to another is the greatest of all the distances between any point in the first space to the closest point in the second.

Wikipedia

Consider a pair of lines on a grid:

     :
     x
-----xyy---
     :
     :

x₀ = (0, 0), x₁ = (0, 1)

y₀ = (1, 0), y₁ = (2, 0)

x₀ is the closest point in x to y. The distance from x₀ to the farthest point in y is 2.

y₀ is the closest point in y to x. The distance from y₀ to the farthest point in x is 1.414.

Compute the directed hausdorff distances between a set of spaces

>>> result = cuspatial.directed_hausdorff_distance(
        [0, 1, 0, 0], # xs
        [0, 0, 1, 2], # ys
        [0, 2, 4],    # space_offsets
    )
>>> print(result)
         0         1
    0  0.0  1.414214
    1  2.0  0.000000

cuspatial.trajectory_bounding_boxes(num_trajectories, object_ids, xs, ys)#

Compute the bounding boxes of sets of trajectories.

Parameters

num_trajectories: number of trajectories (unique object ids)
object_ids: column of object (e.g., vehicle) ids
xs: column of x-coordinates (in kilometers)
ys: column of y-coordinates (in kilometers)

Returns

resultcudf.DataFrame

minimum bounding boxes (in kilometers) for each trajectory

x_mincudf.Series: the minimum x-coordinate of each bounding box
y_mincudf.Series: the minimum y-coordinate of each bounding box
x_maxcudf.Series: the maximum x-coordinate of each bounding box
y_maxcudf.Series: the maximum y-coordinate of each bounding box

Examples

Compute the minimum bounding boxes of derived trajectories

>>> objects, traj_offsets = trajectory.derive_trajectories(
        [0, 0, 1, 1],  # object_id
        [0, 1, 2, 3],  # x
        [0, 0, 1, 1],  # y
        [0, 10, 0, 10] # timestamp
    )
>>> traj_bounding_boxes = cuspatial.trajectory_bounding_boxes(
        len(traj_offsets),
        objects['object_id'],
        objects['x'],
        objects['y']
    )
>>> print(traj_bounding_boxes)
    x_min   y_min   x_max   y_max
0     0.0     0.0     2.0     2.0
1     1.0     1.0     3.0     3.0

class cuspatial.CubicSpline(t, y, ids=None, size=None, prefixes=None)#

Fits each column of the input Series y to a hermetic cubic spline.

cuspatial.CubicSpline supports two usage patterns: The first is identical to scipy.interpolate.CubicSpline:

curve = cuspatial.CubicSpline(t, y)
new_points = curve(np.linspace(t.min, t.max, 50))

This allows API parity with scipy. This isn’t recommended, as scipy host based interpolation performance is likely to exceed GPU performance for a single curve.

However, cuSpatial massively outperforms scipy when many splines are fit simultaneously. Data must be arranged in a SoA format, and the exclusive prefix_sum of the separate curves must also be passed to the function.:

NUM_SPLINES = 100000
SPLINE_LENGTH = 101
t = cudf.Series(
    np.hstack((np.arange(SPLINE_LENGTH),) * NUM_SPLINES)
).astype('float32')
y = cudf.Series(
    np.random.random(SPLINE_LENGTH*NUM_SPLINES)
).astype('float32')
prefix_sum = cudf.Series(
    cp.arange(NUM_SPLINES + 1)*SPLINE_LENGTH
).astype('int32')
curve = cuspatial.CubicSpline(t, y, prefixes=prefix_sum)
new_samples = cudf.Series(
    np.hstack((np.linspace(
        0, (SPLINE_LENGTH - 1), (SPLINE_LENGTH - 1) * 2 + 1
    ),) * NUM_SPLINES)
).astype('float32')
curve_ids = cudf.Series(np.repeat(
    np.arange(0, NUM_SPLINES), SPLINE_LENGTH * 2 - 1
), dtype="int32")
new_points = curve(new_samples, curve_ids)

Methods

__call__(coordinates[, groups])

Interpolates new input values coordinates using the .c DataFrame or map of DataFrames.

CubicSpline.__init__(t, y, ids=None, size=None, prefixes=None)#

Computes various error preconditions on the input data, then uses CUDA to compute cubic splines for each set of input coordinates on the GPU in parallel.

Parameters

tcudf.Series: time sample values. Must be monotonically increasing.
ycudf.Series: columns to have curves fit to according to x
ids (Optional)cudf.Series: ids of each spline
size (Optional)cudf.Series: fixed size of each spline
prefixes (Optional)cudf.Series: alternative to size, allows splines of varying length. Not yet fully supported.

Returns

CubicSplinecallable o: o.c contains the coefficients that can be used to compute new points along the spline fitting the original t data. o(n) interpolates the spline coordinates along new input values n.

CubicSpline.__call__(coordinates, groups=None)#: Interpolates new input values coordinates using the .c DataFrame or map of DataFrames.

Spatial Indexing

GeoPandas Compatibility