xenial (1) ps.map.1grass.gz

Provided by: grass-doc_7.0.3-1build1_all bug

NAME

       ps.map  - Produces hardcopy PostScript map output.

KEYWORDS

       postscript, printing

SYNOPSIS

       ps.map
       ps.map --help
       ps.map [-rpeb] input=name output=name  [copies=integer]   [--overwrite]  [--help]  [--verbose]  [--quiet]
       [--ui]

   Flags:
       -r
           Rotate plot 90 degrees

       -p
           List paper formats (name width height left right top bottom(margin))

       -e
           Create EPS (Encapsulated PostScript) instead of PostScript file

       -b
           Describe map-box’s position on the page and exit (inches from top-left of paper)

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       input=name [required]
           File containing mapping instructions
           Use ’-’ to enter instructions from keyboard)

       output=name [required]
           Name for PostScript output file

       copies=integer
           Number of copies to print
           Options: 1-20

DESCRIPTION

       ps.map 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.

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

NOTES

       The  order  of commands is generally unimportant but may affect how some layers are drawn. For example to
       plot vpoints above vareas list the vpoints 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.

       The  hash  character (’#’) may be used at the beginning of a line to indicate that the line is a comment.
       Blank lines will also be ignored.

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

       The  resolution  and  extent  of  raster  maps  plotted  with ps.map are controlled by the current region
       settings via the g.region 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 300dpi, with 1" margins and the raster filling the entire page, the usable  area
       on  the  page  will be 6.5" x 9", which at 300 dots/inch is equivalent to a region of 1950 columns x 2700
       rows (see "g.region -p"). 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.

       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).

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

       For  users  wanting  to use special characters (such as accented characters) it is important to note that
       ps.map uses ISO-8859-1 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 UTF-8), you have to transform
       your file to the ISO-8859-1 encoding, for example by using the iconv utility:
       iconv -f UTF-8 -t ISO_8859-1 utf_file > iso_file

MAPPING INSTRUCTIONS

       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 end
       instruction.

   Instruction keywords:
       [ border | colortable | comments | copies | eps | geogrid | greyrast | grid | group | header |  labels  |
       line  |  mapinfo  |  maploc  | maskcolor | outline | paper | point | psfile | raster | read | rectangle |
       region | rgb | scale | scalebar | setcolor | text | vareas | vlines | vpoints | vlegend | end ]

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

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

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

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

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

       yes|no
           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.

   Command usage

border

       Controls the border which is drawn around the map area.
       USAGE:  border [y|n]
            color color
            width #
            end
       The color 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.

       The border can be turned off completely with the "border n" instruction. In this  case  the  end  command
       should not be given as the main command will be treated as a single line instruction.

       This example would create a grey border 0.1" wide.
       EXAMPLE:
            border
            color grey
            width 0.1i
            end

colortable

       Prints the color table legend for the raster map layer anywhere on the page.
       USAGE:    colortable [y|n]
            where x y
            raster raster map
            range minimum maximum
            width table width
            height table height (FP legend only)
            cols table columns
            font font name
            fontsize font size
            color text color
            nodata [Y|n]
            tickbar [y|N]
            discrete [y|n]
            end
       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.

       If raster is omitted, the colortable defaults to the previously registered raster layer.

       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.

       Omitting the colortable instruction would result in no color table.  If the colortable is turned off with
       a "colortable N" instruction the end command should not be given as the main command will be treated as a
       single line instruction.

       See also the vlegend command for creating vector map legends.

   Categorical (CELL) Maps
       Adding the nodata N 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.

       Note:  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 discrete N instruction to force a continuous color gradient legend.

       Be  aware  that  the  color table only includes categories which have a label. You can use the r.category
       module to add labels.

   Floating point (FCELL and DCELL) Maps
       The legend’s range 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 r.colors which cover this range.  If the map has been
       given a data-units label with r.support then this label will be displayed.  For  floating  point  legends
       width  is width of color band only. height 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  tickbar  Y
       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  discrete  Y  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 r.category or r.support module to
       set up the range labels first.

       This  example  would  print a color table immediately below any other map legend information, starting at
       the left margin, with 4 columns:
       EXAMPLE:
            colortable y
               cols 4
               width 4
               end

