Add the Box class for specifying box properties of embellishments

Author: seisman

doc/api/index.rst

@@ -194,6 +194,16 @@ Getting metadata from tabular or grid data:
     info
     grdinfo
 
+Common Parameters
+-----------------
+
+.. currentmodule:: pygmt.params
+
+.. autosummary::
+    :toctree: generated
+
+    Box
+
 Xarray Integration
 ------------------
 

pygmt/params/__init__.py

@@ -0,0 +1,5 @@
+"""
+Classes for common parameters in PyGMT.
+"""
+
+from pygmt.params.box import Box

pygmt/params/base.py

@@ -0,0 +1,63 @@
+"""
+Base class for common parameters shared in PyGMT.
+"""
+
+
+class BaseParam:
+    """
+    Base class for parameters in PyGMT.
+
+    To define a new parameter class, inherit from this class and define the attributes
+    that correspond to the parameters you want to include. The class should also
+    implement the ``_aliases`` property, which returns a list of ``Alias`` objects. Each
+    ``Alias`` object represents a parameter and its value, and the ``__str__`` method
+    will concatenate these values into a single string that can be passed to GMT.
+
+    Examples
+    --------
+    >>> from typing import Any
+    >>> import dataclasses
+    >>> from pygmt.params.base import BaseParam
+    >>> from pygmt.alias import Alias
+    >>>
+    >>> @dataclasses.dataclass(repr=False)
+    ... class Test(BaseParam):
+    ...     par1: Any = None
+    ...     par2: Any = None
+    ...     par3: Any = None
+    ...
+    ...     @property
+    ...     def _aliases(self):
+    ...         return [
+    ...             Alias(self.par1),
+    ...             Alias(self.par2, prefix="+a"),
+    ...             Alias(self.par3, prefix="+b", separator="/"),
+    ...         ]
+
+    >>> var = Test(par1="val1")
+    >>> str(var)
+    'val1'
+    >>> repr(var)
+    "Test(par1='val1')"
+
+    >>> var = Test(par1="val1", par2="val2", par3=("val3a", "val3b"))
+    >>> str(var)
+    'val1+aval2+bval3a/val3b'
+    >>> repr(var)
+    "Test(par1='val1', par2='val2', par3=('val3a', 'val3b'))"
+    """
+
+    def __str__(self):
+        """
+        String representation of the object that can be passed to GMT directly.
+        """
+        return "".join(
+            [alias._value for alias in self._aliases if alias._value is not None]
+        )
+
+    def __repr__(self):
+        """
+        String representation of the object.
+        """
+        params = ", ".join(f"{k}={v!r}" for k, v in vars(self).items() if v is not None)
+        return f"{self.__class__.__name__}({params})"

pygmt/params/box.py

@@ -0,0 +1,122 @@
+"""
+The Box class for specifying the box around GMT embellishments.
+"""
+
+import dataclasses
+from collections.abc import Sequence
+
+from pygmt.alias import Alias
+from pygmt.exceptions import GMTValueError
+from pygmt.params.base import BaseParam
+
+
+@dataclasses.dataclass(repr=False)
+class Box(BaseParam):
+    """
+    Class for specifying the box around GMT embellishments.
+
+    Attributes
+    ----------
+    clearance
+        Set clearances between the embellishment and the box border. It can be either a
+        scalar value or a sequence of two/four values.
+
+        - a scalar value means a uniform clearance in all four directions.
+        - a sequence of two values means separate clearances in x- and y- directions.
+        - a sequence of four values means separate clearances for left/right/bottom/top.
+    fill
+        Fill for the box. Default is no fill.
+    pen
+        Pen attributes for the box outline.
+    radius
+        Draw a rounded rectangular borders instead of sharp. Passing a value with unit
+        to control the corner radius (default is ``"6p"``).
+    inner_gap
+        Gap between the outer and inner border. Default is ``"2p"``.
+    inner_pen
+        Pen attributes for the inner border. Default to :gmt-term:`MAP_DEFAULT_PEN`.
+    shading_offset
+        Place an offset background shaded region behind the box. A sequence of two
+        values (dx, dy) indicates the shift relative to the foreground frame. Default is
+        ``("4p", "-4p")``.
+    shading_fill
+        Fill for the shading region. Default is ``"gray50"``.
+
+    Examples
+    --------
+    >>> from pygmt.params import Box
+    >>> str(Box(fill="red@20"))
+    '+gred@20'
+    >>> str(Box(clearance=(0.2, 0.2), fill="red@20", pen="blue"))
+    '+c0.2/0.2+gred@20+pblue'
+    >>> str(Box(clearance=(0.2, 0.2), pen="blue", radius=True))
+    '+c0.2/0.2+pblue+r'
+    >>> str(Box(clearance=(0.1, 0.2, 0.3, 0.4), pen="blue", radius="10p"))
+    '+c0.1/0.2/0.3/0.4+pblue+r10p'
+    >>> str(
+    ...     Box(
+    ...         clearance=0.2,
+    ...         pen="blue",
+    ...         radius="10p",
+    ...         shading_offset=("5p", "5p"),
+    ...         shading_fill="lightred",
+    ...     )
+    ... )
+    '+c0.2+pblue+r10p+s5p/5p/lightred'
+    >>> str(Box(clearance=0.2, inner_gap="2p", inner_pen="1p,red", pen="blue"))
+    '+c0.2+i2p/1p,red+pblue'
+    >>> str(Box(clearance=0.2, shading_offset=("5p", "5p"), shading_fill="lightred"))
+    '+c0.2+s5p/5p/lightred'
+    """
+
+    # The GMT CLI syntax is:
+    #
+    # -F[+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]
+    clearance: float | str | Sequence[float | str] | None = None
+    fill: str | None = None
+    inner_gap: float | str | None = None
+    inner_pen: str | None = None
+    pen: str | None = None
+    radius: str | bool = False
+    shading_offset: Sequence[float | str] | None = None
+    shading_fill: str | None = None
+
+    @property
+    def _innerborder(self) -> list[str | float] | None:
+        """
+        Inner border of the box, formatted as a list of 1-2 values, or None.
+        """
+        return [v for v in (self.inner_gap, self.inner_pen) if v is not None] or None
+
+    @property
+    def _shading(self) -> list[str | float] | None:
+        """
+        Shading for the box, formatted as a list of 1-3 values, or None.
+        """
+        # Local variable to simplify the code.
+        _shading_offset = [] if self.shading_offset is None else self.shading_offset
+
+        # shading_offset must be a sequence of two values (dx, dy) or None.
+        if len(_shading_offset) not in {0, 2}:
+            raise GMTValueError(
+                self.shading_offset,
+                description="value for parameter 'shading_offset'",
+                reason="Must be a sequence of two values (dx, dy) or None.",
+            )
+        return [
+            v for v in (*_shading_offset, self.shading_fill) if v is not None
+        ] or None
+
+    @property
+    def _aliases(self):
+        """
+        Aliases for the parameter.
+        """
+        return [
+            Alias(self.clearance, prefix="+c", separator="/", size=[1, 2, 4]),
+            Alias(self.fill, prefix="+g"),
+            Alias(self._innerborder, prefix="+i", separator="/", size=[1, 2]),
+            Alias(self.pen, prefix="+p"),
+            Alias(self.radius, prefix="+r"),
+            Alias(self._shading, prefix="+s", separator="/", size=[1, 2, 3]),
+        ]