.TH r.transect
.SH NAME
\fIr.transect\fR \- Outputs raster map layer values lying along
user defined transect line(s).
.br
.I "(GRASS Raster Program)"
.SH SYNOPSIS
\fBr.transect\fR
.br
\fBr.transect help\fR
.br
.nf
\fBr.transect  map\fR\*=\fIname\fR [\fBresult\fR\*=\fItype\fR] [\fBwidth\fR\*=\fIvalue\fR]
   \fBline\fR\*=\fIeast,north,azimuth,distance\fR[\fI,east,north,azimuth,distance,...\fR]
.fi
.SH DESCRIPTION
This progream outputs, in ASCII, the values in a raster map which lie along
one or more user-defined transect lines.  The transects are described by their
starting coordinates, azimuth, and distance.
The transects may be single-cell wide lines, or multiple-cell wide lines.
The output, for each transect, may be the values at each of the cells,
or a single aggregate value (e.g., average or median value).
.SH "COMMAND LINE OPTIONS"
\fBParameters:\fR
.IP \fBmap\*=\fIname\fR 18
Name of an existing raster map layer to be queried.
.IP \fBresult\*=\fItype\fR 18
Type of results to be output.
.br
Options:  raw, median, average
.br
Default:  raw

If raw results are output, each of the category values assigned to cells falling
along the transect are output.  Median and average results output a single value
per transect:  average outputs the average category value of all cells
along the transect;  median outputs the median category value of these cells.
.IP "\fBline\fR\*=\fIeast,north,azimuth,distance\fR[\fI,east,north,azimuth,distance,...\fR]" 18
A definition of (each) transect line, specified by the
geographic coordinates of its starting point (\fIeasting, northing\fR),
the angle and direction of its travel (\fIazimuth\fR),
and its distance (\fIdistance\fR).

The \fIazimuth\fR is an angle, in degrees, measured to the east of north.
The \fIdistance\fR is in map units (meters for a metered database, like UTM).
.IP \fBwidth\*=\fIvalue\fR 18
Profile width,  in cells (odd number).
.br
Default:  1

Wider transects can be specified by setting the width to 3, 5, 7, etc.
The transects are then formed as rectangles 3, 5, 7, etc., cells wide.
.SH OUTPUT FORMAT
The output from this command is printed to standard output in ASCII.
The format of the output varies slightly depending on the type of result
requested.
The first number printed is the number of cells associated with the transect.
For raw output, this number is followed by the individual cell values.
For average and median output, this number is followed by a single value
(i.e., the average or the median value).

The following examples use the \fIelevation.dem\fR raster map layer in the
\fIspearfish\fR sample data set distributed with GRASS 4.0.
(To reproduce these examples, first set the geographic region as shown:
.LP
.RS
\fBg.region\ rast\*=elevation.dem \fR


Single-cell transect:
.LP
.RS
.B "r.transect map\*=elevation.dem line\*=593655,4917280,45,100"

4 1540 1551 1557 1550
.RE


3-cell wide transect:
.LP
.RS
.B "r.transect map\*=elevation.dem line\*=593655,4917280,45,100 width\*=3"

22 1556 1538 1525 1570 1555 1540 1528 1578 1565 1551 1536 1523 1569 1557 1546 1533
1559 1550 1542 1552 1543 1548

(Output appears as multiple lines here, but is really one line)
.RE


3-cell wide transect average:
.LP
.RS
.B "r.transect map\*=elevation.dem line\*=593655,4917280,45,100 width\*=3 result\*=average"

22 1548.363636
.RE


3-cell wide transect median:
.LP
.RS
.B "r.transect map\*=elevation.dem line\*=593655,4917280,45,100 width\*=3 result\*=median"

22 1549.000000
.RE
.SH NOTES
This program is a front-end to the \fIr.profile\fR program.
It simply converts the azimuth and distance to an ending coordinate
and then runs \fIr.profile\fR.
.SH "SEE ALSO"
.I r.profile
and
.I parser
.SH AUTHOR
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory