<h2>DESCRIPTION</h2>

<em>ps.map</em> is a cartographic mapping program for producing high quality
hardcopy maps in PostScript format. Output can include a raster map, any
number of vector overlays, text labels, decorations, and other spatial data.

<p>A file of mapping instructions that describes the various spatial and textual
information to be printed must be prepared prior to running <em>ps.map</em>.

<h2>NOTES</h2>

The order of commands is generally unimportant but may affect how some layers
are drawn. For example to plot <b>vpoints</b> above <b>vareas</b> list the
<b>vpoints</b> entry first. Raster maps are always drawn first, and only a
single raster map (or 3 if part of a RGB group) may be used.

<p>The hash character ('<code>#</code>') may be used at the beginning of a line
to indicate that the line is a comment. Blank lines will also be ignored.

<p>Be aware that some mapping instructions require the <i>end</i> command
and some do not. Any instruction that allows subcommands will require
it, any instruction that does not allow subcommands will not.

<p>The resolution and extent of raster maps plotted with <em>ps.map</em> are
controlled by the current region settings via the
<a href="g.region.html">g.region</a> module. The output filesize is largely
a function of the region resolution, so special care should be taken
if working with large raster datasets. For example if the desired output is
US-Letter sized paper at 600dpi, with 1" margins and the raster filling the
entire page, the usable area on the page will be 6.5" x 9", which at 600
dots/inch is equivalent to a region of 3900 columns x 5400 rows (see
"<code>g.region -p</code>"). Any higher resolution settings will make the
output file larger, but with a consumer printer you probably won't be able
to resolve any better detail in the hardcopy.

<p>The user can specify negative or greater than 100 percentage values for
positioning several map decorations and embedded EPS-files, to move them
outside the current map box region (for example to position a caption,
barscale, or legend above or below the map box).

<p>One point ("pixel") is 1/72 of an inch.

<p>For users wanting to use special characters (such as accented characters) it
is important to note that <em>ps.map</em> uses <code>ISO-8859-1</code> encoding.
This means that your instructions file will have to be encoded in this
encoding. If you normally work in a different encoding environment (such as
<code>UTF-8</code>), you have to transform your file to the <code>ISO-8859-1</code>
encoding, for example by using the <code>iconv</code> utility:

<div class="code"><pre>
iconv -f UTF-8 -t ISO_8859-1 utf_file &gt; iso_file
</pre></div>


<p><p>
<h2>MAPPING INSTRUCTIONS</h2>

The mapping instructions allow the user to specify various spatial data
to be plotted. These instructions are normally prepared in a regular
text file using a system editor. Some instructions are single line
instructions while others are multiple line. Multiple line instructions
consist of the main instruction followed by a subsection of one or more
additional instructions and are terminated with an <i>end</i> instruction.
<p>
<h3>Instruction keywords:</h3>
[
<a href="#border">border</a>&nbsp;|
<a href="#colortable">colortable</a>&nbsp;|
<a href="#comments">comments</a>&nbsp;|
<a href="#copies">copies</a>&nbsp;|
<a href="#eps">eps</a>&nbsp;|
<a href="#geogrid">geogrid</a>&nbsp;|
<a href="#greyrast">greyrast</a>&nbsp;|
<a href="#grid">grid</a>&nbsp;|
<a href="#group">group</a>&nbsp;|
<a href="#header">header</a>&nbsp;|
<a href="#labels">labels</a>&nbsp;|
<a href="#line">line</a>&nbsp;|
<a href="#mapinfo">mapinfo</a>&nbsp;|
<a href="#maploc">maploc</a>&nbsp;|
<a href="#maskcolor">maskcolor</a>&nbsp;|
<a href="#outline">outline</a>&nbsp;|
<a href="#paper">paper</a>&nbsp;|
<a href="#point">point</a>&nbsp;|
<a href="#psfile">psfile</a>&nbsp;|
<a href="#raster">raster</a>&nbsp;|
<a href="#read">read</a>&nbsp;|
<a href="#rectangle">rectangle</a>&nbsp;|
<a href="#region">region</a>&nbsp;|
<a href="#rgb">rgb</a>&nbsp;|
<a href="#scale">scale</a>&nbsp;|
<a href="#scalebar">scalebar</a>&nbsp;|
<a href="#setcolor">setcolor</a>&nbsp;|
<a href="#text">text</a>&nbsp;|
<a href="#vareas">vareas</a>&nbsp;|
<a href="#vlines">vlines</a>&nbsp;|
<a href="#vpoints">vpoints</a>&nbsp;|
<a href="#vlegend">vlegend</a>&nbsp;|
<a href="#end">end</a>
]

<h3>Common instructions</h3>
Instructions that may be included in the subsection under several
different main instructions are:

<dl>
<dt><b>where</b> <em>x y</em>

<dd>The top left corner of the bounding box of the item to be plotted
is located <em>x</em> inches from the left edge of the paper and
<em>y</em> inches from the top edge of the paper. If <em>x</em> is less than
or equal to zero, the default horizontal location is used.  If <em>y</em>
is less than or equal to zero, the default vertical location is used.

<dt><b>font</b> <em>font name</em>

<dd>The name of the PostScript font.
Fonts present in all PostScript implementations are:
<code>
Times-Roman,
Times-Italic,
Times-Bold,
Times-BoldItalic,
Helvetica,
Helvetica-Oblique,
Helvetica-Bold,
Helvetica-BoldOblique,
Courier,
Courier-Oblique,
Courier-Bold,
and
Courier-BoldOblique</code>.
<br>
The default is Helvetica.
</dd>


<dt><b>fontsize</b> <em>font size</em>

<dd>The size of the PostScript font (in 1/72nds of an inch).
The default is 10 point.
</dd>


<dt><a name="NAMED_COLORS"></a><b>color</b> <em>name</em>

<dd>The following colors names are accepted by <em>ps.map</em>:
<code>
aqua,
black,
blue,
brown,
cyan,
gray,
grey,
green,
indigo,
magenta,
orange,
purple,
red,
violet,
white,
yellow
</code>.
<br><br>
For vectors and some plotting commands you can also specify
'<code>none</code>' or '<code>R:G:B</code>' (e.g '<code>255:0:0</code>').
</dd>

<dt><b>yes|no</b>
<dd>For options that take a yes or no answer, you can simply use the
letters "y" or "n", or type out the full words "Yes" or "No" if you
prefer. It is not case-sensitive. Typically the option with have a
default answer and you only need to specify one if you wish to
override it.
</dd>


</dl>
<p><br>

<h3>Command usage</h3>

<a name="border"></a>
<h2>border</h2>

Controls the border which is drawn around the map area.
<div class="code"><pre>
USAGE:  <b>border</b> [y|n]
    <b>color</b> color
    <b>width</b> #
    <b>end</b>
