POC: Add the Position class for GMT embellishment placement

doc/api/index.rst

@@ -214,6 +214,7 @@ Class-style Parameters
 
     Box
     Pattern
+    Position
 
 Enums
 -----

pygmt/params/__init__.py

@@ -4,3 +4,4 @@
 
 from pygmt.params.box import Box
 from pygmt.params.pattern import Pattern
+from pygmt.params.position import Position

pygmt/params/position.py

@@ -0,0 +1,87 @@
+"""
+The Position class for positioning GMT embellishments.
+"""
+
+import dataclasses
+from collections.abc import Sequence
+from typing import Literal
+
+from pygmt._typing import AnchorCode
+from pygmt.alias import Alias
+from pygmt.params.base import BaseParam
+
+
+@dataclasses.dataclass(repr=False)
+class Position(BaseParam):
+    """
+    The class for positioning GMT embellishments.
+
+    Example
+    -------
+    >>> import pygmt
+    >>> from pygmt.params import Position
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
+    >>> fig.logo(
+    ...     position=Position((3, 3), type="mapcoords", anchor="ML", offset=(0.2, 0.2)),
+    ...     box=True,
+    ... )
+    >>> fig.show()
+    """
+
+    #: Specify the reference point on the plot. The method of defining the reference
+    #: point is controlled by ``type``, and the exact location is set by ``position``.
+    location: Sequence[float | str] | AnchorCode
+
+    #: Specify the type of coordinates used to define the reference point. It can be
+    #: one of the following values:
+    #:
+    #: - ``"mapcoords"``: ``position`` is specified as (*longitude*, *latitude*) in map
+    #:   coordinates.
+    #: - ``"boxcoords"``: ``position`` is specified as (*nx*, *ny*) in normalized
+    #:   coordinates, i.e., fractional values between 0 and 1 along the x- and y-axes.
+    #: - ``"plotcoords"``: ``position`` is specified as (*x*, *y*) in plot coordinates,
+    #:   i.e., distances from the lower-left plot origin given in inches, centimeters,
+    #:   or points.
+    #: - ``"inside"`` or ``"outside"``: ``position`` is one of the nine
+    #:   :doc:`two-character justification codes </techref/justification_codes>`,
+    #:   indicating a specific location relative to the plot bounding box.
+    #:
+    #: The default value is ``"plotcoords"``.
+    type: Literal["mapcoords", "inside", "outside", "boxcoords", "plotcoords"] = (
+        "plotcoords"
+    )
+
+    #: Specify the anchor point of the GMT logo, using one of the
+    #: :doc:`2-character justification codes </techref/justification_codes>`. The
+    #: default value depends on ``position_type``.
+    #:
+    #: - ``position_type="inside"``: ``anchor`` defaults to the same as ``position``.
+    #: - ``position_type="outside"``: ``anchor`` defaults to the mirror opposite of
+    #:   ``position``.
+    #: - Otherwise, ``anchor`` defaults to ``"MC"`` (middle center).
+    anchor: AnchorCode | None = None
+
+    #: Specifies an offset for the anchor point as *offset* or (*offset_x*, *offset_y*).
+    #: If a single value *offset* is given, both *offset_x* and *offset_y* are set to
+    #: *offset*.
+    offset: Sequence[float | str] | None = None
+
+    @property
+    def _aliases(self):
+        return [
+            Alias(
+                self.type,
+                name="type",
+                mapping={
+                    "mapcoords": "g",
+                    "boxcoords": "n",
+                    "plotcoords": "x",
+                    "inside": "j",
+                    "outside": "J",
+                },
+            ),
+            Alias(self.location, name="location", sep="/", size=2),
+            Alias(self.anchor, name="anchor", prefix="+j"),
+            Alias(self.offset, name="offset", prefix="+o", sep="/", size=2),
+        ]

pygmt/src/logo.py

@@ -7,14 +7,16 @@
 
 from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
-from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
-from pygmt.params import Box
+from pygmt.helpers import build_arg_list, fmt_docstring
+from pygmt.params import Box, Position
 
 
 @fmt_docstring
-@use_alias(D="position")
-def logo(
+def logo(  # noqa: PLR0913
     self,
+    position: Position | None = None,
+    width: float | str | None = None,
+    height: float | str | None = None,
     projection: str | None = None,
     region: Sequence[float | str] | str | None = None,
     style: Literal["standard", "url", "no_label"] = "standard",
@@ -36,7 +38,12 @@ def logo(
 
     Full GMT docs at :gmt-docs:`gmtlogo.html`.
 
-    {aliases}
+    **Aliases:**
+
+    .. hlist::
+       :columns: 3
+
+       - D = position, **+w**: width, **+h**: height
        - F = box
        - J = projection
        - R = region
@@ -73,6 +80,11 @@ def logo(
     self._activate_figure()
 
     aliasdict = AliasSystem(
+        D=[
+            Alias(position, name="position"),
+            Alias(width, name="width", prefix="+w"),
+            Alias(height, name="height", prefix="+h"),
+        ],
         F=Alias(box, name="box"),
         S=Alias(
             style, name="style", mapping={"standard": "l", "url": "u", "no_label": "n"}

pygmt/tests/test_params_position.py

@@ -0,0 +1,32 @@
+"""
+Test the Position class.
+"""
+
+from pygmt.params import Position
+
+
+def test_params_position_types():
+    """
+    Test the Position class with different types of coordinate systems.
+    """
+    assert str(Position((1, 2))) == "x1/2"
+    assert str(Position(location=(1, 2))) == "x1/2"
+    assert str(Position(location=(10, 20), type="mapcoords")) == "g10/20"
+    assert str(Position(location=(0.1, 0.2), type="boxcoords")) == "n0.1/0.2"
+    assert str(Position(location=("5c", "3c"), type="plotcoords")) == "x5c/3c"
+    assert str(Position(location="TL", type="inside")) == "jTL"
+    assert str(Position(location="BR", type="outside")) == "JBR"
+
+
+def test_params_position_anchor_offset():
+    """
+    Test the Position class with anchor and offset parameters.
+    """
+    pos = Position(location=(10, 20), type="mapcoords", anchor="TL")
+    assert str(pos) == "g10/20+jTL"
+
+    pos = Position(location=(10, 20), type="mapcoords", offset=(1, 2))
+    assert str(pos) == "g10/20+o1/2"
+
+    pos = Position(location="TL", type="inside", anchor="MC", offset=("1c", "2c"))
+    assert str(pos) == "jTL+jMC+o1c/2c"