Elements

Map elements other than layers: chrome, cartouches, zoom window, tooltips and gradients. They are added to a map with + or mappyng.Map.add(), like layers.

Chrome

class mappyng.Title(text, *, subtitle=<unset>, loc=<unset>, max_chars=<unset>, subtitle_max_chars=<unset>, font_size=<unset>, fill=<unset>, font_weight=<unset>, font_family=<unset>, subtitle_font_size=<unset>, subtitle_color=<unset>, subtitle_font_weight=<unset>, top_gap=<unset>, position=<unset>, offset_x=<unset>, offset_y=<unset>)

Bases: _Chrome

Map title, drawn above the map content.

Parameters:

• text (str) – Title text. Wrapped onto several lines past max_chars.

• subtitle (str, optional) – Subtitle drawn below the title in a lighter style.

• loc (str, optional) – Horizontal alignment: "left" (default), "center" or "right".

• max_chars (int, optional) – Maximum characters per line of the title before wrapping.

• subtitle_max_chars (int, optional) – Maximum characters per line of the subtitle. If omitted, derived from max_chars scaled by the title/subtitle font-size ratio.

• font_size (float, optional) – Title font size in points (default from style).

• fill (str, optional) – Title color as #RRGGBB (default from style).

• font_weight (str, optional) – Title font weight, e.g. "bold" (default from style).

• font_family (str, optional) – Title font family (default from style).

• subtitle_font_size (float, optional) – Subtitle font size (default derived from font_size).

• subtitle_color (str, optional) – Subtitle color as #RRGGBB (default: same as fill).

• subtitle_font_weight (str, optional) – Subtitle font weight (default "normal").

• top_gap (float, optional) – Vertical gap in pixels between the title baseline and the top of the map content. Default 8.

• position (tuple or dict, optional) – Place the title anywhere instead of above the map. The point is the baseline of the last line, aligned according to loc. Same forms as the scale bar position (fractions, percentages, pixels, geographic coordinates).

• offset_x (float, optional) – Extra horizontal shift in pixels (positive = right). Default 0.

• offset_y (float, optional) – Extra vertical shift in pixels (positive = down). Default 0.

Examples

>>> m = m + Title("Population", subtitle="2024", loc="center")

__init__(text, *, subtitle=<unset>, loc=<unset>, max_chars=<unset>, subtitle_max_chars=<unset>, font_size=<unset>, fill=<unset>, font_weight=<unset>, font_family=<unset>, subtitle_font_size=<unset>, subtitle_color=<unset>, subtitle_font_weight=<unset>, top_gap=<unset>, position=<unset>, offset_x=<unset>, offset_y=<unset>)

name = 'title'

class mappyng.Source(text, *, layout=<unset>, position=<unset>, rotation=<unset>, font_size=<unset>, color=<unset>, opacity=<unset>, font_style=<unset>, font_weight=<unset>, font_family=<unset>, text_anchor=<unset>)

Bases: _Chrome

Source or credit line.

Parameters:

• text (str) – Source text, rendered in italic by default. Use "\n" to split it into several lines.

• layout (str, optional) – "vertical" (default), rotated 90 degrees at the right edge, or "horizontal" at the bottom-right of the map.

• position (tuple or dict, optional) – Manual placement of the start of the text, overriding layout. Fractions (x, y) / {"x": 0.5, "y": 0.9} or percentages ({"x": "50%", "y": "90%"}) of the map content area, pixels ({"px": 120, "py": 80}), or geographic coordinates ({"geo": (x, y)} in the map CRS, {"lon": 4.2, "lat": 42.6} in WGS 84). See mappyng.position.

• rotation (float, optional) – Explicit rotation in degrees. Used only when position is unset.

• font_size (float, optional) – Font size in points (default from style).

• color (str, optional) – Text color as #RRGGBB (default from style).

• opacity (float, optional) – Text opacity in [0, 1] (default from style).

• font_style (str, optional) – CSS font style (default "italic").

• font_weight (str, optional) – CSS font weight (default "normal").

• font_family (str, optional) – Font family (default from style).

• text_anchor (str, optional) – SVG text anchor: "start", "middle" or "end".

Examples

>>> m = m + Source("Source : INSEE", layout="horizontal")

__init__(text, *, layout=<unset>, position=<unset>, rotation=<unset>, font_size=<unset>, color=<unset>, opacity=<unset>, font_style=<unset>, font_weight=<unset>, font_family=<unset>, text_anchor=<unset>)

name = 'source'

class mappyng.ScaleBar(*, length=<unset>, label=<unset>, unit=<unset>, unit_factor=<unset>, location=<unset>, position=<unset>, color=<unset>, bar_color=<unset>, tick_color=<unset>, label_color=<unset>, font_size=<unset>, font_weight=<unset>, font_family=<unset>, bar_height=<unset>, tick_height=<unset>, tick_width=<unset>, margin=<unset>, opacity=<unset>)

Bases: _Chrome

Scale bar.

Parameters:

• length (float, optional) – Bar length in map CRS units, e.g. metres. If omitted, a round value near 20 percent of the map width is chosen.

