.TH r.mask.points
.SH NAME
\fIr.mask.points\fR \-Examines and filters lists of points constituting lines
to determine if they fall within current region and mask and optionally 
an additional
raster map. 
.br
.I "(GRASS Raster Program)"
.SH SYNOPSIS
\fBr.mask.points\fR
.br
\fBr.mask.points help\fR
.br
\fBr.mask.points\fR [\fB\-r\fR] \fB[mask=\fIname\fR] \fB[input=\fIname\fR] \fB[fs=\fIname\fR]
.SH DESCRIPTION
.B r.mask.points
filters a list of points based on the current region and current mask.
The point list consists of lines which have the following format

.RS
.TS
tab(:);
ccc.
easting:northing:[text]
:.:
:.:
:.:
easting:northing:[text]
.TE
.RE

The eastings and northings define points in the coordinate space. Each line
is examined to determine if the point falls within the current region, current
mask (if any), and optionally an additional raster map that acts as a secondary
mask. If the point falls outside the current region or falls in a grid cell
that has value zero (either in the current mask, or the specified mask file),
then the entire line is suppressed. Otherwise it is printed exactly as it is input.
There may be arbitrary text following the coordinate pairs and this text
is output as well.
.SH "COMMAND LINE OPTIONS"
.LP
Flags
.IP \fI-r\fR
Coordinates are reversed: north east

Normal input has the east first and the north second. This option allows
the order of the coordinates to be north first and east next.
.LP
Parameters
.IP \fImask\fR
Raster map used to mask points

This parameter is optional. If not specified, then the points are
mask by the default mask (if there is one). If it is specified,
then the points are mask by this layer as well as the default mask.
.IP \fIinput\fR
Unix input containing point list

If not specified it is assumed that the user will either redirect the input
from a file:

.ti +5
\fIr.mask.points\fP < file

or pipe the results from some other process (e.g., a DBMS query) into
.I r.mask.points

.ti +5
some_process | \fIr.mask.points\fP 

.IP \fIfs\fR
Input field separator character

If the coordinates are not separated by white space, but by some other
character, this option specifies that character. For example, if a colon
is used between the east and north, then
.I r.mask.point
can be told this by:

.ti +5
\fIr.mask.points\fP fs=:

.SH NOTES
Lines that make it through the filtering are output intact. This means
that if the coordinates are reversed they will remain reversed on output.
If there is a field separator, it will also be output.
.SH "SEE ALSO"
.I r.mask, 
.I s.out.ascii, 
.I s.in.ascii, 
.I d.points

.SH "AUTHOR"
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory