NAME

      gmtselect - Select data subsets based on multiple spatial criteria

SYNOPSIS

      gmtselect [ infiles ] [ -Amin_area[/min_level/max_level] ] [
      -Cdist/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) positions 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 hierarchical 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.

      -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
           outside] when a different resolution is selected.

      -F   Pass all records whose location is within one of the closed
           polygons in the multiple-segment file polygonfile.

      -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 distance of any
           line.
                r  select records NOT inside the specified rectangular
           region.
                s  select records NOT considered inside as specified by -A,
           -D, -N.

      -J   Selects the map projection. Scale is inch/degree, 1:xxxxx, or
           width in inch (upper case modifier).

           CYLINDRICAL PROJECTIONS:

           -Jclon0/lat0/scale (Cassini)
           -Jjlon0/scale (Miller)
           -Jmscale (Mercator - Greenwich and Equator as origin)
           -Jmlon0/lat0/scale (Mercator - Give meridian and standard
           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)
           -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)
           -Jllon0/lat0/lat1/lat2/scale (Lambert)

           MISCELLANEOUS PROJECTIONS:

           -Jhlon0/scale (Hammer)
           -Jilon0/scale (Sinusoidal)
           -Jklon0/scale (Eckert VI)
           -Jnlon0/scale (Robinson)
           -Jrlon0/scale (Winkel Tripel)
           -Jwlon0/scale (Mollweide)

           NON-GEOGRAPHICAL PROJECTIONS:

           -Jpscale (Linear projection for polar (theta,r) coordinates)
           -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 individual 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 determined 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, gmt, grdlandmask, pscoast