Globally replace "polyline" with "linestring" (#788)

Replaces all uses of "polyline" (and abbreviations) globally in cuspatial with "linestring" for consistency.  

Fixes #520

Authors:
  - Mark Harris (https://github.com/harrism)

Approvers:
  - Michael Wang (https://github.com/isVoid)

URL: #788

README.md

@@ -18,7 +18,7 @@ cuSpatial supports the following operations on spatial and trajectory data:
 7. Computing spatial bounding boxes of trajectories
 8. Quadtree-based indexing for large-scale point data
 9. Quadtree-based point-in-polygon spatial join
-10. Quadtree-based point-to-polyline nearest neighbor distance
+10. Quadtree-based point-to-linestring nearest neighbor distance
 11. Distance computation (point-point, point-linestring, linestring-linestring)
 12. Finding nearest points between point and linestring
 
@@ -84,13 +84,13 @@ conda env update --file conda/environments/cuspatial_dev_cuda11.5.yml
 
    Some other tests involve I/O from data files under `$CUSPATIAL_HOME/test_fixtures`.
    For example, `$CUSPATIAL_HOME/cpp/build/gtests/SHAPEFILE_READER_TEST` requires three
-   pre-generated polygon shapefiles that contain 0, 1 and 2 polygons, respectively. They are available at 
+   pre-generated polygon shapefiles that contain 0, 1 and 2 polygons, respectively. They are available at
    `$CUSPATIAL_HOME/test_fixtures/shapefiles` <br>
 
 **NOTE:** Currently, cuSpatial supports reading point/polyine/polygon data using
 Structure of Array (SoA) format and a [shapefile reader](./cpp/src/io/shp)
 to read polygon data from a shapefile.
 Alternatively, python users can read any point/polyine/polygon data using
-existing python packages, e.g., [Shapely](https://pypi.org/project/Shapely/) 
+existing python packages, e.g., [Shapely](https://pypi.org/project/Shapely/)
 and [Fiona](https://github.com/Toblerity/Fiona),to generate numpy arrays and feed them to
 [cuSpatial python APIs](https://docs.rapids.ai/api/cuspatial/stable/).

cpp/CMakeLists.txt

@@ -1,5 +1,5 @@
 #=============================================================================
-# Copyright (c) 2019-2020, NVIDIA CORPORATION.
+# Copyright (c) 2019-2022, NVIDIA CORPORATION.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -121,10 +121,10 @@ add_library(cuspatial
     src/io/shp/polygon_shapefile_reader.cpp
     src/io/shp/polygon_shapefile_reader.cu
     src/join/quadtree_point_in_polygon.cu
-    src/join/quadtree_point_to_nearest_polyline.cu
-    src/join/quadtree_poly_filtering.cu
+    src/join/quadtree_point_to_nearest_linestring.cu
+    src/join/quadtree_bbox_filtering.cu
     src/spatial/polygon_bounding_box.cu
-    src/spatial/polyline_bounding_box.cu
+    src/spatial/linestring_bounding_box.cu
     src/spatial/point_in_polygon.cu
     src/spatial_window/spatial_window.cu
     src/spatial/haversine.cu

cpp/include/cuspatial/distance/linestring_distance.hpp

@@ -31,7 +31,7 @@ namespace cuspatial {
  */
 
 /**
- * @brief Compute shortest distance between pairs of linestrings (a.k.a. polylines)
+ * @brief Compute shortest distance between pairs of linestrings
  *
  * 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,

cpp/include/cuspatial/distance/point_linestring_distance.hpp

@@ -19,7 +19,7 @@
 namespace cuspatial {
 
 /**
- * @brief Compute distance between pairs of points and linestrings (a.k.a. polylines)
+ * @brief Compute distance between pairs of points and linestrings
  *
  * The distance between a point and a linestring is defined as the minimum distance
  * between the point and any segment of the linestring. For each input point, this

cpp/include/cuspatial/polyline_bounding_box.hpp → cpp/include/cuspatial/linestring_bounding_box.hpp

@@ -25,14 +25,14 @@
 namespace cuspatial {
 
 /**
- * @brief Compute minimum bounding boxes of a set of polylines and an expansion radius.
+ * @brief Compute minimum bounding boxes of a set of linestrings and an expansion radius.
  *
  * @ingroup spatial_relationship
  *
- * @param poly_offsets Begin indices of the first point in each polyline (i.e. prefix-sum)
- * @param x Polyline point x-coordinates
- * @param y Polyline point y-coordinates
- * @param expansion_radius Radius of each polyline point
+ * @param linestring_offsets Begin indices of the first point in each linestring (i.e. prefix-sum)
+ * @param x Linestring point x-coordinates
+ * @param y Linestring point y-coordinates
+ * @param expansion_radius Radius of each linestring point
  *
  * @return a cudf table of bounding boxes as four columns of the same type as `x` and `y`:
  * x_min - the minimum x-coordinate of each bounding box
@@ -41,8 +41,8 @@ namespace cuspatial {
  * y_max - the maximum y-coordinate of each bounding box
  */
 
-std::unique_ptr<cudf::table> polyline_bounding_boxes(
-  cudf::column_view const& poly_offsets,
+std::unique_ptr<cudf::table> linestring_bounding_boxes(
+  cudf::column_view const& linestring_offsets,
   cudf::column_view const& x,
   cudf::column_view const& y,
   double expansion_radius,

cpp/include/cuspatial/spatial_join.hpp

@@ -30,14 +30,14 @@ namespace cuspatial {
  */
 
 /**
- * @brief Search a quadtree for polygon or polyline bounding box intersections.
+ * @brief Search a quadtree for polygon or linestring bounding box intersections.
  *
  * @note `scale` is applied to (x - x_min) and (y - y_min) to convert coordinates into a Morton code
  * in 2D space.
  * @note `max_depth` should be less than 16, since Morton codes are represented as `uint32_t`.
  *
  * @param quadtree: cudf table representing a quadtree (key, level, is_quad, length, offset).
- * @param poly_bbox: cudf table of bounding boxes as four columns (x_min, y_min, x_max, y_max).
+ * @param bbox: cudf table of bounding boxes as four columns (x_min, y_min, x_max, y_max).
  * @param x_min The lower-left x-coordinate of the area of interest bounding box.
  * @param x_max The upper-right x-coordinate of the area of interest bounding box.
  * @param y_min The lower-left y-coordinate of the area of interest bounding box.
@@ -47,19 +47,21 @@ namespace cuspatial {
  * @param mr The optional resource to use for output device memory allocations.
  *
  * @throw cuspatial::logic_error If the quadtree table is malformed
- * @throw cuspatial::logic_error If the polygon bounding box table is malformed
+ * @throw cuspatial::logic_error If the bounding box table is malformed
  * @throw cuspatial::logic_error If scale is less than or equal to 0
  * @throw cuspatial::logic_error If x_min is greater than x_max
  * @throw cuspatial::logic_error If y_min is greater than y_max
  * @throw cuspatial::logic_error If max_depth is less than 1 or greater than 15
  *
  * @return A cudf table with two columns:
- *   - poly_offset - INT32 column of indices for each poly bbox that intersects with the quadtree.
- *   - quad_offset - INT32 column of indices for each leaf quadrant intersecting with a poly bbox.
+ *   - bbox_offset - INT32 column of indices for each polygon/linestring bbox that intersects with
+ *                   the quadtree.
+ *   - quad_offset - INT32 column of indices for each leaf quadrant intersecting with a
+ *                   polygon/linestring bbox.
  */
 std::unique_ptr<cudf::table> join_quadtree_and_bounding_boxes(
   cudf::table_view const& quadtree,
-  cudf::table_view const& poly_bbox,
+  cudf::table_view const& bbox,
   double x_min,
   double x_max,
   double y_min,
@@ -87,8 +89,8 @@ std::unique_ptr<cudf::table> join_quadtree_and_bounding_boxes(
  * @param point_y y-coordinates of points to test
  * @param poly_offsets Begin indices of the first ring in each polygon (i.e. prefix-sum).
  * @param ring_offsets Begin indices of the first point in each ring (i.e. prefix-sum).
- * @param poly_points_x Polygon point x-coodinates.
- * @param poly_points_y Polygon point y-coodinates.
+ * @param poly_points_x Polygon point x-coordinates.
+ * @param poly_points_y Polygon point y-coordinates.
  * @param mr The optional resource to use for output device memory allocations.
  *
  * @throw cuspatial::logic_error If the poly_quad_pairs table is malformed.
@@ -119,51 +121,51 @@ std::unique_ptr<cudf::table> quadtree_point_in_polygon(
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
 /**
- * @brief Finds the nearest polyline to each point in a quadrant, and computes the distances between
- * each point and polyline.
+ * @brief Finds the nearest linestring to each point in a quadrant, and computes the distances
+ * between each point and linestring.
  *
- * Uses the table of (polyline, quadrant) pairs returned by
- *`cuspatial::join_quadtree_and_bounding_boxes` to ensure distances are computed only for the points
- *in the same quadrant as each polyline.
+ * Uses the table of (linestring, quadrant) pairs returned by
+ * `cuspatial::join_quadtree_and_bounding_boxes` to ensure distances are computed only for the
+ * points in the same quadrant as each linestring.
  *
- * @param poly_quad_pairs cudf table of (polyline, quadrant) index pairs returned by
+ * @param linestring_quad_pairs cudf table of (linestring, quadrant) index pairs returned by
  * `cuspatial::join_quadtree_and_bounding_boxes`
  * @param quadtree cudf table representing a quadtree (key, level, is_quad, length, offset).
  * @param point_indices Sorted point indices returned by `cuspatial::quadtree_on_points`
  * @param point_x x-coordinates of points to test
  * @param point_y y-coordinates of points to test
- * @param poly_offsets Begin indices of the first point in each polyline (i.e. prefix-sum)
- * @param poly_points_x Polyline point x-coordinates
- * @param poly_points_y Polyline point y-coordinates
+ * @param linestring_offsets Begin indices of the first point in each linestring (i.e. prefix-sum)
+ * @param linestring_points_x Linestring point x-coordinates
+ * @param linestring_points_y Linestring point y-coordinates
  * @param mr The optional resource to use for output device memory allocations.
  *
- * @throw cuspatial::logic_error If the poly_quad_pairs table is malformed.
+ * @throw cuspatial::logic_error If the linestring_quad_pairs table is malformed.
  * @throw cuspatial::logic_error If the quadtree table is malformed.
  * @throw cuspatial::logic_error If the number of point indices doesn't match the number of points.
- * @throw cuspatial::logic_error If any polyline has fewer than two vertices.
- * @throw cuspatial::logic_error If the types of point and polyline vertices are different.
+ * @throw cuspatial::logic_error If any linestring has fewer than two vertices.
+ * @throw cuspatial::logic_error If the types of point and linestring vertices are different.
  *
- * @return A cudf table with three columns, where each row represents a point/polyline pair and the
- * distance between the two:
+ * @return A cudf table with three columns, where each row represents a point/linestring pair and
+ * the distance between the two:
  *
- *    point_offset - UINT32 column of point indices
- * polyline_offset - UINT32 column of polyline indices
- *        distance - FLOAT or DOUBLE column (based on input point data type) of distances between
- *                   each point and polyline
+ *   point_offset      - UINT32 column of point indices
+ *   linestring_offset - UINT32 column of linestring indices
+ *   distance          - FLOAT or DOUBLE column (based on input point data type) of distances
+ *                       between each point and linestring
  *
- * @note The returned point and polyline indices are offsets into the (point_x, point_y) and
- * poly_quad_pairs inputs, respectively.
+ * @note The returned point and linestring indices are offsets into the (point_x, point_y) and
+ * linestring_quad_pairs inputs, respectively.
  *
  **/
-std::unique_ptr<cudf::table> quadtree_point_to_nearest_polyline(
-  cudf::table_view const& poly_quad_pairs,
+std::unique_ptr<cudf::table> quadtree_point_to_nearest_linestring(
+  cudf::table_view const& linestring_quad_pairs,
   cudf::table_view const& quadtree,
   cudf::column_view const& point_indices,
   cudf::column_view const& point_x,
   cudf::column_view const& point_y,
-  cudf::column_view const& poly_offsets,
-  cudf::column_view const& poly_points_x,
-  cudf::column_view const& poly_points_y,
+  cudf::column_view const& linestring_offsets,
+  cudf::column_view const& linestring_points_x,
+  cudf::column_view const& linestring_points_y,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
 /**

cpp/include/doxygen_groups.h

@@ -66,7 +66,7 @@
  *          @file point_in_polygon.hpp
  *          @file point_in_polygon.cuh
  *          @file polygon_bounding_box.hpp
- *          @file polyline_bounding_box.hpp
+ *          @file linestring_bounding_box.hpp
  *          @file spatial_window.hpp
  *      @}
  *      @defgroup nearest_points Nearest Points

cpp/src/join/detail/point.cuh → cpp/src/join/detail/get_quad_and_local_point_indices.cuh

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, NVIDIA CORPORATION.
+ * Copyright (c) 2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,7 +23,7 @@
 namespace cuspatial {
 namespace detail {
 
-inline __device__ std::pair<uint32_t, uint32_t> get_quad_poly_and_local_point_indices(
+inline __device__ std::pair<uint32_t, uint32_t> get_quad_and_local_point_indices(
   uint32_t const global_index, uint32_t const* point_offsets, uint32_t const* point_offsets_end)
 {
   // Calculate the position in "point_offsets" that `global_index` falls between.