Merge branch 'main' into image/invert

seisman · web-flow · commit d10b5bd725cf · 2025-12-12T13:27:57.000+08:00
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -214,6 +214,7 @@ Class-style Parameters
 
     Box
     Pattern
+    Position
 
 Enums
 -----
diff --git a/examples/gallery/embellishments/solar.py b/examples/gallery/embellishments/solar.py
@@ -32,7 +32,7 @@
         terminator_datetime=reference_time,
         # Set the fill for the night area to navy blue with 85 % transparency
         fill="navyblue@85",
-        pen="0.5p",  # Set the outline to be 0.5 points thick
+        pen="0.5p",  # Set the outline to be 0.5-point thick
     )
 
 fig.show()
diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
@@ -46,7 +46,7 @@
     # directions, respectively; move the x-label above the horizontal colorbar ("+ml")
     position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",
     # Add a box around the colobar, filled in white and a 30 % transparency, with a
-    # 0.8-points thick, black, outline.
+    # 0.8-point thick, black, outline.
     box=Box(pen="0.8p,black", fill="white@30"),
     # Add x- and y-labels ("+l")
     frame=["x+lElevation", "y+lm"],
@@ -103,7 +103,7 @@
     x=[0, 15],
     y=[0, 0],
     fill="lightblue",  # Fill the polygon in "lightblue"
-    pen="0.25p,black,solid",  # Draw a 0.25-points thick, black, solid outline
+    pen="0.25p,black,solid",  # Draw a 0.25-point thick, black, solid outline
     close="+y-8000",  # Force closed polygon
 )
 
diff --git a/examples/gallery/maps/shorelines.py b/examples/gallery/maps/shorelines.py
@@ -11,6 +11,6 @@
 fig = pygmt.Figure()
 # Make a global Mollweide map with automatic ticks
 fig.basemap(region="g", projection="W15c", frame=True)
-# Display the shorelines as black lines with 0.5 point thickness
+# Display the shorelines as black lines with 0.5-point thickness
 fig.coast(shorelines="0.5p,black")
 fig.show()
diff --git a/examples/gallery/seismology/meca.py b/examples/gallery/seismology/meca.py
@@ -45,7 +45,7 @@
     # Fill extensive quadrants with color "cornsilk"
     # [Default is "white"]
     extensionfill="cornsilk",
-    # Draw a 0.5 points thick dark gray ("gray30") solid outline via
+    # Draw a 0.5-point thick dark gray ("gray30") solid outline via
     # the pen parameter [Default is "0.25p,black,solid"]
     pen="0.5p,gray30,solid",
 )
diff --git a/examples/tutorials/advanced/3d_perspective_image.py b/examples/tutorials/advanced/3d_perspective_image.py
@@ -91,7 +91,7 @@
     surftype="s",
     cmap="geo",
     plane="1000+ggrey",
-    # Set the contour pen thickness to "0.1p"
+    # Set the contour pen thickness to 0.1 points
     contour_pen="0.1p",
 )
 fig.colorbar(perspective=True, frame=["a500", "x+lElevation", "y+lm"])
diff --git a/examples/tutorials/advanced/cartesian_histograms.py b/examples/tutorials/advanced/cartesian_histograms.py
@@ -120,7 +120,7 @@
     frame=["WSne", "xaf10", "ya1f1+lCounts"],
     data=data02,
     series=10,
-    # Draw a 1.5-points thick, dashed outline in "orange"
+    # Draw a 1.5-point thick, dashed outline in "orange"
     pen="1.5p,orange,dashed",
     histtype=0,
     stairs=True,
diff --git a/examples/tutorials/advanced/legends.py b/examples/tutorials/advanced/legends.py
@@ -89,7 +89,7 @@
 fig.plot(x=1, y=0, style="t0.3c", fill="pink", pen="black", label="pink triangle")
 fig.plot(x=[-3, 3], y=[-2, -2], pen="darkred", label="darkred line")
 
-# Add a box with a 2-points thick blue, solid outline and a white fill with a
+# Add a box with a 2-point thick blue, solid outline and a white fill with a
 # transparency of 30 percent ("@30").
 fig.legend(position="jTL+o0.3c/0.2c", box=Box(pen="2p,blue", fill="white@30"))
 
