Add the Position class for GMT embellishment placement

[seisman]

Currently, GMT provides 9 different embellishments

• Map scale by basemap -L or coast -L
• Directional rose by basemap -Td or coast -Td
• Magnetic rose by basemap -Tm or coast -Tm
• Colorbar by colorbar
• Legend by legend
• Raster images by image
• GMT logo by logo
• Map inset by inset
• Vertical scale of wiggles in wiggle

Refer to https://docs.generic-mapping-tools.org/6.5/reference/features.html#plot-embellishments for details.

These embellishments have different properties thus different option flags/modifiers, but they all share the same syntax for positioning, as shown below:

• GMT logo: -D[g|j|J|n|x]refpoint[+hheight|+wwidth][+jjustify][+odx[/dy]] Figure.logo: Add parameters position/width/height to specify logo position and dimensions #4014
• Map inset: -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+odx[/dy]] Figure.inset: Add parameters position/width/height to specify inset position and dimensions #4047
• Legend: -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing][+odx[/dy]] Figure.legend: Add parameters position/width/height/line_spacing to specify legend position and properties #4046
• Vertical scale: -D[g|j|J|n|x]refpoint+wlength[+jjustify][+al|r][+odx[/dy]][+l[label]] Figure.wiggle: Add parameters position/length/label/label_alignment for the scalebar position and properties #4049
• Raster image: -D[g|j|J|n|x]refpoint+rdpi[c]+w[-]width[/height][+jjustify][+nnx[/ny] ][+odx[/dy]] Figure.image: Add parameters position/width/height/dpi/replicate to control image position and properties #4045
• Map scale: -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] Add Figure.scalebar to plot a scale bar on maps #4015
• Directional rose: -Td[g|j|J|n|x]refpoint[+f|F[level]][+jjustify][+l[w,e,s,n]][+odx[/dy]][+wwidth] Add Figure.directional_rose to plot a directional rose on map #4025
• Magnetic rose: -Tm[g|j|J|n|x]refpoint[+ddec[/dlabel]]][+ipen][+jjustify][+l[w,e,s,n]][+ppen][+tints][+odx[/dy]][+wwidth] Add Figure.magnetic_rose to plot a magnetic rose on map #4051
• Colorbar: -D[g|j|J|n|x]refpoint[+wlength[/width]][+e[b|f][length]][+h|v][+jjustify][+m[a|c|l|u]][+n[txt]][+odx[/dy]][+r] Figure.colorbar: Add position/length/width and more parameters to specify colorbar position and properties #4048

The common syntax is

[g|j|J|n|x]refpoint[+jjustify][+odx[/dy]

• g|j|J|n|x specify the coordinate system
• refpoint specifies the reference point
• +j specifies the anchor on the embellishment
• +o set the extra offset of the anchor.

In PR #4014, I propose four parameters: position_type/position/anchor/anchor_offset for such syntax. Since the four parameters will be used in several wrappers, discussions are necessary.

[seisman]

@GenericMappingTools/pygmt-maintainers Any comments before I continue?

[seisman]

I was reading #1082 (comment), and I feel a Position class is not a bad idea, considering that the Position class will be used in 9 wrappers and the class docstring is also the best place to explain how the positioning works (supersedes #4052).

The Position class can be used like this:

fig.logo(
    position=Position((30, 50), type="mapcoords", anchor="TR", offset=(0.3, 0.6)),
    width=5,
    box=True,
)

[seisman]

Ping @GenericMappingTools/pygmt-maintainers to decide if we want to implement it as multiple parameters or a class, i.e., #4014 vs #4212.

I prefer the Position class in #4212.

[yvonnefroehlich]

Ping @GenericMappingTools/pygmt-maintainers to decide if we want to implement it as multiple parameters or a class, i.e., #4014 vs #4212.

I prefer the Position class in #4212.

I also prefer to have a Position class.

[seisman]

As mentioned above, these methods share the same positioning syntax, [g|j|J|n|x]refpoint[+jjustify][+odx[/dy]], for placing embellishments. We have introduced the Position class to control their placement; however, the requirement and behavior of the position parameter are still inconsistent across methods.

Here is a summary of the default behaviors in GMT:

	position is required	size is required
logo	No [Default to x1i/0 (but source codes says x0/0)]	No [Default to 2i]
image	No [Default to x0/0 with some x-offset]	No [Default is based on DPI setting]
colorbar	No [Default to JBC, with some y-offset]	No [Default to 80% of map dimension
scalebar	No [Default to x0/0]	Yes
directional_rose	No [Default to x0/0]	Yes
magnetic_rose	No [Default to x0/0]	Yes
wiggle	No [Default to x0/0]	Yes
inset	Yes	Yes
legend	Yes [In PyGMT, default to JTR+jTR+o0.2c	No [Default to compute based on legend specifications]

I think there is potential bugs for the default positioning of logo and image. For example, gmt logo and gmt logo -D+w2i produce different outputs. I feel it makes sense to let it default to x0/0, rather than x1i/0 (or anything else) for logo and image.

Click the see the script to understand the behavior

Here is a bash script to understand the default behavior in GMT:

gmt begin positions png
	gmt basemap -R0/20/0/10 -JX20c/10c -Baf

	# position and size are not required
	gmt logo
	gmt image @vader1.png
	gmt colorbar -Cseis

	# position is not required, but size is required
	gmt basemap -L+w1c
	gmt basemap -Td+w1c
	gmt basemap -Tm+w1c
cat << EOF | gmt sample1d -I5k | gmt mapproject -G+uk | gmt math STDIN -C2 10 DIV COS = line.txt
0   7                                                                                   
1   8                                                                                   
8   3                                                                                   
10  7                                                                                   
7.5 8                                                                                   
3.5 1.5                                                                                 
1.5 3.5                                                                                 
4.5 10                                                                                  
EOF
	gmt wiggle -W0.25p line.txt -Z4c -T0.5p -A -D+w10

	# position is required
	gmt legend -Dx0/0 << EOF
S 0.1i c 0.15i red 0.25p 0.3i Circle
EOF

	# position is required, size is also required
	gmt inset begin -Dx0/0+w3c -F+p1p,red
		gmt coast -Rg -JH? -W
	gmt inset end

gmt end show

The output is: