1ps.map(1) GRASS GIS User's Manual ps.map(1)
2
3
4
6 ps.map - Produces hardcopy PostScript map output.
7
9 postscript, printing
10
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
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
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 in‐
76 dicate 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 en‐
106 coding, for example by using the iconv utility:
107 iconv -f UTF-8 -t ISO_8859-1 utf_file > iso_file
108
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 in‐
113 structions 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 de‐
145 fault 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
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
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 be‐
222 ing 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 re‐
227 sult in the printing of an extremely long color table! In this situa‐
228 tion it is useful to use the discrete N instruction to force a continu‐
229 ous color gradient legend.
230
231 Be aware that the color table only includes categories which have a la‐
232 bel. 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
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
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
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 in‐
311 formation 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 in‐
325 structions.
326
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 de‐
338 grees, 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
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
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 ev‐
378 ery grid line (1), every other grid line (2), etc., and what color the
379 numbers should be. The cross argument draws grid intersection crosses
380 instead of grid lines, with cross size given in geographic coordinate
381 system units. The defaults are black grid lines, unnumbered.
382
383 This example would overlay a green grid with a spacing of 10000 meters
384 (for a metered database, like UTM) onto the output map. Alternate grid
385 lines would be numbered with red numbers.
386 EXAMPLE:
387 grid 10000
388 color green
389 numbers 2 red
390 end
391
393 Selects an RGB imagery group for output.
394 USAGE: group groupname
395 This is similar to raster, except that it uses an imagery group instead
396 of a raster map layer. The group must contain three raster map layers,
397 comprising the red, green and blue bands of the image.
398
400 Prints the map header above the map.
401 USAGE: header
402 file header file
403 font font name
404 fontsize font size
405 color text color
406 end
407 If the file sub-instruction is absent the header will consist of the
408 map’s title and the location’s description. The text will be centered
409 on the page above the map. The default text color is black.
410
411 If the file sub-instruction is given the header will consist of the
412 text in the text file specified, with some special formatting keys:
413
414 • %% - a literal %
415
416 • %n - ? newline ?
417
418 • %_ - horizontal bar
419
420 • %c - "<raster name> in mapset <mapset name>"
421
422 • %d - today’s date
423
424 • %l - location name
425
426 • %L - Location’s text description
427
428 • %m - mapset name
429
430 • %u - user name
431
432 • %x - mask info
433
434 • %- - advance to this character column number (see example be‐
435 low)
436 Example header file:
437 %_
438 LOCATION: %-27l DATE: %d
439 MAPSET: %-27m USER: %u
440 RASTER MAP: %c
441 MASK: %x
442 %_
443 Produced by: US Army CERL, Champaign Illinois
444 Software: GRASS
445 %_
446
447 This example prints (in red) whatever is in the file soils.hdr above
448 the map, using a 20/72 inch Courier font.
449 EXAMPLE:
450 header
451 file soils.hdr
452 font Courier
453 fontsize 20
454 color red
455 end
456
458 Selects a labels file for output (see manual entry for v.label ).
459 USAGE: labels labelfile
460 font font name
461 end
462
463 NOTE: ps.map can read new option ’ROTATE:’ from labels file, which
464 specifies counter clockwise rotation in degrees.
465
466 This example would paint labels from the labels file called town.names.
467 Presumably, these labels would indicate the names of towns on the map.
468 EXAMPLE:
469 labels town.names
470 end
471
473 Draws lines on the output map.
474 USAGE: line east north east north
475 line x% y% x% y%
476 color color
477 width #
478 masked [y|n]
479 end
480 The beginning and ending points of the line are entered on the main in‐
481 struction. These points can be defined either by map coordinates or by
482 using percentages of the geographic region. The user may also specify
483 line color, width in points (1/72"; accepts decimal values as well as
484 integers), and if the line is to be masked by the current mask. (See
485 manual entry for r.mask
486 for more information on the mask.) The line width (if given) is mea‐
487 sured in points; an i directly following the number indicates that the
488 width is given in inches instead.
489
490 This example would draw a yellow line from the point x=10% y=80% to the
491 point x=30% y=70%. This line would be 2 points wide (2/72") and would
492 appear even if there is a mask.
493 EXAMPLE:
494 line 10% 80% 30% 70%
495 color yellow
496 width 2
497 masked n
498 end
499 Of course, multiple lines may be drawn with multiple line instructions.
500
502 Prints the portion of the map legend containing the scale, grid and re‐
503 gion information, on or below the map.
504 USAGE: mapinfo
505 where x y
506 font font name
507 fontsize font size
508 color text color
509 background box color|none
510 border color|none
511 end
512 The default location is immediately below the map, starting at the left
513 edge of the map. The default text color is black. The default back‐
514 ground box color is white.
515
516 border will draw a border around the legend using the specified color.
517 (see NAMED COLORS)
518
519 This example prints (in brown) the scale, grid and region information
520 immediately below the map and starting 1.5 inches from the left edge of
521 the page, using a 12/72 inch Courier font.
522 EXAMPLE:
523 mapinfo
524 where 1.5 0
525 font Courier
526 fontsize 12
527 color brown
528 end
529
531 Positions the map on the page.
532 USAGE: maploc x y [width height]
533 The upper left corner of the map will be positioned x inches from the
534 left edge of the page and y inches from the top of the page. If width
535 and height (in inches) are present, the map will be rescaled, if neces‐
536 sary, to fit.
537
538 This example positions the upper left corner of the map 2.0 inches from
539 the left edge and 3.5 inches from the top edge of the map.
540 EXAMPLE:
541 maploc 2.0 3.5
542
544 Color to be used for mask.
545 USAGE: maskcolor color
546
548 Outlines the areas of a raster map layer with a specified color.
549 USAGE: outline
550 color color
551 width width of line in points
552 end
553 Distinct areas of the raster map will be separated from each other vis‐
554 ually by drawing a border (or outline) in the specified color (default:
555 black). For width the program accepts decimal points [floating points]
556 as well as integers. Note: it is important the user enter the instruc‐
557 tion end even if a color is not chosen. (It is hoped that in the fu‐
558 ture the outline of a different raster map layer other than the one
559 currently being painted may be placed on the map.)
560
561 This example would outline the category areas of the soils raster map
562 layer in grey.
563 EXAMPLE:
564 raster soils
565 outline
566 color grey
567 width 2
568 end
569
571 Specifies paper size and margins.
572 USAGE: paper paper name
573 height #
574 width #
575 left #
576 right #
577 bottom #
578 top #
579 end
580 paper may select predefined paper name (a4,a3,a2,a1,a0,us-legal,us-let‐
581 ter,us-tabloid). Default paper size is a4. The measures are defined in
582 inches. left, right, bottom and top are paper margins. If the plot is
583 rotated with the -r command line flag, measures are applied to the ro‐
584 tated page.
585
586 EXAMPLE:
587 paper a3
588 end
589
590 EXAMPLE:
591 paper
592 width 10
593 height 10
594 left 2
595 right 2
596 bottom 2
597 top 2
598 end
599
601 Places additional points or icons on the output map.
602 USAGE: point east north
603 point x% y%
604 color color
605 fcolor color
606 symbol symbol group/name
607 size #
608 width #
609 rotate #
610 masked [y|n]
611 end
612 The point location is entered in the main instruction line by giving
613 either the map coordinates or by using percentages of the geographic
614 region. The user may also specify the point color, the size of symbol
615 in points, the rotation angle (in degrees CCW), and whether the point
616 is to be masked by the current mask. (See manual entry for r.mask
617 for more information on the mask.) The symbol line width (if given)
618 is measured in points; an i directly following the number indicates
619 that the width is given in inches instead. If a width is not given it
620 will be set proportional to the symbol size.
621
622 This example would place a purple diamond (from icon file diamond) at
623 the point (E456000 N7890000). This diamond would be the the size of a
624 15 points and would not be masked by the current mask.
625 EXAMPLE:
626 point 456000 7890000
627 fcolor purple
628 color black
629 symbol basic/diamond
630 size 15
631 masked n
632 end
633 Of course, multiple points may be drawn with multiple point instruc‐
634 tions.
635
637 Copies a file containing PostScript commands into the output file.
638
639 Note: ps.map will not search for this file. The user must be in the
640 correct directory or specify the full path on the psfile instruction.
641 (Note to /bin/csh users: ~ won’t work with this instruction).
642 USAGE: psfile filename
643 This example copies the file "logo.ps" into the output file.
644 EXAMPLE:
645 psfile logo.ps
646
648 Selects a raster map layer for output.
649 USAGE: raster mapname
650 For each ps.map run, only one raster map layer (or set of layers or im‐
651 agery group; see below) can be requested. If no raster map layer is re‐
652 quested, a completely white map will be produced. It can be useful to
653 select no raster map layer in order to provide a white background for
654 vector maps.
655
656 Note that an imagery group selected with the group option, or a set of
657 three raster layers selected with the rgb option, count as a raster map
658 layer for the purposes of the preceding paragraph.
659
660 The PostScript file’s internal title will be set to the raster map’s
661 title, which in turn may be set with the r.support module.
662
663 This example would paint a map of the raster map layer soils.
664 EXAMPLE:
665 raster soils
666
668 Provides ps.map with a previously prepared input stream.
669 USAGE: read previously prepared UNIX file
670 Mapping instructions can be placed into a file and read into ps.map.
671
672 Note: ps.map will not search for this file. The user must be in the
673 correct directory or specify the full path on the read instruction.
674 (Note to /bin/csh users: ~ won’t work with this instruction).
675
676 This example reads the UNIX file pmap.roads into ps.map. This file may
677 contain all the ps.map instructions for placing the vector map layer
678 roads onto the output map.
679 EXAMPLE:
680 read pmap.roads
681 The user may have created this file because this vector map layer is
682 particularly useful for many ps.map outputs. By using the read option,
683 the user need not enter all the input for the vector instruction, but
684 simply read the previously prepared file with the correct instructions.
685
687 Draws rectangle on the output map.
688 USAGE: rectangle east north east north
689 rectangle x% y% x% y%
690 color color
691 fcolor fill color
692 width #
693 masked [y|n]
694 end
695 The two corners of the rectangle are entered on the main instruction.
696 These points can be defined either by map coordinates or by using per‐
697 centages of the geographic region. The user may also specify line
698 color, fill color fcolor, width in points (accepts decimal points
699 [floating points] as well as integers), and if the rectangle is to be
700 masked by the current mask. (See manual entry for r.mask for more in‐
701 formation on the mask.) The border line width (if given) is measured
702 in points; an i directly following the number indicates that the width
703 is given in inches instead.
704 Multiple rectangles may be drawn by using multiple rectangle instruc‐
705 tions.
706
707 This example would draw a yellow rectangle filled by green from the
708 point x=10% y=80% to the point x=30% y=70%. The border line would be
709 1/16" wide and would appear even if there is a mask.
710 EXAMPLE:
711 rectangle 10% 80% 30% 70%
712 color yellow
713 fcolor green
714 width 0.0625i
715 masked n
716 end
717
719 Places the outline of a smaller geographic region on the output.
720 USAGE: region regionfile
721 color color
722 width #
723 end
724 Geographic region settings are created and saved using the g.region
725 module. The ps.map region option can be used to show an outline of a
726 smaller region which was printed on a separate run of ps.map on other
727 user-created maps.
728
729 The user can specify the color and the width in point units (accepts
730 decimal points [floating points] as well as integers) of the outline.
731 The default is a black border of one point width (1/72").
732
733 This example would place a white outline, 2 points wide, of the geo‐
734 graphic region called fire.zones onto the output map. This geographic
735 region would have been created and saved using g.region.
736 EXAMPLE:
737 region fire.zones
738 color white
739 width 2
740 end
741
743 Selects three raster map layers for output as an RGB color image.
744 USAGE: rgb red green blue
745 This is similar to raster, except that it uses three raster map layers
746 instead of a single layer. The three layers are composed to form a
747 color image, similar to d.rgb.
748
749 For each layer, only one of the components of the layer’s color table
750 is used: the red component for the red layer, and so on. This will
751 give the desired result if all of the layers have a grey-scale color
752 table, or if each layer’s color table uses the hue appropriate to the
753 layer.
754
756 Selects a scale for the output map.
757 USAGE: scale scale
758 The scale can be selected either as:
759
760
761 a relative ratio, e.g. 1:25000;
762
763
764 an absolute width of the printed map, e.g. 10 inches;
765
766
767 the number of printed paper panels, e.g. 3 panels .I (at the
768 present time, only 1 panel is supported);
769
770
771 the number of miles per inch, e.g. 1 inch equals 4 miles.
772
773 This example would set the scale of the map to 1 unit = 25000 units.
774 EXAMPLE:
775 scale 1:25000
776
778 Draws a scalebar on the map.
779 USAGE: scalebar [f|s]
780 where x y
781 length overall distance in map units
782 units [auto|meters|kilometers|feet|miles|nautmiles]
783 height scale height in inches
784 segment number of segments
785 numbers #
786 fontsize font size
787 background [Y|n]
788 end
789 Draw one of two types of scale bar. Fancy (f) draws alternating black
790 and white scale boxes. Simple (s) draws a plain line scale. The de‐
791 fault type is fancy. The subsection instructions allow the user to set
792 where the scalebar is placed, the length of the scalebar (in geographic
793 coordinate system units, or those given by units), the height of the
794 scalebar in inches, and the number of segments (or tics for simple).
795 The number of annotations numbers every n-th segment. The background
796 command can turn off the background box for the text.
797
798 The scalebar length is the only required argument. The defaults are a
799 fancy scalebar with 4 segments, each segment labeled, and a height of
800 0.1 inches. The default location is 2 inches from the top of the page
801 and halfway across.
802
803 NOTE: The scalebar is centered on the location given.
804
805 This example draws a simple scalebar 1000 meters (for a metered data‐
806 base, like UTM) long, with tics every 200 meters, labeled every second
807 tic. The scalebar is drawn 5 inches from the top and 4 inches from the
808 left and is 0.25 inches high.
809 EXAMPLE:
810 scalebar s
811 where 4 5
812 length 1000
813 height 0.25
814 segment 5
815 numbers 2
816 end
817
819 Overrides the color assigned to one or more categories of the raster
820 map layer.
821 USAGE: setcolor cat(s) color
822 This example would set the color for categories 2,5 and 8 of the raster
823 map layer watersheds to white and category 10 to green. (NOTE: no spa‐
824 ces are inserted between the category values.)
825 EXAMPLE:
826 raster watersheds
827 setcolor 2,5,8 white
828 setcolor 10 green
829 Of course, setcolor can be requested more than once to override the de‐
830 fault color for additional categories. More than one category can be
831 changed for each request by listing all the category values separated
832 by commas (but with no spaces). Also ranges can be included, for exam‐
833 ple "1,2,6-10,12". Colors for "null" and the "default" (i.e.
834 out-of-range) color may also be reassigned.
835
837 Places text on the map.
838 USAGE: text east north text
839 text x% y% text
840 font fontname
841 color color|none
842 width #
843 hcolor color|none
844 hwidth #
845 background color|none
846 border color|none
847 fontsize font size
848 size #
849 ref reference point
850 rotate degrees CCW
851 xoffset #
852 yoffset #
853 opaque [y|n]
854 end
855 The user specifies where the text will be placed by providing map coor‐
856 dinates or percentages of the geographic region. The text follows
857 these coordinates on the same instruction line. More than one line of
858 text can be specified by notating the end of a line with \n (e.g.
859 USA\nCERL).
860
861 The user can then specify various text features:
862
863 font: the PostScript font. Common possibilities are listed at the start
864 of this help page. The default is Helvetica.
865
866 color (see NAMED COLORS);
867
868 width of the lines used to draw the text to make thicker letters (ac‐
869 cepts decimal points [floating points] as well as integers);
870
871 size and fontsize. size gives the vertical height of the letters in
872 meters on the ground (text size will grow or shrink depending on the
873 scale at which the map is painted). Alternatively fontsize can set the
874 font size directly. If neither size or fontsize is given, a default
875 font size of 10 will be used;
876
877 the highlight color (hcolor) and the width of the highlight color
878 (hwidth);
879
880 the text-enclosing-box background color; the text box border color;
881
882 ref. This reference point specifies the text handle - what part of the
883 text should be placed on the location specified by the map coordinates.
884 Reference points can refer to: [lower|upper|center] [left|right|center]
885 of the text to be printed; The default is center center, i.e. the text
886 is centered on the reference point.
887
888 rotate sets the text rotation angle, measured in degrees counter-clock‐
889 wise.
890
891 yoffset, which provides finer placement of text by shifting the text a
892 vertical distance in points (1/72") from the specified north. The ver‐
893 tical offset will shift the location to the south if positive, north if
894 negative;
895
896 xoffset, which shifts the text a horizontal distance in points from the
897 specified east The horizontal offset will shift the location east if
898 positive, west if negative;
899
900 opaque, whether or not the text should be opaque to vectors. Entering
901 no to the opaque option will allow the user to see any vectors which go
902 through the text’s background box. Otherwise, they will end at the
903 box’s edge.
904
905 The following example would place the text SPEARFISH LAND COVER at the
906 coordinates E650000 N7365000. The text would be a total of 3 points
907 wide (2 pixels of red text and 1 pixel black highlight), have a white
908 background enclosed in a red box, and be 500 meters in size. The lower
909 right corner of the text would be centered over the coordinates pro‐
910 vided. All vectors on the map would stop at the border of this text.
911 EXAMPLE:
912 text 650000 7365000 SPEARFISH LAND COVER
913 font romand
914 color red
915 width 2
916 hcolor black
917 hwidth 1
918 background white
919 border red
920 size 500
921 ref lower left
922 opaque y
923 end
924
926 Selects a vector map layer for output and plots areas.
927 USAGE: vareas vectormap
928 layer # (layer number used with cats/where option)
929 cats list of categories (e.g. 1,3,5-7)
930 where SQL where statement
931 masked [y|n]
932 color color
933 fcolor color
934 rgbcolumn column
935 width #
936 label label to use in legend
937 lpos position in legend
938 pat pattern file
939 pwidth #
940 scale #
941 end
942 The user can specify:
943
944 color - color of the vector lines or area boundaries;
945
946 fcolor - the area fill color;
947
948 rgbcolumn - name of color definition column used for the area fill
949 color;
950
951 width - width of the vectors lines or area boundaries in points (ac‐
952 cepts decimal points [floating points] as well as integers);
953
954 masked - whether or not the raster map layer is to be masked by the
955 current mask; (see manual entry r.mask for more information on the
956 mask)
957
958 cats - which categories should be plotted (default is all);
959
960 where - select features using a SQL where statement. For example:
961 vlastnik = ’Cimrman’;
962
963 label - for description in vlegend. Default is: map(mapset);
964
965 lpos - position vector is plotted in legend. If lpos is 0 then this
966 vector is omitted in legend. If more vectors used the same lpos then
967 their symbols in legend are merged and label for first vector is used.
968
969 pat - full path to pattern file. The pattern file contains header and
970 simple PostScript commands. It is similar to EPS but more limited,
971 meaning that while each pattern file is a true EPS file, most EPS files
972 are not useful as pattern files because they contain restricted com‐
973 mands. Color of patterns are set by fcolor (red, green, ..., none,
974 R:G:B). Color of the boundaries remain set by the color instruction.
975 Pattern may be scaled with the scale command. Several standard hatching
976 patterns are provided in $GISBASE/etc/paint/patterns/. Demonstrative
977 images can be found on the GRASS Wiki site. You can also create your
978 own custom pattern files in a text editor. Example of pattern file:
979 %!PS-Adobe-2.0 EPSF-1.2
980 %%BoundingBox: 0 0 10 10
981 newpath
982 5 0 moveto
983 5 10 lineto
984 stroke
985
986 scale - pattern scale
987
988 pwidth - pattern line width, width is used by pattern until the width
989 is overwritten in pattern file.
990
991 EXAMPLE:
992 vareas forest
993 color blue
994 width 1
995 masked y
996 cats 2,5-7
997 end
998
1000 Selects a vector map layer for output and plots lines.
1001 USAGE: vlines vectormap
1002 type line and/or boundary
1003 layer # (layer number used with cats/where option)
1004 cats list of categories (e.g. 1,3,5-7)
1005 where SQL where statement like: vlastnik = ’Cimrman’
1006 masked [y|n]
1007 color color
1008 rgbcolumn column
1009 width #
1010 cwidth #
1011 hcolor color
1012 hwidth #
1013 offset #
1014 coffset #
1015 ref left|right
1016 style 00001111
1017 linecap style
1018 label label
1019 lpos #
1020 end
1021 The user can specify:
1022
1023 type - the default is lines only;
1024
1025 color - color of the vector lines or area boundaries;
1026
1027 rgbcolumn - name of color definition column used for the vector lines
1028 or area boundaries;
1029
1030 width - width of the vectors lines or area boundaries in points (ac‐
1031 cepts decimal points [floating points] as well as integers);
1032
1033 cwidth - width of the vectors lines. If cwidth is used then width of
1034 line is equal to cwidth * category value and width is used in legend;
1035
1036 hcolor - the highlight color for the vector lines;
1037
1038 hwidth - the width of the highlight color in points;
1039
1040 offset (experimental) - offset for the vectors lines in points (1/72")
1041 for plotting parallel lines in distance equal to offset (accepts posi‐
1042 tive or negative decimal points). Useful to print streets with several
1043 parallel lanes;
1044
1045 coffset (experimental) - offset for the vectors lines. If coffset is
1046 used then offset of line is equal to coffset * category value and off‐
1047 set is used in legend;
1048
1049 ref (experimental) - line justification.
1050
1051 masked - whether or not the raster map layer is to be masked by the
1052 current mask; (see manual entry r.mask for more information on the
1053 mask);
1054
1055 style - the line style allows the vectors to be dashed in different
1056 patterns. This is done by either typing "solid", "dashed", "dotted",
1057 or "dashdotted", or as a series of 0’s and 1’s in a desired sequence or
1058 pattern. The first block of repeated zeros or ones represents "draw",
1059 the second block represents "blank". An even number of blocks will re‐
1060 peat the pattern, an odd number of blocks will alternate the pattern.
1061 The default is "solid";
1062
1063 linecap - the linecap specifies the look of the ends of the line, or
1064 the end of the dashes in a dashed line. The parameters are: ’butt’ for
1065 butt caps (default), ’round’ for round caps and ’extended_butt’ for ex‐
1066 tended butt caps. The shape of the round and the extended butt caps is
1067 related to the line thickness: for round butts the radius is half the
1068 linewidth, while for extended butt the line will extend for half the
1069 linewidth.
1070
1071 cats - which categories should be plotted (default is all);
1072
1073 label - for description in vlegend. Default is: map(mapset);
1074
1075 lpos - position vector is plotted in legend. If lpos is 0 then this
1076 vector is omitted in legend. If more vectors used the same lpos then
1077 their symbols in legend are merged and label for first vector is used.
1078
1079 EXAMPLE:
1080 vlines streams
1081 color blue
1082 width 2
1083 hcolor white
1084 hwidth 1
1085 masked y
1086 cats 2
1087 label Streams - category 2
1088 end
1089
1091 Selects vector point data to be placed on the output map
1092 USAGE: vpoints vectormap
1093 type point and/or centroid
1094 layer # (layer number used with cats/where/sizecol options)
1095 cats list of categories (e.g. 1,3,5-7)
1096 where SQL where statement like: vlastnik = ’Cimrman’
1097 masked [y|n]
1098 color color
1099 fcolor color
1100 rgbcolumn column
1101 width #
1102 eps epsfile
1103 symbol symbol group/name
1104 size #
1105 sizecolumn attribute column used for symbol sizing
1106 scale scaling factor for sizecolumn values
1107 rotate #
1108 rotatecolumn column
1109 label legend label
1110 lpos position in legend
1111 end
1112 The user may specify the the color of the sites (see section on NAMED
1113 COLORS); either the GRASS symbol or the eps Encapsulated Postscript
1114 file to be used to represent the presence of a site (if ’$’ is used in
1115 the EPS file path it will be replaced by category number); and rotate
1116 (in degrees) for counter-clockwise rotation.
1117 The size of the icon (number of times larger than the size it is in the
1118 icon file) is typically given by the size option. Alternatively the
1119 size of the symbol or EPS graphic can be taken from an attribute column
1120 by using the sizecolumn command. The value given by sizecolumn may be
1121 scaled by using the scale factor setting (default scaling is 1.0). In
1122 a similar manner symbol color can be read from rgbcolumn and the rota‐
1123 tion angle read from rotatecolumn.
1124 EXAMPLE:
1125 vpoints windmills
1126 color blue
1127 symbol mills/windmill
1128 size 10
1129 end
1130
1132 Prints the portion of the map legend containing the vector information,
1133 on or below the map.
1134 USAGE: vlegend
1135 where x y
1136 font font name
1137 fontsize font size
1138 width width of color symbol
1139 cols number of columns to print
1140 span column separation
1141 border color|none
1142 end
1143 The default location is immediately below the legend containing the
1144 scale, grid and region information, starting at the left edge of the
1145 map. If the where instruction is present and y is less than or equal
1146 to zero, the vector legend will be positioned immediately below the
1147 map, starting x inches from the left edge of the page.
1148
1149 width is the width in inches of the color symbol (for lines) in front
1150 of the legend text. The default is 1/24 * fontsize inches.
1151
1152 cols is the number of columns to split the legend into. The default is
1153 one column. The maximum number of columns is 10, or equal to the number
1154 of legend entries if there are less than 10 entries.
1155
1156 span is the column separation distance between the left edges of two
1157 columns in a multicolumn legend. It is given in inches. The default is
1158 automatic scaling based on the left margin and the right hand side of
1159 the map box.
1160
1161 border will draw a border around the legend using the specified color.
1162 (see NAMED COLORS)
1163
1164 Alternatively, the user can create a custom legend by using the rectan‐
1165 gle, point, and text instructions.
1166
1167 See also the colortable command for creating raster map legends.
1168
1169 This example prints the vector legend immediately below the map and
1170 starting 4.5 inches from the left edge of the page, using a 12/72 inch
1171 Helvetica font.
1172 EXAMPLE:
1173 vlegend
1174 where 4.5 0
1175 font Courier
1176 fontsize 12
1177 end
1178
1180 Terminates input and begin painting the map.
1181 USAGE: end
1182
1184 The following are examples of ps.map script files.
1185
1186 Simple example
1187 The file has been named simple_map.txt:
1188 # this ps.map example draws a map of Wake county, NC
1189 raster elevation
1190 vlines roadsmajor
1191 color 30:144:255
1192 width 2
1193 end
1194 text 50% 105% Wake County Terrain and Roads
1195 size 550
1196 end
1197 end
1198 Generate map as Postsript file:
1199 ps.map input=simple_map.txt output=simple_map.ps
1200
1201 Figure: Result of for the a simple Wake county terrain and roads exam‐
1202 ple
1203
1204 More complicated example
1205 The following is content of a file named elevation_map.txt:
1206 # this ps.map example draws a map of Wake county, NC
1207 raster elevation
1208 colortable y
1209 where 1 6.0
1210 cols 4
1211 width 4
1212 font Helvetica
1213 end
1214 setcolor 6,8,9 white
1215 setcolor 10 green
1216 vlines streams
1217 width 0.1
1218 color blue
1219 masked n
1220 label streams
1221 end
1222 vlines roadsmajor
1223 width 1.5
1224 style 1111
1225 color grey
1226 masked n
1227 label major roads
1228 end
1229 vlegend
1230 where 4.5 0
1231 font Courier
1232 fontsize 8
1233 end
1234 text 30% 100% Wake County Terrain
1235 color black
1236 width 1
1237 background white
1238 size 550
1239 ref lower left
1240 end
1241 text 92% -25% meters
1242 color black
1243 width 1
1244 background white
1245 size 550
1246 ref lower left
1247 end
1248 scale 1:125000
1249 scalebar f
1250 where 1.5 5.5
1251 length 5000
1252 height 0.05
1253 segment 5
1254 numbers 5
1255 end
1256 geogrid 60 s
1257 color gray
1258 numbers 2 black
1259 end
1260 paper a4
1261 end
1262 end
1263 This script file can be entered at the command line:
1264 # First set the region
1265 g.region raster=elevation
1266 # Generate map as Postsript file
1267 ps.map input=elevation_map.txt output=elevation.ps
1268
1269 Figure: Result of for the more complicated Wake county, NC example
1270
1271 More examples can be found on the GRASS Wiki help site.
1272
1274 g.gui.psmap, g.region, v.label, wxGUI
1275
1277 Paul Carlson, USDA, SCS, NHQ-CGIS
1278 Modifications: Radim Blazek, Glynn Clements, Bob Covill, Hamish Bowman
1279
1281 Available at: ps.map source code (history)
1282
1283 Accessed: Saturday Jan 21 20:40:59 2023
1284
1285 Main index | PostScript index | Topics index | Keywords index | Graphi‐
1286 cal index | Full index
1287
1288 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
1289
1290
1291
1292GRASS 8.2.1 ps.map(1)