colimit 0.1.13

better know your limits

colimit is a python library to support the mathematical project on mobility at Darmstadt University of Applied Sciences.

The focus of the project is to provide robust path predictions based on instantaneous geo-location data.

The later are given as positional gps coordinate in latitude and longitude as well as data of motion by speed and direction.

At first - based on these geo-location data - the project will provide algorithm to predict which way we are moving on. Here, way is in the sense of OpenStreetMap.

And in a second step, list of ways are extracted and sorted in the descending order being expected to be taken.

All those predictions are under resource restrictions like limited time, cpu power and data traffic.

As a practical application the algorithm may be supplied to a mobile app backend. This is a python server application, which provides speed limit information according the way the mobile user is assumed to be driving on.

Therefore the mobile app provides geo-location data of its current position and motion. The server backend adds functionality to select ways around those position. Next the supplied algorithm filters and sorts a requested list of ways. Finally the sorted list of ways is send back to the mobile device.

Once identified, information about the ways on speed limits are displayed on the mobile app.

Quick Start

First, install then colimit library. The latest stable version can always be installed or updated via pip:

$ pip install https://limits.pythonanywhere.com/colimit-0-py3-none-any.whl

Now, we can start python interpreter and import the project simply by

>>> import colimit

after installation.

Create a file for your get_limit function, which is the delegate function for your algorithm with in the server backend.

This file should implement as fixed signature:

def get_limit(latitude, longitude, speed, direction, get_ways):
    limit, ways = 1.0, ()
    # ... your code ...
    return limit, ways

For details on the arguments and return value, see Connection().get_limit(). Note all arguments are float except get_ways. get_ways will be a function, for details see Connection().get_ways(). It can be used to request a list of Way() objects within your get_limit function. Now, it is your turn to filter and sort clever!

There are only a few other classes involved, as Speed which is just a simple extension of float to provide convenient unit con version from km/h or mph to mps and back. This is useful since internally all speed figures are in mps.

>>> # create speed from value in unit 'kmh'
>>> v = Speed(30, unit='kmh')
>>> v
8.33 mps (30.00 km/h)

>>> # convert back to 'kmh' as a float
>>> v.kmh
30.0

>>> type(v.kmh)
<class 'float'>

>>> # convert to 'miles per hour' as a float
>>> v.mph
18.64116666666667

>>> # Speed inductances admit simple operations like + and -
>>> v + colimit.Speed(1, 'mps')
9.33 mps (33.60 km/h)

>>> # and * or / with any float or int
>>> v * 2
16.67 mps (60.00 km/h)

Any Way is technically given as a ordered set of points (nodes), which is simply a list of gps coordinate. Each gps coordinate of latitude and longitude states a geo-Location data which can be enriched by data of motion speed and direction. The later can be used to predict future positions, again expressed as Location.

>>> # a simple location given by gps coordinate
>>> hda = colimit.Location(latitude=49.867219, longitude=8.638495)
>>> hda
Location at (49.867219,08.638495) at 21-08-29:22-46-51

>>> hda.coordinate
(49.867219, 8.638495)

>>> # enriched by data of motion
>>> speed = colimit.Speed(30, 'kmh').mps
>>> direction = 41.0  # cardinal direction in degrees to north=0.0
>>> loc = colimit.Location(latitude=49.867219, longitude=8.638495,
                           speed=speed, direction=direction)
>>> loc
Location at (49.867219,08.638495) with speed 30.0 km/h in direction 41.00° at 21-08-29:22-49-32

>>> # using geometric calculations one predicts the position in future time
>>> nxt =loc.next(timedelta=2.0)  # position under constant motion in two seconds
>>> nxt
Location at (49.867317,08.638608) with speed 30.0 km/h in direction 41.00° at 21-08-29:23-36-12

>>> # again using geometric calculations one derives the distance between to points
>>> loc.dist(nxt)  # distance in meter
16.666666666775978

Since such prediction of motion differ on a sphere or ellipsoid to the motion in the flat plane, this becomes a geometric problem. By default, Location uses planar geometry. The relevant algorithm are Location().polar() and Location().xy() which can be replaced by more elaborated ones if needed.

Moreover, to select the most reasonable way depending on Location is a geometric problem, too. Each way is a polygon with vertices being Location points. So a way edge or way segment is just given by the line between tow Location points. To decide which way segment fits best, distances and directions in non planar geometry have to be derived.

All this will take place in the get_limit file using plain python functionality plus the three colimit classes Speed, Location and Way.

Once implemented, the file can be tested locally using Connection.get_limit() with Connection().get_ways(). Further test tools like test() and gpx() may be supportive.

After successful local testing the get_limit file can be uploaded using a Connection().update_get_limit_code() to the backend server. Now user tests on mobile devices can follow to evaluate the performance of the algorithm in practice.

License

Code and documentation are only available for personal usage during the project course. No re-use without permission by the author (jan-philipp.hoffmann (at) h-da.de).