• label (str, optional) – Text above the bar. Generated from length if omitted. Pass "" to hide it.

• unit (str, optional) – Display unit for generated labels (default "km").

• unit_factor (float, optional) – Divisor from CRS units to display units (default 1000).

• location (str, optional) – Preset corner: "lower right", "lower left", "upper right" or "upper left".

• position (tuple or dict, optional) – Manual placement of the left end of the bar, overriding location. Fractions (x, y) / {"x": 0.5, "y": 0.9} or percentages ({"x": "50%", "y": "90%"}) of the map content area, pixels ({"px": 120, "py": 80}), or geographic coordinates ({"geo": (x, y)} in the map CRS, {"lon": 4.2, "lat": 42.6} in WGS 84). See mappyng.position.

• color (str, optional) – Color of bar, ticks and label (default from style).

• bar_color, tick_color, label_color (str, optional) – Per-part colors (override color).

• font_size (float, optional) – Label font size (default 8).

• font_weight (str, optional) – Label font weight (default "normal").

• font_family (str, optional) – Label font family (default sans-serif).

• bar_height (float, optional) – Bar thickness in pixels (default 3).

• tick_height (float, optional) – Tick height in pixels (default bar_height + 3).

• tick_width (float, optional) – Tick stroke width (default 1).

• margin (float, optional) – Distance from the content edge in pixels (default 15).

• opacity (float, optional) – Opacity in [0, 1] (default 1).

Examples

>>> m = m + ScaleBar(length=100_000, position=(0.46, 0.9))

__init__(*, length=<unset>, label=<unset>, unit=<unset>, unit_factor=<unset>, location=<unset>, position=<unset>, color=<unset>, bar_color=<unset>, tick_color=<unset>, label_color=<unset>, font_size=<unset>, font_weight=<unset>, font_family=<unset>, bar_height=<unset>, tick_height=<unset>, tick_width=<unset>, margin=<unset>, opacity=<unset>)

name = 'scale_bar'

class mappyng.NorthArrow(*, location=<unset>, position=<unset>, size=<unset>, color=<unset>, margin=<unset>, label=<unset>, font_size=<unset>, stroke_width=<unset>, rotation=<unset>)

Bases: _Chrome

North arrow.

By convention the top of the map is north, so a north arrow is only needed to lift an ambiguity.

Parameters:

• location (str, optional) – Preset corner: "upper right" (default), "upper left", "lower right" or "lower left".

• position (tuple or dict, optional) – Manual placement of the left end of the bar, overriding location. Fractions (x, y) / {"x": 0.5, "y": 0.9} or percentages ({"x": "50%", "y": "90%"}) of the map content area, pixels ({"px": 120, "py": 80}), or geographic coordinates ({"geo": (x, y)} in the map CRS, {"lon": 4.2, "lat": 42.6} in WGS 84). See mappyng.position.

• size (float, optional) – Arrow height in pixels (default 24).

• color (str, optional) – Color of shaft, arrowhead and label.

• margin (float, optional) – Distance from the content edge in pixels (default 15).

• label (str, optional) – Text above the arrow (default "N"; "" hides it).

• font_size (float, optional) – Label font size (default 9).

• stroke_width (float, optional) – Shaft stroke width (default 1).

• rotation (float, optional) – Rotation in degrees (default 0, points up).

Examples

>>> m = m + NorthArrow(location="lower left")

__init__(*, location=<unset>, position=<unset>, size=<unset>, color=<unset>, margin=<unset>, label=<unset>, font_size=<unset>, stroke_width=<unset>, rotation=<unset>)

name = 'north_arrow'

Legend

class mappyng.Legend(title=None, **options)

Bases: object

Legend settings of a thematic layer.

Passed as the legend parameter of a layer. The accepted options depend on the layer type (see ChoroplethLegendConfig, ProportionalLegendConfig and SituationLegendConfig).

Parameters:

• title (str, optional) – Legend title.

• **options (Any) – Other legend options, e.g. orientation, decimals, nodata_label, position.

Examples

>>> Choropleth(gdf, column="rate",
...            legend=Legend("Rate", orientation="horizontal"))

__init__(title=None, **options)

options: dict[str, Any]

to_dict()

Return the options as a plain dict.

Return type:

dict[str, Any]

Cartouches and zoom

class mappyng.Insets(insets, *, spacing=None, **defaults)

Bases: Element

Group of cartouches, stacked on the left of the main map.

Data layers are drawn in the cartouches by default; pass on_cartouches=False to a layer to keep it off them.

Parameters:

• insets (list of Inset) – The cartouches, top to bottom.

• spacing (float, optional) – Vertical spacing between cartouches in pixels.

• **defaults (Any) – Options applied to every inset that does not set them: title_size, size, border_color, border_width, border_radius, box_shadow, glow.

Examples

>>> insets = Insets([
...     Inset("Guadeloupe", bbox=[-6890454, 1780151, -6799589, 1874186],
...           crs=3857),
...     Inset("Martinique", bbox=[-6826862, 1609607, -6759494, 1685367],
...           crs=3857),
... ], spacing=15, border_radius=6, box_shadow=True)

