[DISCUSSION] Standardize API inputs with GeoSeries

[isVoid]

Today the python computation API accepts raw structure of arrays input. Such as:

cuspatial/python/cuspatial/cuspatial/core/gis.py

Line 29 in da1cb97

def directed_hausdorff_distance(xs, ys, space_offsets):

and

cuspatial/python/cuspatial/cuspatial/core/gis.py

Lines 166 to 173 in da1cb97

	def point_in_polygon(
	test_points_x,
	test_points_y,
	poly_offsets,
	poly_ring_offsets,
	poly_points_x,
	poly_points_y,
	):

The history of this input interface is that cuspatial was used to accelerate specific workflow where developers are very familiar with the underlying data structure of the geometry and used them. General GIS users are not required to know how the data layout before working with GIS functions, and @thomcom and I believe that using GeoSeries as the abstraction layer between user and underlying APIs is important.

cuSpatial's GeoSeries API is implemented based on GeoArrow specification: https://github.com/geopandas/geo-arrow-spec, under the hood it's an arrow UnionArray. This allows GeoSeries represent an array of pure or mixed geometry types. Currently many computation API only supports pure geometry array inputs. This falls within the range where GeoSeries is capable of supporting.

Ideally, the above APIs should look like:

def directed_hausdorff_distance(points: cuspatial.GeoSeries, space_offset: cudf.Series):

def points_in_polygons(points: cuspatial.GeoSeries, polygons: cuspatial.GeoSeries)

TODO:

Distance

Preview Give feedback

1. Convert Directed hausdorff distance to Accept GeoSeries as Input #920
   +0
2. Convert Haversine distance to Accept GeoSeries as Input #921
   +0

Bounding

Preview Give feedback

1. Convert Polygon Bounding Boxes to Accept GeoSeries as Input #929
   +0
2. Convert LineString Bounding Boxes to Accept GeoSeries as Input #930
   +0

Filtering

Preview Give feedback

1. Convert Points in Spatial Window to Accept GeoSeries as Input #936
   +0

Indexing

Preview Give feedback

1. Convert Quadtree on Points to Accept GeoSeries as Input #937
   +0

Join

Preview Give feedback

1. Convert Point in Polygon to Accept GeoSeries as Input #939
   +0
   
2. Convert join quadtree and bounding boxes to Accept GeoSeries as Input #940
   +0
   
3. Convert quadtree point in polygon to Accept GeoSeries as Input #941
   +0
4. Convert quadtree point to nearest linestring to Accept GeoSeries as Input #942
   +0

Projection

Preview Give feedback

1. Convert Sinusoidal projection to Accept GeoSeries as Input #949
   +0

Trajectory

Preview Give feedback

1. Convert Derive trajectories to Accept GeoSeries as Input #950
   +0
2. Convert Trajectory Bounding Boxes to Accept GeoSeries as Input #951
   +0
3. Convert Trajectory distances and speeds to Accept GeoSeries as Input #952
   +0

Docs

Preview Give feedback

1. Update User Notebook Update user guide notebook to reflect geoseries refactor effort #935

[harrism]

Ideally, the above APIs should look like:

def directed_hausdorff_distance(points: cuspatial.GeoSeries):

Hmmm, this ignores the spaces in the Hausdorff distance API. This is a directed all-pairs distance computation. So the grouping and order of points matters.

[isVoid]

Edited PR description to address the change.

[harrism]

I like this direction. API looks much cleaner. As long as we provide factories / converters from other layouts / dataframes.

[thomcom]

Thanks for creating this discussion. I agree that we should use GeoSeries in any API call that uses coordinates or offsets as much as possible.

[thomcom]

I propose that we create individual issues for each API that needs to be updated.

[github-actions]

This issue has been labeled inactive-30d due to no recent activity in the past 30 days. Please close this issue if no further response or action is needed. Otherwise, please respond with a comment indicating any updates or changes to the original issue and/or confirm this issue still needs to be addressed. This issue will be labeled inactive-90d if there is no activity in the next 60 days.

[harrism]

let's convert this to a milestone.

[isVoid]

I propose that we create individual issues for each API that needs to be updated.

Went with this way - this issue is now a meta issue that tracks the progress, where each API is tracked with a sub issue in the task list.

[isVoid]

This is done.