comments

       Prints comments anywhere on the page.
       USAGE:    comments commentfile
            where x y
            font font name
            fontsize font size
            color text color
            end
       The default location is immediately below the last item item printed, starting at the  left  margin.  The
       default text color is black.

       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. ’\(’ and ’\)’

       This example prints in blue whatever is in the file veg.comments 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.
       EXAMPLE:
            raster vegetation
            comments veg.comments
            where 1.5 7.25
            font Helvetica Bold
            fontsize 15
            color blue
            end
       Presumably, the file veg.comments contain comments pertaining to the raster map layer vegetation, such as
       "This map was created by classifying a LANDSAT TM image".

copies

       Specifies the number of copies to be printed.
       USAGE:    copies n
       Each page will be printed n times.

       This instruction is identical to the copies command line parameter.

eps

       Places EPS (Encapsulated PostScript) pictures on the output map.
       USAGE:    eps east north
            eps x% y%
            epsfile EPS file
            scale #
            rotate #
            masked [y|n]
            end
       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 centered at the given position.
       The user must specify full EPS file path epsfile.  The user may  also  specify  the  scale  of  the  icon
       (default  is  1.0),  the  rotate  i.e.  rotation in degrees (default is 0) and whether the point is to be
       masked by the current mask.  (See manual entry for r.mask for more information on the mask.)

       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.
       EXAMPLE:
            eps 456000 7890000
            epsfile ./epsf/logo.eps
            scale 3
            rotate 20
            masked n
            end
       Of course, multiple EPS pictures may be drawn with multiple eps instructions.

geogrid

       Overlays a geographic grid onto the output map.
       USAGE:    geogrid spacing unit
            color color
            numbers # [color]
            font font name
            fontsize font size
            width #
            end
       The spacing and spacing unit of the geographic grid is given on the main instruction line.   The  spacing
       unit  is  given  as  one of d for degrees, m for minutes, and s for seconds.  The subsection instructions
       allow the user to specify the color of the geographic  grid  lines,  whether  coordinate  numbers  should
       appear  on the geographic grid lines, the width 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.

       NOTE: The geogrid draws grid numbers on the east and south borders of the map.

       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.
       EXAMPLE:
            geogrid 30 m
            color blue
            numbers 2 yellow
            end

greyrast

       Selects a raster map layer for output in shades of grey.
       USAGE:    greyrast mapname
       For each ps.map run, only one raster map layer can be requested (using either the greyrast or the  raster
       instruction).

grid

       Overlays a coordinate grid onto the output map.
       USAGE:    grid spacing
            color color
            numbers # [color]
            cross cross size
            font font name
            fontsize font size
            width #
            end
       The  spacing  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  color  of  the  grid  lines,  whether
       coordinate  numbers 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  cross  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.

       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.
       EXAMPLE:
            grid 10000
            color green
            numbers 2 red
            end

group

       Selects an RGB imagery group for output.
       USAGE:    group groupname
       This  is similar to raster, 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.

       Prints the map header above the map.
       USAGE:    header
            file header file
            font font name
            fontsize font size
            color text color
            end
       If the file sub-instruction is absent the header will consist of  the  map’s  title  and  the  location’s
       description.  The text will be centered on the page above the map.  The default text color is black.

       If the file sub-instruction is given the header will consist of the text in the text file specified, with
       some special formatting keys:

           •   %%  - a literal %

           •   %n  - ? newline ?

           •   %_  - horizontal bar

           •   %c  - "<raster name> in mapset <mapset name>"

           •   %d  - today’s date

           •   %l  - location name

           •   %L  - Location’s text description

           •   %m  - mapset name

           •   %u  - user name

           •   %x  - mask info

           •   %-  - advance to this character column number (see example below)
       Example header file:
       %_
       LOCATION: %-27l  DATE: %d
       MAPSET:   %-27m  USER: %u
       RASTER MAP: %c
       MASK:     %x
       %_
       Produced by: US Army CERL, Champaign Illinois
       Software:    GRASS
       %_

       This example prints (in red) whatever is in the file soils.hdr above the map, using a 20/72 inch  Courier
       font.
       EXAMPLE:
            header
            file soils.hdr
            font Courier
            fontsize 20
            color red
            end

