Figure.shift_origin: Allow shifting the origin back to the original position after plotting

[seisman]

Background

The full syntax of GMT's -X and -Y options is (https://docs.generic-mapping-tools.org/dev/gmt.html#xy-full):

-X[a|c|f|r][xshift].

As mentioned in the upstream issue GenericMappingTools/gmt#7296, -Xc and -Xf make no sense in modern mode. So, we only focus on -Xr (the same as -X) and -Xa in PyGMT.

• -Xr: move the origin relative to its current location.
• -Xa: move the origin relative to its current location, and move the origin back to the original position after plotting

The following GMT bash script shows the behavior of -Xr and -Xa:

gmt begin                                                                       
for mode in "r" "a"; do                                                         
    echo "Shift plotting origin with -X${mode}10c"                              
    gmt figure shift-X${mode}10c png                                            
    gmt basemap -R0/10/0/10 -JX10c -Baf -B+tFrame1                              
    gmt basemap -R0/10/0/10 -JX10c -Baf -B+tFrame2 -X${mode}10c                 
    gmt basemap -R0/5/0/5 -JX5c -Baf -B+tFrame3                                 
done                                                                            
gmt end show 

For -Xr, the output image is:

For -Xa, the output image is:

Limitations of Figure.shift_origin()

Currently, the Figure.shift_origin() function can shift the origin but can't move the origin back to the original position, as shown by the following PyGMT script:

import pygmt

fig = pygmt.Figure()
fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=["af", "WSen+tFrame1"])
fig.shift_origin(xshift="a6c")
fig.basemap(region=[0, 10, 0, 10], projection="X10c", frame=["af", "WSen+tFrame2"])
fig.basemap(region=[0, 5, 0, 5], projection="X5c", frame=["af", "WSen+tFrame3"])
fig.savefig("map1.png")

With xshift="a6c", the Figure.shift_origin() call shifts the plotting origin by 6 cm in X direction and then move the plotting origin back before the 2nd Figure.basemap call. Thus, the above script produces an image like:

Enhancement of Figure.shift_origin()

Figure.shift_origin should be able to revert to its original position after plotting. This can be done using the with Figure.shift_origin(): syntax, similar to the pygmt.config() function.

The new syntax can be:

# permanently shift the plotting origin
Figure.shift_origin(xshift="1c")  

# temporarily shift the plotting origin
with Figure.shift_origin(xshift="1c"):
    ...
    ...

TODOs

• Currently, the shift_origin function is in the pygmt/figure.py file. I think it makes sense to move it to pygmt/src/shift_origin.py because the function will be much longer now. (Move Figure.shift_origin to a standalone Python file #2485)
• Implement the with Figure.shift_origin(xshift="1c") syntax. The implementation is very similar to the pygmt.config() function. We just need to remember the shift parameters and then do the inverse shift when exiting the context manager (e.g., use xshift="-1c" when exiting). (@seisman)
• Write good docstrings explain its usage
• Add a good tutorial example

Are you willing to help implement and maintain this feature?

Maybe. This function should be easy to implement, so volunteers are welcomed and I'm glad to review this PR.