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)