diff --git a/doc/api/index.rst b/doc/api/index.rst index 7828a225652..830ddad82e1 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -31,6 +31,7 @@ Plotting map elements Figure.inset Figure.legend Figure.logo + Figure.scalebar Figure.solar Figure.text Figure.timestamp diff --git a/pygmt/figure.py b/pygmt/figure.py index 474cd91179b..64b13663a83 100644 --- a/pygmt/figure.py +++ b/pygmt/figure.py @@ -449,6 +449,7 @@ def _repr_html_(self) -> str: plot3d, psconvert, rose, + scalebar, set_panel, shift_origin, solar, diff --git a/pygmt/src/__init__.py b/pygmt/src/__init__.py index 8905124f917..2aa4e6b5587 100644 --- a/pygmt/src/__init__.py +++ b/pygmt/src/__init__.py @@ -43,6 +43,7 @@ from pygmt.src.project import project from pygmt.src.psconvert import psconvert from pygmt.src.rose import rose +from pygmt.src.scalebar import scalebar from pygmt.src.select import select from pygmt.src.shift_origin import shift_origin from pygmt.src.solar import solar diff --git a/pygmt/src/scalebar.py b/pygmt/src/scalebar.py new file mode 100644 index 00000000000..a5980d932f2 --- /dev/null +++ b/pygmt/src/scalebar.py @@ -0,0 +1,114 @@ +""" +scalebar - Add a scale bar. +""" + +from collections.abc import Sequence +from typing import Literal + +from pygmt._typing import AnchorCode +from pygmt.alias import Alias, AliasSystem +from pygmt.clib import Session +from pygmt.helpers import build_arg_list + + +def scalebar( # noqa: PLR0913 + self, + position, + length, + position_type: Literal[ + "mapcoords", + "boxcoords", + "plotcoords", + "inside", + "outside", + ] = "mapcoords", + label_alignment: Literal["left", "right", "top", "bottom"] | None = None, + scale_position=None, + justify: AnchorCode | None = None, + anchor_offset: Sequence[float | str] | None = None, + label: str | bool = False, + fancy: bool = False, + unit: bool = False, + vertical: bool = False, + box=None, +): + """ + Add a scale bar. + + Parameters + ---------- + position/position_type + Location of the map scale bar. The actual meaning of this parameter depends + on the ``position_type`` parameter. + - ``position_type="mapcoords"``: *position* is given as (x, y) in user + coordinates. + - ``position_type="boxcoords"``: *position* is given as (nx, ny) in normalized + coordinates, where (0, 0) is the lower-left corner and (1, 1) is the + upper-right corner of the plot. + - ``position_type="plotcoords"``: *position* is given as (x, y) in plot + coordinates, i.e., the distances in inches, centimeters, or points from the + lower left plot origin. + - ``position_type="inside"``: *position* is given as a two-character + justification code, meaning the anchor point of the rose is inside the plot + bounding box. + - ``position_type="outside"``: *position* is given as a two-character + justification code, but the rose is outside the plot bounding box. + + Parameters + ---------- + TODO + + Examples + -------- + >>> import pygmt + >>> from pygmt.params import Box + >>> fig = pygmt.Figure() + >>> fig.basemap(region=[0, 80, -30, 30], projection="M10c", frame=True) + >>> fig.scalebar( + ... position=(10, 10), + ... position_type="mapcoords", + ... length=1000, + ... fancy=True, + ... label="Scale", + ... unit=True, + ... ) + >>> fig.show() + """ + self._preprocess() + + aliasdict = AliasSystem( + L=[ + Alias( + position_type, + name="position_type", + mapping={ + "mapcoords": "g", + "boxcoords": "n", + "plotcoords": "x", + "inside": "j", + "outside": "J", + }, + ), + Alias(position, name="position", sep="/", size=2), + Alias(length, name="length", prefix="+w"), + Alias( + label_alignment, + name="label_alignment", + prefix="+a", + mapping={"left": "l", "right": "r", "top": "t", "bottom": "b"}, + ), + Alias(scale_position, name="scale_position", prefix="+c", sep="/"), + Alias(fancy, name="fancy", prefix="+f"), + Alias(justify, name="justify", prefix="+j"), + Alias(label, name="label", prefix="+l"), + Alias( + anchor_offset, name="anchor_offset", prefix="+o", sep="/", size=[1, 2] + ), + Alias(unit, name="unit", prefix="+u"), + Alias(vertical, name="vertical", prefix="+v"), + ], + F=Alias(box, name="box"), + ) + + with Session() as lib: + lib.call_module(module="basemap", args=build_arg_list(aliasdict))