</pre></div>
The <b>color</b> may be either a standard GRASS color, a R:G:B triplet,
or "none". The width is specified in points, unless followed by an "i"
in which case it is measured in inches.
The default is a black border box of width 1 point.
<p>The border can be turned off completely with the
&quot;<code>border&nbsp;n</code>&quot; instruction. In this case
the <b>end</b> command should not be given as the
main command will be treated as a single line instruction.
<p>
This example would create a grey border 0.1&quot; wide.
<div class="code"><pre>
EXAMPLE:
    <b>border</b>
    <b>color</b> grey
    <b>width</b> 0.1i
    <b>end</b>
</pre></div>
<p>

<a name="colortable"></a>
<h2>colortable</h2>

Prints the color table legend for the raster map layer anywhere on the page.
<div class="code"><pre>
USAGE:    <b>colortable</b> [y|n]
    <b>where</b> x y
    <b>raster</b> raster map
    <b>range</b> minimum maximum
    <b>width</b> table width
    <b>height</b> table height (FP legend only)
    <b>cols</b> table columns
    <b>font</b> font name
    <b>fontsize</b> font size
    <b>color</b> text color
    <b>nodata</b> [Y|n]
    <b>tickbar</b> [y|N]
    <b>discrete</b> [y|n]
    <b>end</b>
</pre></div>

For a categorical (CELL) map the color table will create a legend displaying
the colors for each of a raster map's category values along with its
associated category label. For a floating point (FCELL or DCELL) map a
continuous gradient legend will be created.
<p>
If <b>raster</b> is omitted, the colortable defaults to the previously
registered raster layer.
<p>
The default location for the colortable is immediately below any other
map legend information, starting at the left margin.
The default text color is black.
<p>
Omitting the <b>colortable</b> instruction would result in no color table.
If the colortable is turned off with a &quot;<code>colortable&nbsp;N</code>&quot;
instruction the <b>end</b> command should not be given as the
main command will be treated as a single line instruction.
<p>
See also the <a href="#vlegend">vlegend</a> command for creating vector map
legends.

<h3>Categorical (CELL) Maps</h3>

Adding the <b>nodata N</b> instruction will prevent the "no data" box
from being drawn (category based legends only). If you have manually
added a "no data" label to the cats/ file it will be shown regardless.
<p>
<b>Note</b>:  Be careful about asking for color tables for integer
raster map layers which have many categories, such as elevation.
This could result in the printing of an extremely long color table!
In this situation it is useful to use the <b>discrete N</b> instruction
to force a continuous color gradient legend.
<p>
Be aware that the color table only includes categories which
have a label. You can use the <em>r.category</em> module to add labels.

<h3>Floating point (FCELL and DCELL) Maps</h3>

The legend's <b>range</b> can be adjusted for floating point rasters, but if
set beyond the extent of the map's range be sure that you have set up color
rules with <em>r.colors</em> which cover this range.

If the map has been given a data-units label with <em>r.support</em>
then this label will be displayed.
<!-- bonus prize for code explorers: you can switch the label placement by
    editing the label_posn variable in ps.map/ps_fclrtbl.c -->

For floating point legends <b>width</b> is width of color
band only. <b>height</b> is used only for floating point legend.
A horizontal gradient legend can be achieved by setting the legend
width greater than its height.

Adding the <b>tickbar Y</b> instruction will change the tick mark style
so that ticks are drawn across the color table instead of protruding out
to the right (floating point legends only).

Adding the <b>discrete Y</b> instruction will command the program to treat
the map as a categorical map. In this way the legend can be created with
discrete range bands instead of a continuous gradient. You must use the
<em>r.category</em> or <em>r.support</em> module to set up the range labels
first.

<br>
<p>This example would print a color table immediately below any other map legend
information, starting at the left margin, with 4 columns:
<div class="code"><pre>
EXAMPLE:
    <b>colortable</b> y
        <b>cols</b> 4
        <b>width</b> 4
        <b>end</b>
</pre></div>
<p>

<a name="comments"></a>
<h2>comments</h2>

Prints comments anywhere on the page.
<div class="code"><pre>
USAGE:    <b>comments</b> commentfile
    <b>where</b> x y
    <b>font</b> font name
    <b>fontsize</b> font size
    <b>color</b> text color
    <b>end</b>
</pre></div>
The default location is immediately below the last item item printed,
starting at the left margin. The default text color is black.
<p>If you wish to use parentheses spanning multiple lines you will need to
quote them with a backslash to prevent the PostScript interpreter from
getting confused. e.g. '<b><code>\(</code></b>' and '<b><code>\)</code></b>'

<p>
This example prints in blue
whatever is in the file <em>veg.comments</em> starting at
1.5 inches from the left edge of the page and 7.25 inches from the top of
the page, using a 15/72 inch Helvetica Bold font.
<div class="code"><pre>
EXAMPLE:
    <b>raster</b> vegetation
    <b>comments</b> veg.comments
    <b>where</b> 1.5 7.25
    <b>font</b> Helvetica Bold
    <b>fontsize</b> 15
    <b>color</b> blue
    <b>end</b>
</pre></div>
Presumably, the file
<em>veg.comments</em>
contain comments
pertaining to the raster map layer <em>vegetation</em>,
such as "This map was created by classifying a LANDSAT TM image".
<p>

<a name="copies"></a>
<h2>copies</h2>

Specifies the number of copies to be printed.
<div class="code"><pre>
USAGE:    <b>copies</b> n
</pre></div>
Each page will be printed n times.
<p>This instruction is identical to the <em>copies</em> command line parameter.
<p>

<a name="eps"></a>
<h2>eps</h2>

Places EPS (Encapsulated PostScript) pictures on the output map.
<div class="code"><pre>
USAGE:    <b>eps</b> east north
    <b>eps</b> x% y%
    <b>epsfile</b> EPS file
    <b>scale</b> #
    <b>rotate</b> #
    <b>masked</b> [y|n]
    <b>end</b>
</pre></div>
The EPS picture location is entered in the main
instruction line by giving either the map
coordinates or by using percentages of the geographic region.
The EPS picture will be <i>centered</i> at the given position.
The user must specify full EPS file path <b>epsfile</b>.
The user may also specify the <b>scale</b> of the icon
(default is 1.0), the <b>rotate</b> i.e. rotation in degrees
(default is 0)
and whether the point is to be <b>masked</b>
by the current mask.
(See manual entry for <em><a href="r.mask.html">r.mask</a></em>
for more information on the mask.)
<p>
This example would place a EPS file ./epsf/logo.eps
at the point (E456000 N7890000).  This picture would be
rotated 20 degrees clockwise, 3 times bigger than
in original file and would not be masked by the current mask.
<div class="code"><pre>
EXAMPLE:
    <b>eps</b> 456000 7890000
    <b>epsfile</b> ./epsf/logo.eps
    <b>scale</b> 3
    <b>rotate</b> 20
    <b>masked</b> n
    <b>end</b>
</pre></div>
Of course, multiple EPS pictures may be drawn with multiple
<em>eps</em>
instructions.
<p>

