projmap 2.0.0

Simplify the generation of maps using Cartopy

projmap

A Python package that simplifies the creation of geographic maps using Cartopy. Projmap handles projection setup, map styling, and common plotting tasks so you can focus on your data. Originally developed for oceanography but applicable to any domain.

Installation

pip install projmap

Quick start

import projmap

mp = projmap.Map("westcoast")
mp.nice()

nice() draws land, ocean background, and country borders in one call.

Configuration and regions

Maps are defined by regions stored in TOML configuration files. Projmap searches for settings in this order:

1. /etc/projmap/settings.toml
2. ~/.config/projmap/settings.toml
3. ./settings.toml (current directory)
4. Path in the environment variable PROJMAP_SETTINGS_FILE_FOR_DYNACONF

Each region is a TOML table with projection parameters and optional styling:

[default.regions.myregion]
lat1 = 48.0
lat2 = 62.0
lon1 = -10.0
lon2 = 20.0
projection = "lcc"      # Lambert Conformal Conic
style.oceancolor = "0.15"
style.landface = "0.6"

Supported projections: lcc (Lambert Conformal), merc (Mercator), eckert4 (Eckert IV), north_stereo, south_stereo, and Robinson (default).

List available regions:

projmap.show_regions()            # list all regions
projmap.show_regions("myregion")  # show settings for one region

Projection parameters can also be passed directly to the constructor:

mp = projmap.Map("default", lat1=48, lat2=62, lon1=-10, lon2=20)

Usage

Basic map

import projmap

mp = projmap.Map("myregion")
mp.nice()                          # land + ocean + borders
mp.nice(rivers=True, states=True)  # optionally add rivers and state borders

Plotting data

All plotting methods accept lon/lat arrays and pass extra keyword arguments through to the underlying Matplotlib/Cartopy call. A colorbar keyword can be added to any of them.

import numpy as np

# Filled contours
mp.contourf(lon, lat, data, levels=20, cmap="RdBu_r", colorbar=True)

# Contour lines with automatic labels on all levels
mp.contour(lon, lat, data, levels=[-1000, -500, -200, -100],
           colors="0.5", linewidths=0.5, clabel=True)

# Contour labels with custom options
mp.contour(lon, lat, data, levels=[-1000, -500, -200, -100],
           colors="0.4", clabel=dict(fontsize=6, fmt=" {:.0f} ".format))

# Pseudocolor
mp.pcolor(lon, lat, data, cmap="viridis", colorbar=True)

# Scatter plot
mp.scatter(lons, lats, c=values, s=10, cmap="plasma", colorbar=True)

# Line / track
mp.plot(lons, lats, color="red", linewidth=1)

# Vector field
mp.streamplot(u, v, lon=lon, lat=lat, color="white", density=1.5)

Multiple subplots

mp = projmap.Map("myregion")
axes = mp.subplots(nrows=1, ncols=2)

mp.pcolor(lon, lat, sst, ax=axes[0], cmap="RdYlBu_r")
mp.contourf(lon, lat, ssh, ax=axes[1], levels=20, cmap="viridis")

Annotations

mp.text(lon, lat, "Label", fontsize=8, color="white")
mp.rectangle(lon1=-5, lat1=50, lon2=10, lat2=58, edgecolor="red", linewidth=1)

Colorbars

mp.contourf(lon, lat, data, cmap="RdBu_r")
mp.colorbar()   # add colorbar after the fact

Tile imagery

import cartopy.io.img_tiles as cimgt

mp = projmap.Map("myregion")
mp.add_tiles(zoom=8)                                       # OpenStreetMap (default)
mp.add_tiles(zoom=10, tile_source=cimgt.Stamen("terrain"))

Styling

mp = projmap.Map("myregion")
mp.set_style(landfill="0.65", landedge="0.4")
mp.nice()

Style values can also be set permanently in your settings.toml:

[default.regions.myregion.style]
landface = "0.65"
landedge = "0.4"
oceancolor = "0.15"
landresolution = "10m"   # Natural Earth resolution: 10m, 50m, 110m

Named locations

Add labelled point markers to a region by defining them in settings.toml:

[[default.regions.myregion.locations]]
name = "Oslo"
lon = 10.75
lat = 59.91
color = "white"
ha = "left"    # horizontal alignment
va = "bottom"  # vertical alignment

They are drawn automatically by mp.nice() / mp.add_locations().

API reference

Method	Description
Map(region, **proj_kw)	Create a map for the given region
nice(borders, rivers, states)	Draw a complete base map
pcolor(lon, lat, data, **kw)	Pseudocolor plot
contourf(lon, lat, data, **kw)	Filled contour plot
contour(lon, lat, data, **kw)	Contour lines (supports clabel=True)
scatter(lons, lats, **kw)	Scatter plot
plot(lons, lats, **kw)	Line plot
streamplot(u, v, lon, lat, **kw)	Vector streamlines
hatch(lon, lat, mask, **kw)	Hatching over masked regions
text(lon, lat, s, **kw)	Text annotation
rectangle(lon1, lat1, lon2, lat2, **kw)	Projection-correct rectangle
colorbar(**kw)	Add horizontal colorbar
add_tiles(zoom, tile_source)	Add tile imagery
add_land(**kw)	Draw land features
subplots(nrows, ncols, **kw)	Create multi-panel figure
set_style(landfill, landedge)	Override map style
set_extent(**kw)	Set geographic extent
set_circle_boundary()	Circular boundary (polar projections)
show_regions(region)	List available regions

All plotting methods accept a colorbar=True keyword to add a colorbar, and pass remaining keyword arguments to the underlying Matplotlib/Cartopy function.

Dependencies

• Cartopy >= 0.25
• Matplotlib >= 3.10
• NumPy >= 2.4
• Dynaconf >= 3.2
• matplotlib-scalebar >= 0.9
• xarray >= 2026.2
• netCDF4 >= 1.7

License

See LICENSE for details.