labels

       Selects a labels file for output (see manual entry for v.label ).
       USAGE:    labels  labelfile
            font font name
            end

       NOTE:  ps.map  can read new option ’ROTATE:’ from labels file, which specifies counter clockwise rotation
       in degrees.

       This example would paint labels from the labels file called town.names.  Presumably, these  labels  would
       indicate the names of towns on the map.
       EXAMPLE:
            labels town.names
            end

line

       Draws lines on the output map.
       USAGE:    line east north east north
            line x% y% x% y%
            color color
            width #
            masked [y|n]
            end
       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 color, width in points (1/72"; accepts decimal values as well as integers), and if the line
       is to be masked by the current mask.  (See manual entry for r.mask
        for more information on the mask.)  The line width (if given) is  measured  in  points;  an  i  directly
       following the number indicates that the width is given in inches instead.

       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.
       EXAMPLE:
            line 10% 80% 30% 70%
            color yellow
            width 2
            masked n
            end
       Of course, multiple lines may be drawn with multiple line instructions.

mapinfo

       Prints the portion of the map legend containing the scale, grid and region information, on or  below  the
       map.
       USAGE:    mapinfo
            where x y
            font font name
            fontsize font size
            color text color
            background box color|none
            border color|none
            end
       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.

       border will draw a border around the legend using the specified color.  (see NAMED COLORS)

       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 Courier font.
       EXAMPLE:
            mapinfo
            where 1.5 0
            font Courier
            fontsize 12
            color brown
            end

maploc

       Positions the map on the page.
       USAGE:    maploc  x y [width height]
       The  upper left corner of the map will be positioned x inches from the left edge of the page and y inches
       from the top of the page.  If width and height (in inches) are present, the  map  will  be  rescaled,  if
       necessary, to fit.

       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.
       EXAMPLE:
            maploc 2.0 3.5

maskcolor

       Color to be used for mask.
       USAGE:    maskcolor  color

outline

       Outlines the areas of a raster map layer with a specified color.
       USAGE:    outline
            color  color
            width  width of line in points
            end
       Distinct areas of the raster map will be separated from each other  visually  by  drawing  a  border  (or
       outline)  in the specified color (default: black). For width the program accepts decimal points [floating
       points] as well as integers.  Note: it is important the user enter the instruction end 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.)

       This example would outline the category areas of the soils raster map layer in grey.
       EXAMPLE:
            raster soils
            outline
            color grey
            width 2
            end

paper

       Specifies paper size and margins.
       USAGE:    paper paper name
            height #
            width #
            left #
            right #
            bottom #
            top #
            end
       paper 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 inches.  left, right, bottom and top are paper margins.  If the
       plot is rotated with the -r command line flag, measures are applied to the rotated page.

       EXAMPLE:
            paper a3
            end

       EXAMPLE:
            paper
            width 10
            height 10
            left 2
            right 2
            bottom 2
            top 2
            end

point

       Places additional points or icons on the output map.
       USAGE:    point east north
            point x% y%
            color color
            fcolor color
            symbol symbol group/name
            size #
            width #
            rotate #
            masked [y|n]
            end
       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 color, the size of
       symbol in points, the rotation angle (in degrees CCW), and whether the point  is  to  be  masked  by  the
       current mask.  (See manual entry for  r.mask
        for  more  information  on  the  mask.)   The  symbol  line width (if given) is measured in points; an i
       directly following the number indicates that the width is given in inches instead.  If  a  width  is  not
       given it will be set proportional to the symbol size.

       This example would place a purple diamond (from icon file diamond) 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.
       EXAMPLE:
            point 456000 7890000
            fcolor purple
            color black
            symbol basic/diamond
            size 15
            masked n
            end
       Of course, multiple points may be drawn with multiple point instructions.

