From cc9ca1317a30c315528d2a4fa66814a8b752408a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Sun, 1 Feb 2026 19:35:59 +0100 Subject: [PATCH 1/4] Update scalebar example to used highlevel method --- examples/gallery/embellishments/scalebar.py | 75 +++++++-------------- 1 file changed, 26 insertions(+), 49 deletions(-) diff --git a/examples/gallery/embellishments/scalebar.py b/examples/gallery/embellishments/scalebar.py index 569d3131ae5..3674b793caa 100644 --- a/examples/gallery/embellishments/scalebar.py +++ b/examples/gallery/embellishments/scalebar.py @@ -1,48 +1,14 @@ -r""" +""" Scale bar ========= -The ``map_scale`` parameter of the :meth:`pygmt.Figure.basemap` and -:meth:`pygmt.Figure.coast` methods is used to add a scale bar to a map. -This example shows how such a scale bar can be customized: - - - position: **g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**. Set the position - of the reference point. Choose from - - - **g**: Give map coordinates as *longitude*\/\ *latitude*. - - **j**\|\ **J**: Specify a - :doc:`2-character justification code `. - Lower / uppercase **j** / **J** mean inside / outside of the map - bounding box. - - **n**: Give normalized bounding box coordinates as *nx*\/\ *ny*. - - **x**: Give plot coordinates as *x*\/\ *y*. - - - length: **+w**. Give a distance value, and, optionally a distance unit. - Choose from **e** (meters), **f** (feet), **k** (kilometers) [Default], - **M** (statute miles), **n** (nautical miles), or **u** (US survey feet). - - origin: **+c**\ [*slon*/]\ *slat*. Control where on the map the scale bar - applies. If **+c** is not given the reference point is used. If only - **+c** is appended the middle of the map is used. Note that *slon* is only - optional for projections with constant scale along parallels, e.g., - Mercator projection. - - justify: **+j**. Set the anchor point. Specify a - :doc:`2-character justification code `. - - offset: **+o**\ *offset* or **+o**\ *xoffset*/\ *yoffset*. Give either a - common shift or individual shifts in x- (longitude) and y- (latitude) - directions. - - height: Use :gmt-term:`MAP_SCALE_HEIGHT` via :func:`pygmt.config`. - - fancy style: **+f**. Get a scale bar that looks like train tracks. - - unit: **+u**. Add the distance unit given via **+w** to the single - distance values. - - label: **+l**. Add the distance unit given via **+w** as label. Append - text to get a customized label instead. - - alignment: **+a**. Set the label alignment. Choose from **t**\(op) - [Default], **b**\(ottom), **l**\(eft), or **r**\(ight). +The the :meth:`pygmt.Figure.scalebar` method can be used to add a scale bar +to a map. This example shows how such a scale bar can be customized. """ # %% import pygmt -from pygmt.params import Box +from pygmt.params import Box, Position # Create a new Figure instance fig = pygmt.Figure() @@ -55,14 +21,16 @@ # It is placed based on geographic coordinates (g) 42° West and 1° South, # applies at the reference point (+c is not given), and represents a # length (+w) of 500 kilometers -fig.basemap(map_scale="g-42/-1+w500k") +# fig.basemap(map_scale="g-42/-1+w500k") +fig.scalebar(length="500k", position=Position()) # ----------------------------------------------------------------------------- # Top Right: Add a fancy scale bar # It is placed based on normalized bounding box coordinates (n) # Use a fancy style (+f) to get a scale bar that looks like train tracks # Add the distance unit (+u) to the single distance values -fig.basemap(map_scale="n0.8/0.95+w500k+f+u") +# fig.basemap(map_scale="n0.8/0.95+w500k+f+u") +fig.scalebar(length="500k", fancy=True, position=Position()) # ----------------------------------------------------------------------------- # Bottom Left: Add a thick scale bar @@ -71,14 +39,24 @@ # It applies (+c) at the middle of the map (no location is appended to +c) # Without appending text, +l adds the distance unit as label with pygmt.config(MAP_SCALE_HEIGHT="10p"): - fig.basemap(map_scale="n0.2/0.15+c+w500k+f+l") + # fig.basemap(map_scale="n0.2/0.15+c+w500k+f+l") + fig.scalebar( + length="500k", + fancy=True, + position=Position(), + ) # ----------------------------------------------------------------------------- # Bottom Right: Add a scale bar valid for a specific location # It is placed at BottomRight (j) using MiddleRight as anchor point (+j) with # an offset (+o) of 1 centimeter in both x- and y-directions # It applies (+c) at -7° South, add a customized label by appending text to +l -fig.basemap(map_scale="jBR+jMR+o1c/1c+c-7+w500k+f+u+lvalid at 7° S") +# fig.basemap(map_scale="jBR+jMR+o1c/1c+c-7+w500k+f+u+lvalid at 7° S") +fig.scalebar( + length="500k", + fancy=True, + position=Position("BR", anchor="MR", offset=1), +) fig.show() @@ -93,14 +71,13 @@ # Create a new Figure instance fig = pygmt.Figure() -fig.coast( - region=[-45, -25, -15, 0], - projection="M10c", - land="tan", - water="steelblue", - frame=["WSne", "af"], +fig.basemap(region=[-45, -25, -15, 0], projection="M10c", frame=["WSne", "af"]) +fig.coast(land="tan", water="steelblue") +fig.scalebar( + length="500k", # Set the label alignment (+a) to right (r) - map_scale="jBL+o1c/1c+c-7+w500k+f+lkm+ar", + # map_scale="jBL+o1c/1c+c-7+w500k+f+lkm+ar", + fancy=True, # Fill the box in white with a transparency of 30 percent, add a solid # outline in darkgray (gray30) with a thickness of 0.5 points, and use # rounded edges with a radius of 3 points From 9edb23020ad4a4de0162b467e59777b80f611cb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Sun, 1 Feb 2026 21:50:11 +0100 Subject: [PATCH 2/4] Translate more modifieres, adjust comments --- examples/gallery/embellishments/scalebar.py | 55 ++++++++++++--------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/examples/gallery/embellishments/scalebar.py b/examples/gallery/embellishments/scalebar.py index 3674b793caa..b658e60ae6e 100644 --- a/examples/gallery/embellishments/scalebar.py +++ b/examples/gallery/embellishments/scalebar.py @@ -18,55 +18,63 @@ # ----------------------------------------------------------------------------- # Top Left: Add a plain scale bar -# It is placed based on geographic coordinates (g) 42° West and 1° South, -# applies at the reference point (+c is not given), and represents a -# length (+w) of 500 kilometers +# It is placed based on geographic coordinates 42° West and 1° South, +# applies at the reference point (scale_loc not specified) and represents a +# length of 500 kilometers # fig.basemap(map_scale="g-42/-1+w500k") -fig.scalebar(length="500k", position=Position()) +fig.scalebar(length="500k", position=Position((-42, -1), cstype="mapcoords")) # ----------------------------------------------------------------------------- # Top Right: Add a fancy scale bar -# It is placed based on normalized bounding box coordinates (n) -# Use a fancy style (+f) to get a scale bar that looks like train tracks -# Add the distance unit (+u) to the single distance values +# It is placed based on normalized bounding box coordinates +# Use a fancy style to get a scale bar that looks like train tracks +# Add the distance unit to the single distance values # fig.basemap(map_scale="n0.8/0.95+w500k+f+u") -fig.scalebar(length="500k", fancy=True, position=Position()) +fig.scalebar( + position=Position((0.8, 0.95), cstype="boxcoords"), + length="500k", + fancy=True, + unit=True, +) # ----------------------------------------------------------------------------- # Bottom Left: Add a thick scale bar # Adjust the GMT default parameter MAP_SCALE_HEIGHT locally (the change applies # only to the code within the "with" statement) -# It applies (+c) at the middle of the map (no location is appended to +c) -# Without appending text, +l adds the distance unit as label +# It applies at the middle of the map (no location is passed to scale_loc) +# Without providing a text, the label parameter adds the distance unit as label with pygmt.config(MAP_SCALE_HEIGHT="10p"): # fig.basemap(map_scale="n0.2/0.15+c+w500k+f+l") fig.scalebar( + position=Position((0.2, 0.15), cstype="boxcoords"), + scale_loc=True, length="500k", fancy=True, - position=Position(), + label=True, ) # ----------------------------------------------------------------------------- # Bottom Right: Add a scale bar valid for a specific location -# It is placed at BottomRight (j) using MiddleRight as anchor point (+j) with -# an offset (+o) of 1 centimeter in both x- and y-directions -# It applies (+c) at -7° South, add a customized label by appending text to +l +# It is placed at BottomRight using MiddleRight as anchor point with an offset +# of 1 centimeter in both x- and y-directions +# It applies at -7° South +# A customized label is added via the label parameter # fig.basemap(map_scale="jBR+jMR+o1c/1c+c-7+w500k+f+u+lvalid at 7° S") fig.scalebar( + position=Position("BR", anchor="MR", offset=1), + scale_loc=-7, length="500k", fancy=True, - position=Position("BR", anchor="MR", offset=1), + unit=True, + label="valid at 7° S", ) fig.show() # %% -# The ``box`` parameter allows surrounding the scale bar. This can be useful -# when adding a scale bar to a colorful map. To fill the box, append **+g** -# with the desired color (or pattern). The outline of the box can be adjusted -# by appending **+p** with the desired thickness, color, and style. To force -# rounded edges append **+r** with the desired radius. +# The ``box`` parameter allows surrounding the scale bar. This can be useful when +# adding a scale bar to a colorful map to improve the contrast and readability. # Create a new Figure instance fig = pygmt.Figure() @@ -74,10 +82,13 @@ fig.basemap(region=[-45, -25, -15, 0], projection="M10c", frame=["WSne", "af"]) fig.coast(land="tan", water="steelblue") fig.scalebar( - length="500k", - # Set the label alignment (+a) to right (r) # map_scale="jBL+o1c/1c+c-7+w500k+f+lkm+ar", + position=Position("BL", cstype="inside", offset=1), + scale_loc=-7, + length="500k", fancy=True, + label="km", + label_alignment="right", # Fill the box in white with a transparency of 30 percent, add a solid # outline in darkgray (gray30) with a thickness of 0.5 points, and use # rounded edges with a radius of 3 points From 81dbf7007ebf3b6b102fe9838c1fb500713ff132 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 2 Feb 2026 20:27:11 +0100 Subject: [PATCH 3/4] Improve comments --- examples/gallery/embellishments/scalebar.py | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/examples/gallery/embellishments/scalebar.py b/examples/gallery/embellishments/scalebar.py index b658e60ae6e..066c60495dd 100644 --- a/examples/gallery/embellishments/scalebar.py +++ b/examples/gallery/embellishments/scalebar.py @@ -2,8 +2,8 @@ Scale bar ========= -The the :meth:`pygmt.Figure.scalebar` method can be used to add a scale bar -to a map. This example shows how such a scale bar can be customized. +The the :meth:`pygmt.Figure.scalebar` method can be used to add a scale bar to a map. +This example shows how such a scale bar can be customized. """ # %% @@ -19,8 +19,8 @@ # ----------------------------------------------------------------------------- # Top Left: Add a plain scale bar # It is placed based on geographic coordinates 42° West and 1° South, -# applies at the reference point (scale_loc not specified) and represents a -# length of 500 kilometers +# applies at the reference point (scale_loc is not used and by default False), and +# represents a length of 500 kilometers # fig.basemap(map_scale="g-42/-1+w500k") fig.scalebar(length="500k", position=Position((-42, -1), cstype="mapcoords")) @@ -41,7 +41,7 @@ # Bottom Left: Add a thick scale bar # Adjust the GMT default parameter MAP_SCALE_HEIGHT locally (the change applies # only to the code within the "with" statement) -# It applies at the middle of the map (no location is passed to scale_loc) +# It applies at the middle of the map (scale_loc is set to True) # Without providing a text, the label parameter adds the distance unit as label with pygmt.config(MAP_SCALE_HEIGHT="10p"): # fig.basemap(map_scale="n0.2/0.15+c+w500k+f+l") @@ -74,9 +74,8 @@ # %% # The ``box`` parameter allows surrounding the scale bar. This can be useful when -# adding a scale bar to a colorful map to improve the contrast and readability. +# adding a scale bar to a colorful map to improve contrast and readability. -# Create a new Figure instance fig = pygmt.Figure() fig.basemap(region=[-45, -25, -15, 0], projection="M10c", frame=["WSne", "af"]) From 0fdf35246bfba3320a3fc1a5cd00aed6409b0b90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yvonne=20Fr=C3=B6hlich?= Date: Mon, 2 Feb 2026 20:29:18 +0100 Subject: [PATCH 4/4] Remove old codes --- examples/gallery/embellishments/scalebar.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/examples/gallery/embellishments/scalebar.py b/examples/gallery/embellishments/scalebar.py index 066c60495dd..7ebc260a9f5 100644 --- a/examples/gallery/embellishments/scalebar.py +++ b/examples/gallery/embellishments/scalebar.py @@ -21,7 +21,6 @@ # It is placed based on geographic coordinates 42° West and 1° South, # applies at the reference point (scale_loc is not used and by default False), and # represents a length of 500 kilometers -# fig.basemap(map_scale="g-42/-1+w500k") fig.scalebar(length="500k", position=Position((-42, -1), cstype="mapcoords")) # ----------------------------------------------------------------------------- @@ -29,7 +28,6 @@ # It is placed based on normalized bounding box coordinates # Use a fancy style to get a scale bar that looks like train tracks # Add the distance unit to the single distance values -# fig.basemap(map_scale="n0.8/0.95+w500k+f+u") fig.scalebar( position=Position((0.8, 0.95), cstype="boxcoords"), length="500k", @@ -44,7 +42,6 @@ # It applies at the middle of the map (scale_loc is set to True) # Without providing a text, the label parameter adds the distance unit as label with pygmt.config(MAP_SCALE_HEIGHT="10p"): - # fig.basemap(map_scale="n0.2/0.15+c+w500k+f+l") fig.scalebar( position=Position((0.2, 0.15), cstype="boxcoords"), scale_loc=True, @@ -59,7 +56,6 @@ # of 1 centimeter in both x- and y-directions # It applies at -7° South # A customized label is added via the label parameter -# fig.basemap(map_scale="jBR+jMR+o1c/1c+c-7+w500k+f+u+lvalid at 7° S") fig.scalebar( position=Position("BR", anchor="MR", offset=1), scale_loc=-7, @@ -81,7 +77,6 @@ fig.basemap(region=[-45, -25, -15, 0], projection="M10c", frame=["WSne", "af"]) fig.coast(land="tan", water="steelblue") fig.scalebar( - # map_scale="jBL+o1c/1c+c-7+w500k+f+lkm+ar", position=Position("BL", cstype="inside", offset=1), scale_loc=-7, length="500k",