#1 Work in progress:

-Add example files
-Update documentation
-Update README

[ci skip]

README.md

@@ -3,6 +3,10 @@
 ## 🔎 Description
 Easy to use Python GPX library.
 
+- Documentation: https://ezgpx.readthedocs.io/en/latest/
+- Source code: https://github.com/FABallemand/ezGPX
+- Bug reports: https://github.com/FABallemand/ezGPX/issues
+
 ## 🛠️ Installation
 
 ```bash
@@ -21,27 +25,24 @@ gpx = ezgpx.GPX("file.gpx")
 gpx.simplify()
 
 # Plot with Matplotlib
-gpx.matplotlib_plot(title="Track", base_color="#FF0000",
-                    start_stop=True, way_points=False, file_path="img_1")
-
-# Plot with Matplotlib Basemap Toolkit
-gpx.matplotlib_basemap_plot(title="Track", base_color="#00FF00",
-                            start_stop=False, way_points=False, file_path="img_2")
-
-# Plot with gmap (Google Maps)
-gpx.gmap_plot(title="Track", base_color="#0000FF", start_stop=True,
-              way_points=True, file_path="map_1.html", open=True)
-
-# Plot with Folium
-gpx.folium_plot(title="Track", tiles="OpenStreetMap", base_color="#000000", start_stop=True,
-                way_points=True, minimap=True, coord_popup=True, file_path="map_2.html", open=True)
+gpx.matplotlib_plot(elevation_color=True,
+                    start_stop_colors=("green", "red"),
+                    way_points_color="blue",
+                    title=gpx.name(),
+                    duration=(0, 0),
+                    distance=(0.5, 0),
+                    ascent=None,
+                    pace=(1, 0),
+                    speed=None,
+                    file_path="img_1")
 
 # Remove metadata
 gpx.remove_metadata()
 
 # Write new simplified GPX file
 gpx.to_gpx("new_file.gpx")
 ```
+![](img/matplotlib_plot_1.png)
 
 ## 📚 References:
 

doc/description.rst

@@ -0,0 +1,8 @@
+Description
+===========
+
+Easy to use Python GPX library.
+
+- Documentation: https://ezgpx.readthedocs.io/en/latest/
+- Source code: https://github.com/FABallemand/ezGPX
+- Bug reports: https://github.com/FABallemand/ezGPX/issues

doc/index.rst

@@ -10,7 +10,10 @@ Welcome to ezGPX's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   modules
+   description.rst
+   installation.rst
+   tutorials/index.rst
+   modules.rst
 
 
 Indices and tables

doc/installation.rst

@@ -0,0 +1,9 @@
+Installation
+============
+
+.. warning:: In order to use advanced plotting features, ezgpx uses gmap and folium.
+
+Install ezGPX with :command:`pip`::
+
+    python3 -m pip install --upgrade pip
+    python3 -m pip install --upgrade ezgpx

doc/tutorials/index.rst

@@ -0,0 +1,11 @@
+Tutorials
+=========
+
+
+.. toctree::
+  :maxdepth: 2
+
+  parsing.rst
+  plotting.rst
+  modifying.rst
+  writing.rst

doc/tutorials/modifying.rst

