Figure.clip_xxx: A consistent API for clipping by polygon, land, water, solar, and mask

[seisman]

GMT supports several related clipping operations:

Description	Activate	Deactivate	User input
Clip land areas	coast -G	coast -Q	No
Clip water areas	coast -S	coast -Q	No
Clip by polygon	clip	clip -C	(x, y) coordinates
Clip by mask	mask	mask -C	(x, y) coordinates
Clip by a country or region code	coast -E+c	coast -Q	No
Clip by solar terminators	solar -G	clip -C	No

For every mode, subsequent plotting commands are clipped until the path is explicitly ended. This stateful behavior makes clipping a natural fit for context managers.

Possible API designs:

1. Low-level begin/end methods

   fig.begin_clip(data=polygon)
   fig.plot(...)
   fig.end_clip()
   

   This closely mirrors GMT, but requires users to end clipping explicitly and can leave a clip path active after an exception.

2. A single context-manager method with a mode

   with fig.clip(mode="polygon", data=polygon):
       ...
   with fig.clip(mode="land"):
       ...
   with fig.clip(mode="dcw", code="US"):
       ...
   

   This has a compact API, but each mode wraps a different GMT module and accepts different parameters. Documenting and validating this mixed argument set could become complicated.

3. A clip namespace

   with fig.clip.polygon(data=polygon):
       ...
   
   with fig.clip.land():
       ...
   

   This groups related functionality neatly, but may be challenging to expose and document correctly. See the proof of concept in POC: Figure.clip: Clip paths by polygons, land or water #3878.

4. Explicit context-manager methods

   with fig.clip_polygon(data=polygon):    
       ...
   with fig.clip_land():
      ...
   with fig.clip_water():
      ...
   

   This one is much easier to document that option 4. A POC PR is at WIP + POC: Figure.clip_xxx methods #4703.

I feel option 4 is the best API design.