Feature/Add support for OpenStreetMaps (#28)

* Move internal file methods to utils file

* Add OpenStreetMap config to figure

* Breakup WKTPlot to add osm components

* Separate figure creation from plotting logic

* Fix flake8 errors

* Add standard plot tests

* Add osm plot unittests

* Bump minor version

* Add flake8 check for tests

* Add standard map unittests

* Add unittests for osm mapper

* Remove non Python 3.7 compatible string format

* Rename maps to mappers

* Add docstring to _create_figure abstractmethod

* Remove commented code

* Fix method signature

* Add more examples

* Update README

Author: misimpso

README.md

@@ -17,36 +17,63 @@ The [well-known-text](https://en.wikipedia.org/wiki/Well-known_text_representati
 
 WKTPlot is a library provides an easy-to-use API for visualizing well-known-text strings and shapely objects programatically. This library wraps around the [Bokeh](https://github.com/bokeh/bokeh) library, which is a powerful plotting library for generating interactive visualizations. Bokeh also provides a rich assortment of [stylizing options](https://docs.bokeh.org/en/latest/docs/user_guide/styling.html) which are all usable through WKTPlot's `add_shape` method.
 
+---
+
+### Supported datatypes
+WKTPlot supports the majority of well-known-text primitives, including:
+* Point
+* MultiPoint
+* LineString
+* MultiLineString
+* LinearRing
+* Polygon
+* MultiPolygon
+* GeometryCollection
+
+---
+
 ## Basic Usage
 ``` python
-from shapely.geometry import Polygon
+from shapely.geometry import LineString
 from wktplot import WKTPlot
 
 # Create plot object
 plot = WKTPlot(title="My first plot!", save_dir="/path/to/directory")
 
 # Define shapes either through well-known-text (WKT) string, or shapely object
-shape_1 = "POINT (30 10)"
-shape_2 = Polygon([[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]])
+line_string = LineString([[45, 5], [30, -7], [40, 10]])
+polygon = "POLYGON ((35 10, 45 45, 15 40, 10 20, 35 10),(20 30, 35 35, 30 20, 20 30))"
+points = "MULTIPOINT (17 11, 13 0, 22 -5, 25 7)"
 
-# Add shapes to the plot
-plot.add_shape(shape_1, fill_color="green", line_width=3)
-plot.add_shape(shape_2, fill_color="cyan", fill_alpha=0.7)
+# Add shapes to the plot with style args
+plot.add_shape(line_string, line_color="firebrick", line_alpha=0.5, line_width=20)
+plot.add_shape(polygon, fill_color="#6495ED", fill_alpha=0.5)
+plot.add_shape(points, fill_color=(50, 205, 50, 0.25), fill_alpha=0.7, size=30)
 
-# Save the plot to disk [/path/to/directory/my_first_plot.html]
+# Save plot to disk [/path/to/directory/my_first_plot.html]
 plot.save()
 ```
 
-### Supported datatypes
-WKTPlot supports majority of shapely objects including:
-* Point
-* MultiPoint
-* LineString
-* MultiLineString
-* LinearRing
-* Polygon
-* MultiPolygon
-* GeometryCollection
+![Output](https://i.imgur.com/aajbppI.png)
+
+---
+## OpenStreetMaps
+WKTPlot now supports the ability to integrate with OpenStreetMaps. Shape coordinates will be projected to the Mercator coordinate system, which appear to distort shape proportions compared to standard geometric projection.
+```python
+# Import OpenStreetMaps plotting class
+from wktplot.plots.osm import OpenStreetMapsPlot
+
+# Create plot object just like standard WKTPlot class
+plot = OpenStreetMapsPlot("Open Street Map Plot", save_dir="/path/to/directory")
+
+shape = "POLYGON ((35 10, 45 45, 15 40, 10 20, 35 10), (20 30, 35 35, 30 20, 20 30))"
+plot.add_shape(shape, fill_alpha=0.5, fill_color="firebrick")
+
+plot.save()
+```
+![Output](https://i.imgur.com/JdUDMh7.png)
+
+---
 
 ## Advanced Usage
 Example for plotting from shapefile. Shapefile is of California's county boundaries from [here](https://data.ca.gov/dataset/ca-geographic-boundaries).
@@ -70,6 +97,33 @@ plot.save()
 Which will result in this output:
 ![CaliforniaCounties](https://i.imgur.com/YPQQlml.png)
 
-## Future Plans
-* Add native support for visualizing GeoDataframes and shapefiles.
-* Make web view more interactive.
+---
+
+## Development
+### Bugs / Feature Requests
+Plese open an `Issue` in Github with any bugs found or feature requests, and follow the prompts so that developers can reproduce or implement the necessary changes.
+
+### Local development
+Development of this model is centered around the Makefile. All you need to spin up a working environment to build and test this module can be done with the Makefile.
+
+1. Clone the repository onto your machine.
+    ```sh
+    git clone https://github.com/FuzzFoundation/WKTPlot.git
+    ```
+2. Create the Python virtaul environment and install module's development / testing dependencies. This will also install WKTPlot in [develop mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).
+    ```sh
+    make develop
+    ```
+3. Activate virtual environment
+    ```sh
+    source venv/bin/activate
+    ```
+4. Run linting and unittests.
+    ```sh
+    make test
+    ```
+5. When you want to remove the virtual environment and clean up after development.
+    ```sh
+    deactivate
+    make clean  # This will remove all generated files, like .coverage and build/
+    make sparkling  # This will remove all generate files and the virtual env.

examples/basic.py

@@ -0,0 +1,18 @@
+from shapely.geometry import LineString
+from wktplot import WKTPlot
+
+# Create plot object
+plot = WKTPlot(title="My first plot!", save_dir="/path/to/directory")
+
+# Define shapes either through well-known-text (WKT) string, or shapely object
+line_string = LineString([[45, 5], [30, -7], [40, 10]])
+polygon = "POLYGON ((35 10, 45 45, 15 40, 10 20, 35 10),(20 30, 35 35, 30 20, 20 30))"
+points = "MULTIPOINT (17 11, 13 0, 22 -5, 25 7)"
+
+# Add shapes to the plot with style args
+plot.add_shape(line_string, line_color="firebrick", line_alpha=0.5, line_width=20)
+plot.add_shape(polygon, fill_color="#6495ED", fill_alpha=0.5)
+plot.add_shape(points, fill_color=(50, 205, 50, 0.25), fill_alpha=0.7, size=30)
+
+# Save plot to disk [/path/to/directory/my_first_plot.html]
+plot.save()

examples/open_street_map.py

@@ -0,0 +1,7 @@
+from wktplot.plots.osm import OpenStreetMapsPlot
+
+shape = "POLYGON ((35 10, 45 45, 15 40, 10 20, 35 10), (20 30, 35 35, 30 20, 20 30))"
+
+plot = OpenStreetMapsPlot("Open Street Map Plot", save_dir="/path/to/directory")
+plot.add_shape(shape, fill_alpha=0.5, fill_color="firebrick")
+plot.save()

requirements-dev.txt

@@ -1,3 +1,4 @@
 flake8>=4.0.1
-pytest-cov>=2.10.1
 pytest>=6.1.2
+pytest-cov>=2.10.1
+pytest-mock>=3.8.2

setup.cfg

@@ -45,7 +45,6 @@ exclude =
     .git,
     .eggs,
     __pycache__,
-    tests/,
     build/,
     dist/,
     setup.py,

src/wktplot/__init__.py

@@ -1,3 +1,3 @@
-from .wktplot import WKTPlot  # noqa: F401
+from .plots.standard import WKTPlot  # noqa: F401
 
-__version__ = "2.2.1"
+__version__ = "2.3.0"

src/wktplot/common/file_utils.py

@@ -0,0 +1,38 @@
+import random
+import re
+import string
+
+from re import Pattern
+from typing import List
+
+ALPHA_NUM_REGEX: Pattern = re.compile(r'[A-Za-z0-9]+')
+
+
+def sanitize_text(text: str) -> str:
+    """ Remove symbols from given argument `text`.
+            e.g. "wow 123_ @#$%    1" --> "wow_123_1"
+
+    Args:
+        text (str): Text to remove symbols from.
+
+    Returns:
+        str: Sanitized text.
+    """
+
+    words: List[str] = ALPHA_NUM_REGEX.findall(text.lower())
+    return "_".join(words)
+
+
+def get_random_string(string_length: int = 6) -> str:
+    """ Generate string of random alpha-numeric charcters of a given length `string_length`.
+
+    Args:
+        string_length (int, default = 6): String length of returned string.
+
+    Returns:
+        str: Random string containing alpha-numeric characters.
+    """
+
+    options: str = string.ascii_letters + string.digits
+    random_chars: List[str] = random.choices(options, k=string_length)
+    return "".join(random_chars)

src/wktplot/common/types.py

@@ -0,0 +1,24 @@
+from shapely.geometry import (
+    GeometryCollection,
+    LineString,
+    LinearRing,
+    MultiLineString,
+    MultiPoint,
+    MultiPolygon,
+    Point,
+    Polygon,
+)
+from shapely.geometry.base import BaseGeometry
+from typing import Tuple, Type
+
+
+SUPPORTED_GEOMS: Tuple[Type[BaseGeometry]] = (
+    GeometryCollection,
+    LineString,
+    LinearRing,
+    MultiLineString,
+    MultiPoint,
+    MultiPolygon,
+    Point,
+    Polygon,
+)

src/wktplot/mappers/__init__.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractclassmethod
+from shapely.geometry import Point, LineString, LinearRing, Polygon
+from typing import List, Tuple, Union
+
+
+class BaseMapper(ABC):
+
+    @abstractclassmethod
+    def _get_point_coords(cls, shape: Point) -> Tuple[float, float]:
+        """ Get x, y coordinate of the given `shape` geometry.
+
+        Args:
+            shape (obj: Point): Point shape.
+
+        Returns:
+            tuple[float, float]: Tuple with x, y coordinate values.
+        """
+
+    @abstractclassmethod
+    def _get_line_string_coords(cls, shape: Union[LineString, LinearRing]) -> Tuple[List[int], List[int]]:
+        """ Get x, y coordinates of the given `shape` geometry.
+
+        Args:
+            shape (obj: LineString | obj: LinearRing): LineString or LinearRing shape.
+
+        Returns:
+            tuple[list[float], list[float]]: Tuple with x, y coordinate value lists.
+        """
+
+    @abstractclassmethod
+    def _get_polygon_coords(cls, shape: Polygon) -> Tuple[List[List[float]], List[List[float]]]:
+        """ Get x, y coordinates of the given `shape` geometry.
+
+        Args:
+            shape (obj: Polygon): Polygon shape.
+
+        Returns:
+            tuple[list[list[float]], list[list[float]]]: Tuple with x, y coordinate values as 2D lists.
+        """