psmask
Clip or mask map areas with no data table coverage
Synopsis
gmt psmask [ table ] -Iincrement -Jparameters -Rregion [ -B[p|s]parameters ] [ -C ] [ -Ddumpfile ] [ -F[l|r] ] [ -Gfill ] [ -K ] [ -Lnodegrid[+i|o] ] [ -N ] [ -O ] [ -P ] [ -Qcut ] [ -Sradius ] [ -T ] [ -U[stamp] ] [ -V[level] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -bibinary ] [ -dinodata[+ccol] ] [ -eregexp ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -qiflags ] [ -rreg ] [ -ttransp ] [ -wflags ] [ -:[i|o] ] [ --PAR=value ]
Description
Reads a (x,y,z) file [or standard input] and uses this information to find out which grid cells are reliable. Only grid cells which have one or more data points are considered reliable. As an option, you may specify a radius of influence. Then, all grid cells that are within the search radius of a data point are considered reliable. Furthermore, an option is provided to reverse the sense of the test. Having found the reliable/not reliable points, the module will either paint tiles to mask these nodes (with the -T switch), or use contouring to create polygons that will clip out regions of no interest. When clipping is initiated, it will stay in effect until turned off by a second call to the module using the -C option.
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.
- -Ix_inc[+e|n][/y_inc[+e|n]]
Set the grid spacing as x_inc [and optionally y_inc].
Geographical (degrees) coordinates: Optionally, append an increment unit. Choose among:
d - Indicate arc degrees
m - Indicate arc minutes
s - Indicate arc seconds
If one of e (meter), f (foot), k (km), M (mile), n (nautical mile) or u (US survey foot), the the increment will be converted to the equivalent degrees longitude at the middle latitude of the region (the conversion depends on PROJ_ELLIPSOID). If y_inc is not given or given but set to 0 it will be reset equal to x_inc; otherwise it will be converted to degrees latitude.
All coordinates: The following modifiers are supported:
+e - Slightly adjust the max x (east) or y (north) to fit exactly the given increment if needed [Default is to slightly adjust the increment to fit the given domain].
+n - Define the number of nodes rather than the increment, in which case the increment is recalculated from the number of nodes, the registration (see GMT File Formats), and the domain. Note: If -Rgrdfile is used then the grid spacing and the registration have already been initialized; use -I and -R to override these values.
- -Jparameters
Specify the projection. [Not mandatory with -D]. (See full description) (See cookbook summary) (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 cookbook information).
For perspective view -p, optionally append /zmin/zmax. (more …)
Optional Arguments
- -B[p|s]parameters
Set map boundary frame and axes attributes. (See full description) (See cookbook information).
- -C
Mark end of existing clip path. No input file is needed. Implicitly sets -O. Also supply -X and -Y settings if you have moved since the clip started.
- -Ddumpfile
Dump the (x, y) coordinates of each clipping polygon to one or more output files (or standard output if template is not given). No plotting will take place. If template contains the C-format specifier %d (including modifications like %05d) then polygons will be written to different files; otherwise all polygons are written to the specified file (template). The files are ASCII unless -bo is used. See -Q to exclude small polygons from consideration.
- -F[l|r]
Force clip contours (polygons) to be oriented so that data points are to the left (-Fl [Default]) or right (-Fr) as we move along the perimeter [Default is arbitrary orientation]. Requires -D.
- -Gfill
Paint the clip polygons (or tiles) with a selected fill [Default is no fill].
- -Jz|Zparameters
Set z-axis scaling; same syntax as -Jx.
- -Lnodegrid[+i|o]
Save the internal grid with ones (data constraint) and zeros (no data) to the named nodegrid [no grid saved]. Append +o to convert the outside (no data) nodes to NaNs before writing the grid, while appending +i will instead convert the inside (data) flags to NaNs.
- -N
Invert the sense of the test, i.e., clip regions where there is data coverage.
- -Qcut
Do not dump polygons with less than cut number of points [Dumps all polygons]. Only applicable if -D has been specified.
- -Ssearch_radius
Sets search radius of influence. Grid nodes within radius of a data point are considered reliable. [Default is 0, which means that only grid cells with data in them are reliable]. Append the distance unit (see Units).
- -U[label|+c][+jjustify][+odx[/dy]][+ttext]
Draw GMT time stamp logo on plot. (See full description) (See cookbook information).
- -V[level]
Select verbosity level [w]. (See full description) (See cookbook information).
- -X[a|c|f|r][xshift]
Shift plot origin. (See full description) (See cookbook information).
- -Y[a|c|f|r][yshift]
Shift plot origin. (See full description) (See cookbook information).
- -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.
- -h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)
Skip or produce header record(s). Not used with binary data.
- -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].
- -r[g|p] (more …)
Set node registration [gridline].
- -ttransp[/transp2] (more …)
Set transparency level(s) in percent.
- -wy|a|w|d|h|m|s|cperiod[/phase][+ccol] (more …)
Convert an input coordinate to a cyclical coordinate.
- -:[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.
Units
For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default unless stated otherwise], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).
Classic Mode Arguments
These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.
- -K (more …)
Do not finalize the PostScript plot.
- -O (more …)
Append to existing PostScript plot.
- -P (more …)
Select “Portrait” plot orientation.
Examples
Note: Below are some examples of valid syntax for this module.
The examples that use remote files (file names starting with @)
can be cut and pasted into your terminal for testing.
Other commands requiring input files are just dummy examples of the types
of uses that are common but cannot be run verbatim as written.
To make an overlay that will mask out the regions of a contour map where there is no control data using clip polygons, use:
gmt psmask africa_grav.xyg -R20/40/20/40 -I5m -JM10i -O -K > mask.ps
We do it again, but this time we wish to save the clipping polygons to file all_pols.txt:
gmt psmask africa_grav.xyg -R20/40/20/40 -I5m -Dall_pols.txt
A repeat of the first example but this time we use white tiling:
gmt psmask africa_grav.xyg -R20/40/20/40 -I5m -JM10i -T -O -K -Gwhite > mask.ps