.TH GMTSELECT 1gmt "Feb 27 2014" "GMT 4.5.13 (SVN)" "Generic Mapping Tools"
.SH NAME
gmtselect \- Select data subsets based on multiple spatial criteria 
.SH SYNOPSIS
\fBgmtselect\fP [ \fIinfiles\fP ] [ \fB\-A\fP\fImin_area\fP[\fI/min_level/max_level\fP][\fB+r\fP|\fBl\fP][\fBp\fP\fIpercent\fP] ] 
[ \fB\-C\fP[\fBf\fP]\fIdist/ptfile\fP ] [ \fB\-D\fP\fIresolution\fP[\fB+\fP] ] [ \fB\-F\fP\fIpolygonfile\fP ] 
[ \fB\-H\fP[\fBi\fP][\fInrec\fP] ] [ \fB\-I\fP[\fBcflrsz\fP] ] [ \fB\-J\fP\fIparameters\fP ] [ \fB\-L\fP[\fBp\fP]\fIdist/linefile\fP ] 
[ \fB\-N\fP\fImaskvalues\fP[\fBo\fP] ] [ \fB\-R\fP\fIwest\fP/\fIeast\fP/\fIsouth\fP/\fInorth\fP[\fBr\fP] ] [ \fB\-V\fP ] [ \fB\-Z\fP\fImin/max\fP] ] 
[ \fB\-:\fP[\fBi\fP|\fBo\fP] ] [ \fB\-b\fP[\fBi\fP|\fBo\fP][\fBs\fP|\fBS\fP|\fBd\fP|\fBD\fP[\fIncol\fP]|\fBc\fP[\fIvar1\fP\fB/\fP\fI...\fP]] ] [ \fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP ] [ \fB\-m\fP[\fBi\fP|\fBo\fP][\fIflag\fP] ]
.SH DESCRIPTION
\fBgmtselect\fP is a filter that reads (longitude, latitude) positions from the first 2 columns of
\fIinfiles\fP [or standard input] and uses a combination of 1-6 criteria to pass or reject the records.
Records can be selected based on whether or not they are 1) inside a rectangular region (\fB\-R\fP
[and \fB\-J\fP]), 2) within \fIdist\fP km of any point in \fIptfile\fP, 3) within \fIdist\fP km of
any line in \fIlinefile\fP, 4) inside one of the polygons in the \fIpolygonfile\fP, 5) inside
geographical features (based on coastlines), or 6) has z-values within a given range.
The sense of the tests can be reversed for each of these 6 criteria by using the \fB\-I\fP option.
See option \fB\-:\fP on how to read (latitude,longitude) files.
.TP
\fIinfiles\fP
ASCII (or binary, see \fB\-b\fP) data file(s) to be operated on.  If not given, standard input is read.
.SH OPTIONS
No space between the option flag and the associated arguments.
.TP
\fB\-A\fP
Features with an area smaller than \fImin_area\fP in km^2 or of hierarchical level
that is lower than \fImin_level\fP or higher than \fImax_level\fP
will not be plotted [Default is 0/0/4 (all features)].  Level 2 (lakes) contains
regular lakes and wide river bodies which we normally include as lakes;
append \fB+r\fP to just get river-lakes or \fB+l\fP to just get regular lakes
(requires GSHHS 2.0.1 or higher).  Finally, append \fB+p\fP\fIpercent\fP to exclude
polygons whose percentage area of the corresponding full-resolution feature is less
than \fIpercent\fP (requires GSHHS 2.0 or higher).
See GSHHS INFORMATION below for more details.
Ignored unless \fB\-N\fP is set.
.TP
\fB\-C\fP
Pass all records whose location is within \fIdist\fP of any of the points in the ASCII file \fIptfile\fP.
If \fIdist\fP is zero then the 3rd column of \fIptfile\fP must have each point's individual radius of influence.\"'
Distances are Cartesian and in user units; specify \fB\-fg\fP to indicate spherical distances in km.
Use \fB\-Cf\fP to indicate you want flat Earth distances (quicker but approximate) rather than
geodesic distances (slower but exact).
If \fBELLIPSOID\fP is spherical then geodesics become great circles (faster to compute than geodesic).
Alternatively, if \fB\-R\fP and \fB\-J\fP are used then geographic coordinates are projected to map coordinates
(in cm, inch, m, or points, as determined by \fBMEASURE_UNIT\fP) before Cartesian distances are compared to \fIdist\fP.
.TP
\fB\-D\fP
Ignored unless \fB\-N\fP is set.  Selects the resolution of the coastline data set to use ((\fBf\fP)ull, (\fBh\fP)igh, (\fBi\fP)ntermediate, (\fBl\fP)ow, or (\fBc\fP)rude).  The
resolution drops off by ~80% between data sets. [Default is \fBl\fP].  Append \fP+\fP to automatically select a lower resolution should
the one requested not be available [abort if not found].  Note that because the coastlines differ in details it is not guaranteed that a point will remain inside [or outside] when a different resolution is selected.
.TP
\fB\-F\fP
Pass all records whose location is within one of the closed polygons in the multiple-segment
file \fIpolygonfile\fP.  For spherical polygons (lon, lat), make sure no consecutive points
are separated by 180 degrees or more in longitude.  Note that \fIpolygonfile\fP must be in ASCII regardless
of whether \fB\-b\fP is used.
.TP
\fB\-H\fP
Input file(s) has header record(s).  If used, the default number of header records is \fBN_HEADER_RECS\fP.
Use \fB\-Hi\fP if only input data should have header records [Default will write out header records if the
input data have them]. Blank lines and lines starting with # are always skipped.
.TP
\fB\-I\fP
Reverses the sense of the test for each of the criteria specified:
.br
	\fBc\fP  select records NOT inside any point's circle of influence.\"'