__init__(insets, *, spacing=None, **defaults)

insets: list[Inset]

to_params()

Return the cartouches as the cartouche_params mapping.

Return type:

dict[int, dict[str, Any]]

class mappyng.Inset(title=<unset>, *, bbox, crs, title_size=<unset>, size=<unset>, spacing=<unset>, border_color=<unset>, border_width=<unset>, border_radius=<unset>, box_shadow=<unset>, glow=<unset>)

Bases: object

One cartouche: a small map of a separate area.

Parameters:

• title (str, optional) – Title drawn above the cartouche.

• bbox (list of float) – Area shown, [minx, miny, maxx, maxy] in crs.

• crs (int or str) – CRS of bbox; the cartouche is drawn in this CRS.

• title_size (float, optional) – Title font size.

• size (float, optional) – Scale factor of the cartouche (default 1).

• spacing (float, optional) – Space above this cartouche in pixels.

• border_color (str, optional) – Border color.

• border_width (float, optional) – Border width.

• border_radius (float, optional) – Corner radius in pixels.

• box_shadow (bool or dict, optional) – Drop shadow behind the cartouche.

• glow (bool or dict, optional) – Outer glow.

__init__(title=<unset>, *, bbox, crs, title_size=<unset>, size=<unset>, spacing=<unset>, border_color=<unset>, border_width=<unset>, border_radius=<unset>, box_shadow=<unset>, glow=<unset>)

options: dict[str, Any]

to_params(defaults=None)

Return the cartouche parameters, defaults filling the gaps.

Return type:

dict[str, Any]

class mappyng.Zoom(bbox, *, x=<unset>, y=<unset>, width=<unset>, height=<unset>, border_color=<unset>, border_width=<unset>, border_radius=<unset>, box_shadow=<unset>, glow=<unset>)

Bases: Element

Zoom window showing a magnified area inside the main map.

Layers with on_zoom=True (the default for thematic layers) are redrawn in the window.

Parameters:

• bbox (list of float) – Area shown, [minx, miny, maxx, maxy] in the map CRS.

• x, y (float, optional) – Top-left corner of the window in pixels.

• width, height (float, optional) – Window size in pixels.

• border_color (str, optional) – Border color.

• border_width (float, optional) – Border width.

• border_radius (float, optional) – Corner radius in pixels.

• box_shadow (bool or dict, optional) – Drop shadow behind the window.

• glow (bool or dict, optional) – Outer glow.

Examples

>>> m = m + Zoom([634000, 6841000, 674000, 6882000],
...              x=705, y=160, width=128, height=140)

__init__(bbox, *, x=<unset>, y=<unset>, width=<unset>, height=<unset>, border_color=<unset>, border_width=<unset>, border_radius=<unset>, box_shadow=<unset>, glow=<unset>)

params: dict[str, Any]

Interactive export

class mappyng.Tooltip(columns=None, *, aliases=None, style=None, hover_opacity=None)

Bases: Element

Hover tooltips of the interactive export.

Used by Map.to_interactive() and by Map.render() with a .html path.

Parameters:

• columns (list of str, optional) – Columns shown in the tooltip. Detected automatically if omitted.

• aliases (dict, optional) – Display names of the columns.

• style (dict or TooltipStyle, optional) – Tooltip appearance (see TooltipStyle).

• hover_opacity (float, optional) – Opacity of the hovered feature.

Examples

>>> m = m + Tooltip(["LIB_GEO", "rate"], aliases={"LIB_GEO": "Name"})

__init__(columns=None, *, aliases=None, style=None, hover_opacity=None)

to_kwargs()

Return the matching Map.to_interactive() arguments.

Return type:

dict[str, Any]

Gradients

class mappyng.RadialGradient(stops, *, gradient_id=None, cx=0.5, cy=0.5, r=0.5, fx=None, fy=None, units='objectBoundingBox', spread='pad')

Bases: Element

Radial gradient usable as a fill.

The gradient must be added to the map; layers reference it through url. Offsetting the focal point (fx, fy) from the centre fakes a highlight, turning a flat disc into a lit sphere.

Parameters:

• stops (list of tuple) – Colour stops from centre to edge: (offset, color) or (offset, color, opacity), offset in [0, 1].

• gradient_id (str, optional) – Element id. Derived from the parameters if omitted.

• cx, cy (float, default 0.5) – Centre of the gradient.

• r (float, default 0.5) – Radius of the gradient.

• fx, fy (float, optional) – Focal point. Defaults to (cx, cy).

• units (str, default "objectBoundingBox") – "objectBoundingBox" or "userSpaceOnUse".

• spread (str, default "pad") – "pad", "reflect" or "repeat".

Examples

>>> ocean = RadialGradient([(0.0, "#bfe6ff"), (1.0, "#0b3a57")],
...                        fx=0.35, fy=0.35)
>>> m = m + ocean + Vector(disc, fill=ocean.url)

__init__(stops, *, gradient_id=None, cx=0.5, cy=0.5, r=0.5, fx=None, fy=None, units='objectBoundingBox', spread='pad')

params: dict[str, Any]

property url: str

Fill reference, "url(#<id>)".