diff --git a/examples/tutorials/advanced/working_with_panel.py b/examples/tutorials/advanced/working_with_panel.py
@@ -50,7 +50,7 @@
     frame="g30",  # Add frame and gridlines in steps of 30 degrees on top
     land="gray",  # Color land masses in "gray"
     water="lightblue",  # Color water masses in "lightblue"
-    # Add coastlines with a 0.25 points thick pen in "gray50"
+    # Add coastlines with a 0.25-point thick pen in "gray50"
     shorelines="1/0.25p,gray50",
 )
 fig.show()
diff --git a/examples/tutorials/basics/lines.py b/examples/tutorials/basics/lines.py
@@ -14,7 +14,7 @@
 #
 # Create a Cartesian figure using the :meth:`pygmt.Figure.basemap` method. Pass lists
 # containing two values to the ``x`` and ``y`` parameters of the
-# :meth:`pygmt.Figure.plot` method. By default, a 0.25-points thick, black, solid
+# :meth:`pygmt.Figure.plot` method. By default, a 0.25-point thick, black, solid
 # line is drawn between these two data points.
 
 fig = pygmt.Figure()
@@ -96,7 +96,7 @@
 fig = pygmt.Figure()
 fig.basemap(region=[0, 10, 0, 10], projection="X15c/10c", frame=True)
 
-# Draw a 7-points thick, green line with style "-.-" (dash dot dash)
+# Draw a 7-point thick, green line with style "-.-" (dash dot dash)
 fig.plot(x=[1, 8], y=[3, 9], pen="7p,green,-.-")
 
 fig.show()
diff --git a/examples/tutorials/basics/polygons.py b/examples/tutorials/basics/polygons.py
@@ -29,7 +29,7 @@
 # Create a Cartesian plot via the :meth:`pygmt.Figure.basemap` method. Pass arrays to
 # the ``x`` and ``y`` parameters of the :meth:`pygmt.Figure.plot` method. Without
 # further adjustments, lines are drawn between the data points. By default, the lines
-# are 0.25-points thick, black, and solid. In this example, the data points are chosen
+# are 0.25-point thick, black, and solid. In this example, the data points are chosen
 # to make the lines form a polygon.
 
 fig = pygmt.Figure()
@@ -44,7 +44,7 @@
 
 fig = pygmt.Figure()
 fig.basemap(region=[-5, 5, -5, 5], projection="X5c", frame=True)
-# Use a 2-points thick, darkred, dashed outline
+# Use a 2-point thick, darkred, dashed outline
 fig.plot(x=x, y=y, pen="2p,darkred,dashed")
 fig.show()
 
diff --git a/examples/tutorials/basics/text.py b/examples/tutorials/basics/text.py
@@ -77,15 +77,15 @@
 
 # Plot text labels at the x and y positions of the markers while varying the anchor
 # point via the justify parameter
-fig.text(x=-0.5, y=0.5, text="TL", justify="TL")  # TopLeft
-fig.text(x=0, y=0.5, text="TC", justify="TC")  # TopCenter
-fig.text(x=0.5, y=0.5, text="TR", justify="TR")  # TopRight
-fig.text(x=-0.5, y=0, text="ML", justify="ML")  # MiddleLeft
-fig.text(x=0, y=0, text="MC", justify="MC")  # MiddleCenter
-fig.text(x=0.5, y=0, text="MR", justify="MR")  # MiddleRight
-fig.text(x=-0.5, y=-0.5, text="BL", justify="BL")  # BottomLeft
-fig.text(x=0, y=-0.5, text="BC", justify="BC")  # BottomCenter
-fig.text(x=0.5, y=-0.5, text="BR", justify="BR")  # BottomRight
+fig.text(x=-0.5, y=0.5, text="TL", justify="TL")  # Top Left
+fig.text(x=0, y=0.5, text="TC", justify="TC")  # Top Center
+fig.text(x=0.5, y=0.5, text="TR", justify="TR")  # Top Right
+fig.text(x=-0.5, y=0, text="ML", justify="ML")  # Middle Left
+fig.text(x=0, y=0, text="MC", justify="MC")  # Middle Center
+fig.text(x=0.5, y=0, text="MR", justify="MR")  # Middle Right
+fig.text(x=-0.5, y=-0.5, text="BL", justify="BL")  # Bottom Left
+fig.text(x=0, y=-0.5, text="BC", justify="BC")  # Bottom Center
+fig.text(x=0.5, y=-0.5, text="BR", justify="BR")  # Bottom Right
 
 fig.show()
 
