Add Figure.scalebar to plot a scale bar on maps #4015

seisman · 2025-07-26T07:23:12Z

This PR implements the Figure.scalebar method, which wraps the -L option in basemap/coast. Related to #4268.

The full syntax of -L is:

-L[g|j|J|n|x]refpoint+wlength[e|f|k|M|n|u][+aalign][+c[[slon/]slat]][+f][+jjustify][+l[label]][+odx[/dy]][+u][+v]

Here is a comparison of names used in PyGMT, GMT, and GMT.jl:

modifier	PyGMT	GMT	GMT.jl
+w	length	length	length
+a	label_alignment	align	align
+c	scale_loc	loc	scale_at_lat
+l	label	label	label
+u	unit	units	units
+v	vertical	vertical	vertical

Preview: https://pygmt-dev--4015.org.readthedocs.build/en/4015/api/generated/pygmt.Figure.scalebar.html#pygmt.Figure.scalebar

Related to #4268

TODO in separate PRs

Update gallery examples using the new scalebar method
Deprecate map_scale in Figure.coast/Figure.basemap Figure.basemap/Figure.coast: Recommend to use the Figure.scalebar method to add a scalebar #4337
Update the example in the paper Figure 3: Update with the Figure.scalebar method pygmt-paper-figures#28

github-actions · 2025-12-09T16:13:33Z

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
added	pygmt/tests/baseline/test_scalebar.png
added	pygmt/tests/baseline/test_scalebar_cartesian.png
added	pygmt/tests/baseline/test_scalebar_complete.png

Image diff(s)

Details

Added images

test_scalebar.png

test_scalebar_cartesian.png

test_scalebar_complete.png

Modified images

Path	Old	New

Report last updated at commit cc40c8f

pygmt/src/scalebar.py

seisman · 2025-12-11T11:45:46Z

pygmt/src/scalebar.py

+    length: float | str | None = None,
+    scale_position: float | Sequence[float] | bool = False,
+    label: str | bool = False,
+    label_alignment: Literal["left", "right", "top", "bottom"] | None = None,


GMT and GMT.jl use align, currently PyGMT uses label_alignment, but maybe label_position?

I feel label_position is more consisten, as we have nan_position for Figure.colorbar. And it is a bit shorter.

pygmt/src/scalebar.py

seisman · 2025-12-18T09:33:40Z

I think this PR is ready for review.

The key points we need to agree on (or explicitly discuss) are:

