Introduction to Cartopy¶

Overview¶

The concepts covered in this section include:

1. Learning core Cartopy concepts: map projections and GeoAxes
2. Exploring some of Cartopy’s map projections
3. Creating regional maps

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.

Plotting data on map projections will be covered in later tutorials.

Prerequisites¶

• Time to learn: 30 minutes

Imports¶

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.

Basic concepts: map projections and GeoAxes¶

Extend Matplotlib’s axes into georeferenced GeoAxes¶

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).

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.

Create a map with a specified projection¶

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”.

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.

Add cartographic features to the map¶

Cartopy provides other cartographic features via its features class, which was imported at the beginning of this page, under the name cfeature. These cartographic features are laid out as data in shapefiles. The shapefiles are downloaded when their cartographic features are used for the first time in a script or notebook, and they are downloaded from https://www.naturalearthdata.com/. Once downloaded, they “live” in your ~/.local/share/cartopy directory (note the ~ represents your home directory).

We can add these features to our subplot via the add_feature method; this method allows the definition of attributes using arguments, similar to Matplotlib’s plot method. A list of the various Natural Earth shapefiles can be found at https://scitools.org.uk/cartopy/docs/latest/matplotlib/feature_interface.html. In this example, we add borders and U. S. state lines to our subplot:

Once again, referencing the Figure object will re-render the figure in the notebook, now including the two features.

Explore some of Cartopy’s map projections¶

Mollweide Projection (often used with global satellite mosaics)¶

To save typing later, we can define a projection object to store the definition of the map projection. We can then use this object in the projection kwarg of the subplot method when creating a GeoAxes object. This allows us to use this exact projection in later scripts or Jupyter Notebook cells using simply the object name, instead of repeating the same call to ccrs.

Add in the cartographic shapefiles¶

This example shows how to add cartographic features to the Mollweide projection defined earlier:

Add a fancy background image to the map.¶

We can also use the stock_img method to add a pre-created background to a Mollweide-projection plot:

Lambert Azimuthal Equal Area Projection¶

This example is similar to the above example set, except it uses a Lambert azimuthal equal-area projection instead:

Create regional maps¶

Cartopy’s set_extent method¶

For this example, let’s create another PlateCarree projection, but this time, we’ll use Cartopy’s set_extent method to restrict the map coverage to a North American view. Let’s also choose a lower resolution for coastlines, just to illustrate how one can specify that. In addition, let’s also plot the latitude and longitude lines.

Natural Earth defines three resolutions for cartographic features, specified as the strings “10m”, “50m”, and “110m”. Only one resolution can be used at a time, and the higher the number, the less detailed the feature becomes. You can view the documentation for this functionality at the following reference link: https://www.naturalearthdata.com/downloads/

The PlateCarree projection exaggerates the spatial extent of regions closer to the poles. In the following examples, we use set_extent with stereographic and Lambert-conformal projections, which display polar regions more accurately.

Create a regional map centered over New York State¶

Here we set the domain, which defines the geographical region to be plotted. (This is used in the next section in a set_extent call.) Since these coordinates are expressed in degrees, they correspond to a PlateCarree projection, even though the map projection is set to LambertConformal.

Add some predefined features¶

Some cartographical features are predefined as constants in the cartopy.feature package. The resolution of these features depends on the amount of geographical area in your map, specified by set_extent.

Use lower-resolution shapefiles from Natural Earth¶

In this example, we create a new map. This map uses lower-resolution shapefiles from Natural Earth, and also eliminates the plotting of country borders.

This example requires much more code than previous examples on this page. First, we must create new objects associated with lower-resolution shapefiles. This is performed by the NaturalEarthFeature method, which is part of the Cartopy feature class. Second, we call add_feature to add the new objects to our new map.

A figure with two different regional maps¶

Finally, let’s create a figure with two subplots. On the first subplot, we’ll repeat the high-resolution New York State map created earlier; on the second, we’ll plot over a different part of the world.

An example of plotting data¶

First, we’ll create a lat-lon grid and define some data on it.

Plotting data on a Cartesian grid is equivalent to plotting data in the PlateCarree projection, where meridians and parallels are all straight lines with constant spacing. As a result of this simplicity, the global datasets we use often begin in the PlateCarree projection.

Once we create our map again, we can plot these data values as a contour map. We must also specify the transform keyword argument. This is an argument to a contour-plotting method that specifies the projection type currently used by our data. The projection type specified by this argument will be transformed into the projection type specified in the subplot method. Let’s plot our data in the Mollweide projection to see how shapes change under a transformation.

Summary¶

• Cartopy allows for the georeferencing of Matplotlib Axes objects.
• Cartopy’s crs class supports a variety of map projections.
• Cartopy’s feature class allows for a variety of cartographic features to be overlaid on a georeferenced plot or subplot.

What’s Next?¶

In the next notebook, we will delve further into how one can transform data that is defined in one coordinate reference system (crs) so it displays properly on a map that uses a different crs.

Resources and References¶

1. Cartopy Documentation
2. Full list of projections in Cartopy
3. Maps with Cartopy (Ryan Abernathey)
4. Map Projections (GeoCAT)
5. NCAR xdev Cartopy Tutorial Video