Skip to main content

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

Getting started with a settings file

Run this once in your project directory to create a skeleton projmap_settings.toml:

projmap.init()

This creates a projmap_settings.toml with the default, nwa, korea, and antarctic regions as a starting point. To overwrite an existing file, pass overwrite=True.

Settings file format

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

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

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

[myregion]
description = "My custom region"
lat1 = 48.0
lat2 = 62.0
lon1 = -10.0
lon2 = 20.0
projection = "lcc"      # Lambert Conformal Conic

[myregion.style]
oceancolor = "0.15"
landface = "0.6"
landresolution = "10m"  # Natural Earth resolution: 10m, 50m, 110m

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

Listing and inspecting regions

projmap.show_regions()       # list all available regions across all settings files
projmap.show_region("nwa")   # show all settings for a specific region

Projection parameters can also be passed directly to the constructor to override or extend a region:

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 projmap_settings.toml:

[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 projmap_settings.toml:

[[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)
init(path, overwrite) Create a skeleton projmap_settings.toml in the current directory
show_regions() List all available regions
show_region(region) Print all settings for a specific region

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

Dependencies

License

See LICENSE for details.

Metadata

Release files for projmap 2.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for projmap 2.0.5
File Size Uploaded Provenance Actions
projmap-2.0.5.tar.gz 1.8 MB Without provenance Details for projmap-2.0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for projmap 2.0.5
File Interpreter ABI Platform Actions
projmap-2.0.5-py3-none-any.whl Python 3 none any Details for projmap-2.0.5-py3-none-any.whl

Total release size: 1.9 MB

Release files / projmap-2.0.5.tar.gz

Download URL projmap-2.0.5.tar.gz
Size 1.8 MB
Tags Source
SHA-256 checksum
How to use checksums
a15c46c3d54feb0d547f5c584c9ac799097173d94b36648d8fef92ba2e70a118
BLAKE2b-256 checksum
How to use checksums
deff07da74d25b2fb7aee3f926e93a2dfeaf4e7870bd2b7fba5f8c65a5cc6b4a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / projmap-2.0.5-py3-none-any.whl

Download URL projmap-2.0.5-py3-none-any.whl
Size 47.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1c541aaa5fc4eb6e02846368042d31fc772696374ab00ee881b4819663d98170
BLAKE2b-256 checksum
How to use checksums
7f414c5e9f4aad78a8b3c35fd5c01bd77e76d274d6873966779180388e9f557c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.10 {"installer":{"name":"uv","version":"0.10.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for projmap 2.0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page