1ps.map(1)                     Grass User's Manual                    ps.map(1)
2
3
4

NAME

6       ps.map  - Produces hardcopy PostScript map output.
7

KEYWORDS

9       postscript, printing
10

SYNOPSIS

12       ps.map
13       ps.map --help
14       ps.map [-rpeb] input=name output=name  [copies=integer]   [--overwrite]
15       [--help]  [--verbose]  [--quiet]  [--ui]
16
17   Flags:
18       -r
19           Rotate plot 90 degrees
20
21       -p
22           List paper formats (name width height left  right  top  bottom(mar‐
23           gin))
24
25       -e
26           Create EPS (Encapsulated PostScript) instead of PostScript file
27
28       -b
29           Describe  map-box’s  position  on  the  page  and exit (inches from
30           top-left of paper)
31
32       --overwrite
33           Allow output files to overwrite existing files
34
35       --help
36           Print usage summary
37
38       --verbose
39           Verbose module output
40
41       --quiet
42           Quiet module output
43
44       --ui
45           Force launching GUI dialog
46
47   Parameters:
48       input=name [required]
49           File containing mapping instructions
50           Use ’-’ to enter instructions from keyboard)
51
52       output=name [required]
53           Name for PostScript output file
54
55       copies=integer
56           Number of copies to print
57           Options: 1-20
58

DESCRIPTION

60       ps.map is a cartographic mapping program  for  producing  high  quality
61       hardcopy  maps  in  PostScript format. Output can include a raster map,
62       any number of vector overlays, text labels, decorations, and other spa‐
63       tial data.
64
65       A  file  of mapping instructions that describes the various spatial and
66       textual information to be printed must be  prepared  prior  to  running
67       ps.map.
68

NOTES