@@ -0,0 +1,93 @@
+Modifying
+---------
+
+Remove Data
+^^^^^^^^^^^
+
+All data contained in a GPX file are not always relevant. By working with :py:class:`~ezgpx.gpx.GPX` objects, it is possible to remove useless data such as metadata, elevation and time data.
+
+::
+
+    from ezgpx import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Remove metadata
+    gpx.remove_metadata()
+
+    # Remove elevation data
+    gpx.remove_elevation()
+
+    # Remove time data
+    gpx.remove_time()
+
+    # Write new simplified GPX file
+    gpx.to_gpx("new_file.gpx")
+
+Remove GPS Errors
+^^^^^^^^^^^^^^^^^
+
+GPS devices sometimes loose signal generating errors in GPX files. The most noticeable errors (single isolated points) can be found and removed as follow.
+
+::
+
+    import ezgpx
+
+    # Parse GPX file
+    gpx = ezgpx.GPX("file.gpx")
+
+    # Remove GPS errors
+    gpx.remove_gps_errors()
+
+    # Write new simplified GPX file
+    gpx.to_gpx("new_file.gpx")
+
+Simplify Track
+^^^^^^^^^^^^^^
+
+It is sometimes usefull to reduce the amount of track points contained in a GPX file especially when working with low power and low capacity GPS devices. The :py:meth:`~simplify` allows to reduce the number of points while keeping a great precision.
+
+::
+
+    import ezgpx
+
+    # Parse GPX file
+    gpx = ezgpx.GPX("file.gpx")
+
+    # Simplify (using Ramer-Douglas-Peucker algorithm)
+    gpx.simplify()
+
+    # Write new simplified GPX file
+    gpx.to_gpx("new_file.gpx")
+
+In the following example, one manage to go from 3263 track points to only 1082. This correspond to a 69% decrease in points and allows to save 704.6 kB (ie: 85.4% of the original file size) by reducing the file size from 824.8 kB to 120.2 kB.
+
+::
+
+    from ezgpx import GPX
+
+    # Load and parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Print number of track points
+    print(f"nb_points = {gpx.nb_points()}")
+
+    # Plot tracks
+    gpx.matplotlib_plot(start_stop_colors=("green", "red"), way_points_color="blue", elevation_color=True, title="Run", duration=(0,0), distance=(0.5,0), ascent=(1,0))
+
+    # Simplify tracks
+    gpx.simplify()
+
+    # Print new number of track points
+    print(f"nb_points = {gpx.nb_points()}")
+
+    # Plot tracks
+    gpx.matplotlib_plot(start_stop_colors=("green", "red"), way_points_color="blue", elevation_color=True, title="Run", duration=(0,0), distance=(0.5,0), ascent=(1,0))
+
+    # Save GPX
+    gpx.to_gpx("file_simplified.gpx")
+
+.. image:: ../../img/simplify_1.png
+  :width: 500
+  :alt: Track plot followed by the simplified track plot

doc/tutorials/parsing.rst

@@ -0,0 +1,15 @@
+Parsing
+-------
+
+In order to parse a GPX file, simply create a new :py:class:`~ezgpx.gpx.GPX` object with the path to the file.
+
+.. note::
+
+    In the next tutorials you will learn how to plot, modify and save this :py:class:`~ezgpx.gpx.GPX` object.
+
+::
+
+    from ezGPX import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")

doc/tutorials/plotting.rst

