CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-cartopy

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

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

matplotlib-integration.mddocs/

Matplotlib Integration

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

Capabilities

GeoAxes

Enhanced matplotlib Axes subclass with geographic projection support and cartographic plotting methods.

class GeoAxes:
    """Matplotlib axes subclass for cartographic projections."""
    def __init__(self, fig, rect, projection, **kwargs): ...
    
    # Extent and boundaries
    def set_global(self): ...
    def set_extent(self, extents, crs=None): ...
    @property
    def extent(self): ...
    
    # Geographic features
    def add_feature(self, feature, **kwargs): ...
    def coastlines(self, resolution='auto', color='black', **kwargs): ...
    def stock_img(self): ...
    
    # Gridlines and labels
    def gridlines(self, crs=None, draw_labels=False, **kwargs): ...
    
    # Coordinate transformations
    def transform_point(self, x, y, src_crs): ...
    def transform_points(self, src_crs, x, y, z=None): ...
    
    # Plotting with transformations
    def plot(self, *args, transform=None, **kwargs): ...
    def scatter(self, x, y, transform=None, **kwargs): ...
    def contour(self, x, y, z, transform=None, **kwargs): ...
    def contourf(self, x, y, z, transform=None, **kwargs): ...
    def pcolormesh(self, x, y, z, transform=None, **kwargs): ...
    def quiver(self, x, y, u, v, transform=None, **kwargs): ...
    def streamplot(self, x, y, u, v, transform=None, **kwargs): ...
    def imshow(self, img, extent=None, transform=None, **kwargs): ...
    
    # Tissot's indicatrix
    def tissot(self, rad_km, lons, lats, n_samples=80, **kwargs): ...
    
    # Web map tiles
    def add_image(self, tile_source, level, **kwargs): ...
    def add_wmts(self, wmts, layer_name, **kwargs): ...
    def add_wms(self, wms, layers, **kwargs): ...
    def add_raster(self, raster_source, **kwargs): ...
    
    # Background and stock imagery
    def background_img(self, name='ne_shaded', resolution='low', extent=None, cache=False): ...
    def stock_img(self): ...
    
    # View and coordinate utilities
    def autoscale_view(self, tight=None, scalex=True, scaley=True): ...
    def format_coord(self, x, y): ...
    def get_tightbbox(self, renderer, call_axes_locator=True, bbox_extra_artists=None): ...

Gridlines and Labels

Sophisticated gridline and label management for geographic maps.

class Gridliner:
    """Grid line and label management for GeoAxes."""
    def __init__(self, axes, crs, draw_labels=False, **kwargs): ...
    
    # Style properties
    xlabel_style: dict  # X-axis label styling
    ylabel_style: dict  # Y-axis label styling
    xlines: bool        # Whether to draw longitude lines
    ylines: bool        # Whether to draw latitude lines
    xlabels_top: bool   # Top longitude labels
    xlabels_bottom: bool # Bottom longitude labels  
    ylabels_left: bool  # Left latitude labels
    ylabels_right: bool # Right latitude labels
    
    # Locators and formatters
    xlocator: Any       # Longitude tick locator
    ylocator: Any       # Latitude tick locator
    xformatter: Any     # Longitude label formatter
    yformatter: Any     # Latitude label formatter

class Label:
    """Individual grid label representation."""
    def __init__(self, x, y, text, **kwargs): ...
    @property
    def x(self): ...
    @property  
    def y(self): ...
    @property
    def text(self): ...

Coordinate Formatters and Locators

Specialized tick locators and formatters for geographic coordinates.

class LatitudeFormatter:
    """Format latitude tick labels with N/S indicators."""
    def __init__(self, degree_symbol='°', number_format='g', 
                 southern_hemisphere='S', northern_hemisphere='N'): ...
    def __call__(self, value, pos=None): ...

class LongitudeFormatter:
    """Format longitude tick labels with E/W indicators."""
    def __init__(self, degree_symbol='°', number_format='g',
                 eastern_hemisphere='E', western_hemisphere='W',
                 dateline_direction_label=False, zero_direction_label=False): ...
    def __call__(self, value, pos=None): ...

class LatitudeLocator:
    """Locate latitude tick positions."""
    def __init__(self, nbins='auto'): ...
    def tick_values(self, vmin, vmax): ...

class LongitudeLocator:
    """Locate longitude tick positions."""
    def __init__(self, nbins='auto'): ...  
    def tick_values(self, vmin, vmax): ...

Path and Geometry Utilities

Convert between matplotlib paths and shapely geometries.

def shapely_to_path(shape):
    """
    Convert shapely geometry to matplotlib path.
    
    Parameters:
    - shape: shapely geometry
    
    Returns:
    matplotlib.path.Path
    """

def path_to_shapely(path):
    """
    Convert matplotlib path to shapely geometry.
    
    Parameters:
    - path: matplotlib.path.Path
    
    Returns:
    shapely geometry
    """

def geos_to_path(shape):
    """
    Convert GEOS geometry to matplotlib path.
    
    Parameters:
    - shape: GEOS geometry
    
    Returns:
    matplotlib.path.Path
    """

Feature Artists

Specialized artists for rendering cartographic features.

class FeatureArtist:
    """Artist for rendering cartopy features."""
    def __init__(self, feature, **kwargs): ...
    def draw(self, renderer): ...
    
class SlippyImageArtist:
    """Artist for rendering slippy map tiles."""
    def __init__(self, tile_source, **kwargs): ...
    def draw(self, renderer): ...

Collections and Specialized Plots

Geographic-aware matplotlib collections and specialized plotting utilities.

class GeoQuadMesh:
    """Geographic quadrilateral mesh for pcolormesh plots."""
    def __init__(self, x, y, **kwargs): ...