diff --git a/pygmt/params/__init__.py b/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
diff --git a/pygmt/params/position.py b/pygmt/params/position.py
@@ -0,0 +1,212 @@
+"""
+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.exceptions import GMTValueError
+from pygmt.helpers import is_nonstr_iter
+from pygmt.params.base import BaseParam
+
+
+@dataclasses.dataclass(repr=False)
+class Position(BaseParam):
+    """
+    Class for positioning embellishments on a plot.
+
+    .. figure:: https://docs.generic-mapping-tools.org/dev/_images/GMT_anchor.png
+       :width: 600 px
+       :align: center
+
+       The placement of a GMT embellishment (represented by a green rectangle) in
+       relation to the underlying plot (represented by a bisque rectangle).
+
+    This class provides flexible positioning for GMT embellishments (e.g., logo, scale,
+    rose) by defining a *reference point* on the plot and an *anchor point* on the
+    embellishment. The embellishment is positioned so these two points overlap.
+
+    **Conceptual Model**
+
+    Think of it like dropping an anchor from a boat:
+
+    1. The boat navigates to the *reference point* (a location on the plot)
+    2. The *anchor point* (a specific point on the embellishment) is aligned with the
+       *reference point*
+    3. The embellishment is "dropped" at that position
+
+    **Reference Point**
+
+    The *reference point* can be specified in five different ways using the ``cstype``
+    and ``refpoint`` attributes:
+
+    ``cstype="mapcoords"`` Map Coordinates
+        Use data/geographic coordinates. Specify ``refpoint`` as
+        (*longitude*, *latitude*). Useful when tying the embellishment to a specific
+        geographic location.
+
+        **Example:** ``refpoint=(135, 20), cstype="mapcoords"``
+
+    ``cstype="plotcoords"`` Plot Coordinates
+        Use plot coordinates as distances from the lower-left plot origin. Specify
+        ``refpoint`` as (*x*, *y*) with units (e.g., inches, centimeters, points).
+        Useful for precise layout control.
+
+        **Example:** ``refpoint=("2c", "2.5c"), cstype="plotcoords"``
+
+    ``cstype="boxcoords"`` Normalized Coordinates
+        Use normalized coordinates where (0, 0) is the lower-left corner and (1, 1) is
+        the upper-right corner of the bounding box of the current plot. Specify
+        ``refpoint`` as (*nx*, *ny*). Useful for positioning relative to plot dimensions
+        without units.
+
+        **Example:** ``refpoint=(0.2, 0.1), cstype="boxcoords"``
+
+    ``cstype="inside"`` Inside Plot
+        Select one of the nine :doc:`justification codes </techref/justification_codes>`
+        as the *reference point*. The *anchor point* defaults to be the same as the
+        *reference point*, so the embellishment is placed inside the plot.
+
+        **Example:** ``refpoint="TL", cstype="inside"``
+
+    ``cstype="outside"`` Outside Plot
+        Similar to ``cstype="inside"``, but the *anchor point* defaults to the mirror
+        opposite of the *reference point*. Useful for placing embellishments outside
+        the plot boundaries (e.g., color bars).
+
+        **Example:** ``refpoint="TL", cstype="outside"``
+
+    **Anchor Point**
+
+    The *anchor point* determines which part of the embellishment aligns with the
+    *reference point*. It uses one of nine
+    :doc:`justification codes </techref/justification_codes>`.
+
+    Set ``anchor`` explicitly to override these defaults. If not set, the default
+    *anchor* behaviors are:
+
+    - ``cstype="inside"``: Same as the *reference point* justification code
+    - ``cstype="outside"``: Mirror opposite of the *reference point* justification code
+    - Other cstypes: ``"MC"`` (middle center) for map rose and scale, ``"BL"``
+      (bottom-left) for other embellishments
+
+    **Offset**
+
+    The ``offset`` parameter shifts the *anchor point* from its default position.
+    Offsets are applied to the projected plot coordinates, with positive values moving
+    in the direction indicated by the *anchor point*'s justification code. It should be
+    a single value (applied to both x and y) or as (*offset_x*, *offset_y*).
+
+    Examples
+    --------
+    Position the GMT logo at map coordinates (3, 3) with the logo's middle-left point as
+    the anchor, offset by (0.2, 0.2):
+
+    >>> 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), cstype="mapcoords", anchor="ML", offset=(0.2, 0.2)
+    ...     ),
+    ...     box=True,
+    ... )
+    >>> fig.show()
+
+    Position the GMT logo at the top-left corner inside the plot:
+
+    >>> fig = pygmt.Figure()
+    >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=True)
+    >>> fig.logo(position=Position("TL", cstype="inside", offset="0.2c"), box=True)
+    >>> fig.show()
+    """
+
+    #: Location of the reference point on the plot. The format depends on ``cstype``:
+    #:
+    #: - ``cstype="mapcoords"``: (*longitude*, *latitude*)
+    #: - ``cstype="plotcoords"``: (*x*, *y*) with plot units
+    #: - ``cstype="boxcoords"``: (*nx*, *ny*)
+    #: - ``cstype="inside"`` or ``"outside"``:
+    #:   :doc:`2-character justification codes </techref/justification_codes>`
+    refpoint: Sequence[float | str] | AnchorCode
+
+    #: cstype of the reference point. Valid values are:
+    #:
+    #: - ``"mapcoords"``: Map/Data coordinates
+    #: - ``"plotcoords"``: Plot coordinates
+    #: - ``"boxcoords"``: Normalized coordinates
+    #: - ``"inside"`` or ``"outside"``: Justification codes
+    #:
+    #: If not specified, defaults to ``"inside"`` if ``refpoint`` is a justification
+    #: code; otherwise defaults to ``"plotcoords"``.
+    cstype: (
+        Literal["mapcoords", "inside", "outside", "boxcoords", "plotcoords"] | None
+    ) = None
+
+    #: Anchor point on the embellishment using a
+    #: :doc:`2-character justification code </techref/justification_codes>`.
+    #: If ``None``, defaults are applied based on ``cstype`` (see above).
+    anchor: AnchorCode | None = None
+
+    #: Offset for the anchor point as a single value or (*offset_x*, *offset_y*).
+    #: If a single value is given, the offset is applied to both x and y directions.
+    offset: float | str | Sequence[float | str] | None = None
+
+    def _validate(self):
+        """
+        Validate the parameters.
+        """
+        _valid_anchors = {f"{h}{v}" for v in "TMB" for h in "LCR"} | {
+            f"{v}{h}" for v in "TMB" for h in "LCR"
+        }
+
+        # Default to "inside" if cstype is not specified and location is an anchor code.
+        if self.cstype is None:
+            self.cstype = "inside" if isinstance(self.refpoint, str) else "plotcoords"
+
+        # Validate the location based on cstype.
+        match self.cstype:
+            case "mapcoords" | "plotcoords" | "boxcoords":
+                if not is_nonstr_iter(self.refpoint) or len(self.refpoint) != 2:
+                    raise GMTValueError(
+                        self.refpoint,
+                        description="reference point",
+                        reason="Expect a sequence of two values.",
+                    )
+            case "inside" | "outside":
+                if self.refpoint not in _valid_anchors:
+                    raise GMTValueError(
+                        self.refpoint,
+                        description="reference point",
+                        reason="Expect a valid 2-character justification code.",
+                    )
+        # Validate the anchor if specified.
+        if self.anchor is not None and self.anchor not in _valid_anchors:
+            raise GMTValueError(
+                self.anchor,
+                description="anchor point",
+                reason="Expect a valid 2-character justification code.",
+            )
+
+    @property
+    def _aliases(self):
+        return [
+            Alias(
+                self.cstype,
+                name="cstype",
+                mapping={
+                    "mapcoords": "g",
+                    "boxcoords": "n",
+                    "plotcoords": "x",
+                    "inside": "j",
+                    "outside": "J",
+                },
+            ),
+            Alias(self.refpoint, name="refpoint", sep="/", size=2),
+            Alias(self.anchor, name="anchor", prefix="+j"),
+            Alias(self.offset, name="offset", prefix="+o", sep="/", size=2),
+        ]
diff --git a/pygmt/src/legend.py b/pygmt/src/legend.py
@@ -75,10 +75,9 @@ def legend(  # noqa: PLR0913
         [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\
         **+w**\ *width*\ [/*height*]\ [**+j**\ *justify*]\ [**+l**\ *spacing*]\
         [**+o**\ *dx*\ [/*dy*]].
-        Define the reference point on the map for the
-        legend. By default, uses **JTR**\ **+jTR**\ **+o**\ 0.2c which
-        places the legend at the top-right corner inside the map frame, with a
-        0.2 cm offset.
+        Define the reference point on the map for the legend. By default, uses
+        **JTR**\ **+jTR**\ **+o**\ 0.2c which places the legend at the Top Right corner
+        inside the map frame, with a 0.2 cm offset.
     box
         Draw a background box behind the legend. If set to ``True``, a simple
         rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
diff --git a/pygmt/tests/test_grdview.py b/pygmt/tests/test_grdview.py
@@ -179,7 +179,9 @@ def test_grdview_surface_plot_styled_with_contourpen(xrgrid):
     surface plot.
     """
     fig = Figure()
