NAME
gmtselect - Select data subsets based on multiple spatial
criteria
SYNOPSIS
gmtselect [ infiles ] [ -Amin_area[/min_level/max_level] ] [
-C[f]dist/ptfile ] [ -Dresolution ] [ -Fpolygonfile ] [
-H[nrec] ] [ -I[cflrs] ] [ -Jparameters ] [ -Ldist/linefile
] [ -M[flag] ] [ -Nmaskvalues[o] ] [
-Rwest/east/south/north[r] ] [ -V ] [ -: ] [ -bi[s][n] ] [
-bo[s] ]
DESCRIPTION
gmtselect is a filter that reads (longitude, latitude) posi-
tions from the first 2 columns of infiles [or standard
input] and uses a combination of 1-5 criteria to pass or
reject the records. Records can be selected based on
whether or not they are 1) inside a rectangular region (-R
[and -J]), 2) within dist km of any point in ptfile, 3)
within dist km of any line in linefile, 4) inside one of the
polygons in the polygonfile, and 5) inside geographical
features (based on coastlines). The sense of the tests can
be reversed for each of these 5 criteria by using the -I
option. See option -: on how to read (latitude,longitude)
files.
No space between the option flag and the associated
arguments. Use upper case for the option flags and lower
case for modifiers.
infiles
ASCII (or binary, see-b) data file(s) to be operated
on. If not given, standard input is read.
OPTIONS
-A Ignored unless -N is set. Geographical features with
an area smaller than min_area in km^2 or of hierarchi-
cal level that is lower than min_level or higher than
max_level will be ignored [Default is 0/4 (all
features)]. See DATABASE INFORMATION in the pscoast
man-pages for more details.
-C Pass all records whose location is within dist km of
any of the points in ptfile. If dist is zero then the
3rd column of ptfile must have each point's individual
radius of influence. Prepend f to indicate you want
approximate flat earth distance calculations (faster)
than exact great circle calculations (slower).
-D Ignored unless -N is set. Selects the resolution of
the coastline data set to use ((f)ull, (h)igh,
(i)ntermediate, (l)ow, or (c)rude). The resolution
drops off by ~80% between data sets. [Default is l].
Note that because the coastlines differ in details is
not guaranteed that a point will remain inside [or out-
side] when a different resolution is selected.
-F Pass all records whose location is within one of the
closed polygons in the multiple-segment file polygon-
file.
-H Input file(s) has Header record(s). Number of header
records can be changed by editing your .gmtdefaults
file. If used, GMT default is 1 header record.
-I Reverses the sense of the test for each of the criteria
specified:
c select records NOT inside any point's circle of
influence.
f select records NOT inside any of the polygons.
l select records NOT within the specified dis-
tance of any line.
r select records NOT inside the specified rec-
tangular region.
s select records NOT considered inside as speci-
fied by -A, -D, -N.
-J Selects the map projection. Scale is UNIT/degree,
1:xxxxx, or width in UNIT (upper case modifier). UNIT
is cm, inch, or m, depending on the MEASURE_UNIT set-
ting in .gmtdefaults, but this can be overridden on the
command line by appending the c, i, or m to the
scale/width value.
CYLINDRICAL PROJECTIONS:
-Jclon0/lat0/scale (Cassini)
-Jjlon0/scale (Miller)
-Jmscale (Mercator - Greenwich and Equator as origin)
-Jmlon0/lat0/scale (Mercator - Give meridian and stan-
dard parallel)
-Joalon0/lat0/azimuth/scale (Oblique Mercator - point
and azimuth)
-Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two
points)
-Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point
and pole)
-Jqlon0/scale (Equidistant Cylindrical Projection
(Plate Carree))
-Jtlon0/scale (TM - Transverse Mercator, with Equator
as y = 0)
-Jtlon0/lat0/scale (TM - Transverse Mercator, set ori-
gin)
-Juzone/scale (UTM - Universal Transverse Mercator)
-Jylon0/lats/scale (Basic Cylindrical Projection)
AZIMUTHAL PROJECTIONS:
-Jalon0/lat0/scale (Lambert).
-Jelon0/lat0/scale (Equidistant).
-Jflon0/lat0/horizon/scale (Gnomonic).
-Jglon0/lat0/scale (Orthographic).
-Jslon0/lat0/scale (General Stereographic)
CONIC PROJECTIONS:
-Jblon0/lat0/lat1/lat2/scale (Albers)
-Jdlon0/lat0/lat1/lat2/scale (Equidistant)
-Jllon0/lat0/lat1/lat2/scale (Lambert)
MISCELLANEOUS PROJECTIONS:
-Jhlon0/scale (Hammer)
-Jilon0/scale (Sinusoidal)
-Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
-Jnlon0/scale (Robinson)
-Jrlon0/scale (Winkel Tripel)
-Jvlon0/scale (Van der Grinten)
-Jwlon0/scale (Mollweide)
NON-GEOGRAPHICAL PROJECTIONS:
-Jpscale[/origin] (polar (theta,r) coordinates, option-
ally offset theta [0])
-Jxx-scale[l|ppow][/y-scale[l|ppow]] (Linear, log, and
power scaling)
More details can be found in the psbasemap manpages.
-L Pass all records whose location is within dist km of
any of the line segments in the multiple-segment file
linefile. If dist is zero then the 2nd column of each
sub-header in the ptfile must have each lines's indivi-
dual distance value.
-M Multiple segment file. Segments are separated by a
record whose first character is flag. [Default is
'>'].
-N Pass all records whose location is inside specified
geographical features. Specify if records should be
skipped or kkept using 1 of 2 formats:
-Nwet/dry.
-Nocean/land/lake/island/pond.
Append o to let points exactly on feature boundaries be
considered outside the feature [Default is inside].
[Default is s/k/s/k/s (i.e., s/k), which passes all
points on dry land].
-R west, east, south, and north specify the Region of
interest. To specify boundaries in degrees and minutes
[and seconds], use the dd:mm[:ss] format. Append r if
lower left and upper right map coordinates are given
instead of wesn.
-V Selects verbose mode, which will send progress reports
to stderr [Default runs "silently"].
-: Toggles between (longitude,latitude) and
(latitude,longitude) input/output. [Default is
(longitude,latitude)].
-bi Selects binary input. Append s for single precision
[Default is double]. Append n for the number of
columns in the binary file(s). [Default is 2 input
columns].
-bo Selects binary output. Append s for single precision
[Default is double].
EXAMPLES
To extract the subset of data set that is within 300 km of
any of the points in pts.d but more than 100 km away from
the lines in lines.d, try
gmtselect lonlatfile -C300/pts.d -L100/lines.d -Il > subset
To keep all points in data.d except those on land, as deter-
mined by the high-resolution coastlines, try
gmtselect data.d -R120/121/22/24 -Dh -Ns/k > subset
RESTRICTIONS
All data are assumed to be in geographical coordinates since
great circle distances are calculated. When working on data
in polar regions it may be best to use an appropriate map-
projection. Hence, when -J is supplied all comparisons with
polygons are done with projected coordinates.
SEE ALSO
gmtdefaults(l), gmt(l), grdlandmask(l), pscoast(l)