Figure.text: Allow passing a sequence of offset to the 'offset' parameter (#4652)

Author: seisman

examples/gallery/images/cross_section.py

@@ -61,7 +61,7 @@
     x=[lonA, lonB],
     y=[latA, latB],
     text=["A", "B"],
-    offset="0c/0.3c",  # Move text 0.2 centimeters up (y-direction)
+    offset=(0, 0.3),  # Move text 0.3 centimeters up (y-direction)
     font="15p,red",  # Use a red font with a size of 15 points
 )
 

examples/gallery/lines/decorated_lines.py

@@ -80,7 +80,7 @@
         text=decoline,
         font="Courier-Bold",
         justify="ML",
-        offset="0.75c/0c",
+        offset=(0.75, 0),
     )
 
 fig.show()

examples/gallery/lines/linefronts.py

@@ -90,7 +90,7 @@
         text=frontstyle,
         font="Courier-Bold",
         justify="ML",
-        offset="0.75c/0c",
+        offset=(0.75, 0),
     )
 
 fig.show()

examples/gallery/lines/linestyles.py

@@ -33,7 +33,7 @@
 
 # Plot the line using the default line style
 fig.plot(x=x, y=y)
-fig.text(x=x[-1], y=y[-1], text="solid (default)", justify="ML", offset="0.2c/0c")
+fig.text(x=x[-1], y=y[-1], text="solid (default)", justify="ML", offset=(0.2, 0))
 
 # Plot the line using different line styles
 for linestyle in [
@@ -48,14 +48,14 @@
 ]:
     y -= 1  # Move the current line down
     fig.plot(x=x, y=y, pen=linestyle)
-    fig.text(x=x[-1], y=y[-1], text=linestyle, justify="ML", offset="0.2c/0c")
+    fig.text(x=x[-1], y=y[-1], text=linestyle, justify="ML", offset=(0.2, 0))
 
 # Plot the line like a railway track (black/white).
 # The trick here is plotting the same line twice but with different line styles
 y -= 1  # move the current line down
 fig.plot(x=x, y=y, pen="5p,black")
 fig.plot(x=x, y=y, pen="4p,white,20p_20p")
-fig.text(x=x[-1], y=y[-1], text="5p,black", justify="ML", offset="0.2c/0.2c")
-fig.text(x=x[-1], y=y[-1], text="4p,white,20p_20p", justify="ML", offset="0.2c/-0.2c")
+fig.text(x=x[-1], y=y[-1], text="5p,black", justify="ML", offset=(0.2, 0.2))
+fig.text(x=x[-1], y=y[-1], text="4p,white,20p_20p", justify="ML", offset=(0.2, -0.2))
 
 fig.show()

examples/gallery/lines/quoted_lines.py

@@ -70,7 +70,7 @@
         text=quotedline,
         font="Courier-Bold",
         justify="ML",
-        offset="0.75c/0c",
+        offset=(0.75, 0),
     )
 
 fig.show()

examples/gallery/lines/vector_heads_tails.py

@@ -82,7 +82,7 @@
         x=x, y=y, style=vecstyle, direction=([angle], [length]), pen="2p", fill="red3"
     )
     fig.text(
-        x=6, y=y, text=vecstyle, font="Courier-Bold", justify="ML", offset="0.2c/0c"
+        x=6, y=y, text=vecstyle, font="Courier-Bold", justify="ML", offset=(0.2, 0)
     )
     y -= 1  # move the next vector down
 

examples/gallery/symbols/points_cities.py

@@ -41,7 +41,7 @@
     x=cities_large.geometry.x,
     y=cities_large.geometry.y,
     text=cities_large["name"],
-    offset="0.12c",
+    offset=0.12,
     justify="BL",
     font="6p,Helvetica-Bold",
     fill="white@30",

examples/tutorials/basics/text.py

@@ -59,7 +59,7 @@
 # Shift the text label relatively to the position given via the x and y parameters
 # by 1 centimeter to the right (positive x-direction) and 0.5 centimeters down
 # (negative y-direction)