class GeoContourSet:
    """Geographic contour set with projection awareness."""
    def __init__(self, ax, *args, **kwargs): ...

Usage Examples

Basic Map Creation

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

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

# Set up map
ax.set_global()
ax.add_feature(cfeature.LAND)
ax.add_feature(cfeature.OCEAN)
ax.coastlines()

# Add gridlines with labels
gl = ax.gridlines(draw_labels=True, dms=True, x_inline=False, y_inline=False)
gl.xlabel_style = {'size': 12, 'color': 'blue'}
gl.ylabel_style = {'size': 12, 'color': 'red'}

plt.title('World Map with Custom Gridlines')
plt.show()

Plotting Data with Transformations

import numpy as np
import matplotlib.pyplot as plt
import cartopy.crs as ccrs

# Sample data
lons = np.linspace(-180, 180, 360)
lats = np.linspace(-90, 90, 180)
lon_grid, lat_grid = np.meshgrid(lons, lats)
data = np.sin(np.radians(lat_grid)) * np.cos(np.radians(lon_grid))

# Plot with different projection
fig = plt.figure(figsize=(15, 10))

# PlateCarree data projection
ax1 = plt.subplot(2, 2, 1, projection=ccrs.PlateCarree())
ax1.contourf(lon_grid, lat_grid, data, transform=ccrs.PlateCarree())
ax1.coastlines()
ax1.set_title('PlateCarree Projection')

# Orthographic projection
ax2 = plt.subplot(2, 2, 2, projection=ccrs.Orthographic(-90, 45))
ax2.contourf(lon_grid, lat_grid, data, transform=ccrs.PlateCarree())
ax2.coastlines()
ax2.set_global()
ax2.set_title('Orthographic Projection')

plt.tight_layout()
plt.show()

Custom Gridline Formatting

import matplotlib.pyplot as plt
import cartopy.crs as ccrs
from cartopy.mpl.ticker import LongitudeFormatter, LatitudeFormatter

fig = plt.figure(figsize=(12, 8))
ax = plt.axes(projection=ccrs.PlateCarree())

# Add features
ax.coastlines()
ax.set_global()

# Custom gridlines with formatters
gl = ax.gridlines(draw_labels=True)
gl.xformatter = LongitudeFormatter(zero_direction_label=True)
gl.yformatter = LatitudeFormatter()
gl.xlabel_style = {'size': 10, 'rotation': 45}
gl.ylabel_style = {'size': 10}

plt.show()

Vector Field Plotting

import numpy as np
import matplotlib.pyplot as plt
import cartopy.crs as ccrs

# Create vector field data
lons = np.arange(-120, -60, 5)
lats = np.arange(25, 65, 5)
lon_grid, lat_grid = np.meshgrid(lons, lats)

# Sample wind field
u = 10 * np.sin(np.radians(lat_grid))
v = 5 * np.cos(np.radians(lon_grid))

fig = plt.figure(figsize=(12, 8))
ax = plt.axes(projection=ccrs.PlateCarree())

# Plot vector field
ax.quiver(lon_grid, lat_grid, u, v, transform=ccrs.PlateCarree(),
          regrid_shape=20, alpha=0.7)

# Add map features
ax.coastlines()
ax.add_feature(cfeature.BORDERS)
ax.set_extent([-125, -55, 20, 70])
ax.gridlines(draw_labels=True)

plt.title('Wind Vector Field')
plt.show()

Adding Web Map Tiles

import matplotlib.pyplot as plt
import cartopy.crs as ccrs
from cartopy.io import img_tiles

# Create map with OpenStreetMap tiles
fig = plt.figure(figsize=(12, 8))

# Use the same CRS as the tile source
osm_tiles = img_tiles.OSM()
ax = plt.axes(projection=osm_tiles.crs)

# Add tiles at zoom level 10
ax.add_image(osm_tiles, 10)

# Set extent for London
ax.set_extent([-0.2, 0.1, 51.4, 51.6])

# Add some data points
lons = [-0.1, 0.0, 0.05]
lats = [51.5, 51.52, 51.48]
ax.scatter(lons, lats, color='red', s=100, transform=ccrs.PlateCarree())

plt.title('London with OpenStreetMap Background')
plt.show()

Tissot's Indicatrix

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

# Show projection distortion with Tissot's indicatrix
fig, axes = plt.subplots(1, 2, figsize=(15, 6),
                        subplot_kw={'projection': ccrs.PlateCarree()})

projections = [ccrs.PlateCarree(), ccrs.Mercator()]
titles = ['PlateCarree', 'Mercator']

for ax, proj, title in zip(axes, projections, titles):
    ax = plt.axes(projection=proj)
    ax.coastlines()
    ax.set_global()
    
    # Add Tissot's indicatrix circles
    ax.tissot(rad_km=1000, lons=range(-180, 181, 30), 
              lats=range(-90, 91, 30), alpha=0.5)
    
    ax.set_title(f'{title} - Tissot Indicatrix')

plt.tight_layout()
plt.show()

Style Utilities

def merge(*style_dicts):
    """
    Merge matplotlib style dictionaries.
    
    Parameters:
    - *style_dicts: variable number of style dictionaries
    
    Returns:
    Merged style dictionary
    """

def finalize(style):
    """
    Finalize style dictionary for matplotlib use.
    
    Parameters:
    - style: dict, style parameters
    
    Returns:
    Finalized style dictionary
    """

Install with Tessl CLI

npx tessl i tessl/pypi-cartopy

docs

coordinate-systems.md

data-io.md

geodesic.md

geographic-features.md

index.md

matplotlib-integration.md

transformations.md

tile.json