ezgpx.gpx package

Submodules

ezgpx.gpx.gpx module

Module contents

This file contains the high level GPX object.

class ezgpx.gpx.GPX(source: str | Path | IO[str] | IO[bytes] | bytes | IntoFrameT | None = None, xml_schema: bool = True, xml_extensions_schemas: bool = False)

Bases: object

High level GPX object.

ELEVATION_VALUES = ['ele', 'ascent_rate', 'ascent_speed']

TIME_VALUES = ['time', 'speed', 'pace', 'ascent_speed']

ascent() → float

Return the total ascent of tracks (in meters).

avg_pace(moving: bool = False) → float

Return the average pace (in minutes per kilometer).

Args:

moving (bool, optional): Moving flag. Defaults to False.

Returns:

float: Average moving pace if moving is True, average

pace otherwise.

avg_speed(moving: bool = False) → float

Return the average speed (in kilometers per hour).

Args:

moving (bool, optional): Moving flag. Defaults to False.

Returns:

float: Average moving speed if moving is True, average

speed otherwise.

check_xml_extensions_schemas() → bool

Check XML extension schemas.

Returns:

bool: True if the file follows XML schemas.

check_xml_schema() → bool

Check XML schema.

Returns:

bool: True if the file follows XML schemas.

descent() → float

Return the total descent of tracks (in meters).

distance() → float

Return the total distance of tracks (in meters).

max_ascent_rate() → float

Return the maximum ascent rate.

max_ascent_speed() → float

Return the maximum ascent speed (in meters per hour).

max_descent_rate() → float

Return the minimum ascent rate.

max_elevation() → float

Returns the maximum elevation (in meters).

max_pace() → float

Return the maximum pace (in minutes per kilometer).

max_speed() → float

Return the maximum speed (in kilometers per hour).

static merge(*gpxs: GPX) → GPX

Merge GPX objects into a new instance.

Returns:

GPX: GPX: Merged GPX (new instance).

min_ascent_speed() → float

Return the minimum ascent speed (in meters per hour).

min_elevation() → float

Returns the minimum elevation (in meters).

min_pace() → float

Return the minimum pace (in minutes per kilometer).

min_speed() → float

Return the minimum speed (in kilometers per hour).

moving_time() → datetime

Return the moving time.

remove_elevation()

Remove elevation data.

remove_extensions()

Remove extensions data.

remove_gps_errors(error_distance: float = 100) → list

Remove GPS errors.

Args:

error_distance (float, optional): Error threshold distance

(in meters) between two points. Defaults to 100.

Returns:

list: List of removed points (GPS errors).

remove_metadata()

Remove metadata.

remove_points(reduction_factor: int = 2)

Remove track points naively, i.e.: keep 1 point for every reduction_factor points.

Note: For a more advanced processing, consider using the simplify method.

Args:

reduction_factor (int, optional): Reduction factor. The number of points will be divided by this value. Defaults to 2.

remove_time()

Remove time data.

reverse()

Reverse GPX.

simplify(tolerance: float = 2)

Simplify tracks using Ramer-Douglas-Peucker algorithm.

Args:

tolerance (float, optional): Minimum distance (in meters) between the point and the track if the point were removed. Defaults to 2.

start_time(utc: bool = False) → datetime | None

Return start time.

Args:

utc (bool, optional): Toggle UTC standard. Defaults to False.

Returns:

datetime | None: Start time or None if no time data.

stop_time(utc: bool = False) → datetime | None

Return stop time.

Args:

utc (bool, optional): Toggle UTC standard. Defaults to False.

Returns:

datetime | None: Start time or None if no time data.

stopped_time(tolerance: float = 2.45) → datetime

Return the stopped time.

Args:

tolerance (float, optional): Maximal distance between two

points for movement. Defaults to 2.45.

Returns:

datetime: Stopped time.

time_zone() → str

Return the time zone based on geographic coordinates.

to_csv(dest: str | Path | IO[str] | IO[bytes] | bytes | None = None, values: list[str] = None, **kwargs) → str | None

Write the GPX object track coordinates to a CSV file.

Args:

dest (str | Path | IO[str] | IO[bytes] | bytes, optional):

Path to a file or a file-like object to write in. Defaults to None.

values (list[str], optional): list of values to write.

Supported values: “lat”, “lon”, “ele”, “time”, “speed”, “pace”, “ascent_rate”, “ascent_speed”, “distance_from_start”. Defaults to None.

Returns:

str | None: CSV like string if path is set to None.

to_dict(values: list[str] = None, as_series: bool = False) → dict

Convert GPX object to dictionary (similar to Polars to_dict).

Args:

values (list[str], optional): List of values to write.

Supported values: “lat”, “lon”, “ele”, “time”, “speed”, “pace”, “ascent_rate”, “ascent_speed”, “distance_from_start”. Defaults to None.

as_series (bool, optional): True -> Values are Series,

False -> Values are list[Any]. Defaults to False.

Returns:

dict: Dictionary representing the GPX.

to_dicts(values: list[str] = None) → list[dict[str, Any]]

Convert GPX object to list of dictionaries (similar to Polars to_dicts).

Args:

values (list[str], optional): List of values to write.

Supported values: “lat”, “lon”, “ele”, “time”, “speed”, “pace”, “ascent_rate”, “ascent_speed”, “distance_from_start”. Defaults to None.

Returns:

list[dict[str, Any]]: List of dictionaries representing the GPX.

to_gpx(dest: str | Path | IO[str] | IO[bytes] | bytes | None = None, *, bounds_fields: list[str] | None = None, copyright_fields: list[str] | None = None, email_fields: list[str] | None = None, extensions_fields: dict | None = None, gpx_fields: list[str] | None = None, link_fields: list[str] | None = None, metadata_fields: list[str] | None = None, person_fields: list[str] | None = None, ptseg_fields: list[str] | None = None, pt_fields: list[str] | None = None, rte_fields: list[str] | None = None, trkseg_fields: list[str] | None = None, trk_fields: list[str] | None = None, wpt_fields: list[str] | None = None, trkpt_fields: list[str] | None = None, mandatory_fields: bool = True) → str | None

Write the GPX object to a GPX file.

Args:

dest (str | Path | IO[str] | IO[bytes] | bytes, optional):

Path to a file or a file-like object to write in. Defaults to None.

bounds_fields (Optional[list[str]], optional): _description_. Defaults to None. copyright_fields (Optional[list[str]], optional): _description_. Defaults to None. email_fields (Optional[list[str]], optional): _description_. Defaults to None. extensions_fields (Optional[dict], optional): _description_. Defaults to None. gpx_fields (Optional[list[str]], optional): _description_. Defaults to None. link_fields (Optional[list[str]], optional): _description_. Defaults to None. metadata_fields (Optional[list[str]], optional): _description_. Defaults to None. person_fields (Optional[list[str]], optional): _description_. Defaults to None. ptseg_fields (Optional[list[str]], optional): _description_. Defaults to None. pt_fields (Optional[list[str]], optional): _description_. Defaults to None. rte_fields (Optional[list[str]], optional): _description_. Defaults to None. trkseg_fields (Optional[list[str]], optional): _description_. Defaults to None. trk_fields (Optional[list[str]], optional): _description_. Defaults to None. wpt_fields (Optional[list[str]], optional): _description_. Defaults to None. trkpt_fields (Optional[list[str]], optional): _description_. Defaults to None. mandatory_fields (bool, optional): _description_. Defaults to True.

Returns:

str | None: GPX like string if path is set to None.

to_kml(dest: str | Path | IO[str] | IO[bytes] | bytes | None = None, *, styles: list[tuple[str, dict]] | None = None) → str | None

pt Write the GPX object to a KML file.

Args:

dest (str | Path | IO[str] | IO[bytes] | bytes, optional):

Path to a file or a file-like object to write in. Defaults to None.

styles (Optional[list[tuple[str, dict]]], optional): KML

styles. Defaults to None.

Returns:

str | None: KML like string if path is set to None.

to_pandas(values: list[str] = None) → pandas.DataFrame

Convert GPX object to Pandas Dataframe. Missing values are filled with default values (0 for numerical values and empty string for text).

Args:

values (list[str], optional): List of values to write.

Supported values: “lat”, “lon”, “ele”, “time”, “speed”, “pace”, “ascent_rate”, “ascent_speed”, “distance_from_start”. Defaults to None.

Returns:

pd.DataFrame: Dataframe containing data from GPX.

to_polars(values: list[str] = None) → DataFrame

Convert GPX object to Polars Dataframe. Missing values are filled with default values (0 for numerical values and empty string for text).

Args:

values (list[str], optional): List of values to write.

Supported values: “lat”, “lon”, “ele”, “time”, “speed”, “pace”, “ascent_rate”, “ascent_speed”, “distance_from_start”. Defaults to None.

Returns:

pl.DataFrame: Dataframe containing data from GPX.

total_elapsed_time() → datetime

Return the total elapsed time.

trkpt_bounds() → tuple[Latitude, Longitude, Latitude, Longitude]

Return minimum and maximum latitude and longitude.

Returns:

Tuple[Latitude, Longitude, Latitude, Longitude]: Min

latitude, min longitude, max latitude, max longitude.

trkpt_center() → tuple[Latitude, Longitude]

Return latitude and longitude of the center point.

trkpt_count() → int

Return the number of track points.

trkpt_extreme() → tuple[Wpt, Wpt, Wpt, Wpt]

Return extreme points in track, i.e.: points with lowest and highest latitude and longitude.

Returns:

tuple[Wpt, Wpt, Wpt, Wpt]: Min latitude

point, min longitude point, max latitude point, max longitude points.