From 7d29d568a5bfa510ee604c3c3ba98ddd5d1a8d48 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 1 Jan 2026 13:24:04 +0800
Subject: [PATCH 01/13] Update doc/techref/justification_codes.md

---
 doc/techref/justification_codes.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/doc/techref/justification_codes.md b/doc/techref/justification_codes.md
index 0dccd539360..15566aa9e77 100644
--- a/doc/techref/justification_codes.md
+++ b/doc/techref/justification_codes.md
@@ -25,6 +25,7 @@ tags: [remove-input]
 Script showing the justification codes used in GMT / PyGMT.
 """
 import pygmt
+from pygmt.params import Position
 
 size = 5
 x1 = [-size, 0, size, size, size, 0, -size, -size, 0]
@@ -105,7 +106,14 @@ Script showing justification codes for plot embellishments, e.g., a colorbar.
 fig = pygmt.Figure()
 fig.basemap(projection="X10c/2c", region=[-size, size, -size, size], frame=0)
 
-fig.colorbar(cmap="SCM/buda", frame=0, position="jMC+w10c/2c+h")
+fig.colorbar(
+    cmap="SCM/buda",
+    frame=0,
+    position="MC",
+    length=10,
+    width=2,
+    orientation="horizontal"
+)
 
 for code in codes:
     fig.text(

From 97c5c97d7d61b4565088ff66cc317c135c1ae678 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 1 Jan 2026 14:19:17 +0800
Subject: [PATCH 02/13] Update examples/tutorials/advanced/grid_equalization.py

---
 .../tutorials/advanced/grid_equalization.py   | 29 ++++++++++++++++---
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/examples/tutorials/advanced/grid_equalization.py b/examples/tutorials/advanced/grid_equalization.py
index 8ded7692c28..4017d49f4b7 100644
--- a/examples/tutorials/advanced/grid_equalization.py
+++ b/examples/tutorials/advanced/grid_equalization.py
@@ -8,6 +8,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 # %%
 # Load sample data
@@ -56,7 +57,12 @@
             histtype=1,
             pen="1p,black",
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 
@@ -125,7 +131,12 @@
             pen="1p,black",
             center=True,
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 
@@ -174,7 +185,12 @@
             histtype=1,
             pen="1p,black",
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 
@@ -239,7 +255,12 @@
             pen="1p,black",
             center=True,
         )
-        fig.colorbar(position="JMR+o1.5c/0c+w3c/0.3c", frame=True)
+        fig.colorbar(
+            position=Position("MR", cstype="outside", offset=(1.5, 0)),
+            length=3,
+            width=0.3,
+            frame=True,
+        )
 fig.show()
 
 # sphinx_gallery_thumbnail_number = 3

From 9495537a7ce95c427b2a5fa7d1b7cb0a1947de0b Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Thu, 1 Jan 2026 22:03:20 +0800
Subject: [PATCH 03/13] Update examples/gallery/3d_plots/grdview_surface.py

---
 examples/gallery/3d_plots/grdview_surface.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py
index cfbeca1f5a0..25f6e211c95 100644
--- a/examples/gallery/3d_plots/grdview_surface.py
+++ b/examples/gallery/3d_plots/grdview_surface.py
@@ -18,6 +18,7 @@
 import numpy as np
 import pygmt
 import xarray as xr
+from pygmt.helpers import Position
 
 
 # Define an interesting function of two variables, see:
@@ -46,8 +47,7 @@ def ackley(x, y):
 SCALE = 0.5  # in centimeters
 fig.grdview(
     data,
-    # Set annotations and gridlines in steps of five, and
-    # tick marks in steps of one
+    # Set annotations and gridlines in steps of five, and tick marks in steps of one
     frame=["a5f1g5", "za5f1g5"],
     projection=f"x{SCALE}c",
     zscale=f"{SCALE}c",
@@ -57,10 +57,10 @@ def ackley(x, y):
     shading="+a45",
 )
 
-# Add colorbar for gridded data
+# Add colorbar for gridded data at the Middle Right corner.
 fig.colorbar(
-    frame="a2f1",  # Set annotations in steps of two, tick marks in steps of one
-    position="JMR",  # Place colorbar in the Middle Right (MR) corner
+    frame="a2f1",
+    position=Position("MR", cstype="outside"),
 )
 
 fig.show()

From 3a5d8a1d7ee60485ae92c482780c5de159c1d96a Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 2 Jan 2026 16:50:31 +0800
Subject: [PATCH 04/13] Update examples/gallery/basemaps/ternary.py

---
 examples/gallery/basemaps/ternary.py | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/examples/gallery/basemaps/ternary.py b/examples/gallery/basemaps/ternary.py
index 7b225618154..aa72bd36343 100644
--- a/examples/gallery/basemaps/ternary.py
+++ b/examples/gallery/basemaps/ternary.py
@@ -14,6 +14,7 @@
 
 # %%
 import pygmt
+from pygmt.helpers import Position
 
 fig = pygmt.Figure()
 
@@ -40,7 +41,8 @@
     ],
 )
 
-# Add a colorbar indicating the values given in the fourth column of
-# the input dataset
-fig.colorbar(position="JBC+o0c/1.5c", frame="x+lPermittivity")
+# Add a colorbar indicating the values given in the fourth column of the input dataset
+fig.colorbar(
+    position=Position("BC", cstype="outside", offset=(0, 1.5)), frame="x+lPermittivity"
+)
 fig.show()

From 81229de12ad49b75b4003520c1ae5b6542f17ef0 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 2 Jan 2026 16:51:41 +0800
Subject: [PATCH 05/13] Update examples/gallery/images/grdlandmask.py

---
 examples/gallery/images/grdlandmask.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/examples/gallery/images/grdlandmask.py b/examples/gallery/images/grdlandmask.py
index 323b00392c9..da632c6618d 100644
--- a/examples/gallery/images/grdlandmask.py
+++ b/examples/gallery/images/grdlandmask.py
@@ -8,6 +8,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 fig = pygmt.Figure()
 
@@ -33,6 +34,6 @@
 pygmt.makecpt(cmap="SCM/batlow", series=(0, 1, 1), color_model="+cwater,land")
 
 fig.grdimage(grid=grid, cmap=True)
-fig.colorbar(position="JMR+o0.5c/0c+w8c")
+fig.colorbar(position=Position("MR", cstype="outside", offset=(0.5, 0)), width="8c")
 
 fig.show()

From 5b839855a40ce6196635da922cf4110e2d99b08b Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 2 Jan 2026 16:55:49 +0800
Subject: [PATCH 06/13] Update more examples

---
 examples/gallery/3d_plots/grdview_surface.py   | 2 +-
 examples/gallery/basemaps/ternary.py           | 2 +-
 examples/gallery/images/grdgradient_shading.py | 9 ++++++++-
 examples/gallery/images/grdlandmask.py         | 2 +-
 4 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py
index 25f6e211c95..e07f0711214 100644
--- a/examples/gallery/3d_plots/grdview_surface.py
+++ b/examples/gallery/3d_plots/grdview_surface.py
@@ -18,7 +18,7 @@
 import numpy as np
 import pygmt
 import xarray as xr
-from pygmt.helpers import Position
+from pygmt.params import Position
 
 
 # Define an interesting function of two variables, see:
diff --git a/examples/gallery/basemaps/ternary.py b/examples/gallery/basemaps/ternary.py
index aa72bd36343..91da1586837 100644
--- a/examples/gallery/basemaps/ternary.py
+++ b/examples/gallery/basemaps/ternary.py
@@ -14,7 +14,7 @@
 
 # %%
 import pygmt
-from pygmt.helpers import Position
+from pygmt.params import Position
 
 fig = pygmt.Figure()
 
diff --git a/examples/gallery/images/grdgradient_shading.py b/examples/gallery/images/grdgradient_shading.py
index 1763f9ee7f1..3845c546d44 100644
--- a/examples/gallery/images/grdgradient_shading.py
+++ b/examples/gallery/images/grdgradient_shading.py
@@ -20,6 +20,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 # Load the 3 arc-minutes global relief grid in the target area around Caucasus
 grid = pygmt.datasets.load_earth_relief(resolution="03m", region=[35, 50, 35, 45])
@@ -59,6 +60,12 @@
                 panel=True,
             )
 
-fig.colorbar(position="JBC+w10c/0.25c+h", frame="xa2000f500+lElevation (m)")
+fig.colorbar(
+    position=Position("BC", cstype="outside"),
+    length=10,
+    width=0.25,
+    orientation="horizontal",
+    frame="xa2000f500+lElevation (m)",
+)
 
 fig.show()
diff --git a/examples/gallery/images/grdlandmask.py b/examples/gallery/images/grdlandmask.py
index da632c6618d..808c2375aa8 100644
--- a/examples/gallery/images/grdlandmask.py
+++ b/examples/gallery/images/grdlandmask.py
@@ -34,6 +34,6 @@
 pygmt.makecpt(cmap="SCM/batlow", series=(0, 1, 1), color_model="+cwater,land")
 
 fig.grdimage(grid=grid, cmap=True)
-fig.colorbar(position=Position("MR", cstype="outside", offset=(0.5, 0)), width="8c")
+fig.colorbar(position=Position("MR", cstype="outside", offset=(0.5, 0)), length=8)
 
 fig.show()

From c377f6c2ffc0c15add8605df5da191e2575e89ab Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 2 Jan 2026 16:59:28 +0800
Subject: [PATCH 07/13] Update two examples

---
 examples/gallery/images/cross_section.py | 14 +++++++++-----
 examples/gallery/images/grdgradient.py   |  9 +++++++--
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
index d55f68574e1..a6707ece810 100644
--- a/examples/gallery/images/cross_section.py
+++ b/examples/gallery/images/cross_section.py
@@ -14,7 +14,7 @@
 
 # %%
 import pygmt
-from pygmt.params import Box
+from pygmt.params import Box, Position
 
 # Define region of study area
 # lon_min, lon_max, lat_min, lat_max in degrees East and North
@@ -41,10 +41,14 @@
 
 # Add a colorbar for the elevation
 fig.colorbar(
-    # Place the colorbar inside the plot (lowercase "j") in the Bottom Right (BR)
-    # corner with an offset ("+o") of 0.7 centimeters and 0.3 centimeters in x- or y-
-    # directions, respectively; move the x-label above the horizontal colorbar ("+ml")
-    position="jBR+o0.7c/0.8c+h+w5c/0.3c+ml",
+    # Place the colorbar inside the plot in the Bottom Right (BR) corner with an offset
+    # of 0.7 centimeters and 0.3 centimeters in x- or y-directions, respectively;
+    # move the x-label above the horizontal colorbar.
+    position=Position("BR", offset=(0.7, 0.8)),
+    length=5,
+    width=0.3,
+    orientation="horizontal",
+    move_text=["label"],
     # Add a box around the colobar, filled in white and a 30 % transparency, with a
     # 0.8-point thick, black, outline.
     box=Box(pen="0.8p,black", fill="white@30"),
diff --git a/examples/gallery/images/grdgradient.py b/examples/gallery/images/grdgradient.py
index 89ded87ca46..8fd4976eeb6 100644
--- a/examples/gallery/images/grdgradient.py
+++ b/examples/gallery/images/grdgradient.py
@@ -13,6 +13,7 @@
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 # Define region of interest around Yosemite valley
 region = [-119.825, -119.4, 37.6, 37.825]
@@ -37,8 +38,12 @@
     frame=["WSrt+tOriginal Data Elevation Model", "xa0.1", "ya0.1"],
     cmap=True,
 )
-
-fig.colorbar(position="JML+o1.4c/0c+w7c/0.5c", frame=["xa1000f500+lElevation", "y+lm"])
+fig.colorbar(
+    position=Position("ML", cstype="outside", offset=(1.4, 0)),
+    length=7,
+    width=0.5,
+    frame=["xa1000f500+lElevation", "y+lm"],
+)
 
 # --------------- plotting the hillshade map -----------
 

From 1e95469ed1a628dca597321075bcf47521689b94 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 7 Jan 2026 16:59:48 +0800
Subject: [PATCH 08/13] Fix examples/gallery/3d_plots/grdview_surface.py

---
 examples/gallery/3d_plots/grdview_surface.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py
index e07f0711214..535203fbe2d 100644
--- a/examples/gallery/3d_plots/grdview_surface.py
+++ b/examples/gallery/3d_plots/grdview_surface.py
@@ -58,9 +58,6 @@ def ackley(x, y):
 )
 
 # Add colorbar for gridded data at the Middle Right corner.
-fig.colorbar(
-    frame="a2f1",
-    position=Position("MR", cstype="outside"),
-)
+fig.colorbar(frame="a2f1", position=Position("MR", cstype="outside"))
 
 fig.show()

From 27021ab505528fc67b0023ea4685f068ad881ac1 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 7 Jan 2026 17:17:10 +0800
Subject: [PATCH 09/13] Update more examples

---
 examples/gallery/embellishments/colorbar.py   | 62 +++++++++----------
 examples/gallery/images/grdclip.py            | 15 +++--
 examples/gallery/maps/choropleth_map.py       | 10 ++-
 .../advanced/draping_on_3d_surface.py         |  2 +-
 4 files changed, 49 insertions(+), 40 deletions(-)

diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py
index 24bcd304129..07a653f4185 100644
--- a/examples/gallery/embellishments/colorbar.py
+++ b/examples/gallery/embellishments/colorbar.py
@@ -2,30 +2,18 @@
 Colorbar
 ========
 
-The :meth:`pygmt.Figure.colorbar` method creates a color scalebar.
-The colormap is set via the ``cmap`` parameter. A full list of available
-color palette tables can be found at :gmt-docs:`reference/cpts.html`.
-Use the ``frame`` parameter to add labels to the **x** and **y** axes
-of the colorbar by appending **+l** followed by the desired text. To add
-and adjust the annotations (**a**) and ticks (**f**) append the letter
-followed by the desired interval. The placement of the colorbar is set
-via the ``position`` parameter. There are the following options:
-
-- **j/J**: placed inside/outside the plot bounding box using a
-  :doc:`2-character justification code </techref/justification_codes>`, e.g.,
-  ``position="jTR"`` for Top Right.
-- **g**: using map coordinates, e.g. ``position="g170/-45"`` for longitude
-  170° East, latitude 45° South.
-- **x**: using paper coordinates, e.g. ``position="x5c/7c"`` for 5 cm, 7 cm
-  from anchor point.
-- **n**: using normalized (0-1) coordinates, e.g. ``position="n0.4/0.8"``.
-
-Note that the anchor point defaults to Bottom Left (**BL**). Append ``+h`` to
-``position`` to get a horizontal colorbar instead of a vertical one (``+v``).
+The :meth:`pygmt.Figure.colorbar` method creates a color scalebar. The colormap is set
+via the ``cmap`` parameter. A full list of available color palette tables can be found
+at :gmt-docs:`reference/cpts.html`. Use the ``frame`` parameter to add labels to the
+**x** and **y** axes of the colorbar by appending **+l** followed by the desired text.
+To add and adjust the annotations (**a**) and ticks (**f**) append the letter followed
+by the desired interval. The placement of the colorbar is set by passing a
+:class:`pygmt.params.Position` object to the ``position`` parameter.
 """
 
 # %%
 import pygmt