-fig.text(x=0, y=-3, text="my text", offset="1c/-0.5c")
+fig.text(x=0, y=-3, text="my text", offset=(1, -0.5))
 
 fig.shift_origin(xshift="w+0.5c")
 
@@ -196,19 +196,13 @@
 fig = pygmt.Figure()
 
 # -----------------------------------------------------------------------------
-# Left: Add a tag to a subplot
+# Left: Add a tag to a subplot at the Top Left corner
 fig.basemap(
     region=[-5, 5, -5, 5],
     projection="X5c",
     frame=Frame(axes="WStr", axis=Axis(annot=True, tick=True)),
 )
-
-fig.text(
-    text="(a)",
-    position="TL",  # Top Left
-    justify="TL",  # Top Left
-    offset="0.1c/-0.1c",
-)
+fig.text(text="(a)", position="TL", justify="TL", offset=(0.1, -0.1))
 
 fig.shift_origin(xshift="w+1c")
 
@@ -224,7 +218,7 @@
     text="@@100 km",  # "@@" gives "@" in GMT or PyGMT
     position="TC",  # Top Center
     justify="MC",  # Middle Center
-    offset="0c/0.2c",
+    offset=(0, 0.2),
     no_clip=True,  # Allow plotting outside of the plot frame
 )
 

pygmt/src/text.py

@@ -25,7 +25,6 @@
 @fmt_docstring
 @use_alias(
     C="clearance",
-    D="offset",
     a="aspatial",
     e="find",
     f="coltypes",
@@ -45,6 +44,7 @@ def text(  # noqa: PLR0912, PLR0913, PLR0915
     fill: str | None = None,
     pen: str | None = None,
     justify: bool | None | AnchorCode | Sequence[AnchorCode] = None,
+    offset: Sequence[float | str] | str | None = None,
     no_clip: bool = False,
     projection: str | None = None,
     region: Sequence[float | str] | str | None = None,
@@ -77,6 +77,7 @@ def text(  # noqa: PLR0912, PLR0913, PLR0915
 
     $aliases
        - B = frame
+       - D = offset
        - F = **+a**: angle, **+c**: position, **+j**: justify, **+f**: font
        - G = fill
        - J = projection
@@ -157,16 +158,14 @@ def text(  # noqa: PLR0912, PLR0913, PLR0915
     pen
         Set the pen used to draw a rectangle around the text string (see ``clearance``)
         [Default is ``"0.25p,black,solid"``].
-    offset : str
-        [**j**\|\ **J**]\ *dx*\[/*dy*][**+v**\[*pen*]].
-        Offset the text from the projected (x, y) point by *dx*/\ *dy*
-        [Default is ``"0/0"``].
-        If *dy* is not specified then it is set equal to *dx*. Use **j** to
-        offset the text away from the point instead (i.e., the text
-        justification will determine the direction of the shift). Using
-        **J** will shorten diagonal offsets at corners by sqrt(2).
-        Optionally, append **+v** which will draw a line from the original
-        point to the shifted point; append a pen to change the attributes
+    offset
+        (*dx*, *dy*) or [**j**\|\ **J**]\ *dx*\[/*dy*][**+v**\[*pen*]].
+        Offset the text from the projected (x, y) point by (*dx*, *dy*) [Default is
+        (0, 0)]. If *dy* is not specified then it is set equal to *dx*. Use **j** to
+        offset the text away from the point instead (i.e., the text justification will
+        determine the direction of the shift). Using **J** will shorten diagonal offsets
+        at corners by sqrt(2). Optionally, append **+v** which will draw a line from
+        the original point to the shifted point; append a pen to change the attributes
         for this line.
     no_clip
         Do **not** clip text at the frame boundaries [Default is ``False``].
@@ -281,6 +280,7 @@ def text(  # noqa: PLR0912, PLR0913, PLR0915
                 )
 
     aliasdict = AliasSystem(
+        D=Alias(offset, name="offset", sep="/", size=2),
         G=Alias(fill, name="fill"),
         N=Alias(no_clip, name="no_clip"),
         W=Alias(pen, name="pen"),