add_scalebar

Maps.add_scalebar(m, preset=None, scale=None, n=10, autoscale_fraction=0.1, auto_position=(0.75, 0.25), size_factor=1, scale_props=None, patch_props=None, label_props=None, line_props=None, layer=None)

Add a scalebar to the map.

The scalebar represents a ruler in units of meters whose direction follows geodesic lines.

Note

You can click on the scalebar to dynamically adjust its position, orientation and size!

Use ` .print_code()` to print the command that will reproduce the current appearance of the scalebar to the console.

  • LEFT-CLICK on the scalebar to make the scalebar interactive

  • drag the scalebar with the <LEFT MOUSE BUTTON>

  • use the SCROLL WHEEL to adjust the (auto-)scale of the scalebar (hold < shift > to make bigger steps)

  • use < control > + SCROLL WHEEL to adjust the size of the labels

Keyboard-shortcuts (only active if a scalebar is selected):

  • use < + > and < - > to rotate the scalebar

  • use the < arrow-keys > to increase the frame size

  • use < alt > + < arrow-keys > to decrease the frame size

  • use < control > + < left > and < right > keys to adjust the label-offset

  • use < control > + < up > and < down > keys to rotate the labels

  • use < delete > to remove the scalebar from the plot

  • use the < escape > to exit editing the scalebar

Parameters:

  • pos ((float, float)) – The longitude and latitude of the starting point for the scalebar (If None, the center of the axis is used )

  • rotation (float) – The azimuth-direction (in degrees) in which the scalebar points. The default is 90.

  • preset (str) –

    The name of the style preset to use.

    • ”bw” : a black and white scalebar with no background color

    • ”bw_2” : a black and white scalebar with white background

    • ”kr” : a black and red scalebar with semi-transparent white background

  • scale (float or None, optional) –

    The distance of the segments of the scalebar.

    • If None: the scale is automatically updated based on the current zoom level and the provided “autoscale_fraction”.

    • If float: A fixed length of the segments (in meters). (e.g. the total length of the scalebar will be n * scale

    The default is None.

  • n (int, optional) – The number of segments to use. The default is 10.

  • autoscale_fraction (float, optional) – The (approximate) fraction of the axis width to use as size for the scalebar in the autoscale procedure. Note that this is number is not exact since (depending on the crs) the final scalebar might be curved. The default is 0.25.

  • auto_position (tuple or False, optional) –

    Re-position the scalebar automatically on pan/zoom events.

    • If False: the position of the scalebar remains fixed.

    • If a tuple is provided, it is identified as relative (x, y) position on the axes (e.g. (0,0)=lower left, (1,1)=upper right )

    The default is (0.75, 0.25).

  • size_factor (float, optional) – A factor that is used to adjust the relative size of the labels. The default is 1

  • scale_props (dict, optional) –

    A dictionary that is used to set the properties of the scale.

    • ”n”: (int) The number of scales (e.g. line-segments) to draw.

    • ”width”: (float) The width of the scalebar

    • ”colors” (tuple): A sequence of colors that will be repeated to color the individual line-fragments of the scalebar. (you can provide more than 2 colors!) The default is (“k”, “w”).

    The default is:
    >>> dict(n=10, width=5, colors=("k", "w"))

  • patch_props (dict, optional) –

    A dictionary that is used to set the properties of the frame-patch.

    • ”offsets”: A tuple that is used to adjust the offset of the frame-patch. Individual values represent (top, bottom, left, right) on a horizontally oriented scalebar. The default is (1, 1, 1, 1).

    • … additional kwargs are passed to the PolygonPatch used to draw the frame. Possible values are:

    • ”facecolor”, “edgecolor”, “linewidth”, “linestyle”, “alpha” …

    The default is:
    >>> dict(fc=".75", ec="k", lw=1)

  • label_props (dict, optional) –

    A dictionary that is used to set the properties of the labels.

    • ”scale”: A scaling factor for the fontsize

    • ”offset” : A scaling factor to adjust the offset of the labels relative to the scalebar

    • ”rotation” : the rotation angle of the labels (in degrees) relative to the curvature of the scalebar

    • ”color” : The color of the text

    • ”every” : indicator which sections should be labelled If an integer is provided, every nth section is labelled, If a list or tuple is provided, it is used to label the selected sections.

    • … additional kwargs are passed to matplotlib.font_manager.FontProperties to set the used font-properties. Possible values are:

      • ”family”, “style”, “variant”, “stretch”, and “weight”

      for example: {family=”Helvetica”, style=”italic”}

    The default is:
    >>> dict(scale=1, offset=1, rotation=0, every=2)

  • line_props (dict, optional) –

    A dictionary that is used to set the properties of the text-indicator lines. (e.g. the lines between the scale and the labels)

    All arguments are passed to the LineCollection used to draw the lines. Possible values are:

    • ”edgecolor” (or “ec”), “linewidth” (or “lw”), “linestyle” (or “ls”) …

  • layer (str, optional) – The layer at which the scalebar should be visible. If None, the layer of the Maps-object used to create the scalebar is used. The default is None.

  • pickable (bool, optional) – If True, the scalebar can be interactively adjusted using the mouse and keyboard-shortcuts. If False, the scalebar is non-interactive. The default is True