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:
/etc/projmap/projmap_settings.toml~/.config/projmap/projmap_settings.toml./projmap_settings.toml(current directory)- 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
- Cartopy >= 0.25
- Matplotlib >= 3.10
- NumPy >= 2.4
- Dynaconf >= 3.2
- matplotlib-scalebar >= 0.9
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.