.br
	\fBf\fP  select records NOT inside any of the polygons.
.br
	\fBl\fP  select records NOT within the specified distance of any line.
.br
	\fBr\fP  select records NOT inside the specified rectangular region.
.br
	\fBs\fP  select records NOT considered inside as specified by \fB\-N\fP (and \fB\-A\fP, \fB\-D\fP).
.br
	\fBz\fP  select records NOT within the range specified by \fB\-Z\fP.
.TP
\fB\-J\fP
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 \fBMEASURE_UNIT\fP setting in \.gmtdefaults4, but this can be
overridden on the command line by appending \fBc\fP, \fBi\fP, or \fBm\fP to the scale/width value.
When central meridian is optional, default is center of longitude range on \fB\-R\fP option.
Default standard parallel is the equator.
For map height, max dimension, or min dimension, append \fBh\fP, \fB+\fP, or \fB-\fP to the width,
respectively.
.br
More details can be found in the \fBpsbasemap\fP man pages.
.br
.sp
\fBCYLINDRICAL PROJECTIONS:\fP
.br
.sp
\fB\-Jc\fP\fIlon0/lat0/scale\fP (Cassini)
.br
\fB\-Jcyl_stere\fP/[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP (Cylindrical Stereographic)
.br
\fB\-Jj\fP[\fIlon0/\fP]\fIscale\fP (Miller)
.br
\fB\-Jm\fP[\fIlon0\fP/[\fIlat0/\fP]]\fIscale\fP (Mercator)
.br
\fB\-Jm\fP\fIlon0/lat0/scale\fP (Mercator - Give meridian and standard parallel)
.br
\fB\-Jo\fP[\fBa\fP]\fIlon0/lat0/azimuth/scale\fP (Oblique Mercator - point and azimuth)
.br
\fB\-Jo\fP[\fBb\fP]\fIlon0/lat0/lon1/lat1/scale\fP (Oblique Mercator - two points)
.br
\fB\-Joc\fP\fIlon0/lat0/lonp/latp/scale\fP (Oblique Mercator - point and pole)
.br
\fB\-Jq\fP[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP (Cylindrical Equidistant)
.br
\fB\-Jt\fP\fIlon0/\fP[\fIlat0/\fP]\fIscale\fP (TM - Transverse Mercator)
.br
\fB\-Ju\fP\fIzone/scale\fP (UTM - Universal Transverse Mercator)
.br
\fB\-Jy\fP[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP (Cylindrical Equal-Area) 
.br
.sp
\fBCONIC PROJECTIONS:\fP
.br
.sp
\fB\-Jb\fP\fIlon0/lat0/lat1/lat2/scale\fP (Albers)
.br
\fB\-Jd\fP\fIlon0/lat0/lat1/lat2/scale\fP (Conic Equidistant)
.br
\fB\-Jl\fP\fIlon0/lat0/lat1/lat2/scale\fP (Lambert Conic Conformal)
.br
\fB\-Jpoly\fP/[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP ((American) Polyconic)
.br
.sp
\fBAZIMUTHAL PROJECTIONS:\fP
.br
.sp
\fB\-Ja\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Lambert Azimuthal Equal-Area)
.br
\fB\-Je\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Azimuthal Equidistant)
.br
\fB\-Jf\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Gnomonic)
.br
\fB\-Jg\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Orthographic)
.br
\fB\-Jg\fP\fIlon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale\fP (General Perspective).
.br
\fB\-Js\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (General Stereographic)
.br
.sp
\fBMISCELLANEOUS PROJECTIONS:\fP
.br
.sp
\fB\-Jh\fP[\fIlon0/\fP]\fIscale\fP (Hammer)
.br
\fB\-Ji\fP[\fIlon0/\fP]\fIscale\fP (Sinusoidal)
.br
\fB\-Jkf\fP[\fIlon0/\fP]\fIscale\fP (Eckert IV)
.br
\fB\-Jk\fP[\fBs\fP][\fIlon0/\fP]\fIscale\fP (Eckert VI)
.br
\fB\-Jn\fP[\fIlon0/\fP]\fIscale\fP (Robinson)
.br
\fB\-Jr\fP[\fIlon0/\fP]\fIscale\fP (Winkel Tripel)
.br
\fB\-Jv\fP[\fIlon0/\fP]\fIscale\fP (Van der Grinten)
.br
\fB\-Jw\fP[\fIlon0/\fP]\fIscale\fP (Mollweide)
.br
.sp
\fBNON-GEOGRAPHICAL PROJECTIONS:\fP
.br
.sp
\fB\-Jp\fP[\fBa\fP]\fIscale\fP[\fI/origin\fP][\fBr\fP|\fBz\fP] (Polar coordinates (theta,r))
.br
\fB\-Jx\fP\fIx-scale\fP[\fBd\fP|\fBl\fP|\fBp\fP\fIpow\fP|\fBt\fP|\fBT\fP][\fI/y-scale\fP[\fBd\fP|\fBl\fP|\fBp\fP\fIpow\fP|\fBt\fP|\fBT\fP]] (Linear, log, and power scaling)
.br
.TP
\fB\-L\fP
Pass all records whose location is within \fIdist\fP of any of the line segments in the ASCII multiple-segment
file \fIlinefile\fP.  If \fIdist\fP is zero then the 2nd column of each
sub-header in the \fIptfile\fP must have each lines's individual distance value.\"'
Distances are Cartesian and in user units; specify \fB\-fg\fP to indicate spherical distances in km.
If \fBELLIPSOID\fP is spherical then geodesics become great circles (faster to compute than geodesic).
Alternatively, if \fB\-R\fP and \fB\-J\fP are used then geographic coordinates are projected to map coordinates
(in cm, inch, m, or points, as determined by \fBMEASURE_UNIT\fP) before Cartesian distances are compared to \fIdist\fP.
Use \fB\-Lp\fP to ensure only points whose orthogonal projections onto the nearest line-segment
fall within the segments endpoints [Default considers points "beyond" the line's endpoints.\"'
.TP
\fB\-N\fP
Pass all records whose location is inside specified geographical features.
Specify if records should be skipped (s) or kept (k) using 1 of 2 formats:
.br
	\fB\-N\fP\fIwet/dry\fP.
.br
	\fB\-N\fP\fIocean/land/lake/island/pond\fP.
.br
Append \fBo\fP 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].
.TP
\fB\-R\fP
\fIxmin\fP, \fIxmax\fP, \fIymin\fP, and \fIymax\fP specify the Region of interest.  For geographic
regions, these limits correspond to \fIwest, east, south,\fP and \fInorth\fP and you may specify them
in decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append \fBr\fP if lower left and upper right
map coordinates are given instead of w/e/s/n.  The two shorthands \fB\-Rg\fP and \fB\-Rd\fP stand for global domain
(0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude).  Alternatively, specify the name
of an existing grid file and the \fB\-R\fP settings (and grid spacing, if applicable) are copied from the grid.
For calendar time coordinates you may either give (a) relative
time (relative to the selected \fBTIME_EPOCH\fP and in the selected \fBTIME_UNIT\fP; append \fBt\fP to
\fB\-JX\fP|\fBx\fP), or (b) absolute time of the form [\fIdate\fP]\fBT\fP[\fIclock\fP]
(append \fBT\fP to \fB\-JX\fP|\fBx\fP).  At least one of \fIdate\fP and \fIclock\fP
must be present; the \fBT\fP is always required.  The \fIdate\fP string must be of the form [-]yyyy[-mm[-dd]]
(Gregorian calendar) or yyyy[-Www[-d]] (ISO week calendar), while the \fIclock\fP string must be of
the form hh:mm:ss[.xxx].  The use of delimiters and their type and positions must be exactly as indicated
(however, input, output and plot formats are customizable; see \fBgmtdefaults\fP). 
If no map projection is supplied we implicitly set \fB\-Jx\fP 1. Note: only supply \fB\-J\fP when your \fB\-R\fP
is indicating a rectangular region in the projected coordinates (i.e., an oblique projection).
.TP
\fB\-V\fP
Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
.TP
\fB\-Z\fP
Pass all records whose 3rd column (z) lies within the given range.  Input file must have at least
three columns.  To indicate no limit on min or max, specify a hyphen (-).  If your 3rd column
is absolute time then remember to supply \fB\-f\fP 2T.
.TP
\fB\-:\fP
Toggles between (longitude,latitude) and (latitude,longitude) input and/or output.  [Default is (longitude,latitude)].
Append \fBi\fP to select input only or \fBo\fP to select output only.  [Default affects both].
.TP
\fB\-bi\fP
Selects binary input.
Append \fBs\fP for single precision [Default is \fBd\fP (double)].
Uppercase \fBS\fP or \fBD\fP will force byte-swapping.
Optionally, append \fIncol\fP, the number of columns in your binary input file
if it exceeds the columns needed by the program.
Or append \fBc\fP if the input file is netCDF. Optionally, append \fIvar1\fP\fB/\fP\fIvar2\fP\fB/\fP\fI...\fP to
specify the variables to be read.
[Default is 2 input columns].
.TP
\fB\-bo\fP
Selects binary output.
Append \fBs\fP for single precision [Default is \fBd\fP (double)].
Uppercase \fBS\fP or \fBD\fP will force byte-swapping.
Optionally, append \fIncol\fP, the number of desired columns in your binary output file.
[Default is same as input].
.TP
\fB\-f\fP
Special formatting of input and/or output columns (time or geographical data).
Specify \fBi\fP or \fBo\fP to make this apply only to input or output [Default applies to both].
Give one or more columns (or column ranges) separated by commas.
Append \fBT\fP (absolute calendar time), \fBt\fP (relative time in chosen \fBTIME_UNIT\fP since \fBTIME_EPOCH\fP),
\fBx\fP (longitude), \fBy\fP (latitude), or \fBf\fP (floating point) to each column
or column range item.  Shorthand \fB\-f\fP[\fBi\fP|\fBo\fP]\fBg\fP means \fB\-f\fP[\fBi\fP|\fBo\fP]0\fBx\fP,1\fBy\fP
(geographic coordinates).
.TP
\fB\-m\fP
Multiple segment file(s).  Segments are separated by a special record.
For ASCII files the first character must be \fIflag\fP [Default is '>'].
For binary files all fields must be NaN and \fB\-b\fP must
set the number of output columns explicitly.  By default the \fB\-m\fP
setting applies to both input and output.  Use \fB\-mi\fP and \fB\-mo\fP
to give separate settings to input and output.
The \fB\-m\fP option make sure that segment headers in the input files are copied to output, but it has no effect
on the data selection. Selection is always done point by point, not by segment.
.SH ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters in
your \.gmtdefaults4 file.  Longitude and latitude are formatted according to
\fBOUTPUT_DEGREE_FORMAT\fP, whereas other values are formatted according
to \fBD_FORMAT\fP.  Be aware that the format in effect can lead to loss of
precision in the output, which can lead to various problems downstream.  If
you find the output is not written with enough precision, consider switching
to binary output (\fB\-bo\fP if available) or specify more decimals using
the \fBD_FORMAT\fP setting.
.br
This note applies to ASCII output only in combination with binary or netCDF input or the \fB\-:\fP option.
See also the note below.
.SH NOTE ON PROCESSING ASCII INPUT RECORDS
Unless you are using the \fB\-:\fP option, selected ASCII input records are copied verbatim to output.
That means that options like \fB\-foT\fP and settings like \fBD_FORMAT\fP and \fBOUTPUT_DEGREE_FORMAT\fP
will not have any effect on the output.
On the other hand, it allows selecting records with diverse content, including character strings, quoted
or not, comments, and other non-numerical content.
.SH NOTE ON DISTANCES
If options \fB\-C\fP or \fB\-L\fP are selected then distances are Cartesian and in user units;
use \fB\-fg\fP to imply spherical distances in km and geographical (lon, lat) coordinates.
Alternatively, specify \fB\-R\fP and \fB\-J\fP to measure projected Cartesian distances in map units
(cm, inch, m, or points, as determined by \fBMEASURE_UNIT\fP).
.br
This program has evolved over the years.  Originally, the \fB\-R\fP and \fB\-J\fP were mandatory in order
to handle geographic data, but now there is full support for spherical calculations.  Thus, \fB\-J\fP
should only be used if you want the tests to be applied on projected data and not the original
coordinates.  If \fB\-J\fP is used the distances given via \fB\-C\fP and \fB\-L\fP are projected distances.
.SH 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, run
.br
.sp
\fBgmtselect\fP lonlatfile \fB\-fg\fP \fB\-C\fP 300/pts.d \fB\-L\fP 100/lines.d \fB\-Il\fP > subset
.br
.sp
Here, you must specify \fB\-fg\fP so the program knows you are processing geographical data (otherwise
300 would be interpreted as Cartesian distance in x-y units instead of km).
.br
.sp
To keep all points in data.d within the specified region, except the points on land (as determined by the high-resolution
coastlines), use
.br
.sp
\fBgmtselect\fP data.d \fB\-R\fP 120/121/22/24 \fB\-Dh\fP \fB\-Nk\fP/\fBs\fP > subset
.br
.sp
To return all points in quakes.d that are inside the spherical polygon lonlatpath.d, try
.br
.sp
\fBgmtselect\fP quakes.d \fB\-F\fP lonlatpath.d \fB\-fg\fP > subset1
.br
.sp
To return all points in stations.d that are within 5 cm of the point in origin.d for a certain projection, try
.br
.sp
\fBgmtselect\fP stations.d \fB\-F\fP origin.d \fB\-R\fP 20/50/-10/20 \fB\-JM\fP 20c > subset2
.SH GSHHS INFORMATION
The coastline database is GSHHS which is compiled from two sources:
World Vector Shorelines (WVS) and CIA World Data Bank II (WDBII).
In particular, all level-1 polygons (ocean-land boundary) are derived
from the more accurate WVS while all higher level polygons (level 2-4,
representing land/lake, lake/island-in-lake, and island-in-lake/lake-in-island-in-lake boundaries)
are taken from WDBII.  Much processing has taken place to convert WVS
and WDBII data into usable form for \fBGMT\fP:
assembling closed polygons from line segments, checking for duplicates,
and correcting for crossings between polygons.  The area of each polygon
has been determined so that the user may choose not to draw features smaller
than a minimum area (see \fB\-A\fP); one may also limit the highest hierarchical
level of polygons to be included (4 is the maximum).  The 4 lower-resolution
databases were derived from the full resolution database using the
Douglas-Peucker line-simplification algorithm.  The classification of rivers
and borders follow that of the WDBII.  See the \fBGMT\fP Cookbook and
Technical Reference Appendix K for further details.
.br
.SH "SEE ALSO"
.IR gmtdefaults (1),
.IR GMT (1),
.IR grdlandmask (1),
.IR pscoast (1)