Skip to content

Commit

Permalink
Merge branch 'develop'
Browse files Browse the repository at this point in the history
  • Loading branch information
Sbetti Davide (Student Com16) committed Dec 12, 2021
2 parents bed87f4 + 86062b1 commit 37a8fab
Show file tree
Hide file tree
Showing 28 changed files with 32,200 additions and 194 deletions.
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
build/*
dist/*
traces_and_results/*
tflite_tests/*
__pycache__
.ipynb_checkpoints
pyinstaller_command.txt
Expand Down
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) [year] [fullname]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
19 changes: 9 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@

### The goal

GPSClean is an Open Source application developed with the goal of automatically detect and correct errors in GPS traces, using machine learning techniques and without prior geographical knowledge. It is the result of the research undertaken for my thesis project during the Master in Computational Data Science (University of Bolzano).
GPSClean is an Open Source application developed with the goal of automatically detect and correct errors in GPS traces, exported in the widely adopted GPX format, using machine learning techniques and without prior geographical knowledge. It is the result of the research undertaken for my thesis project during the Master in Computational Data Science (University of Bolzano).

Feel free to try the application and report any feedback here on Gitlab.
Feel free to try the application and report any feedback on the project's [Github page](https://github.com/sbettid/GPSClean).

### How does it work?

Expand Down Expand Up @@ -60,18 +60,17 @@ The corrected version of the trace is then exported in the GPX format.

In order to run the application, please follow the subsequent steps:

1) Clone the repository and open a shell in the main folder
2) Execute `pip install -r requirements.txt` to install the required libraries
3) Now you are ready to clean your first GPS trace by executing the following command: `python gpsclean.py path/to/your_trace.gpx`
4) In the same folder where the original trace resides, you will find a cleaned version of the trace with the suffix "_cleaned"
1) Install the package by executing the following command: `pip install -i https://test.pypi.org/simple/ gpsclean`
2) Now you are ready to clean your first GPS trace by executing the following command: `gpsclean path/to/your_trace.gpx`
3) In the same folder where the original trace resides, you will find a cleaned version of the trace with the suffix "_cleaned"

## Downloading a pre-built all-in-one executable

On the other hand, if you prefer to download a all-in-one executable which does not require any prior software installed (not even Python), you can find pre-built all-in-one packages in the [Release section](https://github.com/sbettid/GPSClean/releases) of this repository.
On the other hand, if you prefer to download a all-in-one executable which does not require any prior software installed (not even Python), you can find pre-built all-in-one packages in the [Release section](https://github.com/sbettid/GPSClean/releases) of the repository.


## How to manually create the all-in-one executable

1) Clone the repository and open a shell in the main folder
2) Execute the following command: `pyinstaller -F --add-data "model_42t_traces.h5;." gpsclean.py`
3) At the end of the process, a dist folder can be found inside the main folder, containing the packaged executable.
1) Clone the [repository](https://github.com/sbettid/GPSClean) and open a shell in the `src/gpsclean` folder
2) Execute the following command: `pyinstaller -F --add-data "data/model_42t_traces.h5;data" gpsclean.py`
3) At the end of the process, a dist folder can be found inside the `src/gpsclean` folder, containing the packaged executable.
176 changes: 0 additions & 176 deletions gpsclean.py

This file was deleted.

6 changes: 6 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
[build-system]
requires = [
"setuptools>=42",
"wheel"
]
build-backend = "setuptools.build_meta"
46 changes: 46 additions & 0 deletions setup.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import setuptools

with open("README.md", "r", encoding="utf-8") as fh:
long_description = fh.read()

setuptools.setup(
name="gpsclean",
version="0.2.0",
author="Davide Sbetti",
author_email="[email protected]",
description="An application to correct a GPS trace using machine learning techniques",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/sbettid/GPSClean",
project_urls={
"Bug Tracker": "https://github.com/sbettid/GPSClean/issues",
},
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
package_dir={"": "src"},
packages=setuptools.find_packages(where="src"),
python_requires=">=3.6",
install_requires=[
"art==5.3",
"filterpy==1.4.5",
"geojson==2.5.0",
"gpxpy==1.4.2",
"tensorflow==2.7.0",
"pandas==0.25.3",
"scipy==1.6.1",
"pyproj==3.1.0",
"numpy==1.21.4",
"pyinstaller==4.5.1",
],
package_data={
"gpsclean": ["data/*.h5"],
},
entry_points={
'console_scripts': [
'gpsclean = gpsclean.gpsclean:main',
],
},
)
94 changes: 94 additions & 0 deletions src/gpsclean.egg-info/PKG-INFO
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
Metadata-Version: 2.1
Name: gpsclean
Version: 0.2.0
Summary: An application to correct a GPS trace using machine learning techniques
Home-page: https://github.com/sbettid/GPSClean
Author: Davide Sbetti
Author-email: [email protected]
License: UNKNOWN
Project-URL: Bug Tracker, https://github.com/sbettid/GPSClean/issues
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# GPSClean

## What is GPSClean?

### The goal

GPSClean is an Open Source application developed with the goal of automatically detect and correct errors in GPS traces, exported in the widely adopted GPX format, using machine learning techniques and without prior geographical knowledge. It is the result of the research undertaken for my thesis project during the Master in Computational Data Science (University of Bolzano).

Feel free to try the application and report any feedback on the project's [Github page](https://github.com/sbettid/GPSClean).

### How does it work?

The activity undertaken by GPSClean can be divided in three main steps:

- Data Preprocessing
- Error detection
- Error correction

The following sections briefly explain the three activities, for further details I invite you to consult the jupyter notebooks available at the [Transform and Model](https://gitlab.inf.unibz.it/gps-clean/transform-and-model) repository.

### Data preprocessing

The first operations performed by GPSClean are related to data pre-processing. In particular, the machine learning model adopted by the application considers the differences (deltas) between the registered points, since it does not use any geographical knowledge abou the region in which the trace was registered.

For this reason, the latitude, longitude and altitude original coordinates are converted to ECEF (Earth Centered Earth Fixed) coordinates, enabling so a simpler calculation of the deltas given their cartesian nature.

The second pre-processing step is the calculation of the deltas between two consecutive points, with the result being the input that will be provided to the machine learning model.

### Error detection

The error detection step is based on a previously trained machine learning model. The model, based on a neural network composed by Bidirectional LSTM (Long-Short Term Memory) cells, was trained on a set of annotated GPS traces, namely traces on which the errors were explicitly marked using an ad-hoc developed web-based tool: [Track annotation](https://api.dawnets.unibz.it/).

The considered errors are the following:

- Pauses: when the selected movements were a pause and are the result of GPS reception errors.
- Outliers: when the point, due to a reception error, is in an incorrect position.
- Indoor: a point collected while being indoor in a building.

The result of the application of the model is an annotated trace, used then in the following step.

### Error correction

#### A special type of error: pauses

Firstly, it should be noted how one of the considered error categories, namely pauses, differs fromthe others, when it comes to correction. In fact, points representing pauses should appear, in the ideal case, stacked one upon the other, given that the position of the receiver did not change in the considered time frame. However, often pauses are represented, in the GPS trace, by a cloud of points resulting from a measurement error bythe GPS sensor. For the aforementioned reasons, points identified by the model as belonging to a pause can bedirectly removed, resulting so in a more smoothed trace with no unnecessary points

#### Correcting misplaced points

Pauses, as explained in the previous section, can be directly removed, step that can not be performed on misplaced points, which need then to be corrected.

In order to obtain the most appropriate error correction, various techniques were investigated during the thesis research. The selected approach was denoted Bidirectional Separate Kalman Filters, a variation of the widely adopted Kalman Filter.

A Kalman Filter is a structure which predicts the following observation (in our case position) in time series and joins it together with the observed value to obtain the final observation. The predicted value of the next observation, represented by a state vector, is based on the covariance and relation of the different components, combined with an external influence and uncertainty. The values for the covariance and uncertainty were derived from previous researches in the field.

The proposed variation applies two separate Kalman Filters for each detected error area, one in each direction, and takes the mean of the resulting corrected positions as the final ones, smoothing so the initial corrections exploiting the availability of the entire time series.

The corrected version of the trace is then exported in the GPX format.

## Running the application

In order to run the application, please follow the subsequent steps:

1) Install the package by executing the following command: `pip install -i https://test.pypi.org/simple/ gpsclean`
2) Now you are ready to clean your first GPS trace by executing the following command: `gpsclean path/to/your_trace.gpx`
3) In the same folder where the original trace resides, you will find a cleaned version of the trace with the suffix "_cleaned"

## Downloading a pre-built all-in-one executable

On the other hand, if you prefer to download a all-in-one executable which does not require any prior software installed (not even Python), you can find pre-built all-in-one packages in the [Release section](https://github.com/sbettid/GPSClean/releases) of the repository.


## How to manually create the all-in-one executable

1) Clone the [repository](https://github.com/sbettid/GPSClean) and open a shell in the `src/gpsclean` folder
2) Execute the following command: `pyinstaller -F --add-data "data/model_42t_traces.h5;." gpsclean.py`
3) At the end of the process, a dist folder can be found inside the `src/gpsclean` folder, containing the packaged executable.

Loading

0 comments on commit 37a8fab

Please sign in to comment.