|
| 1 | +""" |
| 2 | +1. Making your first figure |
| 3 | +=========================== |
| 4 | +
|
| 5 | +This tutorial page covers the basics of creating a figure using PyGMT - a |
| 6 | +Python wrapper for the Generic Mapping Tools (GMT). It will only use |
| 7 | +the ``coast`` module for plotting. Later examples will address other PyGMT |
| 8 | +modules. |
| 9 | +""" |
| 10 | + |
| 11 | +############################################################################### |
| 12 | +# Setting up the development environment |
| 13 | +# -------------------------------------- |
| 14 | +# |
| 15 | +# PyGMT can be used in both a Python script and a notebook environment, such |
| 16 | +# as Jupyter. The tutorial's recommended method is to use a notebook, and the |
| 17 | +# code will be for a notebook environment. |
| 18 | + |
| 19 | + |
| 20 | +############################################################################### |
| 21 | +# Loading the library |
| 22 | +# ------------------- |
| 23 | +# |
| 24 | +# The first step is to import ``pygmt``. All modules and figure generation is |
| 25 | +# accessible from the :mod:`pygmt` top level package. |
| 26 | + |
| 27 | +# sphinx_gallery_thumbnail_number = 4 |
| 28 | +import pygmt |
| 29 | + |
| 30 | +############################################################################### |
| 31 | +# Creating a figure |
| 32 | +# ----------------- |
| 33 | +# |
| 34 | +# All figure generation in PyGMT is handled by the :class:`pygmt.Figure` class. |
| 35 | +# Start a new figure by creating an instance of this class: |
| 36 | + |
| 37 | +fig = pygmt.Figure() |
| 38 | + |
| 39 | +############################################################################### |
| 40 | +# To add to a plot object (``fig`` in this example), the PyGMT module is used |
| 41 | +# as a method on the class. This example will use the module ``coast``, which |
| 42 | +# can be used to create a map without any other modules or external data. The |
| 43 | +# ``coast`` module plots the coastlines, borders, and bodies of water using a |
| 44 | +# database that is included in GMT. |
| 45 | +# |
| 46 | +# First, a region for the figure must be selected. This example will plot some |
| 47 | +# of the coast of Maine in the northeastern US. A Python list can be passed to |
| 48 | +# the ``region`` argument with the minimum and maximum X-values (longitude) |
| 49 | +# and the minimum and maximum Y-values (latitude). For this example, the |
| 50 | +# minimum (bottom left) coordinates are (N43.75, W69) and the maximum (top |
| 51 | +# right) coordinates are (N44.75, W68). Negative values can be passed for |
| 52 | +# latitudes in the southern hemisphere or longitudes in the western hemisphere. |
| 53 | +# |
| 54 | +# In addition to the region, an argument needs to be passed to ``coast`` to |
| 55 | +# tell it what to plot. In this example, ``coast`` will be told to plot the |
| 56 | +# shorelines by passing the Boolean value ``True`` to the ``shorelines`` |
| 57 | +# parameter. The ``shorelines`` parameter has other options for finer control, |
| 58 | +# but setting it to ``True`` uses the default values. |
| 59 | + |
| 60 | +fig.coast(region=[-69, -68, 43.75, 44.75], shorelines=True) |
| 61 | + |
| 62 | +############################################################################### |
| 63 | +# To see the figure, call :meth:`pygmt.Figure.show`. |
| 64 | + |
| 65 | +fig.show() |
| 66 | + |
| 67 | +############################################################################### |
| 68 | +# Color the land and water |
| 69 | +# ------------------------ |
| 70 | +# |
| 71 | +# This figure plots all of the coastlines in the given region, but it does not |
| 72 | +# indicate where the land and water are. Color values can be passed to ``land`` |
| 73 | +# and ``water`` to set the colors on the figure. |
| 74 | +# |
| 75 | +# When plotting colors in PyGMT, there are multiple |
| 76 | +# :gmt-docs:`color codes <gmtcolors.html>`, that can be used. This includes |
| 77 | +# standard GMT color names (like ``skyblue``), R/G/B levels (like ``0/0/255``), |
| 78 | +# a hex value (like ``#333333``), or a graylevel (like ``50``). For this |
| 79 | +# example, GMT color names are used. |
| 80 | + |
| 81 | +fig = pygmt.Figure() |
| 82 | +fig.coast( |
| 83 | + region=[-69, -68, 43.75, 44.75], |
| 84 | + shorelines=True, |
| 85 | + land="lightgreen", |
| 86 | + water="lightblue", |
| 87 | +) |
| 88 | +fig.show() |
| 89 | + |
| 90 | +############################################################################### |
| 91 | +# Set the projection |
| 92 | +# ------------------ |
| 93 | +# |
| 94 | +# This figure now has its colors set, but there is no projection or size |
| 95 | +# set for the map. Both of these values are set using the ``projection`` |
| 96 | +# parameter. |
| 97 | +# |
| 98 | +# The appropriate projection varies for the type of map. The available |
| 99 | +# projections are explained in the :doc:`projection </projections/index>` |
| 100 | +# gallery. For this example, the Mercator projection is set using ``"M"``. |
| 101 | +# The width of the figure will be 10 centimeters, as set by ``"10c"``. The map |
| 102 | +# size can also be set in inches using "i" (e.g. a 5 inch wide Mercator |
| 103 | +# projection would use ``"M5i"``). |
| 104 | + |
| 105 | +fig = pygmt.Figure() |
| 106 | +fig.coast( |
| 107 | + region=[-69, -68, 43.75, 44.75], |
| 108 | + shorelines=True, |
| 109 | + land="lightgreen", |
| 110 | + water="lightblue", |
| 111 | + projection="M10c", |
| 112 | +) |
| 113 | +fig.show() |
| 114 | + |
| 115 | +############################################################################### |
| 116 | +# Add a frame |
| 117 | +# ----------- |
| 118 | +# |
| 119 | +# While that the map's colors, projection, and size have been set, the region |
| 120 | +# that is being displayed is not apparent. A frame can be added to |
| 121 | +# annotate the latitude and longitude of the region. |
| 122 | +# |
| 123 | +# The ``frame`` parameter is used to add a frame to the figure. For now, it |
| 124 | +# will be set to ``True`` to use default settings, but later tutorials will |
| 125 | +# show how ``frame`` can be used to customize the axes, gridlines, and titles. |
| 126 | + |
| 127 | +fig = pygmt.Figure() |
| 128 | +fig.coast( |
| 129 | + region=[-69, -68, 43.75, 44.75], |
| 130 | + shorelines=True, |
| 131 | + land="lightgreen", |
| 132 | + water="lightblue", |
| 133 | + projection="M10c", |
| 134 | + frame=True, |
| 135 | +) |
| 136 | +fig.show() |
| 137 | + |
| 138 | +############################################################################### |
| 139 | +# Additional exercises |
| 140 | +# -------------------- |
| 141 | +# |
| 142 | +# This is the end of the first tutorial. Here are some additional exercises |
| 143 | +# for the concepts that were discussed: |
| 144 | +# |
| 145 | +# 1. Make a map of Germany using its ISO country code ("DE"). Pass the ISO |
| 146 | +# code as a Python string to the ``region`` parameter. |
| 147 | +# |
| 148 | +# 2. Change the color of the land to "khaki" and the water to "azure". |
| 149 | +# |
| 150 | +# 3. Change the color of the lakes (using the ``lakes`` parameter) to "red". |
| 151 | +# |
| 152 | +# 4. Create a global map. Set the region to "d" to center the map at the Prime |
| 153 | +# Meridian or "g" to center the map at the International Date Line. When the |
| 154 | +# region is set without using a list full of integers or floating numbers, |
| 155 | +# the argument needs to be passed as a Python string. Create a 15 centimeter |
| 156 | +# map using the Mollwide ("W") projection. |
0 commit comments