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:

• 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] WIP: 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] WIP: Figure.colorbar: Refactor using the new alias system #4048
• Legend: -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+lspacing][+odx[/dy]] WIP: Figure.legend: Refactor using the new alias system #4046
• Raster image: -D[g|j|J|n|x]refpoint+rdpi[c]+w[-]width[/height][+jjustify][+nnx[/ny] ][+odx[/dy]] WIP: Figure.image: Refactor using the new alias system #4045
• GMT logo: -D[g|j|J|n|x]refpoint[+hheight|+wwidth][+jjustify][+odx[/dy]] Figure.logo: Add parameters 'position/position_type/anchor/anchor_offset/width/height' to specify the location and size #4014
• Map inset: -D[g|j|J|n|x]refpoint+wwidth[/height][+jjustify][+odx[/dy]] WIP: Figure.inset: Refactor using the new alias system #4047
• Vertical scale: -D[g|j|J|n|x]refpoint+wlength[+jjustify][+al|r][+odx[/dy]][+l[label]] Figure.wiggle: Refactor using the new alias system #4049

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.