70       The  order of commands is generally unimportant but may affect how some
71       layers are drawn. For example to plot vpoints  above  vareas  list  the
72       vpoints  entry  first.  Raster  maps are always drawn first, and only a
73       single raster map (or 3 if part of a RGB group) may be used.
74
75       The hash character (’#’) may be used at the  beginning  of  a  line  to
76       indicate that the line is a comment. Blank lines will also be ignored.
77
78       Be  aware  that  some  mapping instructions require the end command and
79       some do not. Any instruction that allows subcommands will  require  it,
80       any instruction that does not allow subcommands will not.
81
82       The  resolution  and extent of raster maps plotted with ps.map are con‐
83       trolled by the current region settings via  the  g.region  module.  The
84       output filesize is largely a function of the region resolution, so spe‐
85       cial care should be taken if working with large  raster  datasets.  For
86       example  if the desired output is US-Letter sized paper at 600dpi, with
87       1" margins and the raster filling the entire page, the usable  area  on
88       the  page  will be 6.5" x 9", which at 600 dots/inch is equivalent to a
89       region of 3900 columns x 5400 rows (see "g.region -p"). Any higher res‐
90       olution  settings will make the output file larger, but with a consumer
91       printer you probably won’t be able to resolve any better detail in  the
92       hardcopy.
93
94       The user can specify negative or greater than 100 percentage values for
95       positioning several map decorations and  embedded  EPS-files,  to  move
96       them outside the current map box region (for example to position a cap‐
97       tion, barscale, or legend above or below the map box).
98
99       One point ("pixel") is 1/72 of an inch.
100
101       For users wanting to use special characters (such as  accented  charac‐
102       ters)  it  is  important  to note that ps.map uses ISO-8859-1 encoding.
103       This means that your instructions file will have to be encoded in  this
104       encoding.  If  you  normally  work  in a different encoding environment
105       (such as UTF-8), you have to transform  your  file  to  the  ISO-8859-1
106       encoding, for example by using the iconv utility:
107       iconv -f UTF-8 -t ISO_8859-1 utf_file > iso_file
108

MAPPING INSTRUCTIONS

110       The mapping instructions allow the user to specify various spatial data
111       to be plotted. These instructions are normally prepared  in  a  regular
112       text  file  using  a  system  editor. Some instructions are single line
113       instructions while others are multiple line. Multiple line instructions
114       consist of the main instruction followed by a subsection of one or more
115       additional instructions and are terminated with an end instruction.
116
117   Instruction keywords:
118       [  border |  colortable |  comments |  copies |  eps |  geogrid |
119       greyrast |  grid |  group |  header |  labels | line | mapinfo |
120       maploc | maskcolor | outline | paper | point | psfile | raster |
121       read |  rectangle | region | rgb | scale | scalebar | setcolor |
122       text | vareas | vlines | vpoints | vlegend | end ]
123
124   Common instructions
125       Instructions that may be included in the subsection under several  dif‐
126       ferent main instructions are:
127
128       where x y
129           The  top  left corner of the bounding box of the item to be plotted
130           is located x inches from the left edge of the paper  and  y  inches
131           from the top edge of the paper. If x is less than or equal to zero,
132           the default horizontal location is used.  If  y  is  less  than  or
133           equal to zero, the default vertical location is used.
134
135       font font name
136           The  name  of the PostScript font.  Fonts present in all PostScript
137           implementations   are:   Times-Roman,   Times-Italic,   Times-Bold,
138           Times-BoldItalic,   Helvetica,  Helvetica-Oblique,  Helvetica-Bold,
139           Helvetica-BoldOblique, Courier, Courier-Oblique, Courier-Bold,  and
140           Courier-BoldOblique.
141           The default is Helvetica.
142
143       fontsize font size
144           The  size  of  the  PostScript  font  (in 1/72nds of an inch).  The
145           default is 10 point.
146
147       color name
148           The following colors names are accepted  by  ps.map:  aqua,  black,
149           blue, brown, cyan, gray, grey, green, indigo, magenta, orange, pur‐
150           ple, red, violet, white, yellow .
151           For vectors and some plotting commands you can also specify  ’none’
152           or ’R:G:B’ (e.g ’255:0:0’).
153
154       yes|no
155           For  options  that  take a yes or no answer, you can simply use the
156           letters "y" or "n", or type out the full words "Yes" or "No" if you
157           prefer.  It is not case-sensitive. Typically the option with have a
158           default answer and you only need to specify  one  if  you  wish  to
159           override it.
160
161   Command usage

border

163       Controls the border which is drawn around the map area.
164       USAGE:  border [y|n]
165            color color
166            width #
167            end
168       The  color  may  be  either a standard GRASS color, a R:G:B triplet, or
169       "none". The width is specified in points, unless followed by an "i"  in
170       which case it is measured in inches.  The default is a black border box
171       of width 1 point.
172
173       The border can be turned off completely with the  "border n"  instruc‐
174       tion. In this case the end command should not be given as the main com‐
175       mand will be treated as a single line instruction.
176
177       This example would create a grey border 0.1" wide.
178       EXAMPLE:
179            border
180            color grey
181            width 0.1i
182            end
183

colortable

185       Prints the color table legend for the raster map layer anywhere on  the
186       page.
187       USAGE:    colortable [y|n]
188            where x y
189            raster raster map
190            range minimum maximum
191            width table width
192            height table height (FP legend only)
193            cols table columns
194            font font name
195            fontsize font size
196            color text color
197            nodata [Y|n]
198            tickbar [y|N]
199            discrete [y|n]
200            end
201       For  a categorical (CELL) map the color table will create a legend dis‐
202       playing the colors for each of a raster  map’s  category  values  along
203       with  its  associated  category  label.  For a floating point (FCELL or
204       DCELL) map a continuous gradient legend will be created.
205
206       If raster is omitted, the colortable defaults to the previously  regis‐
207       tered raster layer.
208
209       The  default location for the colortable is immediately below any other
210       map legend information, starting at the left margin.  The default  text
211       color is black.
212
213       Omitting the colortable instruction would result in no color table.  If
214       the colortable is turned off with a "colortable N" instruction the end
215       command  should  not  be given as the main command will be treated as a
216       single line instruction.
217
218       See also the vlegend command for creating vector map legends.
219
220   Categorical (CELL) Maps
221       Adding the nodata N instruction will prevent the  "no  data"  box  from
222       being drawn (category based legends only). If you have manually added a
223       "no data" label to the cats/ file it will be shown regardless.
224
225       Note:  Be careful about asking for color tables for integer raster  map
226       layers  which  have  many  categories,  such  as elevation.  This could
227       result in the printing of an extremely long color table!  In this situ‐
228       ation it is useful to use the discrete N instruction to force a contin‐
229       uous color gradient legend.
230
231       Be aware that the color table only includes  categories  which  have  a
232       label. You can use the r.category module to add labels.
233
234   Floating point (FCELL and DCELL) Maps
235       The  legend’s  range can be adjusted for floating point rasters, but if
236       set beyond the extent of the map’s range be sure that you have  set  up
237       color  rules with r.colors which cover this range.  If the map has been
238       given a data-units label with r.support then this label  will  be  dis‐
239       played.   For floating point legends width is width of color band only.
240       height is used only for floating point legend.  A  horizontal  gradient
241       legend  can  be  achieved  by setting the legend width greater than its
242       height.  Adding the tickbar Y instruction will  change  the  tick  mark
243       style  so  that  ticks are drawn across the color table instead of pro‐
244       truding out to the right (floating point  legends  only).   Adding  the
245       discrete  Y  instruction will command the program to treat the map as a
246       categorical map. In this way the legend can be  created  with  discrete
247       range  bands instead of a continuous gradient. You must use the r.cate‐
248       gory or r.support module to set up the range labels first.
249
250       This example would print a color table immediately below any other  map
251       legend information, starting at the left margin, with 4 columns:
252       EXAMPLE:
253            colortable y
254               cols 4
255               width 4
256               end
257

comments

259       Prints comments anywhere on the page.
260       USAGE:    comments commentfile
261            where x y
262            font font name
263            fontsize font size
264            color text color
265            end
266       The  default  location is immediately below the last item item printed,
267       starting at the left margin. The default text color is black.
268
269       If you wish to use parentheses spanning multiple lines you will need to
270       quote  them with a backslash to prevent the PostScript interpreter from
271       getting confused. e.g. ’\(’ and ’\)
272
273       This example prints in blue whatever is in the file veg.comments start‐
274       ing  at  1.5 inches from the left edge of the page and 7.25 inches from
275       the top of the page, using a 15/72 inch Helvetica Bold font.
276       EXAMPLE:
277            raster vegetation
278            comments veg.comments
279            where 1.5 7.25
280            font Helvetica Bold
281            fontsize 15
282            color blue
283            end
284       Presumably, the file veg.comments contain comments  pertaining  to  the
285       raster map layer vegetation, such as "This map was created by classify‐
286       ing a LANDSAT TM image".
287

copies

289       Specifies the number of copies to be printed.
290       USAGE:    copies n
291       Each page will be printed n times.
292
293       This instruction is identical to the copies command line parameter.
294

eps

296       Places EPS (Encapsulated PostScript) pictures on the output map.
297       USAGE:    eps east north
298            eps x% y%
299            epsfile EPS file
300            scale #
301            rotate #
302            masked [y|n]
303            end
304       The EPS picture location is entered in the  main  instruction  line  by
305       giving  either  the map coordinates or by using percentages of the geo‐
306       graphic region.  The EPS picture will be centered at  the  given  posi‐
307       tion.   The user must specify full EPS file path epsfile.  The user may
308       also specify the scale of the icon (default is 1.0),  the  rotate  i.e.
309       rotation  in  degrees  (default  is  0)  and whether the point is to be
310       masked by the current mask.  (See manual  entry  for  r.mask  for  more
311       information on the mask.)
312
313       This  example  would  place  a  EPS  file  ./epsf/logo.eps at the point
314       (E456000 N7890000).  This picture would be rotated  20  degrees  clock‐
315       wise,  3  times bigger than in original file and would not be masked by
316       the current mask.
317       EXAMPLE:
318            eps 456000 7890000
319            epsfile ./epsf/logo.eps
320            scale 3
321            rotate 20
322            masked n
323            end
324       Of course, multiple  EPS  pictures  may  be  drawn  with  multiple  eps
325       instructions.
326

geogrid

328       Overlays a geographic grid onto the output map.
329       USAGE:    geogrid spacing unit
330            color color
331            numbers # [color]
332            font font name
333            fontsize font size
334            width #
335            end
336       The  spacing  and  spacing  unit of the geographic grid is given on the
337       main instruction line.  The spacing unit is  given  as  one  of  d  for
338       degrees, m for minutes, and s for seconds.  The subsection instructions
339       allow the user to specify the  color  of  the  geographic  grid  lines,
340       whether  coordinate numbers should appear on the geographic grid lines,
341       the width of the lines (accepts decimal  points  [floating  points]  as
342       well as integers), and if they should appear every grid line (1), every
343       other grid line (2), etc., and what color the numbers should  be.   The
344       defaults are black grid lines, unnumbered.
345
346       NOTE:  The  geogrid draws grid numbers on the east and south borders of
347       the map.
348
349       This example would overlay a blue geographic grid with a spacing of  30
350       minutes  onto  the  output map.  Alternate grid lines would be numbered
351       with yellow numbers.
352       EXAMPLE:
353            geogrid 30 m
354            color blue
355            numbers 2 yellow
356            end
357

greyrast

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

grid

365       Overlays a coordinate grid onto the output map.
366       USAGE:    grid spacing
367            color color
368            numbers # [color]
369            cross cross size
370            font font name
371            fontsize font size
372            width #
373            end
374       The  spacing  of the grid is given (in the geographic coordinate system
375       units) on the main instruction line.  The subsection instructions allow
376       the  user  to  specify  the color of the grid lines, whether coordinate
377       numbers should appear on the grid lines,  and  if  they  should  appear
378       every  grid  line  (1), every other grid line (2), etc., and what color
379       the numbers should be.  The  cross  argument  draws  grid  intersection
380       crosses  instead  of  grid  lines,  with cross size given in geographic
381       coordinate system units.  The defaults are  black  grid  lines,  unnum‐
382       bered.
383
384       This  example would overlay a green grid with a spacing of 10000 meters
385       (for a metered database, like UTM) onto the output map.  Alternate grid
386       lines would be numbered with red numbers.
387       EXAMPLE:
388            grid 10000
389            color green
390            numbers 2 red
391            end
392

group

394       Selects an RGB imagery group for output.
395       USAGE:    group groupname
396       This is similar to raster, except that it uses an imagery group instead
397       of a raster map layer. The group must contain three raster map  layers,
398       comprising the red, green and blue bands of the image.
399
401       Prints the map header above the map.
402       USAGE:    header
403            file header file
404            font font name
405            fontsize font size
406            color text color
407            end
408       If  the  file  sub-instruction is absent the header will consist of the
409       map’s title and the location’s description.  The text will be  centered
410       on the page above the map.  The default text color is black.
411
412       If  the  file  sub-instruction  is given the header will consist of the
413       text in the text file specified, with some special formatting keys:
414
415           ·   %%  - a literal %
416
417           ·   %n  - ? newline ?
418
419           ·   %_  - horizontal bar
420
421           ·   %c  - "<raster name> in mapset <mapset name>"
422
423           ·   %d  - today’s date
424
425           ·   %l  - location name
426
427           ·   %L  - Location’s text description
428
429           ·   %m  - mapset name
430
431           ·   %u  - user name
432
433           ·   %x  - mask info
434
435           ·   %-  - advance to this  character  column  number  (see  example
436               below)
437       Example header file:
438       %_
439       LOCATION: %-27l  DATE: %d
440       MAPSET:   %-27m  USER: %u
441       RASTER MAP: %c
442       MASK:     %x
443       %_
444       Produced by: US Army CERL, Champaign Illinois
445       Software:    GRASS
446       %_
447
448       This  example  prints  (in red) whatever is in the file soils.hdr above
449       the map, using a 20/72 inch Courier font.
450       EXAMPLE:
451            header
452            file soils.hdr
453            font Courier
454            fontsize 20
455            color red
456            end
457

labels

459       Selects a labels file for output (see manual entry for v.label ).
460       USAGE:    labels  labelfile
461            font font name
462            end
463
464       NOTE: ps.map can read new option  ’ROTATE:’  from  labels  file,  which
465       specifies counter clockwise rotation in degrees.
466
467       This example would paint labels from the labels file called town.names.
468       Presumably, these labels would indicate the names of towns on the map.
469       EXAMPLE:
470            labels town.names
471            end
472

line

474       Draws lines on the output map.
475       USAGE:    line east north east north
476            line x% y% x% y%
477            color color
478            width #
479            masked [y|n]
480            end
481       The beginning and ending points of the line are  entered  on  the  main
482       instruction.   These points can be defined either by map coordinates or
483       by using percentages of the geographic region.  The user may also spec‐
484       ify  line color, width in points (1/72"; accepts decimal values as well
485       as integers), and if the line is to be  masked  by  the  current  mask.
486       (See manual entry for r.mask
487        for  more information on the mask.)  The line width (if given) is mea‐
488       sured in points; an i directly following the number indicates that  the
489       width is given in inches instead.
490
491       This example would draw a yellow line from the point x=10% y=80% to the
492       point x=30% y=70%.  This line would be 2 points wide (2/72") and  would
493       appear even if there is a mask.
494       EXAMPLE:
495            line 10% 80% 30% 70%
496            color yellow
497            width 2
498            masked n
499            end
500       Of course, multiple lines may be drawn with multiple line instructions.
501

mapinfo

503       Prints  the  portion  of  the map legend containing the scale, grid and
504       region information, on or below the map.
505       USAGE:    mapinfo
506            where x y
507            font font name
508            fontsize font size
509            color text color
510            background box color|none
511            border color|none
512            end
513       The default location is immediately below the map, starting at the left
514       edge  of  the map.  The default text color is black.  The default back‐
515       ground box color is white.
516
517       border will draw a border around the legend using the specified  color.
518       (see NAMED COLORS)
519
520       This  example  prints (in brown) the scale, grid and region information
521       immediately below the map and starting 1.5 inches from the left edge of
522       the page, using a 12/72 inch Courier font.
523       EXAMPLE:
524            mapinfo
525            where 1.5 0
526            font Courier
527            fontsize 12
528            color brown
529            end
530

maploc

532       Positions the map on the page.
533       USAGE:    maploc  x y [width height]
534       The  upper  left corner of the map will be positioned x inches from the
535       left edge of the page and y inches from the top of the page.  If  width
536       and height (in inches) are present, the map will be rescaled, if neces‐
537       sary, to fit.
538
539       This example positions the upper left corner of the map 2.0 inches from
540       the left edge and 3.5 inches from the top edge of the map.
541       EXAMPLE:
542            maploc 2.0 3.5
543

maskcolor

545       Color to be used for mask.
546       USAGE:    maskcolor  color
547

outline

549       Outlines the areas of a raster map layer with a specified color.
550       USAGE:    outline
551            color  color
552            width  width of line in points
553            end
554       Distinct areas of the raster map will be separated from each other vis‐
555       ually by drawing a border (or outline) in the specified color (default:
556       black).  For width the program accepts decimal points [floating points]
557       as well as integers.  Note: it is important the user enter the instruc‐
558       tion  end  even  if  a  color  is not chosen.  (It is hoped that in the
559       future the outline of a different raster map layer other than  the  one
560       currently being painted may be placed on the map.)
561
562       This  example  would outline the category areas of the soils raster map
563       layer in grey.
564       EXAMPLE:
565            raster soils
566            outline
567            color grey
568            width 2
569            end
570

paper

572       Specifies paper size and margins.
573       USAGE:    paper paper name
574            height #
575            width #
576            left #
577            right #
578            bottom #
579            top #
580            end
581       paper may select predefined paper name (a4,a3,a2,a1,a0,us-legal,us-let‐
582       ter,us-tabloid).  Default paper size is a4. The measures are defined in
583       inches.  left, right, bottom and top are paper margins.  If the plot is
584       rotated  with  the  -r  command  line flag, measures are applied to the
585       rotated page.
586
587       EXAMPLE:
588            paper a3
589            end
590
591       EXAMPLE:
592            paper
593            width 10
594            height 10
595            left 2
596            right 2
597            bottom 2
598            top 2
599            end
600

point

602       Places additional points or icons on the output map.
603       USAGE:    point east north
604            point x% y%
605            color color
606            fcolor color
607            symbol symbol group/name
608            size #
609            width #
610            rotate #
611            masked [y|n]
612            end
613       The point location is entered in the main instruction  line  by  giving
614       either  the  map  coordinates or by using percentages of the geographic
615       region.  The user may also specify the point color, the size of  symbol
616       in  points,  the rotation angle (in degrees CCW), and whether the point
617       is to be masked by the current mask.  (See manual entry for  r.mask
618        for more information on the mask.)  The symbol line width  (if  given)
619       is  measured  in  points;  an i directly following the number indicates
620       that the width is given in inches instead. If a width is not  given  it
621       will be set proportional to the symbol size.
622
623       This  example  would place a purple diamond (from icon file diamond) at
624       the point (E456000 N7890000).  This diamond would be the the size of  a
625       15 points and would not be masked by the current mask.
626       EXAMPLE:
627            point 456000 7890000
628            fcolor purple
629            color black
630            symbol basic/diamond
631            size 15
632            masked n
633            end
634       Of  course,  multiple  points may be drawn with multiple point instruc‐
635       tions.
636

psfile

638       Copies a file containing PostScript commands into the output file.
639
640       Note: ps.map will not search for this file.  The user must  be  in  the
641       correct  directory  or specify the full path on the psfile instruction.
642       (Note to /bin/csh users: ~ won’t work with this instruction).
643       USAGE:    psfile filename
644       This example copies the file "logo.ps" into the output file.
645       EXAMPLE:
646            psfile logo.ps
647

raster

649       Selects a raster map layer for output.
650       USAGE:    raster mapname
651       For each ps.map run, only one raster map layer (or  set  of  layers  or
652       imagery  group;  see below) can be requested. If no raster map layer is
653       requested, a completely white map will be produced. It can be useful to
654       select  no  raster map layer in order to provide a white background for
655       vector maps.
656
657       Note that an imagery group selected with the group option, or a set  of
658       three raster layers selected with the rgb option, count as a raster map
659       layer for the purposes of the preceding paragraph.
660
661       The PostScript file’s internal title will be set to  the  raster  map’s
662       title, which in turn may be set with the r.support module.
663
664       This example would paint a map of the raster map layer soils.
665       EXAMPLE:
666            raster soils
667

read

669       Provides ps.map with a previously prepared input stream.
670       USAGE:    read previously prepared UNIX file
671       Mapping instructions can be placed into a file and read into ps.map.
672
673       Note:  ps.map  will  not search for this file.  The user must be in the
674       correct directory or specify the full path  on  the  read  instruction.
675       (Note to /bin/csh users: ~ won’t work with this instruction).
676
677       This example reads the UNIX file pmap.roads into ps.map.  This file may
678       contain all the ps.map instructions for placing the  vector  map  layer
679       roads onto the output map.
680       EXAMPLE:
681            read pmap.roads
682       The  user  may  have created this file because this vector map layer is
683       particularly useful for many ps.map outputs.  By using the read option,
684       the  user  need not enter all the input for the vector instruction, but
685       simply read the previously prepared file with the correct instructions.
686

rectangle

688       Draws rectangle on the output map.
689       USAGE:    rectangle east north east north
690            rectangle x% y% x% y%
691            color color
692            fcolor fill color
693            width #
694            masked [y|n]
695            end
696       The two corners of the rectangle are entered on the  main  instruction.
697       These  points can be defined either by map coordinates or by using per‐
698       centages of the geographic region.  The  user  may  also  specify  line
699       color,  fill  color  fcolor,  width  in  points (accepts decimal points
700       [floating points] as well as integers), and if the rectangle is  to  be
701       masked  by  the  current  mask.   (See manual entry for r.mask for more
702       information on the mask.)  The border line width (if given) is measured
703       in  points; an i directly following the number indicates that the width
704       is given in inches instead.
705       Multiple rectangles may be drawn by using multiple  rectangle  instruc‐
706       tions.
707
708       This  example  would  draw  a yellow rectangle filled by green from the
709       point x=10% y=80% to the point x=30% y=70%.  The border line  would  be
710       1/16" wide and would appear even if there is a mask.
711       EXAMPLE:
712            rectangle 10% 80% 30% 70%
713            color yellow
714            fcolor green
715            width 0.0625i
716            masked n
717            end
718

region

720       Places the outline of a smaller geographic region on the output.
721       USAGE:    region regionfile
722            color color
723            width #
724            end
725       Geographic  region  settings  are created and saved using  the g.region
726       module.  The ps.map region option can be used to show an outline  of  a
727       smaller  region  which was printed on a separate run of ps.map on other
728       user-created maps.
729
730       The user can specify the color and the width in  point  units  (accepts
731       decimal  points  [floating points] as well as integers) of the outline.
732       The default is a black border of one point width (1/72").
733
734       This example would place a white outline, 2 points wide,  of  the  geo‐
735       graphic  region called fire.zones onto the output map.  This geographic
736       region would have been created and saved using g.region.
737       EXAMPLE:
738            region fire.zones
739            color white
740            width 2
741            end
742

rgb

744       Selects three raster map layers for output as an RGB color image.
745       USAGE:    rgb red green blue
746       This is similar to raster, except that it uses three raster map  layers
747       instead  of  a  single  layer.  The three layers are composed to form a
748       color image, similar to d.rgb.
749
750       For each layer, only one of the components of the layer’s  color  table
751       is  used:  the  red  component for the red layer, and so on.  This will
752       give the desired result if all of the layers have  a  grey-scale  color
753       table,  or  if each layer’s color table uses the hue appropriate to the
754       layer.
755

scale

757       Selects a scale for the output map.
758       USAGE:    scale scale
759       The scale can be selected either as:
760
761
762           a relative ratio, e.g. 1:25000;
763
764
765           an absolute width of the printed map, e.g. 10 inches;
766
767
768           the number of printed paper  panels,  e.g.  3  panels  .I  (at  the
769           present time, only 1 panel is supported);
770
771
772           the number of miles per inch, e.g. 1 inch equals 4 miles.
773
774       This example would set the scale of the map to 1 unit = 25000 units.
775       EXAMPLE:
776            scale 1:25000
777

scalebar

779       Draws a scalebar on the map.
780       USAGE:    scalebar [f|s]
781            where x y
782            length overall distance in map units
783            units [auto|meters|kilometers|feet|miles|nautmiles]
784            height scale height in inches
785            segment number of segments
786            numbers #
787            fontsize font size
788            background [Y|n]
789            end
790       Draw  one of two types of scale bar.  Fancy (f) draws alternating black
791       and white scale boxes.  Simple  (s)  draws  a  plain  line  scale.  The
792       default  type  is fancy.  The subsection instructions allow the user to
793       set where the scalebar is placed, the length of the scalebar  (in  geo‐
794       graphic  coordinate  system units, or those given by units), the height
795       of the scalebar in inches, and the number of segments (or tics for sim‐
796       ple).  The number of annotations numbers every n-th segment.  The back‐
797       ground command can turn off the background box for the text.
798
799       The scalebar length is the only required argument. The defaults  are  a
800       fancy  scalebar  with 4 segments, each segment labeled, and a height of
801       0.1 inches. The default location is 2 inches from the top of  the  page
802       and halfway across.
803
804       NOTE: The scalebar is centered on the location given.
805
806       This  example  draws a simple scalebar 1000 meters (for a metered data‐
807       base, like UTM) long, with tics every 200 meters, labeled every  second
808       tic.  The scalebar is drawn 5 inches from the top and 4 inches from the
809       left and is 0.25 inches high.
810       EXAMPLE:
811            scalebar s
812            where 4 5
813            length 1000
814            height 0.25
815            segment 5
816            numbers 2
817            end
818

setcolor

820       Overrides the color assigned to one or more categories  of  the  raster
821       map layer.
822       USAGE:    setcolor cat(s) color
823       This example would set the color for categories 2,5 and 8 of the raster
824       map layer watersheds to white and category 10 to green.  (NOTE: no spa‐
825       ces are inserted between the category values.)
826       EXAMPLE:
827            raster watersheds
828            setcolor 2,5,8 white
829            setcolor 10 green
830       Of  course,  setcolor  can  be requested more than once to override the
831       default color for additional categories.  More than one category can be
832       changed  for  each request by listing all the category values separated
833       by commas (but with no spaces). Also ranges can be included, for  exam‐
834       ple   "1,2,6-10,12".   Colors   for  "null"  and  the  "default"  (i.e.
835       out-of-range) color may also be reassigned.
836

text

838       Places text on the map.
839       USAGE:    text  east north text
840            text  x% y% text
841            font fontname
842            color color|none
843            width #
844            hcolor color|none
845            hwidth #
846            background color|none
847            border color|none
848            fontsize font size
849            size #
850            ref reference point
851            rotate degrees CCW
852            xoffset #
853            yoffset #
854            opaque [y|n]
855            end
856       The user specifies where the text will be placed by providing map coor‐
857       dinates  or  percentages  of  the  geographic region.  The text follows
858       these coordinates on the same instruction line.  More than one line  of
859       text  can  be  specified  by  notating  the end of a line with \n (e.g.
860       USA\nCERL).
861
862       The user can then specify various text features:
863
864       font: the PostScript font. Common possibilities are listed at the start
865       of this help page. The default is Helvetica.
866
867       color (see NAMED COLORS);
868
869       width  of  the  lines  used  to  draw  the text to make thicker letters
870       (accepts decimal points [floating points] as well as integers);
871
872       size and fontsize.  size gives the vertical height of the  letters  in
873       meters  on  the  ground (text size will grow or shrink depending on the
874       scale at which the map is painted). Alternatively fontsize can set  the
875       font  size  directly.  If  neither size or fontsize is given, a default
876       font size of 10 will be used;
877
878       the highlight color (hcolor) and  the  width  of  the  highlight  color
879       (hwidth);
880
881       the text-enclosing-box background color; the text box border color;
882
883       ref.  This reference point specifies the text handle - what part of the
884       text should be placed on the location specified by the map coordinates.
885       Reference points can refer to: [lower|upper|center] [left|right|center]
886       of the text to be printed; The default is center center, i.e. the  text
887       is centered on the reference point.
888
889       rotate sets the text rotation angle, measured in degrees counter-clock‐
890       wise.
891
892       yoffset, which provides finer placement of text by shifting the text  a
893       vertical distance in points (1/72") from the specified north.  The ver‐
894       tical offset will shift the location to the south if positive, north if
895       negative;
896
897       xoffset, which shifts the text a horizontal distance in points from the
898       specified east The horizontal offset will shift the  location  east  if
899       positive, west if negative;
900
901       opaque,  whether or not the text should be opaque to vectors.  Entering
902       no to the opaque option will allow the user to see any vectors which go
903       through  the  text’s  background  box.  Otherwise, they will end at the
904       box’s edge.
905
906       The following example would place the text SPEARFISH LAND COVER at  the
907       coordinates  E650000  N7365000.  The  text would be a total of 3 points
908       wide (2 pixels of red text and 1 pixel black highlight), have  a  white
909       background enclosed in a red box, and be 500 meters in size.  The lower
910       right corner of the text would be centered over  the  coordinates  pro‐
911       vided.  All vectors on the map would stop at the border of this text.
912       EXAMPLE:
913            text 650000 7365000 SPEARFISH LAND COVER
914            font romand
915            color red
916            width 2
917            hcolor black
918            hwidth 1
919            background white
920            border red
921            size 500
922            ref lower left
923            opaque y
924            end
925

vareas

927       Selects a vector map layer for output and plots areas.
928       USAGE:    vareas vectormap
929            layer # (layer number used with cats/where option)
930            cats list of categories (e.g. 1,3,5-7)
931            where SQL where statement
932            masked [y|n]
933            color color
934            fcolor color
935            rgbcolumn column
936            width #
937            label label to use in legend
938            lpos position in legend
939            pat pattern file
940            pwidth #
941            scale #
942            end
943       The user can specify:
944
945       color - color of the vector lines or area boundaries;
946
947       fcolor - the area fill color;
948
949       rgbcolumn  -  name  of  color  definition column used for the area fill
950       color;
951
952       width - width of  the  vectors  lines  or  area  boundaries  in  points
953       (accepts decimal points [floating points] as well as integers);
954
955       masked  -  whether  or  not the raster map layer is to be masked by the
956       current mask; (see manual entry r.mask  for  more  information  on  the
957       mask)
958
959       cats - which categories should be plotted (default is all);
960
961       where  -  select  features  using  a SQL where statement.  For example:
962       vlastnik = ’Cimrman’;
963
964       label - for description in vlegend.  Default is: map(mapset);
965
966       lpos - position vector is plotted in legend. If lpos  is  0  then  this
967       vector  is  omitted  in legend. If more vectors used the same lpos then
968       their symbols in legend are merged and label for first vector is used.
969
970       pat - full path to pattern file. The pattern file contains  header  and
971       simple  PostScript  commands.  It  is  similar to EPS but more limited,
972       meaning that while each pattern file is a true EPS file, most EPS files
973       are  not  useful  as pattern files because they contain restricted com‐
974       mands. Color  of patterns are set by fcolor  (red,  green,  ...,  none,
975       R:G:B).  Color  of  the boundaries remain set by the color instruction.
976       Pattern may be scaled with the scale command. Several standard hatching
977       patterns  are  provided in $GISBASE/etc/paint/patterns/.  Demonstrative
978       images can be found on the GRASS Wiki site.  You can also  create  your
979       own custom pattern files in a text editor.  Example of pattern file:
980       %!PS-Adobe-2.0 EPSF-1.2
981       %%BoundingBox: 0 0 10 10
982       newpath
983       5 0 moveto
984       5 10 lineto
985       stroke
986
987       scale - pattern scale
988
989       pwidth  -  pattern line width, width is used by pattern until the width
990       is overwritten in pattern file.
991
992       EXAMPLE:
993            vareas forest
994            color blue
995            width 1
996            masked y
997            cats 2,5-7
998            end
999

vlines

1001       Selects a vector map layer for output and plots lines.
1002       USAGE:    vlines vectormap
1003            type line and/or boundary
1004            layer # (layer number used with cats/where option)
1005            cats list of categories (e.g. 1,3,5-7)
1006            where SQL where statement like: vlastnik = ’Cimrman’
1007            masked [y|n]
1008            color color
1009            rgbcolumn column
1010            width #
1011            cwidth #
1012            hcolor color
1013            hwidth #
1014            offset #
1015            coffset #
1016            ref left|right
1017            style 00001111
1018            linecap style
1019            label label
1020            lpos #
1021            end
1022       The user can specify:
1023
1024       type - the default is lines only;
1025
1026       color - color of the vector lines or area boundaries;
1027
1028       rgbcolumn - name of color definition column used for the  vector  lines
1029       or area boundaries;
1030
1031       width  -  width  of  the  vectors  lines  or  area boundaries in points
1032       (accepts decimal points [floating points] as well as integers);
1033
1034       cwidth - width of the vectors lines. If cwidth is used  then  width  of
1035       line is equal to cwidth * category value and width is used in legend;
1036
1037       hcolor - the highlight color for the vector lines;
1038
1039       hwidth - the width of the highlight color in points;
1040
1041       offset  (experimental) - offset for the vectors lines in points (1/72")
1042       for plotting parallel lines in distance equal to offset (accepts  posi‐
1043       tive  or negative decimal points). Useful to print streets with several
1044       parallel lanes;
1045
1046       coffset (experimental) - offset for the vectors lines.  If  coffset  is
1047       used then  offset of line is equal to coffset * category value and off‐
1048       set is used in legend;
1049
1050       ref (experimental) - line justification.
1051
1052       masked - whether or not the raster map layer is to  be  masked  by  the
1053       current  mask;  (see  manual  entry  r.mask for more information on the
1054       mask);
1055
1056       style - the line style allows the vectors to  be  dashed  in  different
1057       patterns.   This  is done by either typing "solid", "dashed", "dotted",
1058       or "dashdotted", or as a series of 0’s and 1’s in a desired sequence or
1059       pattern.   The first block of repeated zeros or ones represents "draw",
1060       the second block represents "blank".  An even  number  of  blocks  will
1061       repeat the pattern, an odd number of blocks will alternate the pattern.
1062       The default is "solid";
1063
1064       linecap - the linecap specifies the look of the ends of  the  line,  or
1065       the  end of the dashes in a dashed line. The parameters are: ’butt’ for
1066       butt caps (default), ’round’ for round  caps  and  ’extended_butt’  for
1067       extended  butt  caps. The shape of the round and the extended butt caps
1068       is related to the line thickness: for round butts the  radius  is  half
1069       the  linewidth,  while  for extended butt the line will extend for half
1070       the linewidth.
1071
1072       cats - which categories should be plotted (default is all);
1073
1074       label - for description in vlegend.  Default is: map(mapset);
1075
1076       lpos - position vector is plotted in legend. If lpos  is  0  then  this
1077       vector  is  omitted  in legend. If more vectors used the same lpos then
1078       their symbols in legend are merged and label for first vector is used.
1079
1080       EXAMPLE:
1081            vlines streams
1082            color blue
1083            width 2
1084            hcolor white
1085            hwidth 1
1086            masked y
1087            cats 2
1088            label Streams - category 2
1089            end
1090

vpoints

1092       Selects vector point data to be placed on the output map
1093       USAGE:    vpoints vectormap
1094            type point and/or centroid
1095            layer # (layer number used with cats/where/sizecol options)
1096            cats list of categories (e.g. 1,3,5-7)
1097            where SQL where statement like: vlastnik = ’Cimrman’
1098            masked [y|n]
1099            color color
1100            fcolor color
1101            rgbcolumn column
1102            width #
1103            eps epsfile
1104            symbol symbol group/name
1105            size #
1106            sizecolumn attribute column used for symbol sizing
1107            scale scaling factor for sizecolumn values
1108            rotate #
1109            rotatecolumn column
1110            label legend label
1111            lpos position in legend
1112            end
1113       The user may specify the the color of the sites (see section  on  NAMED
1114       COLORS);  either  the  GRASS  symbol or the eps Encapsulated Postscript
1115       file to be used to represent the presence of a site (if ’$’ is used  in
1116       the  EPS  file path it will be replaced by category number); and rotate
1117       (in degrees) for counter-clockwise rotation.
1118       The size of the icon (number of times larger than the size it is in the
1119       icon  file)  is  typically  given by the size option. Alternatively the
1120       size of the symbol or EPS graphic can be taken from an attribute column
1121       by  using  the sizecolumn command. The value given by sizecolumn may be
1122       scaled by using the scale factor setting (default scaling is 1.0).   In
1123       a  similar manner symbol color can be read from rgbcolumn and the rota‐
1124       tion angle read from rotatecolumn.
1125       EXAMPLE:
1126            vpoints windmills
1127            color blue
1128            symbol mills/windmill
1129            size 10
1130            end
1131

vlegend

1133       Prints the portion of the map legend containing the vector information,
1134       on or below the map.
1135       USAGE:    vlegend
1136            where x y
1137            font font name
1138            fontsize font size
1139            width width of color symbol
1140            cols number of columns to print
1141            span column separation
1142            border color|none
1143            end
1144       The  default  location  is  immediately below the legend containing the
1145       scale, grid and region information, starting at the left  edge  of  the
1146       map.   If  the where instruction is present and y is less than or equal
1147       to zero, the vector legend will be  positioned  immediately  below  the
1148       map, starting x inches from the left edge of the page.
1149
1150       width  is  the width in inches of the color symbol (for lines) in front
1151       of the legend text. The default is 1/24 * fontsize inches.
1152
1153       cols is the number of columns to split the legend into. The default  is
1154       one column. The maximum number of columns is 10, or equal to the number
1155       of legend entries if there are less than 10 entries.
1156
1157       span is the column separation distance between the left  edges  of  two
1158       columns in a multicolumn legend. It is given in inches.  The default is
1159       automatic scaling based on the left margin and the right hand  side  of
1160       the map box.
1161
1162       border  will draw a border around the legend using the specified color.
1163       (see NAMED COLORS)
1164
1165       Alternatively, the user can create a custom legend by using the rectan‐
1166       gle, point, and text instructions.
1167
1168       See also the colortable command for creating raster map legends.
1169
1170       This  example  prints  the  vector legend immediately below the map and
1171       starting 4.5 inches from the left edge of the page, using a 12/72  inch
1172       Helvetica font.
1173       EXAMPLE:
1174            vlegend
1175            where 4.5 0
1176            font Courier
1177            fontsize 12
1178            end
1179

end

1181       Terminates input and begin painting the map.
1182       USAGE:    end
1183

EXAMPLES

1185       The following are examples of ps.map script files.
1186
1187   Simple example
1188       The file has been named simple_map.txt:
1189       # this ps.map example draws a map of Wake county, NC
1190       raster elevation
1191       vlines roadsmajor
1192         color 30:144:255
1193         width 2
1194         end
1195       text 50% 105% Wake County Terrain and Roads
1196          size 550
1197          end
1198       end
1199       Generate map as Postsript file:
1200       ps.map input=simple_map.txt output=simple_map.ps
1201
1202       Figure:  Result of for the a simple Wake county terrain and roads exam‐
1203       ple
1204
1205   More complicated example
1206       The following is content of a file named elevation_map.txt:
1207       # this ps.map example draws a map of Wake county, NC
1208       raster elevation
1209       colortable y
1210         where 1 6.0
1211         cols 4
1212         width 4
1213         font Helvetica
1214         end
1215       setcolor 6,8,9 white
1216       setcolor 10 green
1217       vlines streams
1218         width 0.1
1219         color blue
1220         masked n
1221         label streams
1222         end
1223       vlines roadsmajor
1224         width 1.5
1225         style 1111
1226         color grey
1227         masked n
1228         label major roads
1229         end
1230       vlegend
1231         where 4.5 0
1232         font Courier
1233         fontsize 8
1234         end
1235       text 30% 100% Wake County Terrain
1236         color black
1237         width 1
1238         background white
1239         size 550
1240         ref lower left
1241         end
1242       text 92% -25% meters
1243         color black
1244         width 1
1245         background white
1246         size 550
1247         ref lower left
1248         end
1249       scale 1:125000
1250       scalebar f
1251         where 1.5 5.5
1252         length 5000
1253         height 0.05
1254         segment 5
1255         numbers 5
1256         end
1257       geogrid 60 s
1258         color gray
1259         numbers 2 black
1260         end
1261       paper a4
1262          end
1263       end
1264       This script file can be entered at the command line:
1265       # First set the region
1266       g.region raster=elevation
1267       # Generate map as Postsript file
1268       ps.map input=elevation_map.txt output=elevation.ps
1269
1270       Figure: Result of for the more complicated Wake county, NC example
1271
1272       More examples can be found on the GRASS Wiki help site.
1273

SEE ALSO

1275        g.gui.psmap, g.region, v.label, wxGUI,
1276

AUTHOR

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

SOURCE CODE

1282       Available at: ps.map source code (history)
1283
1284       Main index | PostScript index | Topics index | Keywords index | Graphi‐
1285       cal index | Full index
1286
1287       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
1288
1289
1290
1291GRASS 7.8.2                                                          ps.map(1)
Impressum