psfile

       Copies a file containing PostScript commands into the output file.

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

raster

       Selects a raster map layer for output.
       USAGE:    raster mapname
       For  each  ps.map  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.

       Note  that an imagery group selected with the group option, or a set of three raster layers selected with
       the rgb option, count as a raster map layer for the purposes of the preceding paragraph.

       The PostScript file’s internal title will be set to the raster map’s title, which in turn may be set with
       the r.suppport module.

       This example would paint a map of the raster map layer soils.
       EXAMPLE:
            raster soils

read

       Provides ps.map with a previously prepared input stream.
       USAGE:    read previously prepared UNIX file
       Mapping instructions can be placed into a file and read into ps.map.

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

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

rectangle

       Draws rectangle on the output map.
       USAGE:    rectangle east north east north
            rectangle x% y% x% y%
            color color
            fcolor fill color
            width #
            masked [y|n]
            end
       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
       color, fill color fcolor, width in points (accepts decimal points [floating points] as well as integers),
       and if the rectangle is to be masked by the  current  mask.   (See  manual  entry  for  r.mask  for  more
       information  on  the  mask.)   The  border  line  width  (if  given) is measured in points; an i directly
       following the number indicates that the width is given in inches instead.
       Multiple rectangles may be drawn by using multiple rectangle instructions.

       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.
       EXAMPLE:
            rectangle 10% 80% 30% 70%
            color yellow
            fcolor green
            width 0.0625i
            masked n
            end

region

       Places the outline of a smaller geographic region on the output.
       USAGE:    region regionfile
            color color
            width #
            end
       Geographic  region  settings  are created and saved using  the g.region module.  The ps.map region option
       can be used to show an outline of a smaller region which was printed on a separate run of ps.map on other
       user-created maps.

       The  user can specify the color and the width 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").

       This example would place a white outline, 2 points wide, of the geographic region called fire.zones  onto
       the output map.  This geographic region would have been created and saved using g.region.
       EXAMPLE:
            region fire.zones
            color white
            width 2
            end

rgb

       Selects three raster map layers for output as an RGB color image.
       USAGE:    rgb red green blue
       This  is  similar  to  raster, 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 d.rgb.

       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.

scale

       Selects a scale for the output map.
       USAGE:    scale scale
       The scale can be selected either as:

           a relative ratio, e.g. 1:25000;

           an absolute width of the printed map, e.g. 10 inches;

           the number of printed paper panels, e.g.  3  panels  .I  (at  the  present  time,  only  1  panel  is
           supported);

           the number of miles per inch, e.g. 1 inch equals 4 miles.

       This example would set the scale of the map to 1 unit = 25000 units.
       EXAMPLE:
            scale 1:25000

scalebar

       Draws a scalebar on the map.
       USAGE:    scalebar [f|s]
            where x y
            length overall distance in map units
            units [auto|meters|kilometers|feet|miles|nautmiles]
            height scale height in inches
            segment number of segments
            numbers #
            fontsize font size
            background [Y|n]
            end
       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
       where the scalebar is placed, the length of the scalebar (in geographic coordinate system units, or those
       given by units), the height of the scalebar in inches, and the number of segments (or tics  for  simple).
       The number of annotations numbers every n-th segment.  The background command can turn off the background
       box for the text.

       The scalebar length 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.

       NOTE: The scalebar is centered on the location given.

       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.
       EXAMPLE:
            scalebar s
            where 4 5
            length 1000
            height 0.25
            segment 5
            numbers 2
            end

setcolor

       Overrides the color assigned to one or more categories of the raster map layer.
       USAGE:    setcolor cat(s) color
       This example would set the color for categories 2,5 and 8 of the raster map layer watersheds to white and
       category 10 to green.  (NOTE: no spaces are inserted between the category values.)
       EXAMPLE:
            raster watersheds
            setcolor 2,5,8 white
            setcolor 10 green
       Of  course,  setcolor  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 "null" and the "default" (i.e. out-of-range) color may also be reassigned.

