Cartopy

Warnings

• breaking Python 2 support was removed in Cartopy v0.19. Users on older Python versions must upgrade to Python 3.7+ (v0.20) or 3.10+ (v0.25).
  Fix: Upgrade your Python environment to version 3.10 or newer.
• breaking The `Axes.natural_earth_shp()` method has been removed. Use `Axes.add_feature()` along with classes from the `cartopy.feature` module instead.
  Fix: Replace calls like `ax.natural_earth_shp('110m', 'coastline')` with `ax.add_feature(cfeature.COASTLINE)`. Check `cartopy.feature` for other available features.
• deprecated Gridliner label control attributes like `Gridliner.xlabels_top`, `xlabels_bottom`, `ylabels_left`, and `ylabels_right` are removed. They were deprecated in v0.18 and removed in v0.23.
  Fix: Use the replacement attributes: `Gridliner.top_labels`, `bottom_labels`, `left_labels`, or `right_labels`.
• breaking The `cartopy.mpl.clip_path` module is deprecated without replacement, and `path_to_geos`/`geos_to_path` are deprecated in favor of `path_to_shapely`/`shapely_to_path`. This affects low-level path manipulation.
  Fix: For path conversion, use `cartopy.mpl.path.path_to_shapely` and `cartopy.mpl.path.shapely_to_path`. If `clip_path` functionality is needed, consider vendoring it or finding alternative Matplotlib utilities.
• gotcha Installing Cartopy via `pip` can be challenging due to its complex external (GEOS, PROJ) and Python (Shapely, pyproj) dependencies, especially on Windows or when pre-built wheels are unavailable. Conda is often recommended for a smoother installation.
  Fix: If `pip install cartopy` fails, try `conda install -c conda-forge cartopy`. For pip, ensure development headers for GEOS and PROJ are installed on your system. Also, ensure `shapely>=2.0` for Cartopy v0.25+.
• gotcha From v0.20, Cartopy uses `pyproj` for transformations, which can sometimes be slower. An environment variable can improve performance.
  Fix: Set the environment variable `PYPROJ_GLOBAL_CONTEXT=ON` for faster projection calculations if thread safety is not a concern in your application.
• gotcha Internal function calls in Cartopy (e.g., for geometries) now prefer `(longitude, latitude)` ordering for consistency.
  Fix: When passing coordinate pairs to Cartopy functions, ensure they are in `(longitude, latitude)` order, not `(latitude, longitude)`.

Install

• pip install cartopy PyPI (pip)
• conda install -c conda-forge cartopy Conda (Recommended for dependency handling)

Imports

• crs

  import cartopy.crs as ccrs

  Common alias for Coordinate Reference Systems.
• feature

  import cartopy.feature as cfeature

  Common alias for adding geographical features like coastlines, borders.
• GeoAxes

  from cartopy.mpl.geoaxes import GeoAxes

  Specifically imports the GeoAxes class, often used for type hinting or specific Matplotlib manipulations.

Quickstart

This quickstart creates a basic global map using the Plate Carree projection, adding standard geographical features such as land, ocean, coastlines, country borders, lakes, and rivers. It demonstrates the typical import pattern and usage of `add_subplot` with a Cartopy projection and `add_feature` for geographical elements.

import matplotlib.pyplot as plt
import cartopy.crs as ccrs
import cartopy.feature as cfeature

fig = plt.figure(figsize=(10, 8))
ax = fig.add_subplot(1, 1, 1, projection=ccrs.PlateCarree())

ax.set_global()

# Add basic features
ax.add_feature(cfeature.LAND)
ax.add_feature(cfeature.OCEAN)
ax.add_feature(cfeature.COASTLINE)
ax.add_feature(cfeature.BORDERS, linestyle=':')
ax.add_feature(cfeature.LAKES, alpha=0.5)
ax.add_feature(cfeature.RIVERS)

plt.title('Basic Cartopy Map with Plate Carree Projection')
plt.show()