-    fig.grdview(grid=xrgrid, cmap="relief", surftype="s", contour_pen="0.5p,black,dashed")
+    fig.grdview(
+        grid=xrgrid, cmap="relief", surftype="s", contour_pen="0.5p,black,dashed"
+    )
     return fig
 
 
diff --git a/pygmt/tests/test_params_position.py b/pygmt/tests/test_params_position.py

-Original file line number
+Diff line change
     Box
     Pattern
 +    Position
 Enums
 -----
Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@`
`32`	`32`	`terminator_datetime=reference_time,`
`33`	`33`	`# Set the fill for the night area to navy blue with 85 % transparency`
`34`	`34`	`fill="navyblue@85",`
`35`		`- pen="0.5p", # Set the outline to be 0.5 points thick`
	`35`	`+ pen="0.5p", # Set the outline to be 0.5-point thick`
`36`	`36`	`)`
`37`	`37`
`38`	`38`	`fig.show()`
Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@`
`45`	`45`	`# Fill extensive quadrants with color "cornsilk"`
`46`	`46`	`# [Default is "white"]`
`47`	`47`	`extensionfill="cornsilk",`
`48`		`- # Draw a 0.5 points thick dark gray ("gray30") solid outline via`
	`48`	`+ # Draw a 0.5-point thick dark gray ("gray30") solid outline via`
`49`	`49`	`# the pen parameter [Default is "0.25p,black,solid"]`
`50`	`50`	`pen="0.5p,gray30,solid",`
`51`	`51`	`)`
Original file line number	Diff line number	Diff line change
`@@ -91,7 +91,7 @@`
`91`	`91`	`surftype="s",`
`92`	`92`	`cmap="geo",`
`93`	`93`	`plane="1000+ggrey",`
`94`		`- # Set the contour pen thickness to "0.1p"`
	`94`	`+ # Set the contour pen thickness to 0.1 points`
`95`	`95`	`contour_pen="0.1p",`
`96`	`96`	`)`
`97`	`97`	`fig.colorbar(perspective=True, frame=["a500", "x+lElevation", "y+lm"])`
Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,7 @@`
`50`	`50`	`frame="g30", # Add frame and gridlines in steps of 30 degrees on top`
`51`	`51`	`land="gray", # Color land masses in "gray"`
`52`	`52`	`water="lightblue", # Color water masses in "lightblue"`
`53`		`- # Add coastlines with a 0.25 points thick pen in "gray50"`
	`53`	`+ # Add coastlines with a 0.25-point thick pen in "gray50"`
`54`	`54`	`shorelines="1/0.25p,gray50",`
`55`	`55`	`)`
`56`	`56`	`fig.show()`