or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

coordinate-systems.mddata-io.mdgeodesic.mdgeographic-features.mdindex.mdmatplotlib-integration.mdtransformations.md
tile.json

tessl/pypi-cartopy

A Python package designed to make drawing maps for data analysis and visualisation easy

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/cartopy@0.25.x

To install, run

npx @tessl/cli install tessl/pypi-cartopy@0.25.0

index.mddocs/

Cartopy

A comprehensive Python library for cartographic visualizations with Matplotlib. Cartopy provides object-oriented projection definitions, coordinate transformations, and seamless integration with Matplotlib for advanced mapping capabilities through an intuitive interface.

Package Information

  • Package Name: cartopy
  • Language: Python
  • Installation: pip install cartopy
  • Version Access: import cartopy; print(cartopy.__version__)

Core Imports

import cartopy

Common imports for working with projections and features:

import cartopy.crs as ccrs
import cartopy.feature as cfeature

For matplotlib integration:

import matplotlib.pyplot as plt
# GeoAxes are created via projection parameter

Basic Usage

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

# Create a figure with a GeoAxes subplot using PlateCarree projection
fig = plt.figure(figsize=(12, 8))
ax = plt.axes(projection=ccrs.PlateCarree())

# Add map features
ax.add_feature(cfeature.LAND)
ax.add_feature(cfeature.OCEAN)
ax.add_feature(cfeature.COASTLINE)
ax.add_feature(cfeature.BORDERS, linestyle=':')

# Set global extent
ax.set_global()

# Add gridlines
ax.gridlines(draw_labels=True)

plt.title('Basic World Map')
plt.show()

Architecture

Cartopy's design is built around several key components:

  • Coordinate Reference Systems (CRS): Define map projections and coordinate transformations
  • Features: Geographic data sources for map elements (coastlines, borders, etc.)
  • Matplotlib Integration: GeoAxes extends matplotlib with cartographic projection support
  • IO System: Handles data retrieval from various sources (Natural Earth, GSHHS, web services)

This architecture enables cartopy to serve as the primary cartographic library for Python scientific computing, providing robust support for geospatial data visualization, meteorological applications, and scientific mapping workflows.

Capabilities

Coordinate Reference Systems

Complete collection of map projections including cylindrical, conic, azimuthal, and pseudocylindrical projections. Provides coordinate transformations between different reference systems and supports custom projections.

class CRS:
    def transform_point(self, x, y, src_crs): ...
    def transform_points(self, src_crs, x, y, z=None): ...

class PlateCarree(CRS): ...
class Mercator(CRS): ...
class LambertConformal(CRS): ...
class Orthographic(CRS): ...
class Stereographic(CRS): ...

Coordinate Reference Systems

Geographic Features

Ready-to-use geographic features from Natural Earth and GSHHS datasets. Includes coastlines, country borders, land/ocean polygons, rivers, and lakes with automatic scaling based on map extent.

class Feature:
    def geometries(self): ...
    def intersecting_geometries(self, extent): ...

class NaturalEarthFeature(Feature): ...
class GSHHSFeature(Feature): ...
class ShapelyFeature(Feature): ...

# Pre-defined features
LAND: NaturalEarthFeature
OCEAN: NaturalEarthFeature  
COASTLINE: NaturalEarthFeature
BORDERS: NaturalEarthFeature

Geographic Features

Data Input/Output

Access to various geospatial data sources including web tile services, elevation data, and shapefile readers. Supports caching and automatic data downloading.

class Downloader:
    def path(self, format_dict): ...
    def acquire_resource(self, target_path, format_dict): ...

def natural_earth(resolution='110m', category='physical', name='coastline'): ...
def gshhs(scale='c', level=1): ...

class OSM: ...
class GoogleTiles: ...
class SRTM3Source: ...

Data Input/Output

Matplotlib Integration

Enhanced matplotlib axes with cartographic projection support. Provides specialized plotting functions, coordinate transformations, and gridline management for geographic data visualization.

class GeoAxes:
    def set_global(self): ...
    def set_extent(self, extents, crs=None): ...
    def add_feature(self, feature, **kwargs): ...
    def coastlines(self, resolution=None, **kwargs): ...
    def gridlines(self, **kwargs): ...
    def stock_img(self): ...

class Gridliner:
    def xlabel_style: dict
    def ylabel_style: dict

Matplotlib Integration

Image and Vector Transformations

Functions for transforming raster images and vector data between different coordinate systems. Includes regridding, warping, and mesh generation capabilities.

def warp_array(array, target_proj, source_proj=None, target_res=(400, 200), **kwargs): ...
def warp_img(fname, target_proj, source_proj=None, target_res=(400, 200)): ...
def vector_scalar_to_grid(src_crs, target_proj, regrid_shape, x, y, u, v, *scalars, **kwargs): ...
def add_cyclic_point(data, coord=None, axis=-1): ...

Transformations

Geodesic Calculations

Great circle computations, distance calculations, and geodesic operations on ellipsoidal Earth models. Essential for navigation, surveying, and geographic analysis.

class Geodesic:
    def __init__(self, radius=6378137.0, flattening=1/298.257223563): ...
    def direct(self, points, azimuths, distances): ...
    def inverse(self, points, endpoints): ...
    def circle(self, lon, lat, radius, n_samples=180): ...
    def geometry_length(self, geometry): ...

Geodesic Calculations

Configuration

config: dict  # Global configuration dictionary with keys:
# - 'data_dir': Directory for downloaded data
# - 'cache_dir': Directory for cached tiles  
# - 'pre_existing_data_dir': Directory for existing data
# - 'downloaders': Dictionary of data downloaders

Types

from typing import Tuple, Optional, Union, List
import numpy as np
from shapely.geometry import Polygon, MultiPolygon

Extent = Tuple[float, float, float, float]  # (x0, x1, y0, y1)
Resolution = Tuple[int, int]  # (width, height)
ArrayLike = Union[np.ndarray, List]
GeometryLike = Union[Polygon, MultiPolygon]