Figure.shift_origin: Support shifting origins temporarily when used as a context manager

[seisman]

See #2401 for context.

In the old versions, Figure.shift_origin(...) can only shift origins permanently, but sometimes users may want to shift origins temporarily (i.e., shifting the origins to a new location, plotting and then reverting back to the previous origins).

This PR refactors Figure.shift_origin into a context manager so that it can shift origins permanently when used as a regular method or temporarily when used as a context manager.

Old documentation: https://www.pygmt.org/v0.14.0/api/generated/pygmt.Figure.shift_origin.html
Preview the new documentation: https://pygmt-dev--2509.org.readthedocs.build/en/2509/api/generated/pygmt.Figure.shift_origin.html

Enhanced syntax

The new syntax is:

# Shift origins permanently
Figure.shift_origin(...)

# Shift origins temporarily
with Figure.shift_origin(...):
    ...

Examples

Use as a regular method:

import pygmt
fig = pygmt.Figure()
fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
# Shift the plot origin in x direction by 6 cm
fig.shift_origin(xshift=6)
fig.basemap(region=[0, 7, 0, 5], projection="X7c/5c", frame=True)
# Shift the plot origin in x direction based on the previous plot width.
# Here, the width is 7 cm, and xshift is 8 cm.
fig.shift_origin(xshift="w+1c")
fig.basemap(region=[0, 10, 0, 5], projection="X10c/5c", frame=True)
fig.show()

Use as a context manager:

fig = pygmt.Figure()
fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
# Shift the plot origin in x direction by 6 cm temporarily. The plot origin will
# revert back to the original plot origin after the block of code is executed.
with fig.shift_origin(xshift=6):
    fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
# Shift the plot origin in y direction by 6 cm temporarily.
with fig.shift_origin(yshift=6):
    fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
# Shift the plot origin in x and y directions by 6 cm temporarily.
with fig.shift_origin(xshift=6, yshift=6):
    fig.basemap(region=[0, 5, 0, 5], projection="X5c/5c", frame=True)
fig.show()

[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_shift_origin_context_manager.png
added	pygmt/tests/baseline/test_shift_origin_mixed_modes.png
added	pygmt/tests/baseline/test_shift_origin_nested_context_manager.png

Image diff(s)

Added images

• test_shift_origin_context_manager.png

• test_shift_origin_mixed_modes.png

• test_shift_origin_nested_context_manager.png

Modified images

Path	Old	New

Report last updated at commit a75a440

[seisman]

Finally make it work as expected. @GenericMappingTools/pygmt-maintainers Please try the new Figure.shift_origin method and see if it works well.

[michaelgrund]

Looks good!

[seisman]

It would be better if @yvonnefroehlich and @weiji14 could give this PR a review, since it's a big change to the Figure.shift_origin method.

[yvonnefroehlich]

Wonder if it is better to change the order to first mention permanent and then temporary, as in the examples at the end. At least I would have this always in the same order.

[seisman]

Sounds good. Done in 0d489dc.

[yvonnefroehlich]

How do w (x direction) and h (y direction) work for the temporary option? Is this also refering to the previous plot, or actually the current plot? In case it refers to the previous plot, what is used if the current plot is the first plot?

[seisman]

How do w (x direction) and h (y direction) work for the temporary option? Is this also refering to the previous plot, or actually the current plot?

It always refers to the previous plot.

In case it refers to the previous plot, what is used if the current plot is the first plot?

Figure.shift_origin has no effects if it is called before any plotting methods:

import pygmt

fig = pygmt.Figure()
with fig.shift_origin(xshift="w+2c"):
    fig.basemap(region=[0, 1, 0, 1], projection="X3c", frame=0)
fig.show()

[seisman]

Will merge this PR in 24 hours if no further comments.

[yvonnefroehlich]

Should be fine from my side!

[seisman]

Thanks for all your reviews. I've merged this PR.