pygmt.Figure.scalebar

Figure.scalebar(position=None, length=None, height=None, scale_position=False, label=False, label_alignment=None, unit=False, fancy=False, vertical=False, box=False, verbose=False, panel=False, transparency=None, perspective=False)

Add a scale bar on the map.

Parameters:

  • position (Position | None, default: None) – Specify the location of the scale bar. See pygmt.params.Position for more details.

  • length (float | str | None, default: None) – Length of the scale bar in km. Append a suffix to specify different units. Valid units are: e: meters; f: feet; k: kilometers; M: statute mile; n: nautical miles; u: US Survey foot.

  • height (float | str | None, default: None) – Height of the scale bar. Only works when fancy=True. [Default is "5p"].

  • scale_position (float | Sequence[float] | bool, default: False) –

    Specify the location where on a geographic map the scale applies. It can be:

    • slat: Map scale is calculated for latitude slat

    • (slon, slat): Map scale is calculated for latitude slat and longitude slon, which is useful for oblique projections.

    • True: Map scale is calculated for the middle of the map.

    • False: Default to the location of the reference point.

  • label (str | bool, default: False) – Text string to use as the scale bar label. If False, no label is drawn. If True, the distance unit provided in the length parameter (default is km) is used as the label. This parameter requires fancy=True.

  • label_alignment (Literal['left', 'right', 'top', 'bottom'] | None, default: None) – Alignment of the scale bar label. Choose from "left", "right", "top", or "bottom". [Default is "top"].

  • fancy (bool, default: False) – If True, draw a “fancy” scale bar, which is a segmented bar with alternating black and white rectangles. If False, draw a plain scale bar.

  • unit (bool, default: False) – If True, append the unit to all distance annotations along the scale. For a plain scale, this will instead select the unit to be appended to the distance length. The unit is determined from the suffix in the length or defaults to "km".

  • vertical (bool, default: False) – If True, plot a vertical rather than a horizontal Cartesian scale.

  • box (Box | bool, default: False) – Draw a background box behind the directional rose. If set to True, a simple rectangular box is drawn using MAP_FRAME_PEN. To customize the box appearance, pass a pygmt.params.Box object to control style, fill, pen, and other box properties.

  • perspective (float | Sequence[float] | str | bool, default: False) –

    Select perspective view and set the azimuth and elevation of the viewpoint.

    Accepts a single value or a sequence of two or three values: azimuth, (azimuth, elevation), or (azimuth, elevation, zlevel).

    • azimuth: Azimuth angle of the viewpoint in degrees [Default is 180, i.e., looking from south to north].

    • elevation: Elevation angle of the viewpoint above the horizon [Default is 90, i.e., looking straight down at nadir].

    • zlevel: Z-level at which 2-D elements (e.g., the map frame) are drawn. Only applied when used together with zsize or zscale. [Default is at the bottom of the z-axis].

    Alternatively, set perspective=True to reuse the perspective setting from the previous plotting method, or pass a string following the full GMT syntax for finer control (e.g., adding +w or +v modifiers to select an axis location other than the plot origin). See https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full for details.

  • verbose (bool or str) – Select verbosity level [Full usage].

  • transparency (float) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

Examples

>>> import pygmt
>>> from pygmt.params import Box, Position
>>> fig = pygmt.Figure()
>>> fig.basemap(region=[0, 80, -30, 30], projection="M10c", frame=True)
>>> fig.scalebar(
...     position=Position((10, 10)),
...     length=1000,
...     fancy=True,
...     label="Scale",
...     unit=True,
... )
>>> fig.show()