Quickstart

mappyng produces self-contained SVG maps from GeoDataFrame objects. No display server or GUI is required, output is a plain .svg file or a standalone HTML file.

A map is composed by adding layer objects with add() and configuring the chrome (title, source, scale bar, north arrow):

from mappyng import Map, BasemapLayer
from mappyng.data import load_france_departments

gdf = load_france_departments()

m = Map(gdf, width=800, height="auto", facecolor="#B9D9EB")
m.add(BasemapLayer())
m.title("Départements français")
m.scale_bar()
m.source("Source : IGN")
m.render("france.svg")

width="auto" / height="auto" size the canvas to the data aspect ratio so the map is not letterboxed; autosize() recomputes it on demand.

Map constructor parameters

Parameter	Default	Description
gdf	required	Base GeoDataFrame, defines extent and basemap geometry.
bbox	None	[minx, miny, maxx, maxy]. Computed from gdf if omitted.
width	800	SVG document width in pixels, or "auto" to derive it from the data aspect ratio.
height	600	SVG document height in pixels, or "auto" (recommended) to derive it from the data so the map is not letterboxed.
padding	10	Document-level padding in pixels.
style	"classic"	Preset name ("classic", "modern") or override dict ({"base": "classic", "title_color": "#333"}).
facecolor	None	Ocean / background color drawn inside each viewport.
background	None	Document background color (default white).
basemap_color	None	Override fill color for basemap polygons.
border_radius	4	Corner radius of the main map viewport (SVG px, 0 = sharp).
box_shadow	None	Drop shadow on the main map: True (defaults), False, or dict (keys: dx, dy, blur, color, opacity).
glow	None	Outer glow on the main map: same format as box_shadow.
cartouche_params	None	Inset map definitions. Dict keyed by integer index, each value a dict with required bbox and crs, and optional cartouche_title, size, spacing, border_radius, box_shadow, glow.
cartouche_spacing	None	Global vertical spacing between cartouches (SVG px).
font_scale	"auto"	Global font size multiplier. "auto" (default) scales to the document area; pass a float to override.

Output methods

Method	Description
m.render("map.svg")	Render to a file; format inferred from the extension (.svg native, .png / .pdf via the export extra). Returns self.
m.to_string()	Return SVG markup as a string.
m.to_interactive(...)	Return InteractiveMap with hover tooltips.
m.save_interactive("map.html")	Save as standalone HTML file.
m.to_yaml("map.yaml")	Serialise the map’s intent (layers + chrome) to YAML.
Map.from_yaml("map.yaml", gdf=gdf)	Rebuild a map from YAML, reattaching the supplied geometry.
Map.from_yaml("map.yaml")	Build from a YAML that declares its own data: sources, no geometry argument needed.
python -m mappyng map.yaml -o map.svg	Render a source-bearing YAML to a file from the shell (.svg / .png / .pdf / .html).

Note

m.save(...) is a deprecated alias of m.render(...) and emits a DeprecationWarning. Use render in new code.

Building a map from YAML

A map serialises to a YAML document that captures the configuration, the ordered layers with every parameter, and the chrome. An exported map references its geometry (pass it back with gdf=), but a hand-written document can declare where its data comes from and then build with no Python:

mappyng: 1
map: {width: 820, height: auto}
layers:
- type: ChoroplethLayer
  data:
    dataset: france_departments   # a built-in dataset (or path: file.geojson)
    crs: 2154                       # optional reprojection
    filter: COD_GEO.str.len() == 2  # optional pandas query
    join:                           # optional CSV attribute join
      path: deaths.csv
      left_on: COD_GEO
      right_on: code_dep
  params: {column: rate, cmap: RdBu, method: StdMean, num_classes: 7}
chrome:
  title: {text: Mortality}

python -m mappyng map.yaml -o map.svg      # also .png, .pdf, .html

Warning

Loading a YAML executes its declared sources (file reads and the pandas filter expression), so only build documents you trust.

Style customization

# Use a preset
m = Map(gdf, style="modern")

# Override specific values
m = Map(gdf, style={"base": "classic", "title_color": "#1a1a2e",
                     "basemap_fill": "#f5f5f5"})

# Register a custom style for reuse
from mappyng.config import ConfigManager
ConfigManager.add_style("my_style", {
    "base": "classic",
    "title_color": "#1a1a2e",
    "basemap_fill": "#e8e8e8",
    "basemap_edge_color": "#999999",
})
m = Map(gdf, style="my_style")