DOC: Add basic tutorial "Plotting polygons"

examples/tutorials/basics/polygons.py

@@ -0,0 +1,107 @@
+"""
+Plotting polygons
+=================
+
+Plotting polygons is handled by the :meth:`pygmt.Figure.plot` method.
+
+This tutorial focuses on input data given as NumPy arrays. Besides NumPy arrays,
+array-like objects are supported. For plotting a GeoPandas GeoDataFrame with
+polygon geometries, e.g. to create a choropleth map, see the gallery example
+:doc:`Choropleth map </gallery/symbols/maps/choropleth_map>`.
+"""
+
+# %%
+import numpy as np
+import pygmt
+
+# %%
+# Plot polygons
+# -------------
+#
+# Set up sample data points as NumPy arrays for the x and y values.
+
+x = np.array([-2, 1, 3, 0, -4, -2])
+y = np.array([-3, -1, 1, 3, 2, -3])
+
+# %%
+# Create a Cartesian plot via the :meth:`pygmt.Figure.basemap` method.
+# Pass arrays to the ``x`` and ``y`` parameters of the :meth:`pygmt.Figure.plot`
+# method. Without further adjustments, lines are drawn between the data points.
+# By default, the lines are 0.25-points thick, black, and solid. In this example,
+# the data points are chosen to make the lines form a polygon.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+
+fig.plot(x=x, y=y)
+
+fig.show()
+
+# %%
+# The ``pen`` parameter can be used to adjust the lines or outline of the polygon.
+# The argument passed to ``pen`` is one string with the comma-separated optional
+# values *width*,\ *color*,\ *style*.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+
+# Use a 2-points thick, darkred, dashed outline
+fig.plot(x=x, y=y, pen="2p,darkred,dashed")
+
+fig.show()
+
+# %%
+# Use the ``fill`` parameter to fill the polygon with a color or pattern.
+# For the patterns avilable in GMT see the Technical Reference at
+# https://www.pygmt.org/dev/techref/patterns.html.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+
+# Fill the polygon with color "orange"
+fig.plot(x=x, y=y, fill="orange", pen="2p,darkred,dashed")
+
+fig.show()
+
+
+# %%
+# Close polygons
+# --------------
+#
+# Set up sample data points as NumPy array for the x and y values. Now,
+# the data points do not form a polygon.
+
+x = np.array([-2, 1, 3, 0, -4])
+y = np.array([-3, -1, 1, 3, 2])
+
+# %%
+# The ``close`` parameter can be used to force the polygon to be closed.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+
+fig.plot(x=x, y=y, pen=True)
+
+fig.shift_origin(xshift="w+1c")
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+
+fig.plot(x=x, y=y, pen=True, close=True)
+
+fig.show()
+
+# %%
+# When using the ``fill`` parameter, the polygon is automatically closed.
+
+fig = pygmt.Figure()
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+
+fig.plot(x=x, y=y, pen=True)
+
+fig.shift_origin(xshift="w+1c")
+fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
+
+fig.plot(x=x, y=y, pen=True, fill="orange")
+
+fig.show()
+
+# sphinx_gallery_thumbnail_number = 3