pygmt.src.ClipAccessor.polygon

ClipAccessor.polygon(data=None, x=None, y=None, *, straight_line=None, frame=None, projection=None, invert=None, region=None, verbose=None, pen=None, **kwargs)[source]

Clip polygonal paths.

Must be used as a context manager. Any plotting operations within the context manager will be clipped to the polygons.

Aliases:

  • A = straight_line

  • B = frame

  • J = projection

  • N = invert

  • R = region

  • V = verbose

  • W = pen

Parameters:

  • data (default: None) – Either a file name to an ASCII data table, a 2-D numpy.ndarray, a pandas.DataFrame, an xarray.Dataset made up of 1-D xarray.DataArray data variables, or a geopandas.GeoDataFrame containing the tabular data.

  • x/y – X and Y coordinates of the polygon.

  • frame (bool, str, or list) – Set map boundary frame and axes attributes.

  • region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • projection (str) – projcode[projparams/]width|scale. Select map projection.

  • verbose (bool or str) – Select verbosity level [Full usage].

  • straight_line –

    By default, line segments are connected as straight lines in the Cartesian and polar coordinate systems, and as great circle arcs (by resampling coarse input data along such arcs) in the geographic coordinate system. The straight_line parameter can control the connection of line segments. Valid values are:

    • True: Draw line segments as straight lines in geographic coordinate systems.

    • "x": Draw line segments by first along x, then along y.

    • "y": Draw line segments by first along y, then along x.

    Here, x and y have different meanings depending on the coordinate system

    • Cartesian coordinate system: x and y are the X- and Y-axes.

    • Polar coordinate system: x and y are theta and radius.

    • Geographic coordinate system: x and y are parallels and meridians.

    Attention

    There exits a bug in GMT<=6.5.0 that, in geographic coordinate systems, the meaning of x and y is reversed, i.e., x means meridians and y means parallels. The bug is fixed by upstream PR #8648.

  • invert – Invert the sense of what is inside and outside. For example, when using a single path, this means that only points outside that path will be shown. Cannot be used together with frame.

  • pen – Draw outline of clip path using given pen attributes before clipping is initiated [Default is no outline].

Examples

>>> from pygmt import Figure
>>> from pygmt.datasets import load_earth_relief
>>>
>>> grid = load_earth_relief()
>>> fig = Figure()
>>> fig.basemap(region="g", projection="W15c", frame=True)
>>> with fig.clip.polygon(x=[-10, 10, 10, -10], y=[-10, -10, 10, 10]):
...     fig.grdimage(grid, cmap="geo")
>>> fig.show()