azimlib 0.2.0

Independent cartography in Python, with a familiar plotting API.

Build maps from geographic data, compose scientific figures, and explore them in an interactive viewer. Azimlib owns its geometry, projections, coordinate transformations, map layers, layout and rendering. Matplotlib and other GIS engines are not runtime dependencies.

Getting started · API reference · Examples · Compatibility

The examples above use Azimlib's own renderer. Boundaries and rivers are from Natural Earth; thematic values, terrain and vectors are synthetic. See the reproducible showcase.

Install

Requires Python 3.10 or newer. Version 0.2.0 is being prepared for its first PyPI publication. Once available, choose the output you need:

python -m pip install azimlib           # SVG and portable HTML; no dependencies
python -m pip install "azimlib[png]"    # PNG export
python -m pip install "azimlib[gui]"    # Interactive desktop viewer + PNG

Until the PyPI release is available, install directly from the source:

git clone https://github.com/Kernerian/azimlib.git
cd azimlib
python -m pip install ".[gui]"

The desktop viewer requires Tk, normally included with official Windows and macOS Python installations; on Linux it may need an operating-system package. Pillow, aggdraw and NumPy provide low-level raster support. Optional azimlib[accelerate] uses NumPy/Numba to compile Azimlib's own coverage kernel. No external cartography library is required for any of these installations.

Your first map

Both import styles expose the familiar figure/axes workflow:

import azimlib as azl
# Or: import azimlib.pyplot as plt

fig, ax = azl.subplots(figsize=(8, 9), projection="mercator")
ax.map("brazil", facecolor="white", edgecolor="black", linewidth=0.8)
ax.states(edgecolor="#777777", linewidth=0.4)
ax.rivers(color="#237f96", linewidth=0.8, label="Rivers")
ax.scatter(
    lon=[-46.63, -43.17], lat=[-23.55, -22.90],
    s=[40, 60], c="#c34968", label="Cities",
)
ax.set_title("Brazil")
ax.set_xlabel("Longitude")
ax.set_ylabel("Latitude")
ax.legend()
ax.scale_bar()
ax.north_arrow()

fig.savefig("brazil.svg")        # Static export; no viewer controls
fig.savefig("brazil.png", dpi=200)
azl.show()                       # Interactive desktop viewer

Longitude and latitude are geographic coordinates. Use subplot_kw={"projection": "mercator"} if you prefer the Matplotlib-style subplot configuration. A GeoJSON path, dictionary or feature collection can be added with ax.geojson(data).

savefig() writes a static PNG or SVG. show() opens the independent desktop canvas with Home, Back, Forward, Pan, Zoom, Subplots, Save and cursor coordinates. A separate portable HTML viewer is available with fig.show(backend="browser", path="map.html"); it navigates an exported scene, without a live Python connection.

Add only the components you need

Grid, legend, colorbar, scale bar, north arrow, compass and overview map are optional. There is no default minimap or grid. North arrow and compass are separate components, and a legend has a title only when you provide one.

ax.grid(linestyle="--", linewidth=0.5)
scale = ax.scale_bar()
scale.set_visible(False)
scale.set_visible(True)
ax.compass()
ax.overview(context="brazil")
fig.canvas.draw_idle()

Artists expose editing, visibility and removal controls. You can set limits, change styles, edit labels and update scalar data while retaining the same figure. See components and Artist editing.

Thematic and scientific maps

import azimlib.pyplot as plt
from azimlib import datasets

data = datasets.load("states", country="brazil")
values = list(range(len(data["features"])))  # Synthetic example values

fig, ax = plt.subplots(projection="mercator")
layer = ax.choropleth(data, values, cmap="viridis", bins=None)
bar = fig.colorbar(layer, ax=ax, orientation="horizontal", label="Example value")
ax.set_title("Values by state")
layer.set_clim(0, 30)
bar.set_label("Updated example value")
fig.savefig("thematic.svg")

Lines support widths, opacity, dashes, caps, joins and arrows; polygons support per-feature styling and hatches. Text offers alignment, rotation, backgrounds and halos. Layout includes tight/constrained modes, physical sizing and editable ticks. Colorbars support horizontal/vertical placement, ticks, labels and norms.

The spherical projection implementations include equirectangular, Mercator, orthographic, Lambert conformal conic, Albers equal area and Equal Earth. An orthographic globe is a 2D projection, not a 3D terrain engine.

Learn more

• Tutorial and Matplotlib → Azimlib guide
• API reference
• Maps and components gallery
• Coordinate systems and datasets
• Architecture
• Roadmap and remaining work
• Changelog

Azimlib 0.2.0 is an early independent cartography library, not a complete replacement for every Matplotlib API. Read the compatibility boundaries before migrating. Detailed views can still require expensive rasterization. Urban data workflows, more file formats, 3D and temporal visualization are future work. Automated CI covers Windows, Linux and macOS; native human visual acceptance currently covers Windows.

Contribute and get help

Report bugs or ask questions through GitHub Issues. Include a minimal example, Python/Azimlib versions and the relevant output format. See the contribution guide for local tests, data provenance and independent implementation requirements. Please follow the code of conduct. Use the security policy for sensitive vulnerability reports.

License and provenance

Original code and visual compositions: BSD 3-Clause, copyright 2026 Kernerian. Bundled geographic data, fonts and palettes retain their own terms: Natural Earth is public domain; DejaVu fonts retain their license; Viridis, Plasma, Inferno and Magma tables are CC0; Blues retains ColorBrewer terms. The default AZIM10 color sequence is independently selected.

This product includes color specifications and designs developed by Cynthia Brewer (http://colorbrewer.org/).

See LICENSE, third-party notices and branding assets. The familiar API and navigation are implemented independently; Matplotlib artwork and source code are not distributed as Azimlib's implementation.