Metadata-Version: 2.1
Name: openlr-dereferencer
Version: 1.1.0
Summary: OpenLR location dereferencer
Home-page: https://github.com/tomtom-international/openlr-dereferencer-python
Author: Jan Ole Zabel
Author-email: janole.zabel@tomtom.com
License: Apache 2.0
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: openlr (==1.0.1)
Requires-Dist: geographiclib
Requires-Dist: shapely

# openlr-dereferencer

[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
[![Build status](https://img.shields.io/travis/tomtom-international/openlr-dereferencer-python)](https://travis-ci.org/tomtom-international/openlr-dereferencer-python)
[![Coverage Status](https://img.shields.io/codecov/c/github/tomtom-international/openlr-dereferencer-python/master.svg)](https://codecov.io/github/tomtom-international/openlr-dereferencer-python?branch=master)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/openlr-dereferencer)](https://pypi.org/project/openlr-dereferencer)
[![PyPI](https://img.shields.io/pypi/v/openlr-dereferencer)](https://pypi.org/project/openlr-dereferencer)
[![Documentation](https://readthedocs.org/projects/openlr-dereferencer-python/badge/)](https://openlr-dereferencer-python.readthedocs.io)


This is a Python package for decoding OpenLR™ location references on target maps.
## Dependencies
- Python ≥ 3.6
- geographiclib (PyPi package)
- shapely (PyPi package)
- [openlr](https://github.com/tomtom-international/openlr-python) (PyPi package)
- For unittests, SQlite with spatialite extension is required
## State
- [X] Decoding line locations
- [X] Decoding 'point along line' locations
- [X] Decoding 'POI with access point' locations
## Structure
It is divided into the following submodules:
### maps
Contains an abstract map class, which you may want to implement for your target map.

`maps.wgs84` provides methods for reckoning with WGS84 coordinates.
### example_sqlite_map
Implements the abstract map class for the example map format used in the unittests and examples
### decoding
The actual logic for matching references onto a map.

This includes finding candidate lines and scoring them, and assembling a dereferenced location.

# Installation
This project is available on PyPi:
```sh
pip3 install openlr-dereferencer
```

## Usage
The `decode(reference, mapreader)` function will take a location reference and return map objects.

### Usage Example

First, implement the `MapReader` class for your map.  The `example_sqlite_map` module is an implementation you may look at.

Second, construct a location reference. For instance, parse an OpenLR line location string:
```py
from openlr import binary_decode
reference = binary_decode("CwmG8yVjzCq0Dfzr/gErRRs=")
```

Third, decode the reference on an instance of your map reader class:
```py
from openlr_dereferencer import decode
real_location = decode(reference, mapreader)

real_location.lines # <- A list of map objects
```

## Configuration
The `decode` function takes in an optional `Config` object contaning decoding settings.
You may just change these before decoding:
```py
from openlr_dereferencer import decode, Config

my_config = Config(
    geo_weight = 0.66,
    frc_height = 0.17,
    fow_height = 0.17,
    bear_weight = 0.0
)

decode(reference, mapreader, config=my_config)
```

The full list of available options is located [here](https://openlr-dereferencer-python.readthedocs.io/en/latest/openlr_dereferencer.decoding.html#openlr_dereferencer.decoding.configuration.Config).

## Logging
`openlr-dereferencer` logs all mapmatching decisions using the standard library `logging` module.

Use it to turn on debugging:
```py
import logging

logging.basicConfig(level=logging.DEBUG)
```

## Observing
Via implementing the [Observer](https://openlr-dereferencer-python.readthedocs.io/en/latest/openlr_dereferencer.observer.html#openlr_dereferencer.observer.simple_observer.SimpleObserver) interface, you can hook onto certain events happening while decoding, and inspect the situation:
```py
from openlr_dereferencer import DecoderObserver, SimpleObserver

# Look at SimpleObserver for an example implementation
my_observer = SimpleObserver()
decode(reference, mapreader, observer=my_observer)
```

## Development environment

Firstly create a Python virtual environment for the project.
```sh
python3 -m venv .venv
```

Activate the virtual environment.
```sh
source .venv/bin/activate
```

Install the dependency packages into the virtual environment.
```sh
pip install openlr geographiclib shapely

```

You may need to install the spatialite module for sqlite if this is not already present.
```sh
sudo apt install libsqlite3-mod-spatialite
```

To run the decoding tests.
```sh
python3 -m unittest tests.test_decode
```

## More Documentation
You are welcomed to read the generated API documentation at https://openlr-dereferencer-python.readthedocs.io.


