{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "" ] }, { "cell_type": "markdown", "metadata": { "tags": [] }, "source": [ "# Introduction to Cartopy" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "___" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Overview\n", "\n", "The concepts covered in this section include:\n", "\n", "1. Learning core Cartopy concepts: map projections and `GeoAxes`\n", "2. Exploring some of Cartopy's map projections\n", "3. Creating regional maps\n", "\n", "This tutorial will lead you through some basics of creating maps with specified projections using Cartopy, and adding geographical features (like coastlines and borders) to those maps.\n", "\n", "Plotting data on map projections will be covered in later tutorials." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Prerequisites\n", "\n", "| Concepts | Importance | Notes |\n", "| --- | --- | --- |\n", "| [Matplotlib](../matplotlib) | Necessary | |\n", "\n", "- **Time to learn**: 30 minutes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "___" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Imports\n", "\n", "Here, we import the main libraries of Cartopy: crs and feature. In addition, we import numpy, as well as matplotlib's pyplot interface. Finally, we import a library called warnings, and use it to remove extraneous warnings that Cartopy produces in later examples." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import warnings\n", "\n", "import matplotlib.pyplot as plt\n", "import numpy as np\n", "from cartopy import crs as ccrs, feature as cfeature\n", "\n", "# Suppress warnings issued by Cartopy when downloading data files\n", "warnings.filterwarnings('ignore')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "___" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Basic concepts: map projections and `GeoAxes`" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Extend Matplotlib's `axes` into georeferenced `GeoAxes`" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Recall from earlier tutorials that a *figure* in Matplotlib has two elements: a `Figure` object, and a list of one or more `Axes` objects (subplots).\n", "\n", "Since we imported `cartopy.crs`, we now have access to Cartopy's *Coordinate Reference System*, which contains many geographical projections. We can specify one of these projections for an `Axes` object to convert it into a `GeoAxes` object. This will effectively *georeference* the subplot. Examples of converting `Axes` objects into `GeoAxes` objects can be found later in this section." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Create a map with a specified projection\n", "\n", "In this example, we'll create a `GeoAxes` object that uses the `PlateCarree` projection. `PlateCarree` is a global lat-lon map projection in which each point is evenly spaced in terms of degrees. The name \"Plate Carree\" is French for \"flat square\"." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "fig = plt.figure(figsize=(11, 8.5))\n", "ax = plt.subplot(1, 1, 1, projection=ccrs.PlateCarree(central_longitude=-75))\n", "ax.set_title(\"A Geo-referenced subplot, Plate Carree projection\");" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Although the figure seems empty, it has, in fact, been georeferenced using a map projection; this projection is provided by Cartopy's `crs` (coordinate reference system) class. We can now add in cartographic features, in the form of *shapefiles*, to our subplot. One such cartographic feature is coastlines, which can be added to our subplot using the callable `GeoAxes` method simply called `coastlines`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "ax.coastlines()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
Info
\n", " To get the figure to display again with the features that we've added since the original display, just type the name of the Figure object in its own cell.\n", "Info
\n", " You can find a list of supported projections in Cartopy, with examples, at https://scitools.org.uk/cartopy/docs/latest/reference/crs.html\n", "Info
\n", " Please note, even though the calls to the `subplot` method use different projections, the calls to `set_extent` use PlateCarree. This ensures that the values we passed into `set_extent` will be transformed from degrees into the values appropriate for the projection we use for the map.\n", "Info
\n", " Lat/lon labeling for projections other than Mercator and PlateCarree is a recent addition to Cartopy. As you can see, work still needs to be done to improve the placement of labels.\n", "Warning
\n", " Be patient; when plotting a small geographical area, the high-resolution \"10m\" shapefiles are used by default. As a result, these plots take longer to create, especially if the shapefiles are not yet downloaded from Natural Earth. Similar issues can occur whenever a `GeoAxes` object is transformed from one coordinate system to another. (This will be covered in more detail in a subsequent page.)\n", "Note:
\n", " For high-resolution Natural Earth shapefiles such as this, while we could add Cartopy'sOCEAN
feature, it currently takes much longer to render on the plot. You can create your own version of this example, with the OCEAN
feature added, to see for yourself how much more rendering time is added. Instead, we take the strategy of first setting the facecolor of the entire subplot to match that of water bodies in Cartopy. When we then layer on the LAND
feature, pixels that are not part of the LAND
shapefile remain in the water
facecolor, which is the same color as the OCEAN
.\n",
"