text

       Places text on the map.
       USAGE:    text  east north text
            text  x% y% text
            font fontname
            color color|none
            width #
            hcolor color|none
            hwidth #
            background color|none
            border color|none
            fontsize font size
            size #
            ref reference point
            rotate degrees CCW
            xoffset #
            yoffset #
            opaque [y|n]
            end
       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 \n (e.g. USA\nCERL).

       The user can then specify various text features:

       font: the PostScript font. Common possibilities are listed at the start of this help page. The default is
       Helvetica.

       color (see NAMED COLORS);

       width  of  the  lines  used  to  draw  the text to make thicker letters (accepts decimal points [floating
       points] as well as integers);

       size and fontsize.  size 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 fontsize can set the
       font size directly. If neither size or fontsize is given, a default font size of 10 will be used;

       the highlight color (hcolor) and the width of the highlight color (hwidth);

       the text-enclosing-box background color; the text box border color;

       ref.  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.

       rotate sets the text rotation angle, measured in degrees counter-clockwise.

       yoffset,  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;

       xoffset,  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;

       opaque, whether or not the text should be opaque to vectors.  Entering no 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.

       The following example would place the text SPEARFISH LAND COVER 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.
       EXAMPLE:
            text 650000 7365000 SPEARFISH LAND COVER
            font romand
            color red
            width 2
            hcolor black
            hwidth 1
            background white
            border red
            size 500
            ref lower left
            opaque y
            end

vareas

       Selects a vector map layer for output and plots areas.
       USAGE:    vareas vectormap
            layer # (layer number used with cats/where option)
            cats list of categories (e.g. 1,3,5-7)
            where SQL where statement
            masked [y|n]
            color color
            fcolor color
            rgbcolumn column
            width #
            label label to use in legend
            lpos position in legend
            pat pattern file
            pwidth #
            scale #
            end
       The user can specify:

       color - color of the vector lines or area boundaries;

       fcolor - the area fill color;

       rgbcolumn - name of color definition column used for the area fill color;

       width - width of the vectors lines or area boundaries in points (accepts decimal points [floating points]
       as well as integers);

       masked - whether or not the raster map layer is to be masked by  the  current  mask;  (see  manual  entry
       r.mask for more information on the mask)

       cats - which categories should be plotted (default is all);

       where - select features using a SQL where statement.  For example: vlastnik = ’Cimrman’;

       label - for description in vlegend.  Default is: map(mapset);

       lpos  - 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.

       pat - 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  of patterns are  set  by
       fcolor  (red,  green,  ...,  none,  R:G:B).  Color of the boundaries remain set by the color instruction.
       Pattern may be scaled with the  scale  command.  Several  standard  hatching  patterns  are  provided  in
       $GISBASE/etc/paint/patterns/.   Demonstrative  images  can be found on the GRASS Wiki site.  You can also
       create your own custom pattern files in a text editor.  Example of pattern file:
       %!PS-Adobe-2.0 EPSF-1.2
       %%BoundingBox: 0 0 10 10
       newpath
       5 0 moveto
       5 10 lineto
       stroke

       scale - pattern scale

       pwidth - pattern line width, width is used by pattern until the width is overwritten in pattern file.

       EXAMPLE:
            vareas forest
            color blue
            width 1
            masked y
            cats 2,5-7
            end