<a name="geogrid"></a>
<h2>geogrid</h2>

Overlays a geographic grid onto the output map.
<div class="code"><pre>
USAGE:    <b>geogrid</b> spacing unit
    <b>color</b> color
    <b>numbers</b> # [color]
    <b>font</b> font name
    <b>fontsize</b> font size
    <b>width</b> #
    <b>end</b>
</pre></div>
The <b>spacing</b> and spacing unit of the geographic grid is given
on the main instruction line.  The <b>spacing</b> unit is given as one of <b>d</b> for
degrees, <b>m</b> for minutes, and <b>s</b> for seconds.
The subsection instructions allow the user to specify
the <b>color</b> of the geographic grid lines,
whether coordinate <b>numbers</b> should appear
on the geographic grid lines, the <b>width</b>
of the lines (accepts decimal points [floating points]
as well as integers), and
if they should appear every grid line (1), every other grid line
(2), etc., and what color the numbers should be.  The defaults are
black grid lines, unnumbered.

<p>
NOTE: The <b>geogrid</b> draws grid numbers on the east and south borders of the map.

<p>
This example would overlay a blue geographic grid with a spacing of 30 minutes
onto the output map.  Alternate grid
lines would be numbered with yellow numbers.
<div class="code"><pre>
EXAMPLE:
    <b>geogrid</b> 30 m
    <b>color</b> blue
    <b>numbers</b> 2 yellow
    <b>end</b>
</pre></div>
<p>

<a name="greyrast"></a>
<h2>greyrast</h2>

Selects a raster map layer for output in shades of grey.
<div class="code"><pre>
USAGE:    <b>greyrast</b> mapname
</pre></div>
For each
<em>ps.map</em>
run, only one raster map layer can be requested (using either the
<em>greyrast</em> or the <em>raster</em> instruction).
<p>

<a name="grid"></a>
<h2>grid</h2>

Overlays a coordinate grid onto the output map.
<div class="code"><pre>
USAGE:    <b>grid</b> spacing
    <b>color</b> color
    <b>numbers</b> # [color]
    <b>cross</b> cross size
    <b>font</b> font name
    <b>fontsize</b> font size
    <b>width</b> #
    <b>end</b>
</pre></div>
The <b>spacing</b> of the grid is given (in the geographic coordinate
system units) on the main instruction line.  The subsection instructions
allow the user to specify
the <b>color</b> of the grid lines,
whether coordinate <b>numbers</b> should appear
on the grid lines, and if they
should appear every grid line (1), every other grid line
(2), etc., and what color the numbers should be.
The <b>cross</b> argument draws grid intersection crosses instead of grid lines,
with cross size given in geographic coordinate system units.
The defaults are black grid lines, unnumbered.

<p>
This example would overlay a green grid with a spacing of 10000 meters
(for a metered database, like UTM) onto the output map.  Alternate grid
lines would be numbered with red numbers.
<div class="code"><pre>
EXAMPLE:
    <b>grid</b> 10000
    <b>color</b> green
    <b>numbers</b> 2 red
    <b>end</b>
</pre></div>
<p>

<a name="group"></a>
<h2>group</h2>

Selects an RGB imagery group for output.
<div class="code"><pre>
USAGE:    <b>group</b> <em>groupname</em>
</pre></div>
This is similar to <em>raster</em>, except that it uses an imagery group
instead of a raster map layer. The group must contain three raster map
layers, comprising the red, green and blue bands of the image.
<p>

<a name="header"></a>
<h2>header</h2>

Prints the map header above the map.
<div class="code"><pre>
USAGE:    <b>header</b>
    <b>file</b> header file
    <b>font</b> font name
    <b>fontsize</b> font size
    <b>color</b> text color
    <b>end</b>
</pre></div>
If the <em>file</em> sub-instruction is absent the header will consist
of the map's title <!-- from hist file -->
and the project's description.<!-- PERMANENT/MYNAME -->
The text will be centered on the page above the map.
The default text color is black.
<p>If the <em>file</em> sub-instruction is given the header will consist
of the text in the text file specified, with some special formatting keys:

<ul>
<li><code>%%</code>  - a literal %</li>
<li><code>%n</code>  - ? newline ?</li>
<li><code>%_</code>  - horizontal bar</li>
<li><code>%c</code>  - "&lt;raster name&gt; in mapset &lt;mapset name&gt;"</li>
<li><code>%d</code>  - today's date</li>
<li><code>%l</code>  - project name</li>
<li><code>%L</code>  - project's text description</li>
<li><code>%m</code>  - mapset name</li>
<li><code>%u</code>  - user name</li>
<li><code>%x</code>  - mask info</li>
<li><code>%-</code>  - advance to this character column number (see example below)</li>
</ul>

Example header file:
<div class="code"><pre>
%_
LOCATION: %-27l  DATE: %d
MAPSET:   %-27m  USER: %u

RASTER MAP: %c
MASK:     %x
%_
Produced by: US Army CERL, Champaign Illinois
Software:    GRASS
%_
</pre></div>

<p>
This example prints (in red) whatever is in the file <em>soils.hdr</em> above
the map, using a 20/72 inch <code>Courier</code> font.
<div class="code"><pre>
EXAMPLE:
    <b>header</b>
    <b>file</b> soils.hdr
    <b>font</b> Courier
    <b>fontsize</b> 20
    <b>color</b> red
    <b>end</b>
</pre></div>
<p>

<a name="labels"></a>
<h2>labels</h2>

Selects a labels file for output (see manual entry for
<em>
<a href="v.label.html">v.label</a>
).</em>
<div class="code"><pre>
USAGE:    <b>labels</b>  labelfile
    <b>font</b> font name
    <b>end</b>
</pre></div>
<p>NOTE: ps.map can read new option 'ROTATE:' from labels file, which
specifies counter clockwise rotation in degrees.
<p>This example would paint labels from the labels file called
<em>town.names</em>.  Presumably, these labels would indicate the names of
towns on the map.
<div class="code"><pre>
EXAMPLE:
    <b>labels</b> town.names
    <b>end</b>
</pre></div>
<p>

<a name="line"></a>
<h2>line</h2>

Draws lines on the output map.
<div class="code"><pre>
USAGE:    <b>line</b> east north east north
    <b>line</b> x% y% x% y%
    <b>color</b> color
    <b>width</b> #
    <b>masked</b> [y|n]
    <b>end</b>
