Metadata-Version: 2.4
Name: geo-track-analyzer
Version: 1.7.1
Summary: Analyze geospacial data tracks
Keywords: fit,gpx,visualization,analysis
Author-email: Korbinian Schweiger <korbinian.schweiger@gmail.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
License-File: LICENSE
Requires-Dist: numpy>=1,<2
Requires-Dist: gpxpy~=1.6
Requires-Dist: requests>=2,<3
Requires-Dist: plotly>=5,<6
Requires-Dist: pandas>=2,<3
Requires-Dist: fitparse~=1.2
Requires-Dist: pydantic>=2,<3
Requires-Dist: pydantic-numpy>=5,<6
Requires-Dist: click>=8,<9 ; extra == "cli"
Requires-Dist: rich ; extra == "cli"
Requires-Dist: geo-track-analyzer[cli, postgis] ; extra == "full"
Requires-Dist: psycopg ; extra == "full"
Requires-Dist: SQLAlchemy ; extra == "postgis"
Project-URL: Documentation, https://kschweiger.github.io/track_analyzer/
Project-URL: Home, https://github.com/kschweiger/track_analyzer
Project-URL: Source, https://github.com/kschweiger/track_analyzer
Provides-Extra: cli
Provides-Extra: full
Provides-Extra: postgis

[![Testing](https://github.com/kschweiger/track_analyzer/actions/workflows/test.yml/badge.svg)](https://github.com/kschweiger/track_analyzer/actions/workflows/test.yml)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/geo-track-analyzer)
![PyPI - License](https://img.shields.io/pypi/l/geo-track-analyzer)
![PyPI - Version](https://img.shields.io/pypi/v/geo-track-analyzer)


# Track analyzer

The focus of this package lies on analyzing and visualizing tracks of cycling or similar activities. Depending on the usecase settings like `stopped_speed_threshold` or `max_speed_percentile` may not be appropriate.

Installing the package with **cli** extra, I.e. using `pip install geo-track-analyzer[cli]`, add utility tools. See the [documentation](https://kschweiger.github.io/track_analyzer/cli/) for details.

## From files

Tracks my be initialized from ``.gpx`` and ``.fit`` files using the ``GPXFileTrack`` and ``FITTrack`` object, respectively.


## Programmatically

You can instanciate tracks programmatically inside your code using the `PyTrack` class.

```python
PyTrack(
        points: list[tuple[float, float]] = ...,
        elevations: None | list[float] = ...,
        times: None | list[datetime] = ...,
        heartrate: None | list[int] = None,
        cadence: None | list[int] = None,
        power: None | list[int] = None,
    )
```
## Extracting track data

The data of the track can be extracted into a pandas DataFrame object with the columns:

* **latitude**: Track point latitude value
* **longitude**: Track point longitude value
* **elevation**: Track point elevation value
* **speed**: Speed in m/s calculated relative to previous point. Requires time to be present in track.
* **distance**: Distance in m relative to previous point
* **heartrate**: Heartrate in bpm (if present in input)
* **cadence**: Cadence in rmp(if present in input)
* **power**: Power in W (if present in input)
* **time**: Time in seconds relative to previous point. Time must be present in track.
* **cum_time**: Cummulated time of the track/segment in seconds.  Requires time to be present in track.
* **cum_time_moving**: Cummulated moving time of the track/segment in seconds.  Requires time to be present in track.
* **cum_distance**: Cummulated distance in track/segement in meters.
* **cum_distance_moving**:  Cummulated moving distance in track/segement in meters.
* **cum_distance_stopped**:  Cummulated stopped distance in track/segement in meters.
* **moving**: Bool flag specifing if the `stopped_speed_threshold` was exceeded for the point.

Because some values are relative to previous points, the first point in the segment is not represented in this dataframe.

----------------

Furthermore an summary of the segments and tracks can be generated in the form of a `SegmentOverview` containing:

* Time in seconds (moving and totoal)
* Distance in meters and km (moving and totoal)
* Maximum and average velocity in m/s and km/h
* Maximum and minimum elevation in meters
* Uphill and downhill elevation in meters

## Visualizing the track

Visualizations of a track can be generated via the `plot` method and the ``kind`` parameter. See [documentation](https://kschweiger.github.io/track_analyzer/visualizations/) for further details and examples how to use the visualizations.

## Extras

The following extras are provided by the lib and may be installed additionally:

- **cli**: Adds cli tools for converting fit files to gpx files (`extract-fit-track`) and updating the elevation in a gpx file with via api (`enhance-elevation`)
- **postgis**: Add functions for integrating with a PostGIS instance provided in the `geo_track_analyzer.postgis` module
- **full**: Install package will all extras