This method wraps the -L option of basemap/coast, so there is no corresponding standalone GMT module. For this reason, I prefer not to add common parameters such as projection, zsize, zscale, frame, or region to this method.
Parameter name for +a: align (GMT/GMT.jl) vs label_alignment (PyGMT). An alternative could be label_position.
Parameter name for +c: loc (GMT) vs scale_at_lat (GMT.jl) vs scale_position (PyGMT). Possible alternatives include scale_location or scale_lonlat. [Changed to scale_at following ChatGPT's recommendation]
Parameter name for +u: units (GMT/GMT.jl) vs unit (PyGMT). I think unit is the more appropriate choice.
The GMT configuration MAP_SCALE_HEIGHT controls the height of the fancy scalebar. Here it is exposed as a height parameter so users do not need to call pygmt.config.
Default position of the scalebar: by default, GMT places it at x0/0, which is often not ideal (see below). A more visually pleasing default is jBL+o0.2c/0.4c (bottom-left with offsets). While the optimal offsets depend on the plot dimensions, this works well for a reasonably sized (~15 cm wide) plot.

gmt begin map png
	gmt basemap -R100/120/30/40 -JM15c -Baf
	gmt basemap -L+w500
	gmt basemap -LjBL+o0.2/0.4+w500
gmt end show

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

pygmt/src/scalebar.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

pygmt/src/scalebar.py

yvonnefroehlich · 2026-01-17T13:51:30Z

pygmt/src/scalebar.py

+    length: float | str,
+    height: float | str | None = None,
+    position: Position | Sequence[float | str] | AnchorCode | None = None,
+    scale_at: float | Sequence[float] | bool = False,


Hm. I do not really like this name.

GMT uses loc, GMT.jl uses scale_at_lat.

An alternative name may be scale_loc?

Not so easy finding a good name here. I was thinking about something in the direction of

reference_coords: a bit long

reference_lat, scale_lat: partly also the longitude is given

Maybe location is enough, as "scale" is already contained in the method name "scalebar"?

I feel users may be confused by position and location

Hm, this is something I was also a bit unsure about. Maybe there are ideas or preferences by @weiji14 and @michaelgrund?

I think scale_loc is the best name we have so far:

not too long

location can be all, latitude, longitude, middle of the map, reference point

"loc" as a shortcut for "location" should be OK

the leading "scale" should reduce a potential confusion with position

OK. Done in 0561ba4.

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

pygmt/src/scalebar.py

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

pygmt/src/scalebar.py

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

pygmt/src/scalebar.py

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

seisman · 2026-01-20T03:12:25Z

I'll merge this PR in 24 hours if no further comments.

yvonnefroehlich · 2026-01-20T10:26:21Z

The gallery example (https://www.pygmt.org/dev/gallery/embellishments/scalebar.html) is updated in a separate PR, like for Figure.colorbar?

seisman · 2026-01-20T10:40:57Z

The gallery example (https://www.pygmt.org/dev/gallery/embellishments/scalebar.html) is updated in a separate PR, like for Figure.colorbar?

Yes, too keep this PR small

pygmt/src/scalebar.py

yvonnefroehlich · 2026-01-20T22:47:12Z

pygmt/src/scalebar.py

+    length: float | str | None = None,
+    scale_position: float | Sequence[float] | bool = False,
+    label: str | bool = False,
+    label_alignment: Literal["left", "right", "top", "bottom"] | None = None,


I feel label_position is more consisten, as we have nan_position for Figure.colorbar. And it is a bit shorter.

yvonnefroehlich

Made two more comments.
Besides this, this PR looks good to me.

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

seisman · 2026-01-21T02:45:20Z

I feel label_position is more consisten, as we have nan_position for Figure.colorbar. And it is a bit shorter.

label_alignment is already used in Figure.wiggle. So I prefer to keep it consistent.

seisman · 2026-01-21T02:47:59Z

I'm merging this PR. We can still change the parameter names before releasing v0.19.0.

yvonnefroehlich · 2026-01-21T09:59:46Z

I feel label_position is more consisten, as we have nan_position for Figure.colorbar. And it is a bit shorter.

label_alignment is already used in Figure.wiggle. So I prefer to keep it consistent.

OK, consistency with Figure.wiggle is important.

seisman · 2026-01-23T12:32:20Z

Update gallery examples using the new scalebar method

@yvonnefroehlich Please let me know if you're interested in updating the gallery example https://www.pygmt.org/dev/gallery/embellishments/scalebar.html.

seisman mentioned this pull request Jul 26, 2025

POC: Implement the new alias system, general parameter classes and some refactors #3238

Closed

Base automatically changed from AliasSystem/aliassystem to main July 29, 2025 04:09

seisman force-pushed the feature/scalebar branch 3 times, most recently from 7a276b0 to ec9b800 Compare July 29, 2025 06:57

seisman added the feature Brand new feature label Aug 10, 2025

seisman added this to the 0.18.0 milestone Sep 18, 2025

seisman mentioned this pull request Oct 16, 2025

Add the Position class for GMT embellishment placement #4168

Closed

9 tasks

seisman added this to PyGMT paper Nov 7, 2025

seisman force-pushed the feature/scalebar branch from 8acb461 to 14283bd Compare November 26, 2025 07:32

This was referenced Dec 4, 2025

Figure.basemap: Plot base maps and frames #4239

Closed

Figure.coast: Plot continents, countries, shorelines, rivers, and borders #4240

Closed

seisman changed the base branch from main to params/position December 6, 2025 16:33

seisman mentioned this pull request Dec 7, 2025

Tracking the status of the examples included in the paper GenericMappingTools/pygmt-paper-figures#14

Open

19 tasks

seisman force-pushed the feature/scalebar branch from 2a0ea6b to 17d8427 Compare December 9, 2025 16:12

seisman changed the title ~~WIP: Add Figure.scalebar to plot a scale bar on maps~~ \Add Figure.scalebar to plot a scale bar on maps Dec 10, 2025

seisman changed the title ~~\Add Figure.scalebar to plot a scale bar on maps~~ Add Figure.scalebar to plot a scale bar on maps Dec 10, 2025

Base automatically changed from params/position to main December 11, 2025 01:54

seisman added this to PyGMT: Wrapping GMT modules Dec 11, 2025

seisman removed this from PyGMT: Wrapping GMT modules Dec 11, 2025

seisman commented Dec 11, 2025

View reviewed changes

seisman marked this pull request as ready for review December 11, 2025 11:49

seisman added the needs review This PR has higher priority and needs review. label Dec 11, 2025

seisman mentioned this pull request Dec 11, 2025

Figure.scalebar: Add a scale bar on maps #4268

Closed

30 tasks

seisman force-pushed the feature/scalebar branch 4 times, most recently from 0fdd8a3 to c86e8d5 Compare December 18, 2025 09:12

Copilot AI reviewed Jan 17, 2026

View reviewed changes

pygmt/src/scalebar.py Outdated Show resolved Hide resolved

Update pygmt/src/scalebar.py

c192853

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

yvonnefroehlich reviewed Jan 17, 2026

View reviewed changes

Fix docstrings

777cd3a

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

yvonnefroehlich reviewed Jan 17, 2026

View reviewed changes

pygmt/src/scalebar.py Outdated Show resolved Hide resolved

Improve docstrings for fancy

188367a

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

yvonnefroehlich reviewed Jan 17, 2026

View reviewed changes

pygmt/src/scalebar.py Outdated Show resolved Hide resolved

pygmt/src/scalebar.py Outdated Show resolved Hide resolved

pygmt/src/scalebar.py Outdated Show resolved Hide resolved

pygmt/src/scalebar.py Outdated Show resolved Hide resolved

Apply suggestions from code review

c7b86c9

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

yvonnefroehlich reviewed Jan 17, 2026

View reviewed changes

pygmt/src/scalebar.py Outdated Show resolved Hide resolved

Update pygmt/src/scalebar.py

cc15a31

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

seisman mentioned this pull request Jan 18, 2026

POC: Add a separate documentation for supported plot and distance units #4359

Draft

seisman added 5 commits January 18, 2026 14:26

Merge branch 'main' into feature/scalebar

1c8c5c1

Merge branch 'main' into feature/scalebar

f44f784

Simplify _parse_position

971d147

Merge branch 'main' into feature/scalebar

e2c1254

Rename scale_at to scale_loc

0561ba4

yvonnefroehlich reviewed Jan 20, 2026

View reviewed changes

yvonnefroehlich approved these changes Jan 20, 2026

View reviewed changes

Update pygmt/src/scalebar.py

cc40c8f

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

seisman merged commit 613bdc1 into main Jan 21, 2026
29 of 33 checks passed

seisman deleted the feature/scalebar branch January 21, 2026 02:48

github-project-automation bot moved this to Done in PyGMT paper Jan 21, 2026

seisman removed the final review call This PR requires final review and approval from a second reviewer label Jan 21, 2026

Add Figure.scalebar to plot a scale bar on maps #4015

Add Figure.scalebar to plot a scale bar on maps #4015

Conversation

seisman commented Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of changed images

Image diff(s)

Added images

Modified images

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

seisman commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seisman commented Jan 20, 2026

Uh oh!

yvonnefroehlich commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seisman commented Jan 20, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yvonnefroehlich left a comment

Choose a reason for hiding this comment

Uh oh!

seisman commented Jan 21, 2026

Uh oh!

seisman commented Jan 21, 2026

Uh oh!

Uh oh!

yvonnefroehlich commented Jan 21, 2026

Uh oh!

seisman commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seisman commented Jul 26, 2025 •

edited

Loading

github-actions bot commented Dec 9, 2025 •

edited

Loading

seisman commented Dec 18, 2025 •

edited

Loading

yvonnefroehlich commented Jan 20, 2026 •

edited

Loading