About
=====
Load GPS data from GPX files into Python as a numpy arrays and *pandas* DataFrames. Initial parsing done using the *gpxpy* package. Trajectory plotting on a map available using *mplleaflet* (optional).
Quick Start
===========
Install
-------
```bash
pip install gpxo
```
Load Track
----------
```python
import gpxo
track = gpxo.Track('ExampleTrack.gpx')
```
(it is possible to indicate which track or segment to consider during instantiation, by default it is the first one).
`track.data` is a *pandas* DataFrame containing time, position, elevation etc.; usual *pandas* methods can be used to analyze, manipulate and plot data. Individual columns are also available as numpy arrays as attributes of the class (see below).
Detailed Contents
=================
Track class
-----------
Load, inspect and plot GPX data using the `Track` class, with the following methods and attributes.
### Methods
- `smooth()`: smooth position and elevation data (see `gpxo.smooth()` below),
- `plot()`: plot trajectory data using a combination of shortnames (see shortnames below); also takes `matplotlib.pyplot.plot()` arguments/kwargs,
- `map()`: plot trajectory on a map, using `mplleaflet.show()`,
- `closest_to()`: find index of point in trajectory closest to a (lat, long) point.
### Basic Attributes
(some may not be available depending on actual data present in the GPX file)
- `latitude` (numpy array): latitude in °,
- `longitude` (numpy array): longitude in °,
- `elevation` (numpy array): elevation in meters,
- `time` (numpy array): local time expressed as a datetime.datetime.
### Property attributes
(Read-only, and calculated/updated from basic attributes; some may not be available depending on actual data present in the GPX file)
- `seconds` (numpy array): total number of seconds since beginning of track,
- `distance` (numpy array): total distance (km) since beginning of track,
- `velocity` (numpy array): instantaneous velocity (km/h),
- `compass` (numpy array): instantaneous compass bearing (°),
- `data` (pandas DataFrame): all above attributes in a single dataframe.
## Miscellaneous
Outside of the `Track` class, the following standalone function is also available:
- `compass(pt1, pt2)`: compass bearing (°) between pt1 (lat1, long1) and pt2 (lat2, long2),
- `closest_pt(pt, trajectory)`: index of closest pt in trajectory (latitudes, longitudes) to specified pt (lat, long),
- `smooth(x, n, window)`: smooth 1-d array with a moving window of size n and type *window*.
## Short names
| Short name | Corresponding data
| :--------: | :----------------:
| t | time
| s | duration (s)
| d | distance (km)
| v | velocity (km/h)
| z | elevation (m)
| c | compass (°)
Examples
========
See Jupyter Notebook **Examples.ipynb** (https://github.com/ovinc/gpxo/blob/master/Examples.ipynb) for a detailed example using real GPX data.
**Quick example 1**: Plot distance versus time and velocity versus position for a given track:
```python
import gpxo
track = gpxo.Track('ExampleTrack.gpx')
track.plot('td', '--k') # matplotlib styles can be given
track.plot('dv', c='red') # matplotlib kwargs can be passed
track.data # pandas dataframe with all data
```
**Quick example 2**: show the path of a GPX file on a map with color-coding corresponding to elevation (*see Troubleshooting section below in case of error*):
```python
import gpxo
track = gpxo.Track('ExampleTrack.gpx')
track.map(plot='scatter', c=track.elevation, cmap='plasma')
```
Troubleshooting
===============
In case of the following error:
```
'XAxis' object has no attribute '_gridOnMajor
```
when using the `map()` method, try downgrading Matplotlib to version <= 3.3.2 or install a forked version of mplleaflet (see https://github.com/jwass/mplleaflet/issues/75).
Information
===========
Requirements
------------
Python >= 3.6
Dependencies
------------
(automatically installed by pip if necessary)
- *numpy*
- *pandas*
- *matplotlib*
- *importlib-metadata*
- *gpxpy* (https://github.com/tkrajina/gpxpy)
- *vincenty* (https://github.com/maurycyp/vincenty)
Optional:
- *mplleaflet* (https://github.com/jwass/mplleaflet)
Author
------
Olivier Vincent
(ovinc.py@gmail.com)
License
-------
BSD 3-Clause (see *LICENCE* file)
Raw data
{
"_id": null,
"home_page": null,
"name": "gpxo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "gps, gpx, numpy, pandas, plot, analyze, compass",
"author": null,
"author_email": "Olivier Vincent <ovinc.py@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/69/f1/6342aa280494fd57e7e14d95950f3919e957da0d8941aca307921831c57d/gpxo-0.2.0.tar.gz",
"platform": null,
"description": "About\n=====\n\nLoad GPS data from GPX files into Python as a numpy arrays and *pandas* DataFrames. Initial parsing done using the *gpxpy* package. Trajectory plotting on a map available using *mplleaflet* (optional).\n\nQuick Start\n===========\n\nInstall\n-------\n\n```bash\npip install gpxo\n```\n\nLoad Track\n----------\n\n```python\nimport gpxo\ntrack = gpxo.Track('ExampleTrack.gpx')\n```\n(it is possible to indicate which track or segment to consider during instantiation, by default it is the first one).\n`track.data` is a *pandas* DataFrame containing time, position, elevation etc.; usual *pandas* methods can be used to analyze, manipulate and plot data. Individual columns are also available as numpy arrays as attributes of the class (see below).\n\n\nDetailed Contents\n=================\n\nTrack class\n-----------\n\nLoad, inspect and plot GPX data using the `Track` class, with the following methods and attributes.\n\n### Methods\n\n- `smooth()`: smooth position and elevation data (see `gpxo.smooth()` below),\n- `plot()`: plot trajectory data using a combination of shortnames (see shortnames below); also takes `matplotlib.pyplot.plot()` arguments/kwargs,\n- `map()`: plot trajectory on a map, using `mplleaflet.show()`,\n- `closest_to()`: find index of point in trajectory closest to a (lat, long) point.\n\n### Basic Attributes\n\n(some may not be available depending on actual data present in the GPX file)\n\n- `latitude` (numpy array): latitude in \u00b0,\n- `longitude` (numpy array): longitude in \u00b0,\n- `elevation` (numpy array): elevation in meters,\n- `time` (numpy array): local time expressed as a datetime.datetime.\n\n### Property attributes\n\n(Read-only, and calculated/updated from basic attributes; some may not be available depending on actual data present in the GPX file)\n- `seconds` (numpy array): total number of seconds since beginning of track,\n- `distance` (numpy array): total distance (km) since beginning of track,\n- `velocity` (numpy array): instantaneous velocity (km/h),\n- `compass` (numpy array): instantaneous compass bearing (\u00b0),\n- `data` (pandas DataFrame): all above attributes in a single dataframe.\n\n## Miscellaneous\n\nOutside of the `Track` class, the following standalone function is also available:\n- `compass(pt1, pt2)`: compass bearing (\u00b0) between pt1 (lat1, long1) and pt2 (lat2, long2),\n- `closest_pt(pt, trajectory)`: index of closest pt in trajectory (latitudes, longitudes) to specified pt (lat, long),\n- `smooth(x, n, window)`: smooth 1-d array with a moving window of size n and type *window*.\n\n## Short names\n\n| Short name | Corresponding data\n| :--------: | :----------------:\n| t | time\n| s | duration (s)\n| d | distance (km)\n| v | velocity (km/h)\n| z | elevation (m)\n| c | compass (\u00b0)\n\nExamples\n========\n\nSee Jupyter Notebook **Examples.ipynb** (https://github.com/ovinc/gpxo/blob/master/Examples.ipynb) for a detailed example using real GPX data.\n\n**Quick example 1**: Plot distance versus time and velocity versus position for a given track:\n\n```python\nimport gpxo\ntrack = gpxo.Track('ExampleTrack.gpx')\ntrack.plot('td', '--k') # matplotlib styles can be given\ntrack.plot('dv', c='red') # matplotlib kwargs can be passed\ntrack.data # pandas dataframe with all data\n```\n\n**Quick example 2**: show the path of a GPX file on a map with color-coding corresponding to elevation (*see Troubleshooting section below in case of error*):\n\n```python\nimport gpxo\ntrack = gpxo.Track('ExampleTrack.gpx')\ntrack.map(plot='scatter', c=track.elevation, cmap='plasma')\n```\n\n\n\nTroubleshooting\n===============\n\nIn case of the following error:\n```\n'XAxis' object has no attribute '_gridOnMajor\n```\n\nwhen using the `map()` method, try downgrading Matplotlib to version <= 3.3.2 or install a forked version of mplleaflet (see https://github.com/jwass/mplleaflet/issues/75).\n\nInformation\n===========\n\nRequirements\n------------\n\nPython >= 3.6\n\nDependencies\n------------\n\n(automatically installed by pip if necessary)\n\n- *numpy*\n- *pandas*\n- *matplotlib*\n- *importlib-metadata*\n- *gpxpy* (https://github.com/tkrajina/gpxpy)\n- *vincenty* (https://github.com/maurycyp/vincenty)\n\nOptional:\n- *mplleaflet* (https://github.com/jwass/mplleaflet)\n\nAuthor\n------\n\nOlivier Vincent\n\n(ovinc.py@gmail.com)\n\nLicense\n-------\n\nBSD 3-Clause (see *LICENCE* file)\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Load, analyze and plot GPS data from GPX files with numpy/pandas",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/ovinc/gpxo/README.md",
"Homepage": "https://github.com/ovinc/gpxo",
"Repository": "https://github.com/ovinc/gpxo.git"
},
"split_keywords": [
"gps",
" gpx",
" numpy",
" pandas",
" plot",
" analyze",
" compass"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3a4c980a03904949a933f137b3d1982a2d45e3990cdaf18be7564df5c4fd10fb",
"md5": "5b7ea1664e50f046fe2d6432235c1d13",
"sha256": "299a81849501dcdfe7e4a49450043ade70620926971b6d471ebbca4ccbef3031"
},
"downloads": -1,
"filename": "gpxo-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b7ea1664e50f046fe2d6432235c1d13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10067,
"upload_time": "2025-01-19T17:23:19",
"upload_time_iso_8601": "2025-01-19T17:23:19.909181Z",
"url": "https://files.pythonhosted.org/packages/3a/4c/980a03904949a933f137b3d1982a2d45e3990cdaf18be7564df5c4fd10fb/gpxo-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69f16342aa280494fd57e7e14d95950f3919e957da0d8941aca307921831c57d",
"md5": "61f0eb1dfa70a6cb7e24c5c4e8791012",
"sha256": "9d45f765b238ed07891e34c210ddd34d0df4ca3bafc505a03f0a14f23e3996db"
},
"downloads": -1,
"filename": "gpxo-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "61f0eb1dfa70a6cb7e24c5c4e8791012",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 3455884,
"upload_time": "2025-01-19T17:23:22",
"upload_time_iso_8601": "2025-01-19T17:23:22.607311Z",
"url": "https://files.pythonhosted.org/packages/69/f1/6342aa280494fd57e7e14d95950f3919e957da0d8941aca307921831c57d/gpxo-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-19 17:23:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ovinc",
"github_project": "gpxo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gpxo"
}
JSON