+from pygmt.params import Position
 
 fig = pygmt.Figure()
 fig.basemap(region=[0, 3, 6, 9], projection="x3c", frame=["af", "WSne+tColorbars"])
@@ -41,9 +29,12 @@
 # Create a colorbar showing the scientific rainbow - batlow
 fig.colorbar(
     cmap="SCM/batlow",
-    # Colorbar positioned at map coordinates (g) longitude/latitude 0.3/8.7,
-    # with a length/width (+w) of 4 cm by 0.5 cm, and plotted horizontally (+h)
-    position="g0.3/8.7+w4c/0.5c+h",
+    # A horizontal colorbar positioned at map coordinates (0.3, 8.7), with a
+    # length of 4 cm and width of 0.5 cm.
+    position=Position((0.3, 8.7), cstype="mapcoords"),
+    length=4,
+    width=0.5,
+    orientation="horizontal",
     box=True,
     frame=["x+lTemperature", "y+l°C"],
     scale=100,
@@ -53,13 +44,17 @@
 # Create a colorbar suitable for surface topography - oleron
 fig.colorbar(
     cmap="SCM/oleron",
-    # Colorbar placed outside the plot bounding box (J) at Middle Right (MR),
-    # offset (+o) by 1 cm horizontally and 0 cm vertically from anchor point,
-    # with a length/width (+w) of 7 cm by 0.5 cm and a box for NaN values (+n)
-    position="JMR+o1c/0c+w7c/0.5c+n+mc",
+    # Colorbar placed at Middle Right (MR) outside the plot bounding box, offset by 1 cm
+    # horizontally and 0 cm vertically from anchor point, with a length of 7 cm and
+    # width of 0.5 cm, and a rectangle for NaN values.
     # Note that the label 'Elevation' is moved to the opposite side and plotted
-    # vertically as a column of text using '+mc' in the position parameter
-    # above
+    # vertically as a column of text.
+    position=Position("MR", cstype="outside", offset=(1, 0)),
+    length=7,
+    width=0.5,
+    nan_rectangle=True,
+    move_text=["annotations", "label"],
+    label_as_column=True,
     frame=["x+lElevation", "y+lm"],
     scale=10,
 )
@@ -76,10 +71,11 @@
 # Plot the colorbar
 fig.colorbar(
     cmap=True,  # Use colormap set up above
-    # Colorbar placed inside the plot bounding box (j) in the Bottom Left (BL) corner,
-    # with an offset (+o) by 0.5 cm horizontally and 0.8 cm vertically from the anchor
-    # point, and plotted horizontally (+h)
-    position="jBL+o0.5c/0.8c+h",
+    # Colorbar placed at the Bottom Left (BL) corner inside the plot bounding box, with
+    # an offset by 0.5 cm horizontally and 0.8 cm vertically from the anchor point, and
+    # plotted horizontally.
+    position=Position("BL", offset=(0.5, 0.8)),
+    orientation="horizontal",
     box=True,
     # Divide colorbar into equal-sized rectangles
     equalsize=0.5,
diff --git a/examples/gallery/images/grdclip.py b/examples/gallery/images/grdclip.py
index b034c20223a..522e6e3dba0 100644
--- a/examples/gallery/images/grdclip.py
+++ b/examples/gallery/images/grdclip.py
@@ -2,14 +2,15 @@
 Clipping grid values
 ====================
 
-The :func:`pygmt.grdclip` function allows to clip defined ranges of grid
-values. In the example shown below we set all elevation values (grid points)
-smaller than 0 m (in general the bathymetric part of the grid) to a common
-value of -2000 m via the ``below`` parameter.
+The :func:`pygmt.grdclip` function allows to clip defined ranges of grid values. In the
+example shown below we set all elevation values (grid points) smaller than 0 m (in
+general the bathymetric part of the grid) to a common value of -2000 m via the ``below``
+parameter.
 """
 
 # %%
 import pygmt
+from pygmt.params.position import Position
 
 fig = pygmt.Figure()
 
@@ -41,6 +42,10 @@
     frame=["wSne+tclipped grid", "xa5f1", "ya2f1"],
 )
 fig.grdimage(grid=grid)
-fig.colorbar(frame=["x+lElevation", "y+lm"], position="JMR+o0.5c/0c+w8c")
+fig.colorbar(
+    frame=["x+lElevation", "y+lm"],
+    position=Position("MR", cstype="outside", offset=(0.5, 0)),
+    length=8,
+)
 
 fig.show()
diff --git a/examples/gallery/maps/choropleth_map.py b/examples/gallery/maps/choropleth_map.py
index 9eb3b05bece..dbf4d49fb2d 100644
--- a/examples/gallery/maps/choropleth_map.py
+++ b/examples/gallery/maps/choropleth_map.py
@@ -16,6 +16,7 @@
 # %%
 import geopandas as gpd
 import pygmt
+from pygmt.params.position import Position
 
 provider = "https://naciscdn.org/naturalearth"
 world = gpd.read_file(f"{provider}/110m/cultural/ne_110m_admin_0_countries.zip")
@@ -36,6 +37,13 @@
 fig.plot(data=africa, pen="0.8p,gray50", fill="+z", cmap=True, aspatial="Z=POP_EST")
 
 # Add colorbar legend.
-fig.colorbar(frame="x+lPopulation (millions)", position="jML+o2c/-2.5c+w5c+ef0.2c+ml")
+fig.colorbar(
+    frame="x+lPopulation (millions)",
+    position=Position("ML", offset=(2, -2.5)),
+    length=5,
+    sidebar_triangles="foreground",
+    sidebar_triangles_height=0.2,
+    move_text=["label"],
+)
 
 fig.show()
diff --git a/examples/tutorials/advanced/draping_on_3d_surface.py b/examples/tutorials/advanced/draping_on_3d_surface.py
index 31e82c47a29..6be9cfe5d07 100644
--- a/examples/tutorials/advanced/draping_on_3d_surface.py
+++ b/examples/tutorials/advanced/draping_on_3d_surface.py
@@ -70,7 +70,7 @@
 )
 
 # Add colorbar for the crustal age
-fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], position="+n")
+fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], nan_rectangle=True)
 
 fig.show()
 

From 1bfc5c6a0d0aa83b082d5e3cb44d1cea9999da60 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Wed, 7 Jan 2026 21:10:12 +0800
Subject: [PATCH 10/13] Rename nan_rectangle to nan

---
 examples/gallery/embellishments/colorbar.py          | 2 +-
 examples/tutorials/advanced/draping_on_3d_surface.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py
index 07a653f4185..8fb23e47880 100644
--- a/examples/gallery/embellishments/colorbar.py
+++ b/examples/gallery/embellishments/colorbar.py
@@ -52,7 +52,7 @@
     position=Position("MR", cstype="outside", offset=(1, 0)),
     length=7,
     width=0.5,
-    nan_rectangle=True,
+    nan=True,
     move_text=["annotations", "label"],
     label_as_column=True,
     frame=["x+lElevation", "y+lm"],
diff --git a/examples/tutorials/advanced/draping_on_3d_surface.py b/examples/tutorials/advanced/draping_on_3d_surface.py
index 6be9cfe5d07..c30f1046d48 100644
--- a/examples/tutorials/advanced/draping_on_3d_surface.py
+++ b/examples/tutorials/advanced/draping_on_3d_surface.py
@@ -70,7 +70,7 @@
 )
 
 # Add colorbar for the crustal age
-fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], nan_rectangle=True)
+fig.colorbar(frame=["x+lseafloor crustal age", "y+lMyr"], nan=True)
 
 fig.show()
 

From fc08af4d66c7c8279d2d219fb6c7e3a32ebf2558 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 9 Jan 2026 11:59:25 +0800
Subject: [PATCH 11/13] Fix sidebar_triangles

---
 examples/gallery/maps/choropleth_map.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/gallery/maps/choropleth_map.py b/examples/gallery/maps/choropleth_map.py
index dbf4d49fb2d..32221d41ae1 100644
--- a/examples/gallery/maps/choropleth_map.py
+++ b/examples/gallery/maps/choropleth_map.py
@@ -41,9 +41,9 @@
     frame="x+lPopulation (millions)",
     position=Position("ML", offset=(2, -2.5)),
     length=5,
-    sidebar_triangles="foreground",
-    sidebar_triangles_height=0.2,
-    move_text=["label"],
+    fg_triangle=True,
+    triangle_height=0.2,
+    move_text="label",
 )
 
 fig.show()

From 8b718eab02ba335b9feeaeca64b944c40df4254a Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 9 Jan 2026 12:00:55 +0800
Subject: [PATCH 12/13] Simplify move_text

---
 examples/gallery/images/cross_section.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/gallery/images/cross_section.py b/examples/gallery/images/cross_section.py
index a6707ece810..053b1ba6bd3 100644
--- a/examples/gallery/images/cross_section.py
+++ b/examples/gallery/images/cross_section.py
@@ -48,7 +48,7 @@
     length=5,
     width=0.3,
     orientation="horizontal",
-    move_text=["label"],
+    move_text="label",
     # Add a box around the colobar, filled in white and a 30 % transparency, with a
     # 0.8-point thick, black, outline.
     box=Box(pen="0.8p,black", fill="white@30"),

From 3f37b0c0383846ea2e307153a6acff6830b881c9 Mon Sep 17 00:00:00 2001
From: Dongdong Tian <seisman.info@gmail.com>
Date: Fri, 9 Jan 2026 17:53:36 +0800
Subject: [PATCH 13/13] Apply suggestions from code review

Co-authored-by: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
---
 examples/gallery/3d_plots/grdview_surface.py | 2 +-
 examples/gallery/embellishments/colorbar.py  | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/gallery/3d_plots/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py
index 535203fbe2d..b01b16c5185 100644
--- a/examples/gallery/3d_plots/grdview_surface.py
+++ b/examples/gallery/3d_plots/grdview_surface.py
@@ -57,7 +57,7 @@ def ackley(x, y):
     shading="+a45",
 )
 
-# Add colorbar for gridded data at the Middle Right corner.
+# Add colorbar for gridded data in the Middle Right corner.
 fig.colorbar(frame="a2f1", position=Position("MR", cstype="outside"))
 
 fig.show()
diff --git a/examples/gallery/embellishments/colorbar.py b/examples/gallery/embellishments/colorbar.py
index 8fb23e47880..595e3c7625f 100644
--- a/examples/gallery/embellishments/colorbar.py
+++ b/examples/gallery/embellishments/colorbar.py
@@ -30,7 +30,7 @@
 fig.colorbar(
     cmap="SCM/batlow",
     # A horizontal colorbar positioned at map coordinates (0.3, 8.7), with a
-    # length of 4 cm and width of 0.5 cm.
+    # length of 4 cm and a width of 0.5 cm.
     position=Position((0.3, 8.7), cstype="mapcoords"),
     length=4,
     width=0.5,
@@ -71,7 +71,7 @@
 # Plot the colorbar
 fig.colorbar(
     cmap=True,  # Use colormap set up above
-    # Colorbar placed at the Bottom Left (BL) corner inside the plot bounding box, with
+    # Colorbar placed in the Bottom Left (BL) corner inside the plot bounding box, with
     # an offset by 0.5 cm horizontally and 0.8 cm vertically from the anchor point, and
     # plotted horizontally.
     position=Position("BL", offset=(0.5, 0.8)),