clip

Initialize or terminate polygonal clip paths

Synopsis

gmt clip [ table ] -Jparameters -C[n] -Rwest/east/south/north[/zmin/zmax][+r][+uunit] [ -A[m|p|x|y|r|t] ] [ -B[p|s]parameters ] -Jz|Zparameters ] [ -N ] [ -T ] [ -U[stamp] ] [ -V[level] ] [ -W[pen] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -bibinary ] [ -dinodata[+ccol] ] [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -qiflags ] [ -ttransp ] [ -:[i|o] ] [ --PAR=value ]

Description

Reads (x, y) file(s) [or standard input] and draws polygons that are activated as clipping paths. Several files may be read to create complex paths consisting of several non-connecting segments. Only marks that are subsequently drawn inside the clipping path will be shown. To determine what is inside or outside the clipping path, we use the even-odd rule. When a ray drawn from any point, regardless of direction, crosses the clipping path segments an odd number of times, the point is inside the clipping path. If the number is even, the point is outside. The -N option, reverses the sense of what is the inside and outside of the paths by plotting a clipping path along the map boundary. After subsequent plotting, which will be clipped against these paths, the clipping may be deactivated by running the module a second time with the -C option only.

Required Arguments

table: One or more ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a number of data columns. If no tables are given then we read from standard input.

-C[n]: Mark end of existing clip path(s). No input file will be processed. No projection information is needed unless -B has been selected as well. With no arguments we terminate all active clipping paths. Experts may restrict the termination to just n of the active clipping path by passing that as the argument.

-Jparameters: Specify the projection. (See full description) (See technical reference) (See projections table).

-Rxmin/xmax/ymin/ymax[+r][+uunit]: Specify the region of interest. Note: If using modern mode and -R is not provided, the region will be set based on previous plotting commands. If this is the first plotting command in the modern mode levels and -R is not provided, the region will be automatically determined based on the data in table (equivalent to using -Ra). (See full description) (See technical reference).

For perspective view -p, optionally append /zmin/zmax. (more …)

Optional Arguments

-A[m|p|x|y|r|t]: By default, geographic line segments are connected as great circle arcs. To connect them as straight lines, use the -A flag. Alternatively, add m to connect the line by first following a meridian, then a parallel. Or append p to start following a parallel, then a meridian. (This can be practical to connect lines along parallels, for example). For Cartesian data, points are simply connected, unless you append x or y to construct stair-case paths whose first move is along x or y, respectively. For polar projection, append r or t to draw stair-case curves that whose first move is along r or theta, respectively.

-B[p|s]parameters: Set map boundary frame and axes attributes. (See full description) (See technical reference).

-N: 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 -B.

-T: Rather than read any input files, simply turn on clipping for the current map region. Basically, -T is a convenient way to run the module with the arguments -N /dev/null (or, under Windows, -N NUL). Cannot be used together with -B.

-U[label|+c][+jjustify][+odx[/dy]][+ttext]: Draw GMT time stamp logo on plot. (See full description) (See technical reference).

-V[level]: Select verbosity level [w]. (See full description) (See technical reference).

-Wpen: Draw outline of clip path using given pen attributes before clipping is initiated [Default is no outline].

-X[a|c|f|r][xshift]: Shift plot origin. (See full description) (See technical reference).

-Y[a|c|f|r][yshift]: Shift plot origin. (See full description) (See technical reference).

-birecord[+b|l] (more …): Select native binary format for primary table input. [Default is 2 input columns].

-dinodata[+ccol] (more …): Replace input columns that equal nodata with NaN.

-e[~]“pattern” | -e[~]/regexp/[i] (more …): Only accept data records that match the given pattern.

-f[i|o]colinfo (more …): Specify data types of input and/or output columns.

-gx|y|z|d|X|Y|Dgap[u][+a][+ccol][+n|p] (more …): Determine data gaps and line breaks.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …): Skip or produce header record(s).

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …): Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …): Select perspective view.

-qi[~]rows|limits[+ccol][+a|t|s] (more …): Select input rows or data limit(s) [default is all rows].

-ttransp[/transp2] (more …): Set transparency level(s) in percent.

-:[i|o] (more …): Swap 1st and 2nd column on input and/or output.

-^ or just -: Print a short message about the syntax of the command, then exit (Note: on Windows just use -).
-+ or just +: Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.
-? or no arguments: Print a complete usage (help) message, including the explanation of all options, then exit.
--PAR=value: Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Examples

To see the effect of a simple clip path which result in some symbols being partly visible or missing altogether, try:

gmt begin clip
  gmt clip -R0/6/0/6 -Jx2.5c -W1p,blue << EOF
0 0
5 1
5 5
EOF
  gmt plot @tut_data.txt -Gred -Sc2c
  gmt clip -C -B
gmt end show

where we activate and deactivate the clip path. Note we also draw the outline of the clip path to make it clear what is being clipped.