Update Figure.scalebar and add tests

Author: seisman

pygmt/src/scalebar.py

@@ -2,39 +2,36 @@
 scalebar - Add a scale bar.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.exceptions import GMTInvalidInputError
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import build_arg_list
 from pygmt.params import Box, Position
 
 
 def scalebar(  # noqa: PLR0913
     self,
-    position: Position,
+    position: Position | None = None,
     length: float | str | None = None,
-    label_alignment: Literal["left", "right", "top", "bottom"] | None = None,
-    scale_position: float | tuple[float, float] | bool = False,
+    scale_position: float | Sequence[float] | bool = False,
     label: str | bool = False,
-    fancy: bool = False,
+    label_alignment: Literal["left", "right", "top", "bottom"] | None = None,
     unit: bool = False,
+    fancy: bool = False,
     vertical: bool = False,
     box: Box | bool = False,
-    perspective: str | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
+    perspective: float | Sequence[float] | str | bool = False,
 ):
     """
     Add a scale bar on the map.
 
-    The scale bar is plotted at the location defined by the reference point (specified
-    by the **position** and *position_type** parameters) and anchor point (specified by
-    the **anchor** and **anchor_offset** parameters). Refer to
-    :doc:`/techref/reference_anchor_points` for details about the positioning.
-
     Parameters
     ----------
     position
@@ -59,19 +56,19 @@ def scalebar(  # noqa: PLR0913
         - ``False``: Default to the location of the reference point.
     label
         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. The parameter requires ``fancy=True``.
+        ``True``, the distance unit provided in the ``length` parameter (default is km)
+        is used as the label. This parameter requires ``fancy=True``.
     label_alignment
-        Alignment of the scale bar label. Choose from "left", "right", "top", or
-        "bottom". [Default is "top"].
+        Alignment of the scale bar label. Choose from ``"left"``, ``"right"``,
+        ``"top"``, or ``"bottom"``. [Default is ``"top"``].
     fancy
-        If ``True``, draw a “fancy” scale bar. A fancy scale bar is a segmented bar with
-        alternating black and white rectangles. If ``False``, draw a plain scale bar.
+        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
         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.
+        length. The unit is determined from the suffix in the ``length`` or defaults to
+        ``"km"``.
     vertical
         If ``True``, plot a vertical rather than a horizontal Cartesian scale.
     box
@@ -98,14 +95,14 @@ def scalebar(  # noqa: PLR0913
     ... )
     >>> fig.show()
     """
-    self._preprocess()
+    self._activate_figure()
 
     if position is None:
         msg = "Parameter 'position' must be specified."
-        raise GMTInvalidInputError(msg)
+        raise GMTInvalidInput(msg)
     if length is None:
         msg = "Parameter 'length' must be specified."
-        raise GMTInvalidInputError(msg)
+        raise GMTInvalidInput(msg)
 
     aliasdict = AliasSystem(
         F=Alias(box, name="box"),
@@ -124,9 +121,10 @@ def scalebar(  # noqa: PLR0913
             Alias(unit, name="unit", prefix="+u"),
             Alias(vertical, name="vertical", prefix="+v"),
         ],
-        p=Alias(perspective, name="perspective"),
     ).add_common(
         V=verbose,
+        c=panel,
+        p=perspective,
         t=transparency,
     )
 

pygmt/tests/baseline/test_scalebar.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 0bc967a510306086752fae3b556cc7e2
+  size: 10201
+  hash: md5
+  path: test_scalebar.png

pygmt/tests/baseline/test_scalebar_complete.png.dvc

@@ -0,0 +1,5 @@
+outs:
+- md5: 5a339623e1c78d80484f99321b56ddf2
+  size: 11712
+  hash: md5
+  path: test_scalebar_complete.png

pygmt/tests/test_scalebar.py

@@ -0,0 +1,59 @@
+"""
+Test Figure.scalebar.
+"""
+
+import pytest
+from pygmt import Figure
+from pygmt.exceptions import GMTInvalidInput
+from pygmt.params import Position
+
+
+@pytest.mark.mpl_image_compare
+def test_scalebar():
+    """
+    Create a map with a scale bar.
+    """
+    fig = Figure()
+    fig.basemap(region=[100, 120, 20, 30], projection="M10c", frame=True)
+    fig.scalebar(position=Position((118, 22), cstype="mapcoords"), length=200)
+    return fig
+
+
+@pytest.mark.mpl_image_compare
+def test_scalebar_complete():
+    """
+    Test all parameters of scalebar.
+    """
+    fig = Figure()
+    fig.basemap(region=[100, 120, 20, 30], projection="M10c", frame=True)
+    fig.scalebar(
+        position=Position((110, 22), cstype="mapcoords"),
+        length=1000,
+        fancy=True,
+        label="Scale",
+        label_alignment="left",
+        scale_position=(110, 25),
+        unit=True,
+        box=True,
+    )
+    return fig
+
+
+def test_scalebar_no_position():
+    """
+    Test that an error is raised when position is not provided.
+    """
+    fig = Figure()
+    fig.basemap(region=[100, 120, 20, 30], projection="M10c", frame=True)
+    with pytest.raises(GMTInvalidInput):
+        fig.scalebar(length=200)
+
+
+def test_scalebar_no_length():
+    """
+    Test that an error is raised when length is not provided.
+    """
+    fig = Figure()
+    fig.basemap(region=[100, 120, 20, 30], projection="M10c", frame=True)
+    with pytest.raises(GMTInvalidInput):
+        fig.scalebar(position=Position((118, 22), cstype="mapcoords"))