Add Figure.scalebar to plot a scale bar on maps

[seisman]

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_at	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

TODO in separate PRs

• Update gallery examples using the new scalebar method
• Deprecate map_scale in Figure.coast/Figure.basemap Figure.basemap/Figure.coast: Deprecate the 'map_scale' parameter. Use 'Figure.scalebar' instead #4337
• Update the example in the paper Figure 3: Update with the Figure.scalebar method pygmt-paper-figures#28

[github-actions]

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 2a190b3

[seisman]

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

[seisman]

Ping @GenericMappingTools/pygmt-maintainers for final reviews. I plan to merge it after 48 hours.

[yvonnefroehlich]

Currently we have different versions how we document the valid units:

$ grep "mile" */*
helpers/decorators.py:              **M**\ (iles), or **n**\ (autical miles) [Default is (m)\ **e**\ (ters)].
helpers/decorators.py:              is assumed to be given in meter, foot, km, mile, nautical mile or
src/grdproject.py:        **k** (kilometers), **M** (statute miles), **n** (nautical miles),
src/scalebar.py:        units are: **e**: meters; **f**: feet; **k**: kilometers; **M**: statute mile;
src/scalebar.py:        **n**: nautical miles; **u**: US Survey foot.
src/sphdistance.py:        **M** (miles), **n** (nautical miles), or **u** (survey feet).
src/x2sys_init.py:        - **m**: miles or mi/hr
src/x2sys_init.py:        - **n**: nautical miles or knots
grep: tests/baseline: Is a directory
grep: tests/data: Is a directory

I feel it would be nice to make this consistent (but we can do this in a separat PR, after we agreeded on one version).

[seisman]

I feel we should have a separate page for supported distance units.

[seisman]

I've bumped this PR to v0.19.0 following #4289 (comment).

[Copilot]

Pull request overview

This PR implements the Figure.scalebar method to add scale bars to maps, wrapping GMT's -L option from the basemap/coast modules.

Changes:

• Added new scalebar method to the Figure class with comprehensive parameter support
• Implemented tests covering basic, complete, and Cartesian coordinate use cases
• Integrated the new method into PyGMT's module structure and documentation

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pygmt/src/scalebar.py	New implementation wrapping GMT's basemap -L option for scale bars
pygmt/tests/test_scalebar.py	Test suite with three image comparison tests covering different use cases
pygmt/tests/baseline/test_scalebar.png.dvc	Baseline image for basic scalebar test
pygmt/tests/baseline/test_scalebar_complete.png.dvc	Baseline image for comprehensive parameter test
pygmt/tests/baseline/test_scalebar_cartesian.png.dvc	Baseline image for Cartesian coordinates test
pygmt/src/init.py	Added scalebar import in alphabetical order
pygmt/figure.py	Added scalebar to Figure class methods
doc/api/index.rst	Added Figure.scalebar to API documentation

---

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