vlines

       Selects a vector map layer for output and plots lines.
       USAGE:    vlines vectormap
            type line and/or boundary
            layer # (layer number used with cats/where option)
            cats list of categories (e.g. 1,3,5-7)
            where SQL where statement like: vlastnik = ’Cimrman’
            masked [y|n]
            color color
            rgbcolumn column
            width #
            cwidth #
            hcolor color
            hwidth #
            offset #
            coffset #
            ref left|right
            style 00001111
            linecap style
            label label
            lpos #
            end
       The user can specify:

       type - the default is lines only;

       color - color of the vector lines or area boundaries;

       rgbcolumn - name of color definition column used for the vector lines or area boundaries;

       width - width of the vectors lines or area boundaries in points (accepts decimal points [floating points]
       as well as integers);

       cwidth  -  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;

       hcolor - the highlight color for the vector lines;

       hwidth - the width of the highlight color in points;

       offset (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;

       coffset (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;

       ref (experimental) - line justification.

       masked  -  whether  or  not  the  raster map layer is to be masked by the current mask; (see manual entry
       r.mask for more information on the mask);

       style - 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";

       linecap - 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.

       cats - which categories should be plotted (default is all);

       label - for description in vlegend.  Default is: map(mapset);

       lpos - 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.

       EXAMPLE:
            vlines streams
            color blue
            width 2
            hcolor white
            hwidth 1
            masked y
            cats 2
            label Streams - category 2
            end

vpoints

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

vlegend

       Prints the portion of the map legend containing the vector information, on or below the map.
       USAGE:    vlegend
            where x y
            font font name
            fontsize font size
            width width of color symbol
            cols number of columns to print
            span column separation
            border color|none
            end
       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 where instruction is present and y is less than or equal to
       zero, the vector legend will be positioned immediately below the map, starting x  inches  from  the  left
       edge of the page.

       width  is the width in inches of the color symbol (for lines) in front of the legend text. The default is
       1/24 * fontsize inches.

       cols is the number of columns to split the legend into. The default is one column. The maximum number  of
       colums is 10, or equal to the number of legend entries if there are less than 10 entries.

       span  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.

       border will draw a border around the legend using the specified color.  (see NAMED COLORS)

       Alternatively, the user can create a custom legend by using the rectangle, point, and text instructions.

       See also the colortable command for creating raster map legends.

       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.
       EXAMPLE:
            vlegend
            where 4.5 0
            font Courier
            fontsize 12
            end

end

       Terminates input and begin painting the map.
       USAGE:    end

EXAMPLES

       The following are examples of ps.map script files.

   Simple example
       The file has been named spear.basic:
       # this ps.map example draws a map of Spearfish, SD
       raster elevation.dem
       header
         end
       vlines roads
         color brown
         end
       end
       Generate map as Postsript file:
        ps.map input=spear.basic output=spear_basic.ps

   More complicated example
       The file has been named spear.soils:
       # this ps.map example draws a map of Spearfish, SD
       raster soils
       outline
          color black
          width 1
          end
       comments soil.cmt
          where 1 6
          font Helvetica
          end
       colortable y
          where 1 6.5
          cols 4
          width 4
          font Helvetica
          end
       setcolor 6,8,9 white
       setcolor 10 green
       vlines roads
          width 2
          style 0111
          color grey
          masked n
          end
       vlegend
          where 4.5 0
          font Courier
          fontsize 8
          end
       text 30% 100% SPEARFISH SOILS MAP
          color red
          width 1
          hcolor black
          hwidth 1
          background white
          border red
          size 500
          ref lower left
          end
       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
       scale 1:125000
       scalebar f
          where 4.5 6.5
          length 5000
          height 0.05
          segment 5
          numbers 5
          end
       geogrid 60 s
          color blue
          numbers 2 yellow
          end
       paper a4
           end
       end
       This script file can be entered at the command line:
        # First set the region
        g.region raster=soils
        # Generate comment file (or use text editor)
        echo "Spearfish (SD) soils" > soil.cmt
        # Generate map as Postsript file
        ps.map input=spear.soils output=soils.ps

       More examples can be found on the GRASS Wiki help site.

CHANGES BETWEEN VERSION 5.0.x/5.4.x and 6.0

           •   Devices and ps.select do not exist any more. Paper is defined by the paper instruction.

           •   vpoints are used instead of sites (points are read from vector).

           •   vector is substituted by vpoints, vlines and vareas.

           •   Symbols are used instead of icons (different format and directory).

           •   Map legend can be printed in columns.

SEE ALSO

        g.region, v.label

AUTHOR

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

       Last changed: $Date: 2014-12-19 22:55:37 +0100 (Fri, 19 Dec 2014) $

       Main index | Postscript index | Topics index | Keywords index | Full index

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual