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
• Update the example in the paper

[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 0112a75

[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've bumped this PR to v0.19.0 following #4289 (comment).