gpx-player 0.1.0__py3-none-any.whl

gpx_player-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: gpx-player
+Version: 0.1.0
+Summary: Visualise & animate GPX race tracks.
+Author: Yury Kirienko
+License: MIT License
+        
+        Copyright (c) 2023 Yury Kirienko
+        
+        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.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: folium
+Requires-Dist: jinja2
+Requires-Dist: matplotlib
+Requires-Dist: pytz
+Requires-Dist: lxml
+Requires-Dist: numpy
+Requires-Dist: gpxpy
+Dynamic: license-file
+
+# gpx-player
+## GPX Race Visualizer
+
+GPX Race Visualizer is a Python script to visualize the progression of multiple GPS tracks (e.g., from a race) on a 2D map. 
+It takes as input one or more GPX files and creates an animation showing the movement of each track over time. 
+This is a simple, open-source alternative to features like Strava's Flyby, which require an account and can have privacy issues.
+
+### Modes
+The player supports two modes:
+#### 1. "Video" mode
+Produce an `MP4` or a `GIF` file showing how the situation developed.
+For sailing races, it also calculates the distance covered after the 'start' signal and the current speed.
+##### Example:
+![Example output](example.gif "Example of the script output")
+
+#### 2. Map mode
+Displays the track on OpenSeaMap.
+You can see the full tracks with colour-coded speeds, 
+and you can 'play' the tracks and see the markers move around the map.
+
+#### Example:
+Since GitHub Markdown doesn't allow embedding HTML, 
+you can see an [interactive example](https://kirienko.github.io/static/GinSul-2024.html) here.
+
+Screenshot:
+[![OPS Example](./example_osm.png)](https://kirienko.github.io/static/GinSul-2024.html)
+## Installation
+
+Clone the repository and install the required dependencies with pip:
+
+```bash
+git clone https://github.com/kirienko/gpx-player.git
+cd gpx-player
+pip install -r requirements.txt
+```
+
+## Usage
+To run the script producing `mp4`, pass one or more GPX file paths as command-line arguments:
+```bash
+python main.py example-data/track1.gpx example-data/track2.gpx
+```
+To get a sea map, run the `openseamap.py`:
+```bash
+python openseamap.py --title 'Gin Sul Regatta 2024' --names Alex Yury Richard \
+     --files example-data/osm-demo-Alex.gpx example-data/osm-demo-Richard.gpx \
+             example-data/osm-demo-Yury.gpx
+```
+
+A more sophisticated example, that produced a video above:
+```bash
+python main.py example-data/track1.gpx example-data/track2.gpx example-data/track3.gpx \
+       --start 2023-07-01T10:53:00+0000 \
+       --names "Mr. Pommeroy" "Miss Sophie" "Sir Toby²" \
+       --title "Elbe-Damm Regatta (01.07.2023), Race 1" \
+       --race_start 2023-07-01T10:58:00+0000 --marks example-data/marks.txt -g
+```
+### Additional parameters:
+* `--title` or `-t`: The title of the video
+* `--start` or `-s`: start time in the format `2023-06-30T12:53:00+0200`, all points _before_ that will not be plotted
+* `--end` or `-e`: end time in the format `2023-06-30T13:53:00+0200`, all points _after_ that will not be plotted
+* `--names` or `-n`: names of the participants (otherwise the file names will be used in the legend)
+* `--race_start`, `-r`: Race start time in the format `YYYY-MM-DDTHH:MM:SS%z`, e.g. `2023-07-01T12:29:00+0200`
+* `--names` or `-n`: Names of the participants
+* `--marks`or`-m`: The file with the static marks to put onto the map. One pair of coordinates per line, see below.
+* `--gif` or `-g`: Save as GIF moving picture instead of MP4
+* `--timezone` or `-tz`: Local timezone to use for processing timestamps, e.g. `America/Los_Angeles`, see [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (default: `Europe/Berlin`).
+
+## Marks
+The script also supports visualizing predefined marks on the map, which can be useful for events like sailing regattas.
+The marks are defined as a list of (latitude, longitude) tuples in a separate text file and can be added to the script as follows:
+```
+53.542484632728, 9.801163896918299
+53.542997846049374, 9.80611324310303
+53.54823800356785, 9.812614917755129
+53.54921647691311, 9.807373881340029
+53.54508251196638, 9.80433225631714
+```
+
+## Getting GPX Files
+
+GPX files can be obtained from several GPS-tracking services:
+* Strava: Go to the activity page and click on the wrench icon. Then select "Export GPX".
+* Garmin Connect: Open the activity, go to the gear icon and select "Export to GPX".
+* Endomondo: From the workout page, click the three-dot menu icon and select "Export". Then choose "GPX".
+
+## GPX Validation
+
+For the `gpx-player` to work properly, it needs the correct GPX files.
+You can verify that you are inputting the correct file by using the special validator 
+included in this package.
+
+The `validator.py` script is a command-line utility and module for validating GPX files. 
+It checks for XML schema conformance and timestamp consistency, 
+supporting both strict and lenient modes. 
+Errors are raised as `GPXValidationError` which can be caught in Python code. 
+To run as a CLI tool, use:
+```bash
+python validator.py path/to/yourfile.gpx --strict
+```
+
+The `--strict` parameter is optional. In most cases you do not need it, 
+because files that strictly correspond to the GPX schema are rare. 
+For example, almost all modern files contain coordinates, elevations and time stamps 
+with more decimal places than originally planned.
+
+Also, to better understand your GPX file, you can use the `gpxinfo` console command 
+that comes with `gpxpy`. If you are already using the player, you have it:
+
+```bash
+$ gpxinfo example-data/osm_track1.gpx 
+File: example-data/osm_track1.gpx
+    Waypoints: 0
+    Routes: 0
+    Length 2D: 9.621km
+    Length 3D: 9.648km
+    Moving time: 01:05:22
+    Stopped time: n/a
+    Max speed: 3.12m/s = 11.22km/h
+    Avg speed: 2.46m/s = 8.85km/h
+    Total uphill: 97.20m
+    Total downhill: 98.40m
+    Started: 2024-07-24 15:59:05+00:00
+    Ended: 2024-07-24 17:04:27+00:00
+    Points: 776
+    Avg distance between points: 12.40m
+
+```
+
+## Support
+Now you can buy me a coffee to encourage further development!
+
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/kirienko)

gpx_player-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gpx_utils.py,sha256=8Q5GeZuNl4W0RDkrobIMMrUip51pBLOhuDAD3bivnuc,1341
+main.py,sha256=5hkqeTbwYuWqiEyUeMO-j4cbGjYPe2LDzCYUja1rMms,8645
+openseamap.py,sha256=X4ecjuZ8juHYaumhH9xBbH-0Hphpurw7FpHOp_Zs2Lc,7706
+utils.py,sha256=mpSI0usPsjlLjRqj7S8UrQv-eNjQ4tGlWzxAu946iU8,3039
+validator.py,sha256=0sIDDoD4bxRD3TbzNg96rV8JJcbKzXWthG7Xd4tEgpc,7878
+gpx_player-0.1.0.dist-info/licenses/LICENSE,sha256=Z2JusFyF7CSjDcNSGCsLA5zEK4Q2FcsS_0Owy7wEZME,1070
+gpx_player-0.1.0.dist-info/METADATA,sha256=XRj0aEBTEp32xpAyaRD5lAGTvt16vKHq5_vnVRa1_Xc,7269
+gpx_player-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gpx_player-0.1.0.dist-info/entry_points.txt,sha256=JO1WVud0YaaRmPNvpNMU3M7K8geuvC-LSskt3Df1AU4,71
+gpx_player-0.1.0.dist-info/top_level.txt,sha256=Z74aRgq8oA3AMS6MWoJ7kjLvXPc0T4B_oZ_Vlsov0hw,42
+gpx_player-0.1.0.dist-info/RECORD,,

gpx_player-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gpx_player-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+gpx-player = main:main
+gpx-validate = validator:main

gpx_player-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Yury Kirienko
+
+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.

gpx_player-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,5 @@
+gpx_utils
+main
+openseamap
+utils
+validator

gpx_utils.py

@@ -0,0 +1,38 @@
+import gpxpy
+import gpxpy.gpx
+from datetime import datetime
+
+def cut_gpx_file(file_path, timestamp, cut_type):
+    """
+    Cuts a GPX file at the point closest to the given timestamp.
+
+    :param file_path: Path to the original GPX file.
+    :param timestamp: Timestamp as a datetime instance or string in the format 'YYYY-MM-DDTHH:MM:SS%z'.
+    :param cut_type: 'start' to keep everything after the timestamp, 'end' to keep everything before.
+    :return: Path to the new GPX file.
+    """
+    if isinstance(timestamp, str):
+        timestamp = datetime.strptime(timestamp, '%Y-%m-%dT%H:%M:%S%z')
+
+    with open(file_path, 'r') as gpx_file:
+        gpx = gpxpy.parse(gpx_file)
+
+    new_gpx = gpxpy.gpx.GPX()
+
+    for track in gpx.tracks:
+        new_track = gpxpy.gpx.GPXTrack()
+        new_gpx.tracks.append(new_track)
+
+        for segment in track.segments:
+            new_segment = gpxpy.gpx.GPXTrackSegment()
+            new_track.segments.append(new_segment)
+
+            for point in segment.points:
+                if (cut_type == 'start' and point.time >= timestamp) or (cut_type == 'end' and point.time <= timestamp):
+                    new_segment.points.append(point)
+
+    new_file_path = file_path.replace('.gpx', '_cut.gpx')
+    with open(new_file_path, 'w') as f:
+        f.write(new_gpx.to_xml())
+
+    return new_file_path

main.py

@@ -0,0 +1,192 @@
+import argparse
+import datetime as dt
+import os.path as op
+from math import atan2, degrees
+
+import gpxpy
+import matplotlib.animation as animation
+import matplotlib.pyplot as plt
+import pytz
+from matplotlib.ticker import FuncFormatter, MultipleLocator
+
+from utils import (format_func, gen_arrow_head_marker,
+                   km_to_nm, slug, timedelta_to_hms)
+
+base_path = '.'
+
+# Define argument parser
+parser = argparse.ArgumentParser()
+parser.add_argument('files', nargs='+', help='GPX files to process')
+parser.add_argument('--title', '-t', help='The title of the video')
+parser.add_argument('--start', '-s', type=lambda s: dt.datetime.strptime(s, '%Y-%m-%dT%H:%M:%S%z'), help='Start time (YYYY-MM-DDTHH:MM:SS%z)')
+parser.add_argument('--end', '-e', type=lambda s: dt.datetime.strptime(s, '%Y-%m-%dT%H:%M:%S%z'), help='End time (YYYY-MM-DDTHH:MM:SS%z)')
+parser.add_argument('--race_start', '-r', type=lambda s: dt.datetime.strptime(s, '%Y-%m-%dT%H:%M:%S%z'),
+                    help='Race start time (YYYY-MM-DDTHH:MM:SS%z)')
+parser.add_argument('--names', '-n', nargs='+', help='Names of the participants')
+parser.add_argument('--marks', '-m', help='The file with the static marks to put onto the map. One pair of coordinates per line')
+parser.add_argument('--gif', '-g', action='store_true', help='Save as GIF moving picture instead of MP4')
+parser.add_argument('--timezone', '-tz', default='Europe/Berlin', help='Timezone to use for processing timestamps')
+args = parser.parse_args()
+local_tz = pytz.timezone(args.timezone)
+
+start_time = args.start.astimezone(local_tz) if args.start else None
+end_time = args.end.astimezone(local_tz) if args.end else None
+race_start = args.race_start.astimezone(local_tz) if args.race_start else None
+
+tracks = []
+points_list = []
+
+# Parse the GPX files
+for filename in args.files:
+    with open(op.join(base_path, filename), 'r') as gpx_file:
+        gpx = gpxpy.parse(gpx_file)
+    # all timestamps show the local time from this point on:
+    points = [(point.latitude, point.longitude, point.time.astimezone(local_tz)) for track in gpx.tracks for segment in track.segments for
+              point in segment.points]
+    if start_time:
+        points = [(lat, lon, time) for (lat, lon, time) in points if time >= start_time]
+    if end_time:
+        points = [(lat, lon, time) for (lat, lon, time) in points if time <= end_time]
+    points_list.append(points)
+
+title = args.title if args.title else ''
+
+# Initialize the figure and axis
+fig, ax = plt.subplots()
+ax.set_title(title)
+# Apply the custom formatter to the x and y axes
+ax.xaxis.set_major_formatter(FuncFormatter(format_func))
+ax.yaxis.set_major_formatter(FuncFormatter(format_func))
+ax.xaxis.set_major_locator(MultipleLocator(1/120))  # locator at every 1/60/2 degrees = 30"
+ax.yaxis.set_major_locator(MultipleLocator(1/360))  # locator at every 1/60/0 degrees = 10"
+ax.tick_params(axis='both', labelsize=5)
+
+margin = 0.001  # increase to zoom out
+lat_min = min(point[0] for point in [point for points in points_list for point in points]) - margin
+lat_max = max(point[0] for point in [point for points in points_list for point in points]) + margin
+lon_min = min(point[1] for point in [point for points in points_list for point in points]) - margin
+lon_max = max(point[1] for point in [point for points in points_list for point in points]) + margin
+
+ax.set_xlim(lon_min, lon_max)
+ax.set_ylim(lat_min, lat_max)
+
+# Initialize the plot with the first data
+lines = [ax.plot(points[0][1], points[0][0], '-', linewidth='0.8', label=filename)[0]
+         for points, filename in zip(points_list, args.files)]
+
+marker, scale = gen_arrow_head_marker(0)
+markersize = 10
+heads = [ax.plot(l[0][0], l[0][1], marker=marker, markersize=markersize, color=lines[i].get_color())[0]
+            for i, l in enumerate(points_list)]
+
+if args.names:
+    for i, name in enumerate(args.names):
+        lines[i].set_label(name)
+        ax.text(0.7, 0.95 - 0.03*i,
+                name[:13]+'...' if len(name) > 13 else f'{name:>13}', transform=ax.transAxes,
+                fontsize=6)
+
+
+# Add time labels
+time_text = ax.text(0.30, 0.95, '', transform=ax.transAxes)
+
+# Static points
+if args.marks:
+    with open(args.marks) as fd:
+        marks = [line.strip().split(',') for line in fd.readlines()]
+    for i, (lat, lon) in enumerate(marks, 1):
+        ax.plot(float(lon), float(lat), marker='o', markersize=5, color='orange')
+
+# Initialize counters in number of input files
+counters = [0] * len(points_list)
+dist_counter = [0.0] * len(points_list)
+speeds = [0.0] * len(points_list)
+
+ax_dist = [ax.text(0.83, 0.95 - 0.03*i, '', fontsize=7, transform=ax.transAxes) for i in range(len(points_list))]
+ax_speed = [ax.text(0.93, 0.95 - 0.03*i, '', fontsize=7, transform=ax.transAxes) for i in range(len(points_list))]
+
+# Update function for animation
+def update(current_time, points_list, lines, heads, time_text):
+    # Only advance in points_list if their time is less than or equal to the current time
+    # iterate over points in each file
+    for idx, (points, counter, line) in enumerate(zip(points_list, counters, lines)):
+        pre_start_counter = 0
+        while counter < len(points) and points[counter][2] <= current_time:
+            if race_start or start_time:
+                if counter > 0 and points[counter][2] >= (race_start or start_time):
+                    # Calculate the distance between two consecutive points and add it to dist_counter
+                    lat1, lon1, t1 = points[counter-1]
+                    lat2, lon2, t2 = points[counter]
+                    # gpxpy.geo.haversine_distance returns meters
+                    dst = gpxpy.geo.haversine_distance(lat1, lon1, lat2, lon2) / 1000  # in km
+                    dist_counter[idx] += dst
+                    speeds[idx] = km_to_nm(dst)/(t2-t1).total_seconds()*3600
+                elif counter > 0 and points[counter][2] < (race_start or start_time):
+                    pre_start_counter += 1
+            counter += 1
+        # Update lines
+        if race_start:
+            try:
+                # `start_counter` = 0 before start
+                #                 = counter - 60 after start
+                start_counter = 0 if points[counter][2] < race_start \
+                                else max(pre_start_counter, counter-60)
+            except IndexError:
+                start_counter = counter-60
+        else:
+            start_counter = 0
+
+        line.set_data([point[1] for point in points[start_counter:counter]], [point[0] for point in points[start_counter:counter]])
+        # plot the marker
+        heads[idx].set_data([points[counter-1][1]], [points[counter-1][0]])
+        # Calculate the marker rotation angle
+        try:
+            y1, x1 = points[counter-2][1], points[counter-2][0]
+            y2, x2 = points[counter-1][1], points[counter-1][0]
+            theta = degrees(atan2(y2 - y1, x2 - x1))
+            marker, scale = gen_arrow_head_marker(90-theta)
+            heads[idx].set_marker(marker)
+        except IndexError:
+            heads[idx].set_marker('o')
+        # Update distance/speed table
+        ax_dist[idx].set_text(f'{km_to_nm(dist_counter[idx]):.2f} nm')  # Update the displayed distance
+        ax_speed[idx].set_text(f'{speeds[idx]:.1f} kt')  # Update the displayed speed
+        dist_counter[idx] = 0.
+
+        # Update time text
+        if race_start:
+            diff_time = current_time - race_start
+            minutes = diff_time.total_seconds() / 60
+            if minutes < 0:
+                time_text.set_text(f"Time to start: {timedelta_to_hms(-diff_time)}")
+                time_text.set_color('red')
+            else:
+                time_text.set_text(f"Time of the race: {timedelta_to_hms(diff_time)}")
+                time_text.set_color('black')
+
+        else:
+            time_text.set_text(f'Time: {points[counter-1][2]:%Y-%m-%d %H:%M:%S}' if counter > 0 else '')
+    return [*lines, *heads, time_text, *ax_dist, *ax_speed]
+
+
+# Get common timeline
+# Flatten the list of points from all tracks
+flat_points = [point for points in points_list
+                      for point in points]
+# Extract timestamps
+timestamps = [point[2] for point in flat_points]
+# Create a sorted set of unique timestamps
+timeline = sorted(set(timestamps))
+
+ax.legend(loc='lower right', fontsize=8)
+
+ani = animation.FuncAnimation(fig, update, frames=timeline, fargs=[points_list, lines, heads, time_text],
+                              interval=25, blit=True)
+
+# # Save the animation as a movie
+if args.gif:
+    ani.save(f"{slug(title or 'untitled')}.gif")
+else:
+    ani.save(f"{slug(title or 'untitled')}.mp4", fps=10)
+
+plt.show()

openseamap.py

@@ -0,0 +1,185 @@
+import argparse
+import json
+from typing import List, Tuple
+
+import folium
+import gpxpy
+import gpxpy.gpx
+import jinja2
+import matplotlib.pyplot as plt
+from jinja2 import Environment, FileSystemLoader
+
+from utils import track_serializer
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Animate GPX tracks on an OpenSeaMap.")
+    parser.add_argument('--files', nargs='+', required=True, help='GPX files to process')
+    parser.add_argument('--names', '-n', nargs='+', help='Names of the participants')
+    parser.add_argument('--max-speed', '-ms', type=float, default=12, help='Maximum speed in knots (default: 12)')
+    parser.add_argument('--title', '-t', help='The title of the page')
+    return parser.parse_args()
+
+
+def parse_gpx(file_path: str) -> List[dict]:
+    with open(file_path, 'r') as gpx_file:
+        gpx = gpxpy.parse(gpx_file)
+        all_tracks = []
+        for track in gpx.tracks:
+            points = [
+                {'lat': point.latitude, 'lon': point.longitude, 'time': point.time}
+                for segment in track.segments
+                for point in segment.points
+            ]
+            all_tracks.append({
+                'name': track.name,
+                'description': track.description,
+                'points': points,
+                })
+    return all_tracks
+
+
+def calculate_speeds(points: List[dict], max_speed: float) -> List[float]:
+    """
+    Calculates the speed of each point in the list of points.
+
+    The `max_speed` is used to control the dirty data: if the speed is larger
+    than some reasonable value (max_speed), then usually this means zero division,
+    that's we simply nullify the speed.
+    """
+    speeds = []
+    for i in range(1, len(points)):
+        lat1, lon1, time1 = points[i - 1].values()
+        lat2, lon2, time2 = points[i].values()
+        distance = gpxpy.geo.haversine_distance(lat1, lon1, lat2, lon2)
+        time_diff = (time2 - time1).total_seconds()
+        if time_diff > 0:
+            speed = (distance / time_diff) * 1.94384  # Convert m/s to knots
+            if speed > max_speed:
+                print(f"Warning: speed {speed:.2f} exceeds {max_speed} kn at time {time1} (dt = {time_diff:.2f}s)")
+                speed = 0
+            speeds.append(speed)
+        else:
+            speeds.append(0)
+    return speeds
+
+
+def speed_to_color(speed: float, max_speed: float) -> str:
+    norm_speed = min(speed / max_speed, 1.0)
+    # norm_speed = min(speed / max(1,max_speed), 1.0)
+    color = plt.cm.RdYlGn(norm_speed)
+    return f"#{int(color[0] * 255):x}{int(color[1] * 255):x}{int(color[2] * 255):x}"
+
+
+def create_map(gpx_files: List[str], names: List[str], max_speed: float) -> Tuple[folium.Map, List[List], float, str]:
+    folium_map = folium.Map(location=[0, 0], zoom_start=12, control_scale=True, attributionControl=False, tiles=None)
+    map_id = folium_map.get_name()
+
+    folium.TileLayer('openstreetmap', control=False).add_to(folium_map)
+    # Add OpenSeaMap layer directly to the map, not to the layer control
+    folium.TileLayer(
+        tiles='https://tiles.openseamap.org/seamark/{z}/{x}/{y}.png',
+        attr='OpenSeaMap',
+        overlay=False,
+        control=False,  # Set control to `False` to exclude from layer control
+    ).add_to(folium_map)
+
+    all_tracks = []
+    original_names = []
+    for gpx_file in gpx_files:
+        for track in parse_gpx(gpx_file):
+            points = track['points']
+            speeds = calculate_speeds(points, max_speed)
+            all_tracks.append(list(zip(points, speeds)))
+            original_names.append(track['name'])
+
+    max_speed = max(s for track in all_tracks for _, s in track)
+
+    # Calculate map bounds
+    latitudes = [p['lat'] for track in all_tracks for p, _ in track]
+    longitudes = [p['lon'] for track in all_tracks for p, _ in track]
+    folium_map.fit_bounds([[min(latitudes), min(longitudes)], [max(latitudes), max(longitudes)]])
+
+    track_layers = []
+    colors = ['red', 'green', 'blue', 'orange', 'purple', 'brown', 'pink', 'yellow', 'cyan', 'magenta']
+    
+    for i, track in enumerate(all_tracks):
+        color = colors[i % len(colors)]
+        lat_lon = [(p['lat'], p['lon']) for p, _ in track]
+        speeds = [s for _, s in track]
+        times = [p['time'].strftime('%Y-%m-%d %H:%M:%S') for p, _ in track]
+        name = names[i] if names and i < len(names) else original_names[i]
+
+        track_layer = folium.FeatureGroup(name=f"<span style='color:{color};'>&#9679;</span> {name}", show=True)
+        for j in range(len(lat_lon) - 1):
+            color = speed_to_color(speeds[j], max_speed)
+            tooltip_content = f"Name: {name}<br>Time: {times[j]} UTC<br>Speed: {speeds[j]:.2f} knots"
+            folium.PolyLine(
+                lat_lon[j:j + 2],
+                color=color,
+                weight=2.5,
+                opacity=1,
+                tooltip=folium.Tooltip(tooltip_content)
+            ).add_to(track_layer)
+        track_layers.append(track_layer)
+        folium_map.add_child(track_layer)
+    
+    folium.LayerControl(collapsed=False).add_to(folium_map)
+
+    return folium_map, all_tracks, max_speed, map_id
+
+
+def add_animation(folium_map: folium.Map,
+                  all_tracks: List[List],
+                  jinja_env: jinja2.Environment,
+                  title: str, map_id:str) -> None:
+    gpx_points_data = [[point[0] for point in track] for track in all_tracks]
+    gpx_timestamps = sorted(set(point[0]['time'] for track in all_tracks for point in track))
+    min_time, max_time = min(gpx_timestamps), max(gpx_timestamps)
+    time_range = (max_time - min_time).total_seconds()
+
+    animation_script = f"""
+    <script>
+    var gpx_points_data = {json.dumps(gpx_points_data, default=track_serializer)};
+    var gpx_timestamps = {json.dumps([t for t in gpx_timestamps], default=track_serializer)};
+    var min_time = new Date('{min_time.strftime('%Y-%m-%dT%H:%M:%S%z')}').getTime();
+    var max_time = new Date('{max_time.strftime('%Y-%m-%dT%H:%M:%S%z')}').getTime();
+    var time_range = {time_range};
+    var map_id = "{map_id}";
+    document.title = "{title if title else 'GPX Player'}";
+    </script>
+    <script>                                                                                                                                                                                                                       
+    {open('animate_tracks.js', encoding='UTF-8').read()}                                                                                                                                                                                             
+    </script>
+    """
+    folium_map.get_root().html.add_child(folium.Element(animation_script))
+
+    if title:
+        template = jinja_env.get_template('header_template.html')
+        header_html = template.render(title=title)
+        folium_map.get_root().html.add_child(folium.Element(header_html))
+
+
+def add_legend(folium_map: folium.Map, max_speed: float, jinja_env: jinja2.Environment) -> None:
+    template = jinja_env.get_template('speed_legend_template.html')
+    legend_html = template.render(max_speed=max_speed)
+    folium_map.get_root().html.add_child(folium.Element(legend_html))
+
+
+def main():
+    args = parse_arguments()
+    gpx_files = args.files
+    names = args.names
+
+    env = Environment(loader=FileSystemLoader('.'))
+
+    folium_map, all_tracks, max_speed, map_id = create_map(gpx_files, names, args.max_speed)
+    add_animation(folium_map, all_tracks, env, args.title, map_id)
+
+    add_legend(folium_map, max_speed, env)
+
+    folium_map.save('boat_tracks.html')
+    print('Map has been saved to boat_tracks.html')
+
+if __name__ == "__main__":
+    main()

utils.py

@@ -0,0 +1,94 @@
+import datetime as dt
+import re
+
+import matplotlib as mpl
+import numpy as np
+
+
+def slug(input_string: str) -> str:
+    # Remove leading and trailing spaces
+    input_string = input_string.strip()
+    # Remove non-word characters (everything except numbers, underscores and letters)
+    s = re.sub(r"[^\w\s]", '', input_string)
+    # Replace all runs of whitespace with a single dash
+    s = re.sub(r"\s+", '-', s)
+    return s.lower()
+
+
+def timedelta_to_hms(td: dt.timedelta) -> str:
+    """ converts timedelta to [hours:]minutes:seconds"""
+    total_seconds = int(td.total_seconds())
+    # Break down the seconds into hours, minutes, and seconds
+    hours, remainder = divmod(total_seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+
+    # Format it, including hours only if they are greater than 0
+    if hours:
+        return f"{hours}:{minutes:02}:{seconds:02}"
+    else:
+        return f"{minutes:02}:{seconds:02}"
+
+def track_serializer(obj):
+    if isinstance(obj, dt.datetime):
+        return obj.isoformat()  # Convert datetime to an ISO 8601 string
+    elif isinstance(obj, dt.SimpleTZ):
+        return str(obj)  # Convert timezone info to a string
+    else:
+        raise TypeError(f"Type {type(obj)} not serializable")
+
+def decimal_to_dms(value: float) -> str:
+    degrees = int(value)
+    submin = abs(value - degrees) * 60
+    minutes = int(submin)
+    seconds = int((submin - minutes) * 60)
+    return f"{degrees}°{minutes}'{seconds}\""
+
+def format_func(value, tick_number):
+    # a custom ticker formatter function
+    return decimal_to_dms(value)
+
+
+def km_to_nm(dist: float) -> float:
+    return dist/1.852
+
+def gen_arrow_head_marker(rot: float) -> (mpl.path.Path, float):
+    """generate a marker to plot with matplotlib scatter, plot, ...
+
+    https://matplotlib.org/stable/api/markers_api.html#module-matplotlib.markers
+    
+    Source: https://stackoverflow.com/a/66973317/4222580
+    
+    rot=0: positive x direction
+    Parameters
+    ----------
+    rot : float
+        rotation in degree
+        0 is positive x direction
+
+    Returns
+    -------
+    arrow_head_marker : Path
+        use this path for marker argument of plt.scatter
+    scale : float
+        multiply a argument of plt.scatter with this factor got get markers
+        with the same size independent of their rotation.
+        Paths are autoscaled to a box of size -1 <= x, y <= 1 by plt.scatter
+    """
+    arr = np.array([[.1, .3], [.1, -.3], [1, 0], [.1, .3]])  # arrow shape
+    angle = rot / 180 * np.pi
+    rot_mat = np.array([
+        [np.cos(angle), np.sin(angle)],
+        [-np.sin(angle), np.cos(angle)]
+    ])
+    arr = np.matmul(arr, rot_mat)  # rotates the arrow
+
+    # scale
+    x0 = np.amin(arr[:, 0])
+    x1 = np.amax(arr[:, 0])
+    y0 = np.amin(arr[:, 1])
+    y1 = np.amax(arr[:, 1])
+    scale = np.amax(np.abs([x0, x1, y0, y1]))
+    codes = [mpl.path.Path.MOVETO, mpl.path.Path.LINETO,mpl.path.Path.LINETO, mpl.path.Path.CLOSEPOLY]
+    arrow_head_marker = mpl.path.Path(arr, codes)
+    
+    return arrow_head_marker, scale

validator.py

@@ -0,0 +1,200 @@
+import argparse
+import sys
+from datetime import datetime as dt
+
+from lxml import etree
+
+class GPXValidationError(Exception):
+    """Exception raised for GPX validation errors."""
+    pass
+
+
+def parse_gpx(file_path):
+    try:
+        tree = etree.parse(file_path)
+    except etree.XMLSyntaxError as e:
+        raise GPXValidationError(f"XML Syntax Error: {e}")
+    return tree
+
+
+def parse_timestamp(timestamp_str):
+    """
+    A helper function that tolerates both `2024-06-15T14:46:21.000Z` and `2024-06-15T14:46:21Z` time formats,
+    i.e. both integer and decimal seconds.
+    """
+    formats = ["%Y-%m-%dT%H:%M:%S.%fZ", "%Y-%m-%dT%H:%M:%SZ"]
+    for fmt in formats:
+        try:
+            return dt.strptime(timestamp_str, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"Timestamp '{timestamp_str}' does not match any expected format.")
+
+
+def load_schema(version):
+    xsd_filename = ""
+    if version in ("1.0", "1.1"):
+        xsd_filename = f"schema/gpx_{version}.xsd"
+    else:
+        raise GPXValidationError(f"Unsupported GPX version: {version}")
+
+    try:
+        with open(xsd_filename, 'rb') as f:
+            schema_doc = etree.parse(f)
+            schema = etree.XMLSchema(schema_doc)
+    except Exception as e:
+        raise GPXValidationError(f"Error loading schema file '{xsd_filename}': {e}")
+    return schema
+
+
+def validate_coordinates(root):
+    """Custom check for coordinate values in lenient mode."""
+    for trkpt in root.findall(".//{*}trkpt"):
+        lat = trkpt.get("lat")
+        lon = trkpt.get("lon")
+        try:
+            lat_val = float(lat)
+            lon_val = float(lon)
+        except (TypeError, ValueError):
+            raise GPXValidationError(f"Invalid coordinate values: lat={lat}, lon={lon}")
+        if not (-90 <= lat_val <= 90):
+            raise GPXValidationError(f"Latitude {lat_val} out of range (-90, 90)")
+        if not (-180 <= lon_val <= 180):
+            raise GPXValidationError(f"Longitude {lon_val} out of range (-180, 180)")
+
+
+def validate_elevations(root):
+    """Custom check for elevation values in lenient mode."""
+    for trkpt in root.findall(".//{*}trkpt"):
+        ele_elem = trkpt.find("{*}ele")
+        if ele_elem is not None and ele_elem.text:
+            try:
+                ele_val = float(ele_elem.text)
+            except ValueError:
+                raise GPXValidationError(f"Invalid elevation value: {ele_elem.text}")
+
+
+def validate_schema(tree, schema, strict, root=None):
+    """
+    Validate the XML tree against the provided schema.
+    In default (lenient) mode, if errors are solely due to extra precision on coordinates,
+    perform a manual coordinate check.
+    In strict mode, any schema violation will result in an error.
+    """
+    if schema.validate(tree):
+        return  # Validation passed
+
+    if strict:
+        error_messages = "\n".join(f"  {error.message}" for error in schema.error_log[:10])
+        raise GPXValidationError(f"XML does not conform to the GPX schema (strict mode enabled):\n"
+                                  f"The first {min(10, len(schema.error_log))} errors (out of {len(schema.error_log)}) are:\n"
+                                  f"{error_messages}")
+
+    # Lenient mode: check if errors are exclusively about lat/lon or elevation precision
+
+    # Define allowed keywords for lenient errors: latitude, longitude, and elevation.
+    allowed_keywords = ["latitudeType", "longitudeType", "ele"]
+
+    # Filter out errors that are solely about these issues.
+    error_log = [e.message for e in schema.error_log]
+    filtered_errors = [msg for msg in error_log if not any(keyword in msg for keyword in allowed_keywords)]
+
+    if len(filtered_errors) == 0:
+        # Run manual coordinate validation
+        validate_coordinates(root)
+        validate_elevations(root)
+        print("Warning: GPX file does not strictly conform to the schema (coordinate precision issues), "
+              "but manual checks passed in lenient mode.")
+    else:
+        error_messages = "\n".join(f"  {error}" for error in filtered_errors[:10])
+        raise GPXValidationError(f"XML does not conform to the GPX schema ({len(filtered_errors)} errors):\n"
+                                  f"The first {min(10, len(filtered_errors))} errors (out of {len(filtered_errors)}) are:\n"
+                                  f"{error_messages}")
+
+
+def check_timestamp_consistency(root):
+    """
+    For each track that has at least one timestamped point, ensure that:
+      - Timestamps appear in strictly increasing order.
+      - No two distinct points have the same timestamp.
+    """
+    # Using a namespace-agnostic search with {*}
+    tracks = root.findall(".//{*}trk")
+    if not tracks:
+        # No tracks in the file.
+        return
+
+    # Iterate over each track.
+    for trk in tracks:
+        # List to store timestamps (in order) for the current track.
+        timestamps = []
+        # Process each track segment (trkseg) in the order they appear.
+        for trkseg in trk.findall(".//{*}trkseg"):
+            for trkpt in trkseg.findall("{*}trkpt"):
+                time_elem = trkpt.find("{*}time")
+                if time_elem is not None and time_elem.text:
+                    try:
+                        # GPX timestamps are typically in ISO8601 format ending with 'Z' (UTC).
+                        t = parse_timestamp(time_elem.text)
+                    except ValueError:
+                        print(f"Invalid timestamp format: {time_elem.text}")
+                        sys.exit(1)
+                    # Check for duplicate timestamp (i.e. same time appears more than once in this track)
+                    if t in timestamps:
+                        raise GPXValidationError(f"Duplicate timestamp found in track: {t}")
+                    # If there is a previous timestamp, ensure the current one is later.
+                    if timestamps and t <= timestamps[-1]:
+                        raise GPXValidationError(f"Timestamps not strictly increasing: {t} does not come after {timestamps[-1]}")
+                    timestamps.append(t)
+
+
+def validate_gpx(file_path, strict=False):
+    """Run the full validation procedure on the provided GPX file."""
+    # Step 1. Parse the file as XML.
+    tree = parse_gpx(file_path)
+    root = tree.getroot()
+
+    # Step 2. Determine GPX version from the root element.
+    version = root.get("version")
+    if version not in ("1.0", "1.1"):
+        print(f"Unsupported or missing GPX version: {version}")
+        sys.exit(1)
+
+    # Step 3. Validate against the corresponding GPX XSD.
+    schema = load_schema(version)
+    # Note: lenient mode is the default behavior; strict mode is enabled via command-line flag.
+    validate_schema(tree, schema, strict=strict, root=root)
+    print("XML schema validation passed.")
+
+    # Step 4. GPX-specific content check.
+    tracks = root.findall(".//{*}trk")
+    if not tracks:
+        print("Warning: No tracks found in the GPX file.")
+
+    # Step 5. Timestamp consistency check.
+    check_timestamp_consistency(root)
+    print("Timestamp consistency check passed.")
+
+    print("GPX file is valid.")
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Validate a GPX file for XML schema and timestamp consistency.\n"
+                    "By default, the validator runs in lenient mode (extra precision is allowed).\n"
+                    "Use --strict to enforce strict schema compliance."
+    )
+    parser.add_argument("gpx_file", help="Path to the GPX file to validate")
+    parser.add_argument("--strict", action="store_true", help="Enable strict mode (default is lenient)")
+
+    args = parser.parse_args()
+    try:
+        validate_gpx(args.gpx_file, strict=args.strict)
+    except GPXValidationError as e:
+        print(e, file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()