Closest Point of Approach

[SiggyF]

Closest Point of Approach calculator, as discussed in #31.
Code and testcases are based on the implementation from lwgeom in postgis.

A corresponding notebook in movingpandas-examples will be also prepared as PR.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 99.76134% with 1 line in your changes missing coverage. Please review.

Project coverage is 96.92%. Comparing base (3f462dc) to head (bcffa48).
Report is 36 commits behind head on main.

Files with missing lines	Patch %	Lines
movingpandas/cpa.py	99.36%	1 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #457      +/-   ##
==========================================
+ Coverage   96.35%   96.92%   +0.56%     
==========================================
  Files          35       37       +2     
  Lines        4257     5131     +874     
==========================================
+ Hits         4102     4973     +871     
- Misses        155      158       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[SiggyF]

Note that the coverage report says 1 line is not covered, but it is covered in the test test_non_overlapping_time.

[anitagraser]

Let's clean up the PostGIS-related comments before we finalize

[SiggyF]

Thanks for the comments! I'll update the PR later this week.

[SiggyF]

Removed the leftover postgis code that I used to make sure I was in line with their tests. I kept a reference at the top of the source code, for proper attribution.

[anitagraser]

We'll have to ask Sandro and Paul's permission. Their code is GPL and the license would require any derivative to also be GPL https://github.com/postgis/postgis/blob/1141db62ef435f7b7d2bb4cc13766daff4fe880f/liblwgeom/lwlinearreferencing.c#L1138

[SiggyF]

I suggest that I ask them the following:

Dear Sandro, Paul,

I am working on a Closest Point of Approach calculation in the python movingpandas library, a python library for moving features / trajectory calculations, by Anita Graser (cc). I have prepared an implementation based on the lwgeom's code and tests (recoded in python). 

Is it ok with you if we release our code under the current BSD 3-Clause  license of movingpandas? 

For  reference, please see the corresponding
https://github.com/movingpandas/movingpandas/issues/31
https://github.com/SiggyF/movingpandas/tree/feature/tcpa

We attribute your work as follows.  Happy to adapt if requested. 
In the cpa module:
 # we follow the implementation of postgis
 # In partical the function segments_tcpa in
 # https://github.com/postgis/postgis/blob/master/liblwgeom/lwlinearreferencing.c

In the tests:
# Many tests here are based on the tests in lwgeom, cu_measures / test_lwgeom_tcpa:
# https://github.com/postgis/postgis/blob/master/liblwgeom/cunit/cu_measures.c

Kind regards,

Fedor Baart

[anitagraser]

Yes, let's give it a try. Please go ahead.

(What we can definitely do, is add this functionality to Trajectools, since that is already GPL.)

[SiggyF]

We discussed that we will move this code to the trajectools repository, so that it is complient with GPL license. I'll move the code there and provide the corresponding QGIS code.

I'll wrap up this PR by processing the last comments. After that I'll close it and move the code to trajectools.

A possible reuse of this branch could be from a different module as an optional dependency, like in geopandas.

[SiggyF]

Thanks for your comments. I have updated the code / documentation accordingly.

I noticed that the documentation only includes the Trajectory (hardcoded in docs / api / api.rst). I'd be happy to add a few notes on this implementation in the documentation.

[anitagraser]

What do you think about adding a function to the Trajectory class that uses the CPACalculator? Similar to the existing distance functions, something like

Trajectory.get_cpa_distance(another_trajectory, units=None) ... returns the value of CPA(traj_a, traj_b).min()

Should also accept a units parameter for distance unit conversion.

[anitagraser]

Regarding documentation: yes, please add CPACalculator to the documentation

Update: I've added the documentation.

[anitagraser]

And CPACalculator should be added to https://github.com/movingpandas/movingpandas/blob/main/movingpandas/__init__.py so it can be imported like the other classes

[SiggyF]

What do you think about adding a function to the Trajectory class that uses the CPACalculator? Similar to the existing distance functions, something like

Trajectory.get_cpa_distance(another_trajectory, units=None) ... returns the value of CPA(traj_a, traj_b).min()

I would not expect the somewhat domain specific function on the general trajectory, but I'm happy to add it. I would either return CPACalculator(traj_a, traj_b).min().dist (only the distance) or name it get_cpa and return CPACalculator(traj_a, traj_b).min() all information regarding closest point (time, timespan, distance, geometry).

Should also accept a units parameter for distance unit conversion.
I would need to update the implementation for non-cartesian projections. I could update the implementation to use measure_distance_euclidean vs measure_distance_geodesic. I think both would need to be updated with support for including the z coordinate. They seem to both compute 2d distances.

[SiggyF]

And CPACalculator should be added to https://github.com/movingpandas/movingpandas/blob/main/movingpandas/__init__.py so it can be imported like the other classes

I added this.

[SiggyF]

This PR will be moved to trajectools:

• GPL compatibility
• Nice extra feature for QGIS users