@@ -0,0 +1,109 @@
+Plotting
+--------
+
+ezGPX currently provides four different ways to plot a :py:class:`~ezgpx.gpx.GPX` object.
+
+Matplotlib
+^^^^^^^^^^
+
+::
+
+    import ezgpx
+
+    # Parse GPX file
+    gpx = ezgpx.GPX("file.gpx")
+
+    # Plot with Matplotlib
+    gpx.matplotlib_plot(elevation_color=True,
+                        start_stop_colors=("green", "red"),
+                        way_points_color="blue",
+                        title=gpx.name(),
+                        duration=(0, 0),
+                        distance=(0.5, 0),
+                        ascent=(1, 0),
+                        pace=None,
+                        speed=None,
+                        file_path="img_1")
+
+.. image:: ../../img/matplotlib_plot_1.png
+  :width: 500
+  :alt: Matplotlib plot
+
+Matplotlib Basemap Toolkit
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    import ezgpx
+
+    # Parse GPX file
+    gpx = ezgpx.GPX("file.gpx")
+
+    # Plot with Matplotlib Basemap Toolkit
+    gpx.matplotlib_basemap_plot(base_color="darkorange",
+                                start_stop_colors=("darkgreen", "darkred"),
+                                way_points_color="darkblue",
+                                title=gpx.name(),
+                                duration=(0,0),
+                                distance=(0.5,0),
+                                ascent=None,
+                                pace=None,
+                                speed=(1,0),
+                                file_path="img_2")
+
+.. image:: ../../img/matplotlib_basemap_plot_1.png
+  :width: 500
+  :alt: Matplotlib Basemap Toolkit plot
+
+gmap
+^^^^
+
+.. warning:: Requires :py:mod:`~gmap`.
+
+::
+
+    import ezgpx
+
+    # Parse GPX file
+    gpx = ezgpx.GPX("file.gpx")
+
+    # Plot with gmap (Google Maps)
+    gpx.gmap_plot(base_color="yellow",
+                start_stop_colors=("green", "red"),
+                way_points_color="blue",
+                zoom=13,
+                title=gpx.name(),
+                file_path="map_1.html",
+                open=False)
+
+.. image:: ../../img/gmap_plot_1.png
+  :width: 500
+  :alt: gmap plot
+
+Folium
+^^^^^^
+
+.. warning:: Requires :py:mod:`~folium`.
+
+::
+
+    import ezgpx
+
+    # Parse GPX file
+    gpx = ezgpx.GPX("file.gpx")
+
+    # Plot with Folium
+    gpx.folium_plot(tiles="OpenStreetMap",
+                    base_color="orange",
+                    start_stop_colors=("green", "red"),
+                    way_points_color="blue",
+                    minimap=True,
+                    coord_popup=False,
+                    title="Very nice track!",
+                    zoom=8,
+                    file_path="map_2.html",
+                    open=True)
+
+.. image:: ../../img/folium_plot_1.png
+  :width: 500
+  :alt: Folium plot

doc/tutorials/writing.rst

@@ -0,0 +1,19 @@
+Writing
+-------
+
+Save as GPX file
+^^^^^^^^^^^^^^^^
+
+The :py:meth:`~to_gpx` allows to export a :py:class:`~ezgpx.gpx.GPX` object as a GPX file.
+
+::
+
+    from ezgpx import GPX
+
+    # Parse GPX file
+    gpx = GPX("file.gpx")
+
+    # Do stuff with GPX object
+
+    # Save as GPX file
+    gpx.to_gpx("new_file.gpx")

examples/remove_data.py

@@ -0,0 +1,16 @@
+from ezgpx import GPX
+
+# Parse GPX file
+gpx = GPX("file.gpx")
+
+# Remove metadata
+gpx.remove_metadata()
+
+# Remove elevation data
+gpx.remove_elevation()
+
+# Remove time data
+gpx.remove_time()
+
+# Write new simplified GPX file
+gpx.to_gpx("new_file.gpx")

examples/remove_gps_errors.py

@@ -0,0 +1,10 @@
+from ezgpx import GPX
+
+# Parse GPX file
+gpx = GPX("file.gpx")
+
+# Remove GPS errors
+gpx.remove_gps_errors()
+
+# Write new simplified GPX file
+gpx.to_gpx("new_file.gpx")

examples/simplify.py

@@ -3,7 +3,7 @@
 # Parse GPX file
 gpx = ezgpx.GPX("file.gpx")
 
-# Simplify (using Ramer-Dougle-Peucker algorithm)
+# Simplify (using Ramer-Douglas-Peucker algorithm)
 gpx.simplify()
 
 # Write new simplified GPX file

ezgpx/utils/distance.py

@@ -80,7 +80,7 @@ def line_coefficients(point_1, point_2):
             a = 1
             b = 0
             c = point_1.lon  
-            logging.warning("Vertical line")
+            logging.debug("Vertical line")
 
         return a, b, c
 

setup.py

@@ -20,7 +20,7 @@
     download_url='https://github.com/FABallemand/ezGPX',
     project_urls={
             "Bug Tracker": "https://github.com/FABallemand/ezGPX/issues",
-            # "Documentation": "",
+            "Documentation": "https://ezgpx.readthedocs.io/en/latest/",
             "Source Code": "https://github.com/FABallemand/ezGPX",
         },
     author='Fabien ALLEMAND',