</pre></div>
The beginning and ending points of the line are entered on the main
instruction.  These points can be defined either by map coordinates or
by using percentages of the geographic region.
The user may also specify line <b>color</b>, <b>width</b>
in points (1/72"; accepts decimal values as well as integers),
and if the line is to be <b>masked</b> by the current mask.
(See manual entry for <em><a href="r.mask.html">r.mask</a>
</em> for more information on the mask.)
The line <b>width</b> (if given) is measured in points; an <i>i</i>
directly following the number indicates that the width is given in
inches instead.
<p>
This example would draw a yellow line from the point x=10% y=80%
to the point x=30% y=70%.
This line would be 2 points wide (2/72") and would appear even if
there is a mask.
<div class="code"><pre>
EXAMPLE:
    <b>line</b> 10% 80% 30% 70%
    <b>color</b> yellow
    <b>width</b> 2
    <b>masked</b> n
    <b>end</b>
</pre></div>
Of course, multiple lines may be drawn with multiple
<em>line</em>
instructions.
<p>

<a name="mapinfo"></a>
<h2>mapinfo</h2>

Prints the portion of the map legend containing the scale, grid and
region information, on or below the map.
<div class="code"><pre>
USAGE:    <b>mapinfo</b>
    <b>where</b> x y
    <b>font</b> font name
    <b>fontsize</b> font size
    <b>color</b> text color
    <b>background</b> box color|none
    <b>border</b> color|none
    <b>end</b>
</pre></div>
The default location is immediately below the map,
starting at the left edge of the map.
The default text color is black.
The default background box color is white.
<p><em>border</em> will draw a border around the legend using the specified color.
 (see <a href="#NAMED_COLORS">NAMED COLORS</a>)
<p>
This example prints (in brown) the scale, grid and region information
immediately below the map and starting 1.5 inches from the left edge
of the page, using a 12/72 inch <code>Courier</code> font.

<div class="code"><pre>
EXAMPLE:
    <b>mapinfo</b>
    <b>where</b> 1.5 0
    <b>font</b> Courier
    <b>fontsize</b> 12
    <b>color</b> brown
    <b>end</b>
</pre></div>
<p>

<a name="maploc"></a>
<h2>maploc</h2>

Positions the map on the page.
<div class="code"><pre>
USAGE:    <b>maploc</b>  x y [width height]
</pre></div>
The upper left corner of the map will be positioned <em>x</em> inches from
the left edge of the page and <em>y</em> inches from the top of the page.
If <em>width</em> and <em>height</em> (in inches) are present, the map will be
rescaled, if necessary, to fit.

<p>
This example positions the upper left corner of the map 2.0 inches from
the left edge and 3.5 inches from the top edge of the map.
<div class="code"><pre>
EXAMPLE:
    <b>maploc</b> 2.0 3.5
</pre></div>
<p>

<a name="maskcolor"></a>
<h2>maskcolor</h2>

Color to be used for mask.
<div class="code"><pre>
USAGE:    <b>maskcolor</b>  color
</pre></div>


<a name="outline"></a>
<h2>outline</h2>

Outlines the areas of a raster map layer with a specified color.
<div class="code"><pre>
USAGE:    <b>outline</b>
    <b>color</b>  color
    <b>width</b>  width of line in points
    <b>end</b>
</pre></div>
Distinct areas of the raster map will be separated from each other visually
by drawing a border (or outline) in the specified
<b>color</b>
(default: black). For
<b>width</b>
the program accepts decimal points [floating points] as well as integers.
Note: it is
important the user enter the instruction <b>end</b> even if a color is not
chosen.
(It is hoped that in the future the outline of a different raster map
layer other than the one currently being painted may be placed on the map.)

<p>
This example would outline the category areas of the
<em>soils</em>
raster map layer
in grey.
<div class="code"><pre>
EXAMPLE:
    <b>raster</b> soils
    <b>outline</b>
    <b>color</b> grey
    <b>width</b> 2
    <b>end</b>
</pre></div>
<p>

<a name="paper"></a>
<h2>paper</h2>

Specifies paper size and margins.
<div class="code"><pre>
USAGE:    <b>paper</b> paper name
    <b>height</b> #
    <b>width</b> #
    <b>left</b> #
    <b>right</b> #
    <b>bottom</b> #
    <b>top</b> #
    <b>end</b>
</pre></div>
<b>paper</b> may select predefined paper name
 (a4,a3,a2,a1,a0,us-legal,us-letter,us-tabloid).
 Default paper size is a4. The measures are defined in <em>inches</em>.
<b>left</b>, <b>right</b>, <b>bottom</b> and <b>top</b> are paper margins.
If the plot is rotated with the <b>-r</b> command line flag, measures
are applied to the <em>rotated</em> page.
<p>
<div class="code"><pre>
EXAMPLE:
    <b>paper</b> a3
    <b>end</b>
</pre></div>
<p>
<div class="code"><pre>
EXAMPLE:
    <b>paper</b>
    <b>width</b> 10
    <b>height</b> 10
    <b>left</b> 2
    <b>right</b> 2
    <b>bottom</b> 2
    <b>top</b> 2
    <b>end</b>
</pre></div>
<p>

<a name="point"></a>
<h2>point</h2>

Places additional points or icons on the output map.
<div class="code"><pre>
USAGE:    <b>point</b> east north
    <b>point</b> x% y%
    <b>color</b> color
    <b>fcolor</b> color
    <b>symbol</b> symbol group/name
    <b>size</b> #
    <b>width</b> #
    <b>rotate</b> #
    <b>masked</b> [y|n]
    <b>end</b>
</pre></div>
The point location is entered in the main instruction line by giving either
the map coordinates or by using percentages of the geographic region.
The user may also specify the point <b>color</b>,
the <b>size</b> of symbol in points,
the rotation angle (in degrees CCW),
and whether the point is to be <b>masked</b> by the current mask.
(See manual entry for <em> <a href="r.mask.html">r.mask</a>
</em> for more information on the mask.)
The symbol line <b>width</b> (if given) is measured in points; an <i>i</i>
directly following the number indicates that the width is given in inches
instead. If a <b>width</b> is not given it will be set proportional to the
symbol size.
<p>This example would place a purple diamond (from icon file
<em>diamond</em>) at the point (E456000 N7890000).  This diamond would be the
the size of a 15 points and would not be masked by the current mask.
<div class="code"><pre>
EXAMPLE:
    <b>point</b> 456000 7890000
    <b>fcolor</b> purple
    <b>color</b> black
    <b>symbol</b> basic/diamond
    <b>size</b> 15
    <b>masked</b> n
    <b>end</b>
</pre></div>
Of course, multiple points may be drawn with multiple
<em>point</em>
instructions.
<p>

<a name="psfile"></a>
<h2>psfile</h2>

Copies a file containing PostScript commands into the output file.

<p>
<b>Note:</b>
<em>ps.map</em>
will not search for this file.  The user must be in the
correct directory or specify the full path on the <b>psfile</b> instruction.
(Note to /bin/csh users: ~ won't work with this instruction).
<div class="code"><pre>
USAGE:    <b>psfile</b> filename
</pre></div>
This example copies the file "logo.ps" into the output file.
<div class="code"><pre>
EXAMPLE:
    <b>psfile</b> logo.ps
</pre></div>
<p>

<a name="raster"></a>
<h2>raster</h2>

Selects a raster map layer for output.
<div class="code"><pre>
USAGE:    <b>raster</b> mapname
</pre></div>
For each <em>ps.map</em> run, only one raster map layer (or set
of layers or imagery group; see below) can be requested. If no
raster map layer is requested, a completely white map will be
produced. It can be useful to select no raster map layer in
order to provide a white background for vector maps.
<p>Note that an imagery group selected with the <em>group</em>
option, or a set of three raster layers selected with the
<em>rgb</em> option, count as a raster map layer for the
purposes of the preceding paragraph.
<p>The PostScript file's internal title will be set to the raster map's
title, which in turn may be set with the <em>r.support</em> module.
<p>This example would paint a map of the raster map layer <em>soils</em>.

<div class="code"><pre>
EXAMPLE:
    <b>raster</b> soils
</pre></div>
<p>

<a name="read"></a>
<h2>read</h2>

Provides <em>ps.map</em> with a previously prepared input stream.
<div class="code"><pre>
USAGE:    <b>read</b> previously prepared UNIX file
</pre></div>
Mapping instructions can be placed into a file and read into
<em>ps.map.</em>

<p>
<b>Note:</b>
<em>ps.map</em>
will not search for this file.  The user must be in the
correct directory or specify the full path on the <b>read</b> instruction.
(Note to /bin/csh users: ~ won't work with this instruction).

<p>
This example reads the UNIX file <em>pmap.roads</em> into <em>ps.map</em>.
This file may contain all the <em>ps.map</em> instructions for placing
the vector map layer <em>roads</em> onto the output map.
<div class="code"><pre>
EXAMPLE:
    <b>read</b> pmap.roads
</pre></div>
The user may have created this file because this vector map layer
is particularly useful for many <em>ps.map</em>
outputs.  By using the <b>read</b> option, the user need not enter all the input
for the <b>vector</b> instruction, but simply <b>read</b> the previously prepared
file with the correct instructions.
<p>

<a name="rectangle"></a>
<h2>rectangle</h2>

Draws rectangle on the output map.
<div class="code"><pre>
USAGE:    <b>rectangle</b> east north east north
    <b>rectangle</b> x% y% x% y%
    <b>color</b> color
    <b>fcolor</b> fill color
    <b>width</b> #
    <b>masked</b> [y|n]
    <b>end</b>
</pre></div>
The two corners of the rectangle are entered on the main
instruction.  These points can be defined either by map coordinates or
by using percentages of the geographic region.
The user may also specify line
<b>color</b>, fill color <b>fcolor</b>, <b>width</b>
in points (accepts decimal points [floating points] as well as integers),
and if the rectangle is to be <b>masked</b> by the current mask.
(See manual entry for <em><a href="r.mask.html">r.mask</a></em>
for more information on the mask.)
The border line <b>width</b> (if given) is measured in points; an <i>i</i>
directly following the number indicates that the width is given in inches
instead.
<br>
Multiple rectangles may be drawn by using multiple <em>rectangle</em> instructions.
<p>
This example would draw a yellow rectangle filled by green from the point x=10% y=80%
to the point x=30% y=70%.
The border line would be 1/16" wide and would appear even if there is a mask.
<div class="code"><pre>
EXAMPLE:
    <b>rectangle</b> 10% 80% 30% 70%
    <b>color</b> yellow
    <b>fcolor</b> green
    <b>width</b> 0.0625i
    <b>masked</b> n
    <b>end</b>
</pre></div>
<p>

<a name="region"></a>
<h2>region</h2>

Places the outline of a smaller geographic region
on the output.
<div class="code"><pre>
USAGE:    <b>region</b> regionfile
    <b>color</b> color
    <b>width</b> #
    <b>end</b>
</pre></div>
Geographic region settings are created and saved using <em> the
<a href="g.region.html">g.region</a></em> module.
The <em>ps.map</em> <em>region</em> option can be used to show an outline of
a smaller region which was printed on a separate run of <em>ps.map</em>
on other user-created maps.
<p>The user can specify the <b>color</b>
and the <b>width</b> in point units (accepts decimal points
[floating points] as well as integers) of the outline.
The default is a black border of one point width (1/72").
<p>This example would place a white outline, 2 points wide, of the
geographic region called <em>fire.zones</em> onto the output map.
This geographic region would have been created and saved using
<em><a href="g.region.html">g.region</a></em>.
<div class="code"><pre>
EXAMPLE:
    <b>region</b> fire.zones
    <b>color</b> white
    <b>width</b> 2
    <b>end</b>
</pre></div>
<p>

<a name="rgb"></a>
<h2>rgb</h2>

Selects three raster map layers for output as an RGB color image.
<div class="code"><pre>
USAGE:    <b>rgb</b> <em>red</em> <em>green</em> <em>blue</em>
</pre></div>
This is similar to <em>raster</em>, except that it uses three
raster map layers instead of a single layer. The three layers
are composed to form a color image, similar to <em>d.rgb</em>.
<p>
For each layer, only one of the components of the layer's color
table is used: the red component for the red layer, and so on.
This will give the desired result if all of the layers have a
grey-scale color table, or if each layer's color table uses the
hue appropriate to the layer.
<p>

<a name="scale"></a>
<h2>scale</h2>

Selects a scale for the output map.
<div class="code"><pre>
USAGE:    <b>scale</b> <em>scale</em>
</pre></div>
The scale can be selected either as:
<dl>
<dt>
<dd>a relative ratio, e.g. 1:25000;
<dt>
<dd>an absolute width of the printed map, e.g. 10 inches;
<dt>
<dd>the number of printed paper panels, e.g. 3 panels
<em>.I</em>
(at the present time, only 1 panel is supported);
<dt>
<dd>the number of miles per inch, e.g. 1 inch equals 4 miles.
</dd>
</dl>
<p>
This example would set the scale of the map to 1 unit = 25000
units.
<div class="code"><pre>
EXAMPLE:
    <b>scale</b> 1:25000
</pre></div>
<p>

<a name="scalebar"></a>
<h2>scalebar</h2>

Draws a scalebar on the map.
<div class="code"><pre>
USAGE:    <b>scalebar</b> [f|s]
    <b>where</b> x y
    <b>length</b> overall distance in map units
    <b>units</b> [auto|meters|kilometers|feet|miles|nautmiles]
    <b>height</b> scale height in inches
    <b>segment</b> number of segments
    <b>numbers</b> #
    <b>fontsize</b> font size
    <b>background</b> [Y|n]
    <b>end</b>
</pre></div>
Draw one of two types of scale bar.
Fancy (f) draws alternating black and white scale boxes.
Simple (s) draws a plain line scale. The default type is fancy.

The subsection instructions allow the user to set <b>where</b> the scalebar
is placed, the <b>length</b> of the scalebar (in geographic coordinate
system units, or those given by <b>units</b>),
<!-- bonus prize for code explorers: you can use km and nm abbreviations
     for kilometers and nautmiles units -->
the <b>height</b> of the scalebar in inches, and the number of
<b>segments</b> (or tics for simple). The <b>number</b> of annotations
numbers every n-th segment.

The <b>background</b> command can turn off the background box for the text.
<p>The scalebar <b>length</b> is the only required argument. The defaults are a
fancy scalebar with 4 segments, each segment labeled, and a height of 0.1
inches. The default location is 2 inches from the top of the page and
halfway across.
<p>NOTE: The scalebar is centered on the location given.
<p>This example draws a simple scalebar 1000 meters (for a metered database,
like UTM) long, with tics every 200 meters, labeled every second tic.
The scalebar is drawn 5 inches from the top and 4 inches from the left
and is 0.25 inches high.
<div class="code"><pre>
EXAMPLE:
    <b>scalebar</b> s
    <b>where</b> 4 5
    <b>length</b> 1000
    <b>height</b> 0.25
    <b>segment</b> 5
    <b>numbers</b> 2
    <b>end</b>
</pre></div>


<a name="setcolor"></a>
<h2>setcolor</h2>

Overrides the color assigned to one or more categories
of the raster map layer.
<div class="code"><pre>
USAGE:    <b>setcolor</b> cat(s) color
</pre></div>
This example would set the color for categories 2,5 and 8 of the raster
map layer <em>watersheds</em> to white and category 10 to green.
(<b>NOTE</b>: no spaces are inserted between the category values.)
<div class="code"><pre>
EXAMPLE:
    <b>raster</b> watersheds
    <b>setcolor</b> 2,5,8 white
    <b>setcolor</b> 10 green
</pre></div>
Of course, <em>setcolor</em>
can be requested more than once to override the default color for additional
categories.  More than one category can be changed for each request by listing
all the category values separated by commas (but with no spaces). Also ranges
can be included, for example "1,2,6-10,12". Colors for "<code>null</code>" and the
"<code>default</code>" (i.e. out-of-range) color may also be reassigned.
<p>

<a name="text"></a>
<h2>text</h2>

Places text on the map.
<div class="code"><pre>
USAGE:    <b>text</b>  east north text
    <b>text</b>  x% y% text
    <b>font</b> fontname
    <b>color</b> color|none
    <b>width</b> #
    <b>hcolor</b> color|none
    <b>hwidth</b> #
    <b>background</b> color|none
    <b>border</b> color|none
    <b>fontsize</b> font size
    <b>size</b> #
    <b>ref</b> reference point
    <b>rotate</b> degrees CCW
    <b>xoffset</b> #
    <b>yoffset</b> #
    <b>opaque</b> [y|n]
    <b>end</b>
</pre></div>
The user specifies where the text will be placed by
providing map coordinates or percentages of the geographic region.
The text follows these coordinates on the same instruction line.
More than one line of text can be specified by notating the end of a line with
<b>\n</b>
(e.g. USA<b>\n</b>CERL).
<p>The user can then specify various text features:
<p><b>font:</b>
the PostScript font. Common possibilities are listed at the start of this
help page. The default is <code>Helvetica</code>.
<p><b>color</b>
(see <a href="#NAMED_COLORS">NAMED COLORS</a>);
<p><b>width</b>
of the lines used to draw the text to make thicker letters
(accepts decimal points [floating points] as well as integers);
<p><b>size</b> and <b>fontsize.</b>&nbsp;
<b>size</b> gives the vertical height of the letters in meters on the
ground (text size will grow or shrink depending on the scale at which
the map is painted). Alternatively <b>fontsize</b> can set the font
size directly. If neither <b>size</b> or <b>fontsize</b> is given, a
default font size of 10 will be used;
<p>the highlight color (<b>hcolor</b>) and
the width of the highlight color (<b>hwidth</b>);
<p>the text-enclosing-box <b>background</b> color;
the text box <b>border</b> color;
<p><b>ref.</b>
This reference point specifies the text handle - what
part of the text should be placed on the location specified by the map
coordinates.  Reference points can refer to:
[lower|upper|center] [left|right|center] of the text to be printed;
The default is center center, i.e. the text is centered on the reference point.
<p><b>rotate</b>
sets the text rotation angle, measured in degrees counter-clockwise.
<p><b>yoffset</b>,
which provides finer placement of text by shifting the
text a vertical distance in points (1/72") from the specified north.
The vertical offset will shift the location to the south if positive,
north if negative;
<p><b>xoffset</b>,
which shifts the text a horizontal distance in points from
the specified east The horizontal offset will shift the location east if
positive, west if negative;
<p><b>opaque</b>,
whether or not the text should be <b>opaque</b> to vectors.  Entering <b>no</b>
to the opaque option will allow the user to see any vectors which go
through the text's background box.  Otherwise, they will end at the box's edge.
<p><br>
The following example would place the text <em>SPEARFISH LAND COVER</em>
at the coordinates E650000 N7365000. The text would be a total of
3 points wide (2 pixels of red text and 1 pixel black highlight), have a white
background enclosed in a red box, and be 500 meters in size.  The lower right
corner of the text would be centered over the coordinates provided.  All
vectors on the map would stop at the border of this text.
<div class="code"><pre>
EXAMPLE:
    <b>text</b> 650000 7365000 SPEARFISH LAND COVER
    <b>font</b> romand
    <b>color</b> red
    <b>width</b> 2
    <b>hcolor</b> black
    <b>hwidth</b> 1
    <b>background</b> white
    <b>border</b> red
    <b>size</b> 500
    <b>ref</b> lower left
    <b>opaque</b> y
    <b>end</b>
</pre></div>
<p>

<a name="vareas"></a>
<h2>vareas</h2>

Selects a vector map layer for output and plots areas.
<div class="code"><pre>
USAGE:    <b>vareas</b> vectormap
    <b>layer</b> # (layer number used with cats/where option)
    <b>cats</b> list of categories (e.g. 1,3,5-7)
    <b>where</b> SQL where statement
    <b>masked</b> [y|n]
    <b>color</b> color
    <b>fcolor</b> color
    <b>rgbcolumn</b> column
    <b>width</b> #
    <b>label</b> label to use in legend
    <b>lpos</b> position in legend
    <b>pat</b> pattern file
    <b>pwidth</b> #
    <b>scale</b> #
    <b>end</b>
</pre></div>
The user can specify:
<p><b>color</b> - color of the vector lines or area boundaries;
<p><b>fcolor</b> - the area fill color;
<p><b>rgbcolumn</b> - name of color definition column used for the area fill color;
<p><b>width</b> - width of the vectors lines or area boundaries in points
(accepts decimal points [floating points] as well as integers);
<p><b>masked</b> - whether or not the raster map layer is to be masked
by the current mask;
(see manual entry <em><a href="r.mask.html">r.mask</a></em>
for more information on the mask)
<p><b>cats</b> - which categories should be plotted (default is all);
<p><b>where</b> - select features using a SQL where statement.
For example: <code>vlastnik = 'Cimrman'</code>;
<p><b>label</b> - for description in <a href="#vlegend">vlegend</a>.
Default is: map(mapset);
<p><b>lpos</b> - position vector is plotted in legend. If lpos is
0 then this vector is omitted in legend. If more vectors used the
same lpos then their symbols in legend are merged and label for
first vector is used.
<p><b>pat</b> - full path to pattern file. The pattern file contains header and
simple PostScript commands. It is similar to EPS but more limited, meaning that
while each pattern file is a true EPS file, most EPS files are not useful as pattern
files because they contain restricted commands. Color <!-- and width --> of patterns
are set by <b>fcolor</b> (red, green, ..., none, R:G:B)<!-- no?  and <b>width</b>
until overwritten in the pattern file -->. Color of the boundaries remain set
by the <b>color</b> instruction.
Pattern may be scaled with the <b>scale</b> command. Several standard hatching
patterns are provided in <code>$GISBASE/etc/paint/patterns/</code>.
Demonstrative images can be found on the
<a href="https://grasswiki.osgeo.org/wiki/AreaFillPatterns">GRASS Wiki site</a>.

You can also create your own custom pattern files in a text editor.
Example of pattern file:

<div class="code"><pre>
%!PS-Adobe-2.0 EPSF-1.2
%%BoundingBox: 0 0 10 10
newpath
5 0 moveto
5 10 lineto
stroke
</pre></div>


<p><b>scale</b> - pattern scale
<p><b>pwidth</b> - pattern line width, width is used by pattern until the width is overwritten
in pattern file.
<p>
<div class="code"><pre>
EXAMPLE:
    <b>vareas</b> forest
    <b>color</b> blue
    <b>width</b> 1
    <b>masked</b> y
    <b>cats</b> 2,5-7
    <b>end</b>
</pre></div>
<p>

<a name="vlines"></a>
<h2>vlines</h2>

Selects a vector map layer for output and plots lines.
<div class="code"><pre>
USAGE:    <b>vlines</b> vectormap
    <b>type</b> line and/or boundary
    <b>layer</b> # (layer number used with cats/where option)
    <b>cats</b> list of categories (e.g. 1,3,5-7)
    <b>where</b> SQL where statement like: vlastnik = 'Cimrman'
    <b>masked</b> [y|n]
    <b>color</b> color
    <b>rgbcolumn</b> column
    <b>width</b> #
    <b>cwidth</b> #
    <b>hcolor</b> color
    <b>hwidth</b> #
    <b>offset</b> #
    <b>coffset</b> #
    <b>ref</b> left|right
    <b>style</b> 00001111
    <b>linecap</b> style
    <b>label</b> label
    <b>lpos</b> #
    <b>end</b>
</pre></div>
The user can specify:
<p><b>type</b> - the default is lines only;
<p><b>color</b> - color of the vector lines or area boundaries;
<p><b>rgbcolumn</b> - name of color definition column used for the vector lines
or area boundaries;
<p><b>width</b> - width of the vectors lines or area boundaries in points
(accepts decimal points [floating points] as well as integers);
<p><b>cwidth</b> - width of the vectors lines. If cwidth is used then
width of line is equal to cwidth * category value and width is
used in legend;
<p><b>hcolor</b> - the highlight color for the vector lines;
<p><b>hwidth</b> - the width of the highlight color in points;
<p><b>offset</b> (experimental) - offset for the vectors lines in points (1/72")
for plotting parallel lines in distance equal to offset (accepts positive or
negative decimal points). Useful to print streets with several parallel lanes;
<p><b>coffset</b> (experimental) - offset for the vectors lines. If coffset
is used then  offset of line is equal to coffset * category value and offset
is used in legend;
<p><b>ref</b> (experimental) - line justification.
<p><b>masked</b> - whether or not the raster map layer is to be masked
by the current mask;
(see manual entry <em><a href="r.mask.html">r.mask</a></em>
for more information on the mask);
<p><b>style</b> - the line style allows the vectors to be dashed in different
patterns.  This is done by either typing "solid", "dashed", "dotted", or
"dashdotted", or as a series of 0's and 1's in a desired sequence or pattern.
The first block of repeated zeros or ones represents "draw", the second
block represents "blank".
An even number of blocks will repeat the pattern, an odd number of blocks
will alternate the pattern.
The default is "solid";
<p><b>linecap</b> - the linecap specifies the look of the ends of the line,
or the end of the dashes in a dashed line. The parameters are:
'butt' for butt caps (default), 'round' for round caps and 'extended_butt'
for extended butt caps. The shape of the round and the extended butt caps
is related to the line thickness: for round butts the radius is half the
linewidth, while for extended butt the line will extend for half the linewidth.
<p><b>cats</b> - which categories should be plotted (default is all);
<p><b>label</b> - for description in <a href="#vlegend">vlegend</a>.
Default is: map(mapset);
<p><b>lpos</b> - position vector is plotted in legend. If lpos is
0 then this vector is omitted in legend. If more vectors used the
same lpos then their symbols in legend are merged and label for
first vector is used.
<p>
<div class="code"><pre>
EXAMPLE:
    <b>vlines</b> streams
    <b>color</b> blue
    <b>width</b> 2
    <b>hcolor</b> white
    <b>hwidth</b> 1
    <b>masked</b> y
    <b>cats</b> 2
    <b>label</b> Streams - category 2
    <b>end</b>
</pre></div>
<p>

<a name="vpoints"></a>
<h2>vpoints</h2>

Selects vector point data to be placed on the output map
<div class="code"><pre>
USAGE:    <b>vpoints</b> vectormap
    <b>type</b> point and/or centroid
    <b>layer</b> # (layer number used with cats/where/sizecol options)
    <b>cats</b> list of categories (e.g. 1,3,5-7)
    <b>where</b> SQL where statement like: vlastnik = 'Cimrman'
    <b>masked</b> [y|n]
    <b>color</b> color
    <b>fcolor</b> color
    <b>rgbcolumn</b> column
    <b>width</b> #
    <b>eps</b> epsfile
    <b>symbol</b> symbol group/name
    <b>size</b> #
    <b>sizecolumn</b> attribute column used for symbol sizing
    <b>scale</b> scaling factor for sizecolumn values
    <b>rotate</b> #
    <b>rotatecolumn</b> column
    <b>label</b> legend label
    <b>lpos</b> position in legend
    <b>end</b>
</pre></div>
The user may specify the
the <b>color</b> of the sites (see section on <a href="#NAMED_COLORS">NAMED COLORS</a>);
either the GRASS <b>symbol</b> or
the <b>eps</b> Encapsulated Postscript file to be used to represent the presence of a site
(if '<b>$</b>' is used in the EPS file path it will be replaced by category number);
and <b>rotate</b> (in degrees) for counter-clockwise rotation.
<br>
The size of the icon (number of times larger than the size it is in
the icon file) is typically given by the <b>size</b> option. Alternatively
the size of the symbol or EPS graphic can be taken from an attribute column
by using the <b>sizecolumn</b> command. The value given by <b>sizecolumn</b> may be
scaled by using the <b>scale</b> factor setting (default scaling is 1.0).
In a similar manner symbol color can be read from <b>rgbcolumn</b>
and the rotation angle read from <b>rotatecolumn</b>.

<div class="code"><pre>
EXAMPLE:
    <b>vpoints</b> windmills
    <b>color</b> blue
    <b>symbol</b> mills/windmill
    <b>size</b> 10
    <b>end</b>
</pre></div>
<p>
<a name="vlegend"></a>
<h2>vlegend</h2>

Prints the portion of the map legend containing the
vector information, on or below the map.

<div class="code"><pre>
USAGE:    <b>vlegend</b>
    <b>where</b> x y
    <b>font</b> font name
    <b>fontsize</b> font size
    <b>width</b> width of color symbol
    <b>cols</b> number of columns to print
    <b>span</b> column separation
    <b>border</b> color|none
    <b>end</b>
</pre></div>
The default location is immediately below the legend containing the
scale, grid and region information, starting at the left edge of the map.
If the <em>where</em> instruction is present and <em>y</em> is less than or
equal to zero, the vector legend will be positioned immediately below
the map, starting <em>x</em> inches from the left edge of the page.
<p><em>width</em> is the width in inches of the color symbol (for lines)
in front of the legend text. The default is 1/24 * fontsize inches.
<p><em>cols</em> is the number of columns to split the legend into. The
default is one column. The maximum number of columns is 10, or equal
to the number of legend entries if there are less than 10 entries.
<p><em>span</em> is the column separation distance between the left edges of
two columns in a multicolumn legend. It is given in inches.
The default is automatic scaling based on the left margin and the right
hand side of the map box.
<p><em>border</em> will draw a border around the legend using the specified color.
 (see <a href="#NAMED_COLORS">NAMED COLORS</a>)
<p>Alternatively, the user can create a custom legend by using the
<a href="#rectangle">rectangle</a>, <a href="#point">point</a>, and
<a href="#text">text</a> instructions.
<p>See also the <a href="#colortable">colortable</a> command for creating
raster map legends.
<p>This example prints the vector legend
immediately below the map and starting 4.5 inches from the left edge
of the page, using a 12/72 inch Helvetica font.

<div class="code"><pre>
EXAMPLE:
    <b>vlegend</b>
    <b>where</b> 4.5 0
    <b>font</b> Courier
    <b>fontsize</b> 12
    <b>end</b>
</pre></div>
<p>

<a name="end"></a>
<h2>end</h2>

Terminates input and begin painting the map.

<div class="code"><pre>
USAGE:    <b>end</b>
</pre></div>
<br>
<p>

<h2>EXAMPLES</h2>


The following are examples of <em>ps.map</em> script files.
<p><h3>Simple example</h3>
The file has been named <em>simple_map.txt</em>:

<div class="code"><pre>
<i># this ps.map example draws a map of Wake county, NC</i>
<b>raster</b> elevation
<b>vlines</b> roadsmajor
  <b>color</b> 30:144:255
  <b>width</b> 2
  <b>end</b>
<b>text</b> 50% 105% Wake County Terrain and Roads
   <b>size</b> 550
   <b>end</b>
<b>end</b>
</pre></div>

Generate map as Postsript file:
<div class="code"><pre>
ps.map input=simple_map.txt output=simple_map.ps
</pre></div>

<center>
<img src="ps_map_basic.png">
<p><em>Figure: Result of for the a simple Wake county terrain and roads example</em></p>
</center>

<h3>More complicated example</h3>

The following is content of a file named <em>elevation_map.txt</em>:

<!--
regular expression for syntax highlight
(replace spaces around bs by gt and lt)
^( *)([a-z]+)([ ]|$)
\1 b \2 /b \3
-->

<div class="code"><pre>
<i># this ps.map example draws a map of Wake county, NC</i>
<b>raster</b> elevation
<b>colortable</b> y
  <b>where</b> 1 6.0
  <b>cols</b> 4
  <b>width</b> 4
  <b>font</b> Helvetica
  <b>end</b>
<b>setcolor</b> 6,8,9 white
<b>setcolor</b> 10 green
<b>vlines</b> streams
  <b>width</b> 0.1
  <b>color</b> blue
  <b>masked</b> n
  <b>label</b> streams
  <b>end</b>
<b>vlines</b> roadsmajor
  <b>width</b> 1.5
  <b>style</b> 1111
  <b>color</b> grey
  <b>masked</b> n
  <b>label</b> major roads
  <b>end</b>
<b>vlegend</b>
  <b>where</b> 4.5 0
  <b>font</b> Courier
  <b>fontsize</b> 8
  <b>end</b>
<b>text</b> 30% 100% Wake County Terrain
  <b>color</b> black
  <b>width</b> 1
  <b>background</b> white
  <b>size</b> 550
  <b>ref</b> lower left
  <b>end</b>
<b>text</b> 92% -25% meters
  <b>color</b> black
  <b>width</b> 1
  <b>background</b> white
  <b>size</b> 550
  <b>ref</b> lower left
  <b>end</b>
<b>scale</b> 1:125000
<b>scalebar</b> f
  <b>where</b> 1.5 5.5
  <b>length</b> 5000
  <b>height</b> 0.05
  <b>segment</b> 5
  <b>numbers</b> 5
  <b>end</b>
<b>geogrid</b> 60 s
  <b>color</b> gray
  <b>numbers</b> 2 black
  <b>end</b>
<b>paper</b> a4
   <b>end</b>
<b>end</b>
</pre></div>

This script file can be entered at the command line:

<div class="code"><pre>
# First set the region
g.region raster=elevation

# Generate map as Postsript file
ps.map input=elevation_map.txt output=elevation.ps
</pre></div>

<center>
<img src="ps_map.png">
<p><em>Figure: Result of for the more complicated Wake county, NC example</em></p>
</center>

<!--
todos according to things which were in the Spearfish example
TODO: now we have no example which would contain comment:
# Generate comment file (or use text editor)
echo "Spearfish (SD) soils" &gt; soil.cmt
TODO: now we have no example with point and line
line 606969.73 3423092.91 616969.73 3423092.91
   color yellow
   width 2
   end
point 40% 60%
   color purple
   symbol basic/diamond
   size 25
   masked n
   end
TODO: example with outline
outline
   color black
   width 1
   end
-->

<p>More examples can be found on the
<a href="https://grasswiki.osgeo.org/wiki/Ps.map_scripts">GRASS Wiki</a>
help site.
<p>

<h2>SEE ALSO</h2>

<em>
<a href="g.gui.psmap.html">g.gui.psmap</a>,
<a href="g.region.html">g.region</a>,
<a href="v.label.html">v.label</a>,
<a href="wxGUI.html">wxGUI</a>
</em>

<h2>AUTHORS</h2>

Paul Carlson, USDA, SCS, NHQ-CGIS<br>
Modifications: Radim Blazek, Glynn Clements, Bob Covill, Hamish Bowman