├── images ├── AC.png └── DB.png ├── target_intersection.png └── README.md /images/AC.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/wkelongws/trajectory_clustering_with_cuspatial/HEAD/images/AC.png -------------------------------------------------------------------------------- /images/DB.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/wkelongws/trajectory_clustering_with_cuspatial/HEAD/images/DB.png -------------------------------------------------------------------------------- /target_intersection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/wkelongws/trajectory_clustering_with_cuspatial/HEAD/target_intersection.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Trajectory Clustering Example with CUSPATIAL 2 | 3 | #### Note: This work was done with cuspatial v0.10 (coupled with this [article](https://medium.com/rapids-ai/releasing-cuspatial-to-accelerate-geospatial-and-spatiotemporal-processing-b686d8b32a9)) and may not work as is with newer version of cuspatial. We encourage you to check the [offical cuspatial repo](https://github.com/rapidsai/cuspatial/) for updates. This repo can still serve well as a quickstart read for beginners. 4 | 5 | ------------------ 6 | 7 | [CUSPATIAL](https://github.com/rapidsai/cuspatial) is a C++ library with python bindings that is based on [CUDA](https://developer.nvidia.com/cuda-zone) and [CUDF](https://github.com/rapidsai/cudf). 8 | CUSPATIAL provides significant GPU acceleration to common spatial and spatio- 9 | temporal operations such as point in polygon, distance between trajectories, and 10 | trajectory clustering. The speed-up ranges from 10x to 10000x for different 11 | operations. 12 | 13 | This repo shows an example of accelerating a clustering problem using CUSPATIAL on a real-world vehicle trajectory dataset. On this particular use case, CUSPATIAL brings the end-2-end computation time from around 11 hours down to less than 15 seconds. 14 | 15 | [//]: # (Image References) 16 | 17 | [AC]: ./images/AC.png "AC" 18 | [DB]: ./images/DB.png "DB" 19 | [LOCUST_HILL_EB]: ./images/LOCUST_HILL_EB.png "LOCUST_HILL_EB" 20 | [jitter_effect]: ./output_images/jitter_effect.png "jitter_effect" 21 | [moviepy_saveclip]: ./images/moviepy_saveclip.png "moviepy_saveclip" 22 | 23 | ## Problem Statement - Trajectory Clustering 24 | 25 | The trajectory clustering task is grouping a set of trajectories in such a way that trajectories in the same group are more similar to each other than to those in other groups. It is useful for various problems such as motion pattern extraction, behavior analysis and more. 26 | 27 | The clustering task consists of two major components in general: 28 | 29 | 1. Similarity Metric 30 | 2. Searching Algorithm 31 | 32 | Given a specific similarity metric, different clustering algorithm will have different searching mechanism and different complexity. But in some case people may want to precompute all pairwise similarities. One of the many reasons could be people may need to perform multiple iterations of hyperparameter search for the clustering algorithm to get a good result and we don't want to redo the time-consuming similarity computation each time. 33 | 34 | In this trajectory clustering example, we work on a particular vehicle trajectory dataset. Below is a quick summary stats of the dataset (More description of this dataset can be found in the following section): 35 | 36 | | num_trajectories | 10070 | 37 | |------------------|-------| 38 | | max_length | 961 | 39 | | min_length | 30 | 40 | | avg_length | 87 | 41 | 42 | We use `Hausdorff distance` as the similarity metric between trajectories. We compute the pairwise similarity matrix and apply AgglomerativeClustering (AC) and DBSCAN afterwards. 43 | 44 | In this example, CUSPATIAL can significantly accelerate the computation of the `Hausdorff distance` similarity matrix. Comparing to the typical scikit-learn implementation of `Hausdorff distance` (single CPU thread), CUSPATICAL reduces the computation time from about 5 hours to 13.5 seconds on this particular dataset. 45 | 46 | Since we pre-computed the similarity matrix, we can experiment with different clustering algorithm and different hyperparameter sets much easier. In this example we do it in an interactive way using ipython widgets, you may play with the hyperparameter set and see how the clustering result responds. Below shows one example each for AC and DBSCAN: 47 | 48 | ![alt text][AC] 49 | 50 | ![alt text][DB] 51 | 52 | ## Dataset Used 53 | 54 | The real-world trajectory dataset we used here for this example is collected from a traffic intersection located in Dubuque, Iowa. We applied the following steps to extract vehicle trajectories from multiple cameras implemented at this intersection: 55 | 56 | * Detect vehicle locations in camera domain using AI based detectors; 57 | * Apply tracking algorithm to assign the same id to the same vehicle; 58 | * Project the vehicle location from camera domain to latitudes and longitudes; 59 | * Create trajectories based on vehicle id. 60 | 61 | A python pickle file (created using python 3.7) of this dataset can be downloaded [here](https://drive.google.com/file/d/1GE-_z9HgLp3eV7Lgo_KOl53QuMgiCUMS/view?usp=sharing). 62 | 63 | This dataset is part of a city-wide traffic video database which is developed to support various smart city and smart traffic research tasks (see [AI City Challenge](https://www.aicitychallenge.org/) for more details). 64 | 65 | ## Install Dependencies 66 | 67 | 1. cuSPATIAL: [instructions](https://github.com/rapidsai/cuspatial/blob/branch-0.10/README.md#compile--install-c-backend) 68 | 2. scikit-image: `pip install scikit-image` (DO NOT use conda install) 69 | 3. opencv: `conda install -c conda-forge opencv` 70 | 4. ipywidgets: `conda install -c anaconda ipywidgets` 71 | 5. scikit-learn: `conda install -c anaconda scikit-learn` 72 | --------------------------------------------------------------------------------