Debian Codegraph @

ps/ps.map/ps.map.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <em>ps.map</em> is a cartographic mapping program for producing high quality
4 hardcopy maps in PostScript format. Output can include a raster map, any
5 number of vector overlays, text labels, decorations, and other spatial data.
6
7 <p>A file of mapping instructions that describes the various spatial and textual
8 information to be printed must be prepared prior to running <em>ps.map</em>.
9
10 <h2>NOTES</h2>
11
12 The order of commands is generally unimportant but may affect how some layers
13 are drawn. For example to plot <b>vpoints</b> above <b>vareas</b> list the
14 <b>vpoints</b> entry first. Raster maps are always drawn first, and only a
15 single raster map (or 3 if part of a RGB group) may be used.
16
17 <p>The hash character ('<code>#</code>') may be used at the beginning of a line
18 to indicate that the line is a comment. Blank lines will also be ignored.
19
20 <p>Be aware that some mapping instructions require the <i>end</i> command
21 and some do not. Any instruction that allows subcommands will require
22 it, any instruction that does not allow subcommands will not.
23
24 <p>The resolution and extent of raster maps plotted with <em>ps.map</em> are
25 controlled by the current region settings via the
26 <a href="g.region.html">g.region</a> module. The output filesize is largely
27 a function of the region resolution, so special care should be taken
28 if working with large raster datasets. For example if the desired output is
29 US-Letter sized paper at 600dpi, with 1" margins and the raster filling the
30 entire page, the usable area on the page will be 6.5" x 9", which at 600
31 dots/inch is equivalent to a region of 3900 columns x 5400 rows (see
32 "<code>g.region -p</code>"). Any higher resolution settings will make the
33 output file larger, but with a consumer printer you probably won't be able
34 to resolve any better detail in the hardcopy.
35
36 <p>The user can specify negative or greater than 100 percentage values for
37 positioning several map decorations and embedded EPS-files, to move them
38 outside the current map box region (for example to position a caption,
39 barscale, or legend above or below the map box).
40
41 <p>One point ("pixel") is 1/72 of an inch.
42
43 <p>For users wanting to use special characters (such as accented characters) it
44 is important to note that <em>ps.map</em> uses <code>ISO-8859-1</code> encoding.
45 This means that your instructions file will have to be encoded in this
46 encoding. If you normally work in a different encoding environment (such as
47 <code>UTF-8</code>), you have to transform your file to the <code>ISO-8859-1</code>
48 encoding, for example by using the <code>iconv</code> utility:
49
50 <div class="code"><pre>
51 iconv -f UTF-8 -t ISO_8859-1 utf_file &gt; iso_file
52 </pre></div>
53
54
55 <p><p>
56 <h2>MAPPING INSTRUCTIONS</h2>
57
58 The mapping instructions allow the user to specify various spatial data
59 to be plotted. These instructions are normally prepared in a regular
60 text file using a system editor. Some instructions are single line
61 instructions while others are multiple line. Multiple line instructions
62 consist of the main instruction followed by a subsection of one or more
63 additional instructions and are terminated with an <i>end</i> instruction.
64 <p>
65 <h3>Instruction keywords:</h3>
66 [
67 <a href="#border">border</a>&nbsp;|
68 <a href="#colortable">colortable</a>&nbsp;|
69 <a href="#comments">comments</a>&nbsp;|
70 <a href="#copies">copies</a>&nbsp;|
71 <a href="#eps">eps</a>&nbsp;|
72 <a href="#geogrid">geogrid</a>&nbsp;|
73 <a href="#greyrast">greyrast</a>&nbsp;|
74 <a href="#grid">grid</a>&nbsp;|
75 <a href="#group">group</a>&nbsp;|
76 <a href="#header">header</a>&nbsp;|
77 <a href="#labels">labels</a>&nbsp;|
78 <a href="#line">line</a>&nbsp;|
79 <a href="#mapinfo">mapinfo</a>&nbsp;|
80 <a href="#maploc">maploc</a>&nbsp;|
81 <a href="#maskcolor">maskcolor</a>&nbsp;|
82 <a href="#outline">outline</a>&nbsp;|
83 <a href="#paper">paper</a>&nbsp;|
84 <a href="#point">point</a>&nbsp;|
85 <a href="#psfile">psfile</a>&nbsp;|
86 <a href="#raster">raster</a>&nbsp;|
87 <a href="#read">read</a>&nbsp;|
88 <a href="#rectangle">rectangle</a>&nbsp;|
89 <a href="#region">region</a>&nbsp;|
90 <a href="#rgb">rgb</a>&nbsp;|
91 <a href="#scale">scale</a>&nbsp;|
92 <a href="#scalebar">scalebar</a>&nbsp;|
93 <a href="#setcolor">setcolor</a>&nbsp;|
94 <a href="#text">text</a>&nbsp;|
95 <a href="#vareas">vareas</a>&nbsp;|
96 <a href="#vlines">vlines</a>&nbsp;|
97 <a href="#vpoints">vpoints</a>&nbsp;|
98 <a href="#vlegend">vlegend</a>&nbsp;|
99 <a href="#end">end</a>
100 ]
101
102 <h3>Common instructions</h3>
103 Instructions that may be included in the subsection under several
104 different main instructions are:
105
106 <dl>
107 <dt><b>where</b> <em>x y</em>
108
109 <dd>The top left corner of the bounding box of the item to be plotted
110 is located <em>x</em> inches from the left edge of the paper and
111 <em>y</em> inches from the top edge of the paper. If <em>x</em> is less than
112 or equal to zero, the default horizontal location is used. If <em>y</em>
113 is less than or equal to zero, the default vertical location is used.
114
115 <dt><b>font</b> <em>font name</em>
116
117 <dd>The name of the PostScript font.
118 Fonts present in all PostScript implementations are:
119 <code>
120 Times-Roman,
121 Times-Italic,
122 Times-Bold,
123 Times-BoldItalic,
124 Helvetica,
125 Helvetica-Oblique,
126 Helvetica-Bold,
127 Helvetica-BoldOblique,
128 Courier,
129 Courier-Oblique,
130 Courier-Bold,
131 and
132 Courier-BoldOblique</code>.
133 <br>
134 The default is Helvetica.
135 </dd>
136
137
138 <dt><b>fontsize</b> <em>font size</em>
139
140 <dd>The size of the PostScript font (in 1/72nds of an inch).
141 The default is 10 point.
142 </dd>
143
144
145 <dt><a name="NAMED_COLORS"></a><b>color</b> <em>name</em>
146
147 <dd>The following colors names are accepted by <em>ps.map</em>:
148 <code>
149 aqua,
150 black,
151 blue,
152 brown,
153 cyan,
154 gray,
155 grey,
156 green,
157 indigo,
158 magenta,
159 orange,
160 purple,
161 red,
162 violet,
163 white,
164 yellow
165 </code>.
166 <br><br>
167 For vectors and some plotting commands you can also specify
168 '<code>none</code>' or '<code>R:G:B</code>' (e.g '<code>255:0:0</code>').
169 </dd>
170
171 <dt><b>yes|no</b>
172 <dd>For options that take a yes or no answer, you can simply use the
173 letters "y" or "n", or type out the full words "Yes" or "No" if you
174 prefer. It is not case-sensitive. Typically the option with have a
175 default answer and you only need to specify one if you wish to
176 override it.
177 </dd>
178
179
180 </dl>
181 <p><br>
182
183 <h3>Command usage</h3>
184
185 <a name="border"></a>
186 <h2>border</h2>
187
188 Controls the border which is drawn around the map area.
189 <div class="code"><pre>
190 USAGE: <b>border</b> [y|n]
191 <b>color</b> color
192 <b>width</b> #
193 <b>end</b>
194 </pre></div>
195 The <b>color</b> may be either a standard GRASS color, a R:G:B triplet,
196 or "none". The width is specified in points, unless followed by an "i"
197 in which case it is measured in inches.
198 The default is a black border box of width 1 point.
199 <p>The border can be turned off completely with the
200 &quot;<code>border&nbsp;n</code>&quot; instruction. In this case
201 the <b>end</b> command should not be given as the
202 main command will be treated as a single line instruction.
203 <p>
204 This example would create a grey border 0.1&quot; wide.
205 <div class="code"><pre>
206 EXAMPLE:
207 <b>border</b>
208 <b>color</b> grey
209 <b>width</b> 0.1i
210 <b>end</b>
211 </pre></div>
212 <p>
213
214 <a name="colortable"></a>
215 <h2>colortable</h2>
216
217 Prints the color table legend for the raster map layer anywhere on the page.
218 <div class="code"><pre>
219 USAGE: <b>colortable</b> [y|n]
220 <b>where</b> x y
221 <b>raster</b> raster map
222 <b>range</b> minimum maximum
223 <b>width</b> table width
224 <b>height</b> table height (FP legend only)
225 <b>cols</b> table columns
226 <b>font</b> font name
227 <b>fontsize</b> font size
228 <b>color</b> text color
229 <b>nodata</b> [Y|n]
230 <b>tickbar</b> [y|N]
231 <b>discrete</b> [y|n]
232 <b>end</b>
233 </pre></div>
234
235 For a categorical (CELL) map the color table will create a legend displaying
236 the colors for each of a raster map's category values along with its
237 associated category label. For a floating point (FCELL or DCELL) map a
238 continuous gradient legend will be created.
239 <p>
240 If <b>raster</b> is omitted, the colortable defaults to the previously
241 registered raster layer.
242 <p>
243 The default location for the colortable is immediately below any other
244 map legend information, starting at the left margin.
245 The default text color is black.
246 <p>
247 Omitting the <b>colortable</b> instruction would result in no color table.
248 If the colortable is turned off with a &quot;<code>colortable&nbsp;N</code>&quot;
249 instruction the <b>end</b> command should not be given as the
250 main command will be treated as a single line instruction.
251 <p>
252 See also the <a href="#vlegend">vlegend</a> command for creating vector map
253 legends.
254
255 <h3>Categorical (CELL) Maps</h3>
256
257 Adding the <b>nodata N</b> instruction will prevent the "no data" box
258 from being drawn (category based legends only). If you have manually
259 added a "no data" label to the cats/ file it will be shown regardless.
260 <p>
261 <b>Note</b>: Be careful about asking for color tables for integer
262 raster map layers which have many categories, such as elevation.
263 This could result in the printing of an extremely long color table!
264 In this situation it is useful to use the <b>discrete N</b> instruction
265 to force a continuous color gradient legend.
266 <p>
267 Be aware that the color table only includes categories which
268 have a label. You can use the <em>r.category</em> module to add labels.
269
270 <h3>Floating point (FCELL and DCELL) Maps</h3>
271
272 The legend's <b>range</b> can be adjusted for floating point rasters, but if
273 set beyond the extent of the map's range be sure that you have set up color
274 rules with <em>r.colors</em> which cover this range.
275
276 If the map has been given a data-units label with <em>r.support</em>
277 then this label will be displayed.
278 <!-- bonus prize for code explorers: you can switch the label placement by
279 editing the label_posn variable in ps.map/ps_fclrtbl.c -->
280
281 For floating point legends <b>width</b> is width of color
282 band only. <b>height</b> is used only for floating point legend.
283 A horizontal gradient legend can be achieved by setting the legend
284 width greater than its height.
285
286 Adding the <b>tickbar Y</b> instruction will change the tick mark style
287 so that ticks are drawn across the color table instead of protruding out
288 to the right (floating point legends only).
289
290 Adding the <b>discrete Y</b> instruction will command the program to treat
291 the map as a categorical map. In this way the legend can be created with
292 discrete range bands instead of a continuous gradient. You must use the
293 <em>r.category</em> or <em>r.support</em> module to set up the range labels
294 first.
295
296 <br>
297 <p>This example would print a color table immediately below any other map legend
298 information, starting at the left margin, with 4 columns:
299 <div class="code"><pre>
300 EXAMPLE:
301 <b>colortable</b> y
302 <b>cols</b> 4
303 <b>width</b> 4
304 <b>end</b>
305 </pre></div>
306 <p>
307
308 <a name="comments"></a>
309 <h2>comments</h2>
310
311 Prints comments anywhere on the page.
312 <div class="code"><pre>
313 USAGE: <b>comments</b> commentfile
314 <b>where</b> x y
315 <b>font</b> font name
316 <b>fontsize</b> font size
317 <b>color</b> text color
318 <b>end</b>
319 </pre></div>
320 The default location is immediately below the last item item printed,
321 starting at the left margin. The default text color is black.
322 <p>If you wish to use parentheses spanning multiple lines you will need to
323 quote them with a backslash to prevent the PostScript interpreter from
324 getting confused. e.g. '<b><code>\(</code></b>' and '<b><code>\)</code></b>'
325
326 <p>
327 This example prints in blue
328 whatever is in the file <em>veg.comments</em> starting at
329 1.5 inches from the left edge of the page and 7.25 inches from the top of
330 the page, using a 15/72 inch Helvetica Bold font.
331 <div class="code"><pre>
332 EXAMPLE:
333 <b>raster</b> vegetation
334 <b>comments</b> veg.comments
335 <b>where</b> 1.5 7.25
336 <b>font</b> Helvetica Bold
337 <b>fontsize</b> 15
338 <b>color</b> blue
339 <b>end</b>
340 </pre></div>
341 Presumably, the file
342 <em>veg.comments</em>
343 contain comments
344 pertaining to the raster map layer <em>vegetation</em>,
345 such as "This map was created by classifying a LANDSAT TM image".
346 <p>
347
348 <a name="copies"></a>
349 <h2>copies</h2>
350
351 Specifies the number of copies to be printed.
352 <div class="code"><pre>
353 USAGE: <b>copies</b> n
354 </pre></div>
355 Each page will be printed n times.
356 <p>This instruction is identical to the <em>copies</em> command line parameter.
357 <p>
358
359 <a name="eps"></a>
360 <h2>eps</h2>
361
362 Places EPS (Encapsulated PostScript) pictures on the output map.
363 <div class="code"><pre>
364 USAGE: <b>eps</b> east north
365 <b>eps</b> x% y%
366 <b>epsfile</b> EPS file
367 <b>scale</b> #
368 <b>rotate</b> #
369 <b>masked</b> [y|n]
370 <b>end</b>
371 </pre></div>
372 The EPS picture location is entered in the main
373 instruction line by giving either the map
374 coordinates or by using percentages of the geographic region.
375 The EPS picture will be <i>centered</i> at the given position.
376 The user must specify full EPS file path <b>epsfile</b>.
377 The user may also specify the <b>scale</b> of the icon
378 (default is 1.0), the <b>rotate</b> i.e. rotation in degrees
379 (default is 0)
380 and whether the point is to be <b>masked</b>
381 by the current mask.
382 (See manual entry for <em><a href="r.mask.html">r.mask</a></em>
383 for more information on the mask.)
384 <p>
385 This example would place a EPS file ./epsf/logo.eps
386 at the point (E456000 N7890000). This picture would be
387 rotated 20 degrees clockwise, 3 times bigger than
388 in original file and would not be masked by the current mask.
389 <div class="code"><pre>
390 EXAMPLE:
391 <b>eps</b> 456000 7890000
392 <b>epsfile</b> ./epsf/logo.eps
393 <b>scale</b> 3
394 <b>rotate</b> 20
395 <b>masked</b> n
396 <b>end</b>
397 </pre></div>
398 Of course, multiple EPS pictures may be drawn with multiple
399 <em>eps</em>
400 instructions.
401 <p>
402
403 <a name="geogrid"></a>
404 <h2>geogrid</h2>
405
406 Overlays a geographic grid onto the output map.
407 <div class="code"><pre>
408 USAGE: <b>geogrid</b> spacing unit
409 <b>color</b> color
410 <b>numbers</b> # [color]
411 <b>font</b> font name
412 <b>fontsize</b> font size
413 <b>width</b> #
414 <b>end</b>
415 </pre></div>
416 The <b>spacing</b> and spacing unit of the geographic grid is given
417 on the main instruction line. The <b>spacing</b> unit is given as one of <b>d</b> for
418 degrees, <b>m</b> for minutes, and <b>s</b> for seconds.
419 The subsection instructions allow the user to specify
420 the <b>color</b> of the geographic grid lines,
421 whether coordinate <b>numbers</b> should appear
422 on the geographic grid lines, the <b>width</b>
423 of the lines (accepts decimal points [floating points]
424 as well as integers), and
425 if they should appear every grid line (1), every other grid line
426 (2), etc., and what color the numbers should be. The defaults are
427 black grid lines, unnumbered.
428
429 <p>
430 NOTE: The <b>geogrid</b> draws grid numbers on the east and south borders of the map.
431
432 <p>
433 This example would overlay a blue geographic grid with a spacing of 30 minutes
434 onto the output map. Alternate grid
435 lines would be numbered with yellow numbers.
436 <div class="code"><pre>
437 EXAMPLE:
438 <b>geogrid</b> 30 m
439 <b>color</b> blue
440 <b>numbers</b> 2 yellow
441 <b>end</b>
442 </pre></div>
443 <p>
444
445 <a name="greyrast"></a>
446 <h2>greyrast</h2>
447
448 Selects a raster map layer for output in shades of grey.
449 <div class="code"><pre>
450 USAGE: <b>greyrast</b> mapname
451 </pre></div>
452 For each
453 <em>ps.map</em>
454 run, only one raster map layer can be requested (using either the
455 <em>greyrast</em> or the <em>raster</em> instruction).
456 <p>
457
458 <a name="grid"></a>
459 <h2>grid</h2>
460
461 Overlays a coordinate grid onto the output map.
462 <div class="code"><pre>
463 USAGE: <b>grid</b> spacing
464 <b>color</b> color
465 <b>numbers</b> # [color]
466 <b>cross</b> cross size
467 <b>font</b> font name
468 <b>fontsize</b> font size
469 <b>width</b> #
470 <b>end</b>
471 </pre></div>
472 The <b>spacing</b> of the grid is given (in the geographic coordinate
473 system units) on the main instruction line. The subsection instructions
474 allow the user to specify
475 the <b>color</b> of the grid lines,
476 whether coordinate <b>numbers</b> should appear
477 on the grid lines, and if they
478 should appear every grid line (1), every other grid line
479 (2), etc., and what color the numbers should be.
480 The <b>cross</b> argument draws grid intersection crosses instead of grid lines,
481 with cross size given in geographic coordinate system units.
482 The defaults are black grid lines, unnumbered.
483
484 <p>
485 This example would overlay a green grid with a spacing of 10000 meters
486 (for a metered database, like UTM) onto the output map. Alternate grid
487 lines would be numbered with red numbers.
488 <div class="code"><pre>
489 EXAMPLE:
490 <b>grid</b> 10000
491 <b>color</b> green
492 <b>numbers</b> 2 red
493 <b>end</b>
494 </pre></div>
495 <p>
496
497 <a name="group"></a>
498 <h2>group</h2>
499
500 Selects an RGB imagery group for output.
501 <div class="code"><pre>
502 USAGE: <b>group</b> <em>groupname</em>
503 </pre></div>
504 This is similar to <em>raster</em>, except that it uses an imagery group
505 instead of a raster map layer. The group must contain three raster map
506 layers, comprising the red, green and blue bands of the image.
507 <p>
508
509 <a name="header"></a>
510 <h2>header</h2>
511
512 Prints the map header above the map.
513 <div class="code"><pre>
514 USAGE: <b>header</b>
515 <b>file</b> header file
516 <b>font</b> font name
517 <b>fontsize</b> font size
518 <b>color</b> text color
519 <b>end</b>
520 </pre></div>
521 If the <em>file</em> sub-instruction is absent the header will consist
522 of the map's title <!-- from hist file -->
523 and the project's description.<!-- PERMANENT/MYNAME -->
524 The text will be centered on the page above the map.
525 The default text color is black.
526 <p>If the <em>file</em> sub-instruction is given the header will consist
527 of the text in the text file specified, with some special formatting keys:
528
529 <ul>
530 <li><code>%%</code> - a literal %</li>
531 <li><code>%n</code> - ? newline ?</li>
532 <li><code>%_</code> - horizontal bar</li>
533 <li><code>%c</code> - "&lt;raster name&gt; in mapset &lt;mapset name&gt;"</li>
534 <li><code>%d</code> - today's date</li>
535 <li><code>%l</code> - project name</li>
536 <li><code>%L</code> - project's text description</li>
537 <li><code>%m</code> - mapset name</li>
538 <li><code>%u</code> - user name</li>
539 <li><code>%x</code> - mask info</li>
540 <li><code>%-</code> - advance to this character column number (see example below)</li>
541 </ul>
542
543 Example header file:
544 <div class="code"><pre>
545 %_
546 LOCATION: %-27l DATE: %d
547 MAPSET: %-27m USER: %u
548
549 RASTER MAP: %c
550 MASK: %x
551 %_
552 Produced by: US Army CERL, Champaign Illinois
553 Software: GRASS
554 %_
555 </pre></div>
556
557 <p>
558 This example prints (in red) whatever is in the file <em>soils.hdr</em> above
559 the map, using a 20/72 inch <code>Courier</code> font.
560 <div class="code"><pre>
561 EXAMPLE:
562 <b>header</b>
563 <b>file</b> soils.hdr
564 <b>font</b> Courier
565 <b>fontsize</b> 20
566 <b>color</b> red
567 <b>end</b>
568 </pre></div>
569 <p>
570
571 <a name="labels"></a>
572 <h2>labels</h2>
573
574 Selects a labels file for output (see manual entry for
575 <em>
576 <a href="v.label.html">v.label</a>
577 ).</em>
578 <div class="code"><pre>
579 USAGE: <b>labels</b> labelfile
580 <b>font</b> font name
581 <b>end</b>
582 </pre></div>
583 <p>NOTE: ps.map can read new option 'ROTATE:' from labels file, which
584 specifies counter clockwise rotation in degrees.
585 <p>This example would paint labels from the labels file called
586 <em>town.names</em>. Presumably, these labels would indicate the names of
587 towns on the map.
588 <div class="code"><pre>
589 EXAMPLE:
590 <b>labels</b> town.names
591 <b>end</b>
592 </pre></div>
593 <p>
594
595 <a name="line"></a>
596 <h2>line</h2>
597
598 Draws lines on the output map.
599 <div class="code"><pre>
600 USAGE: <b>line</b> east north east north
601 <b>line</b> x% y% x% y%
602 <b>color</b> color
603 <b>width</b> #
604 <b>masked</b> [y|n]
605 <b>end</b>
606 </pre></div>
607 The beginning and ending points of the line are entered on the main
608 instruction. These points can be defined either by map coordinates or
609 by using percentages of the geographic region.
610 The user may also specify line <b>color</b>, <b>width</b>
611 in points (1/72"; accepts decimal values as well as integers),
612 and if the line is to be <b>masked</b> by the current mask.
613 (See manual entry for <em><a href="r.mask.html">r.mask</a>
614 </em> for more information on the mask.)
615 The line <b>width</b> (if given) is measured in points; an <i>i</i>
616 directly following the number indicates that the width is given in
617 inches instead.
618 <p>
619 This example would draw a yellow line from the point x=10% y=80%
620 to the point x=30% y=70%.
621 This line would be 2 points wide (2/72") and would appear even if
622 there is a mask.
623 <div class="code"><pre>
624 EXAMPLE:
625 <b>line</b> 10% 80% 30% 70%
626 <b>color</b> yellow
627 <b>width</b> 2
628 <b>masked</b> n
629 <b>end</b>
630 </pre></div>
631 Of course, multiple lines may be drawn with multiple
632 <em>line</em>
633 instructions.
634 <p>
635
636 <a name="mapinfo"></a>
637 <h2>mapinfo</h2>
638
639 Prints the portion of the map legend containing the scale, grid and
640 region information, on or below the map.
641 <div class="code"><pre>
642 USAGE: <b>mapinfo</b>
643 <b>where</b> x y
644 <b>font</b> font name
645 <b>fontsize</b> font size
646 <b>color</b> text color
647 <b>background</b> box color|none
648 <b>border</b> color|none
649 <b>end</b>
650 </pre></div>
651 The default location is immediately below the map,
652 starting at the left edge of the map.
653 The default text color is black.
654 The default background box color is white.
655 <p><em>border</em> will draw a border around the legend using the specified color.
656 (see <a href="#NAMED_COLORS">NAMED COLORS</a>)
657 <p>
658 This example prints (in brown) the scale, grid and region information
659 immediately below the map and starting 1.5 inches from the left edge
660 of the page, using a 12/72 inch <code>Courier</code> font.
661
662 <div class="code"><pre>
663 EXAMPLE:
664 <b>mapinfo</b>
665 <b>where</b> 1.5 0
666 <b>font</b> Courier
667 <b>fontsize</b> 12
668 <b>color</b> brown
669 <b>end</b>
670 </pre></div>
671 <p>
672
673 <a name="maploc"></a>
674 <h2>maploc</h2>
675
676 Positions the map on the page.
677 <div class="code"><pre>
678 USAGE: <b>maploc</b> x y [width height]
679 </pre></div>
680 The upper left corner of the map will be positioned <em>x</em> inches from
681 the left edge of the page and <em>y</em> inches from the top of the page.
682 If <em>width</em> and <em>height</em> (in inches) are present, the map will be
683 rescaled, if necessary, to fit.
684
685 <p>
686 This example positions the upper left corner of the map 2.0 inches from
687 the left edge and 3.5 inches from the top edge of the map.
688 <div class="code"><pre>
689 EXAMPLE:
690 <b>maploc</b> 2.0 3.5
691 </pre></div>
692 <p>
693
694 <a name="maskcolor"></a>
695 <h2>maskcolor</h2>
696
697 Color to be used for mask.
698 <div class="code"><pre>
699 USAGE: <b>maskcolor</b> color
700 </pre></div>
701
702
703 <a name="outline"></a>
704 <h2>outline</h2>
705
706 Outlines the areas of a raster map layer with a specified color.
707 <div class="code"><pre>
708 USAGE: <b>outline</b>
709 <b>color</b> color
710 <b>width</b> width of line in points
711 <b>end</b>
712 </pre></div>
713 Distinct areas of the raster map will be separated from each other visually
714 by drawing a border (or outline) in the specified
715 <b>color</b>
716 (default: black). For
717 <b>width</b>
718 the program accepts decimal points [floating points] as well as integers.
719 Note: it is
720 important the user enter the instruction <b>end</b> even if a color is not
721 chosen.
722 (It is hoped that in the future the outline of a different raster map
723 layer other than the one currently being painted may be placed on the map.)
724
725 <p>
726 This example would outline the category areas of the
727 <em>soils</em>
728 raster map layer
729 in grey.
730 <div class="code"><pre>
731 EXAMPLE:
732 <b>raster</b> soils
733 <b>outline</b>
734 <b>color</b> grey
735 <b>width</b> 2
736 <b>end</b>
737 </pre></div>
738 <p>
739
740 <a name="paper"></a>
741 <h2>paper</h2>
742
743 Specifies paper size and margins.
744 <div class="code"><pre>
745 USAGE: <b>paper</b> paper name
746 <b>height</b> #
747 <b>width</b> #
748 <b>left</b> #
749 <b>right</b> #
750 <b>bottom</b> #
751 <b>top</b> #
752 <b>end</b>
753 </pre></div>
754 <b>paper</b> may select predefined paper name
755 (a4,a3,a2,a1,a0,us-legal,us-letter,us-tabloid).
756 Default paper size is a4. The measures are defined in <em>inches</em>.
757 <b>left</b>, <b>right</b>, <b>bottom</b> and <b>top</b> are paper margins.
758 If the plot is rotated with the <b>-r</b> command line flag, measures
759 are applied to the <em>rotated</em> page.
760 <p>
761 <div class="code"><pre>
762 EXAMPLE:
763 <b>paper</b> a3
764 <b>end</b>
765 </pre></div>
766 <p>
767 <div class="code"><pre>
768 EXAMPLE:
769 <b>paper</b>
770 <b>width</b> 10
771 <b>height</b> 10
772 <b>left</b> 2
773 <b>right</b> 2
774 <b>bottom</b> 2
775 <b>top</b> 2
776 <b>end</b>
777 </pre></div>
778 <p>
779
780 <a name="point"></a>
781 <h2>point</h2>
782
783 Places additional points or icons on the output map.
784 <div class="code"><pre>
785 USAGE: <b>point</b> east north
786 <b>point</b> x% y%
787 <b>color</b> color
788 <b>fcolor</b> color
789 <b>symbol</b> symbol group/name
790 <b>size</b> #
791 <b>width</b> #
792 <b>rotate</b> #
793 <b>masked</b> [y|n]
794 <b>end</b>
795 </pre></div>
796 The point location is entered in the main instruction line by giving either
797 the map coordinates or by using percentages of the geographic region.
798 The user may also specify the point <b>color</b>,
799 the <b>size</b> of symbol in points,
800 the rotation angle (in degrees CCW),
801 and whether the point is to be <b>masked</b> by the current mask.
802 (See manual entry for <em> <a href="r.mask.html">r.mask</a>
803 </em> for more information on the mask.)
804 The symbol line <b>width</b> (if given) is measured in points; an <i>i</i>
805 directly following the number indicates that the width is given in inches
806 instead. If a <b>width</b> is not given it will be set proportional to the
807 symbol size.
808 <p>This example would place a purple diamond (from icon file
809 <em>diamond</em>) at the point (E456000 N7890000). This diamond would be the
810 the size of a 15 points and would not be masked by the current mask.
811 <div class="code"><pre>
812 EXAMPLE:
813 <b>point</b> 456000 7890000
814 <b>fcolor</b> purple
815 <b>color</b> black
816 <b>symbol</b> basic/diamond
817 <b>size</b> 15
818 <b>masked</b> n
819 <b>end</b>
820 </pre></div>
821 Of course, multiple points may be drawn with multiple
822 <em>point</em>
823 instructions.
824 <p>
825
826 <a name="psfile"></a>
827 <h2>psfile</h2>
828
829 Copies a file containing PostScript commands into the output file.
830
831 <p>
832 <b>Note:</b>
833 <em>ps.map</em>
834 will not search for this file. The user must be in the
835 correct directory or specify the full path on the <b>psfile</b> instruction.
836 (Note to /bin/csh users: ~ won't work with this instruction).
837 <div class="code"><pre>
838 USAGE: <b>psfile</b> filename
839 </pre></div>
840 This example copies the file "logo.ps" into the output file.
841 <div class="code"><pre>
842 EXAMPLE:
843 <b>psfile</b> logo.ps
844 </pre></div>
845 <p>
846
847 <a name="raster"></a>
848 <h2>raster</h2>
849
850 Selects a raster map layer for output.
851 <div class="code"><pre>
852 USAGE: <b>raster</b> mapname
853 </pre></div>
854 For each <em>ps.map</em> run, only one raster map layer (or set
855 of layers or imagery group; see below) can be requested. If no
856 raster map layer is requested, a completely white map will be
857 produced. It can be useful to select no raster map layer in
858 order to provide a white background for vector maps.
859 <p>Note that an imagery group selected with the <em>group</em>
860 option, or a set of three raster layers selected with the
861 <em>rgb</em> option, count as a raster map layer for the
862 purposes of the preceding paragraph.
863 <p>The PostScript file's internal title will be set to the raster map's
864 title, which in turn may be set with the <em>r.support</em> module.
865 <p>This example would paint a map of the raster map layer <em>soils</em>.
866
867 <div class="code"><pre>
868 EXAMPLE:
869 <b>raster</b> soils
870 </pre></div>
871 <p>
872
873 <a name="read"></a>
874 <h2>read</h2>
875
876 Provides <em>ps.map</em> with a previously prepared input stream.
877 <div class="code"><pre>
878 USAGE: <b>read</b> previously prepared UNIX file
879 </pre></div>
880 Mapping instructions can be placed into a file and read into
881 <em>ps.map.</em>
882
883 <p>
884 <b>Note:</b>
885 <em>ps.map</em>
886 will not search for this file. The user must be in the
887 correct directory or specify the full path on the <b>read</b> instruction.
888 (Note to /bin/csh users: ~ won't work with this instruction).
889
890 <p>
891 This example reads the UNIX file <em>pmap.roads</em> into <em>ps.map</em>.
892 This file may contain all the <em>ps.map</em> instructions for placing
893 the vector map layer <em>roads</em> onto the output map.
894 <div class="code"><pre>
895 EXAMPLE:
896 <b>read</b> pmap.roads
897 </pre></div>
898 The user may have created this file because this vector map layer
899 is particularly useful for many <em>ps.map</em>
900 outputs. By using the <b>read</b> option, the user need not enter all the input
901 for the <b>vector</b> instruction, but simply <b>read</b> the previously prepared
902 file with the correct instructions.
903 <p>
904
905 <a name="rectangle"></a>
906 <h2>rectangle</h2>
907
908 Draws rectangle on the output map.
909 <div class="code"><pre>
910 USAGE: <b>rectangle</b> east north east north
911 <b>rectangle</b> x% y% x% y%
912 <b>color</b> color
913 <b>fcolor</b> fill color
914 <b>width</b> #
915 <b>masked</b> [y|n]
916 <b>end</b>
917 </pre></div>
918 The two corners of the rectangle are entered on the main
919 instruction. These points can be defined either by map coordinates or
920 by using percentages of the geographic region.
921 The user may also specify line
922 <b>color</b>, fill color <b>fcolor</b>, <b>width</b>
923 in points (accepts decimal points [floating points] as well as integers),
924 and if the rectangle is to be <b>masked</b> by the current mask.
925 (See manual entry for <em><a href="r.mask.html">r.mask</a></em>
926 for more information on the mask.)
927 The border line <b>width</b> (if given) is measured in points; an <i>i</i>
928 directly following the number indicates that the width is given in inches
929 instead.
930 <br>
931 Multiple rectangles may be drawn by using multiple <em>rectangle</em> instructions.
932 <p>
933 This example would draw a yellow rectangle filled by green from the point x=10% y=80%
934 to the point x=30% y=70%.
935 The border line would be 1/16" wide and would appear even if there is a mask.
936 <div class="code"><pre>
937 EXAMPLE:
938 <b>rectangle</b> 10% 80% 30% 70%
939 <b>color</b> yellow
940 <b>fcolor</b> green
941 <b>width</b> 0.0625i
942 <b>masked</b> n
943 <b>end</b>
944 </pre></div>
945 <p>
946
947 <a name="region"></a>
948 <h2>region</h2>
949
950 Places the outline of a smaller geographic region
951 on the output.
952 <div class="code"><pre>
953 USAGE: <b>region</b> regionfile
954 <b>color</b> color
955 <b>width</b> #
956 <b>end</b>
957 </pre></div>
958 Geographic region settings are created and saved using <em> the
959 <a href="g.region.html">g.region</a></em> module.
960 The <em>ps.map</em> <em>region</em> option can be used to show an outline of
961 a smaller region which was printed on a separate run of <em>ps.map</em>
962 on other user-created maps.
963 <p>The user can specify the <b>color</b>
964 and the <b>width</b> in point units (accepts decimal points
965 [floating points] as well as integers) of the outline.
966 The default is a black border of one point width (1/72").
967 <p>This example would place a white outline, 2 points wide, of the
968 geographic region called <em>fire.zones</em> onto the output map.
969 This geographic region would have been created and saved using
970 <em><a href="g.region.html">g.region</a></em>.
971 <div class="code"><pre>
972 EXAMPLE:
973 <b>region</b> fire.zones
974 <b>color</b> white
975 <b>width</b> 2
976 <b>end</b>
977 </pre></div>
978 <p>
979
980 <a name="rgb"></a>
981 <h2>rgb</h2>
982
983 Selects three raster map layers for output as an RGB color image.
984 <div class="code"><pre>
985 USAGE: <b>rgb</b> <em>red</em> <em>green</em> <em>blue</em>
986 </pre></div>
987 This is similar to <em>raster</em>, except that it uses three
988 raster map layers instead of a single layer. The three layers
989 are composed to form a color image, similar to <em>d.rgb</em>.
990 <p>
991 For each layer, only one of the components of the layer's color
992 table is used: the red component for the red layer, and so on.
993 This will give the desired result if all of the layers have a
994 grey-scale color table, or if each layer's color table uses the
995 hue appropriate to the layer.
996 <p>
997
998 <a name="scale"></a>
999 <h2>scale</h2>
1000
1001 Selects a scale for the output map.
1002 <div class="code"><pre>
1003 USAGE: <b>scale</b> <em>scale</em>
1004 </pre></div>
1005 The scale can be selected either as:
1006 <dl>
1007 <dt>
1008 <dd>a relative ratio, e.g. 1:25000;
1009 <dt>
1010 <dd>an absolute width of the printed map, e.g. 10 inches;
1011 <dt>
1012 <dd>the number of printed paper panels, e.g. 3 panels
1013 <em>.I</em>
1014 (at the present time, only 1 panel is supported);
1015 <dt>
1016 <dd>the number of miles per inch, e.g. 1 inch equals 4 miles.
1017 </dd>
1018 </dl>
1019 <p>
1020 This example would set the scale of the map to 1 unit = 25000
1021 units.
1022 <div class="code"><pre>
1023 EXAMPLE:
1024 <b>scale</b> 1:25000
1025 </pre></div>
1026 <p>
1027
1028 <a name="scalebar"></a>
1029 <h2>scalebar</h2>
1030
1031 Draws a scalebar on the map.
1032 <div class="code"><pre>
1033 USAGE: <b>scalebar</b> [f|s]
1034 <b>where</b> x y
1035 <b>length</b> overall distance in map units
1036 <b>units</b> [auto|meters|kilometers|feet|miles|nautmiles]
1037 <b>height</b> scale height in inches
1038 <b>segment</b> number of segments
1039 <b>numbers</b> #
1040 <b>fontsize</b> font size
1041 <b>background</b> [Y|n]
1042 <b>end</b>
1043 </pre></div>
1044 Draw one of two types of scale bar.
1045 Fancy (f) draws alternating black and white scale boxes.
1046 Simple (s) draws a plain line scale. The default type is fancy.
1047
1048 The subsection instructions allow the user to set <b>where</b> the scalebar
1049 is placed, the <b>length</b> of the scalebar (in geographic coordinate
1050 system units, or those given by <b>units</b>),
1051 <!-- bonus prize for code explorers: you can use km and nm abbreviations
1052 for kilometers and nautmiles units -->
1053 the <b>height</b> of the scalebar in inches, and the number of
1054 <b>segments</b> (or tics for simple). The <b>number</b> of annotations
1055 numbers every n-th segment.
1056
1057 The <b>background</b> command can turn off the background box for the text.
1058 <p>The scalebar <b>length</b> is the only required argument. The defaults are a
1059 fancy scalebar with 4 segments, each segment labeled, and a height of 0.1
1060 inches. The default location is 2 inches from the top of the page and
1061 halfway across.
1062 <p>NOTE: The scalebar is centered on the location given.
1063 <p>This example draws a simple scalebar 1000 meters (for a metered database,
1064 like UTM) long, with tics every 200 meters, labeled every second tic.
1065 The scalebar is drawn 5 inches from the top and 4 inches from the left
1066 and is 0.25 inches high.
1067 <div class="code"><pre>
1068 EXAMPLE:
1069 <b>scalebar</b> s
1070 <b>where</b> 4 5
1071 <b>length</b> 1000
1072 <b>height</b> 0.25
1073 <b>segment</b> 5
1074 <b>numbers</b> 2
1075 <b>end</b>
1076 </pre></div>
1077
1078
1079 <a name="setcolor"></a>
1080 <h2>setcolor</h2>
1081
1082 Overrides the color assigned to one or more categories
1083 of the raster map layer.
1084 <div class="code"><pre>
1085 USAGE: <b>setcolor</b> cat(s) color
1086 </pre></div>
1087 This example would set the color for categories 2,5 and 8 of the raster
1088 map layer <em>watersheds</em> to white and category 10 to green.
1089 (<b>NOTE</b>: no spaces are inserted between the category values.)
1090 <div class="code"><pre>
1091 EXAMPLE:
1092 <b>raster</b> watersheds
1093 <b>setcolor</b> 2,5,8 white
1094 <b>setcolor</b> 10 green
1095 </pre></div>
1096 Of course, <em>setcolor</em>
1097 can be requested more than once to override the default color for additional
1098 categories. More than one category can be changed for each request by listing
1099 all the category values separated by commas (but with no spaces). Also ranges
1100 can be included, for example "1,2,6-10,12". Colors for "<code>null</code>" and the
1101 "<code>default</code>" (i.e. out-of-range) color may also be reassigned.
1102 <p>
1103
1104 <a name="text"></a>
1105 <h2>text</h2>
1106
1107 Places text on the map.
1108 <div class="code"><pre>
1109 USAGE: <b>text</b> east north text
1110 <b>text</b> x% y% text
1111 <b>font</b> fontname
1112 <b>color</b> color|none
1113 <b>width</b> #
1114 <b>hcolor</b> color|none
1115 <b>hwidth</b> #
1116 <b>background</b> color|none
1117 <b>border</b> color|none
1118 <b>fontsize</b> font size
1119 <b>size</b> #
1120 <b>ref</b> reference point
1121 <b>rotate</b> degrees CCW
1122 <b>xoffset</b> #
1123 <b>yoffset</b> #
1124 <b>opaque</b> [y|n]
1125 <b>end</b>
1126 </pre></div>
1127 The user specifies where the text will be placed by
1128 providing map coordinates or percentages of the geographic region.
1129 The text follows these coordinates on the same instruction line.
1130 More than one line of text can be specified by notating the end of a line with
1131 <b>\n</b>
1132 (e.g. USA<b>\n</b>CERL).
1133 <p>The user can then specify various text features:
1134 <p><b>font:</b>
1135 the PostScript font. Common possibilities are listed at the start of this
1136 help page. The default is <code>Helvetica</code>.
1137 <p><b>color</b>
1138 (see <a href="#NAMED_COLORS">NAMED COLORS</a>);
1139 <p><b>width</b>
1140 of the lines used to draw the text to make thicker letters
1141 (accepts decimal points [floating points] as well as integers);
1142 <p><b>size</b> and <b>fontsize.</b>&nbsp;
1143 <b>size</b> gives the vertical height of the letters in meters on the
1144 ground (text size will grow or shrink depending on the scale at which
1145 the map is painted). Alternatively <b>fontsize</b> can set the font
1146 size directly. If neither <b>size</b> or <b>fontsize</b> is given, a
1147 default font size of 10 will be used;
1148 <p>the highlight color (<b>hcolor</b>) and
1149 the width of the highlight color (<b>hwidth</b>);
1150 <p>the text-enclosing-box <b>background</b> color;
1151 the text box <b>border</b> color;
1152 <p><b>ref.</b>
1153 This reference point specifies the text handle - what
1154 part of the text should be placed on the location specified by the map
1155 coordinates. Reference points can refer to:
1156 [lower|upper|center] [left|right|center] of the text to be printed;
1157 The default is center center, i.e. the text is centered on the reference point.
1158 <p><b>rotate</b>
1159 sets the text rotation angle, measured in degrees counter-clockwise.
1160 <p><b>yoffset</b>,
1161 which provides finer placement of text by shifting the
1162 text a vertical distance in points (1/72") from the specified north.
1163 The vertical offset will shift the location to the south if positive,
1164 north if negative;
1165 <p><b>xoffset</b>,
1166 which shifts the text a horizontal distance in points from
1167 the specified east The horizontal offset will shift the location east if
1168 positive, west if negative;
1169 <p><b>opaque</b>,
1170 whether or not the text should be <b>opaque</b> to vectors. Entering <b>no</b>
1171 to the opaque option will allow the user to see any vectors which go
1172 through the text's background box. Otherwise, they will end at the box's edge.
1173 <p><br>
1174 The following example would place the text <em>SPEARFISH LAND COVER</em>
1175 at the coordinates E650000 N7365000. The text would be a total of
1176 3 points wide (2 pixels of red text and 1 pixel black highlight), have a white
1177 background enclosed in a red box, and be 500 meters in size. The lower right
1178 corner of the text would be centered over the coordinates provided. All
1179 vectors on the map would stop at the border of this text.
1180 <div class="code"><pre>
1181 EXAMPLE:
1182 <b>text</b> 650000 7365000 SPEARFISH LAND COVER
1183 <b>font</b> romand
1184 <b>color</b> red
1185 <b>width</b> 2
1186 <b>hcolor</b> black
1187 <b>hwidth</b> 1
1188 <b>background</b> white
1189 <b>border</b> red
1190 <b>size</b> 500
1191 <b>ref</b> lower left
1192 <b>opaque</b> y
1193 <b>end</b>
1194 </pre></div>
1195 <p>
1196
1197 <a name="vareas"></a>
1198 <h2>vareas</h2>
1199
1200 Selects a vector map layer for output and plots areas.
1201 <div class="code"><pre>
1202 USAGE: <b>vareas</b> vectormap
1203 <b>layer</b> # (layer number used with cats/where option)
1204 <b>cats</b> list of categories (e.g. 1,3,5-7)
1205 <b>where</b> SQL where statement
1206 <b>masked</b> [y|n]
1207 <b>color</b> color
1208 <b>fcolor</b> color
1209 <b>rgbcolumn</b> column
1210 <b>width</b> #
1211 <b>label</b> label to use in legend
1212 <b>lpos</b> position in legend
1213 <b>pat</b> pattern file
1214 <b>pwidth</b> #
1215 <b>scale</b> #
1216 <b>end</b>
1217 </pre></div>
1218 The user can specify:
1219 <p><b>color</b> - color of the vector lines or area boundaries;
1220 <p><b>fcolor</b> - the area fill color;
1221 <p><b>rgbcolumn</b> - name of color definition column used for the area fill color;
1222 <p><b>width</b> - width of the vectors lines or area boundaries in points
1223 (accepts decimal points [floating points] as well as integers);
1224 <p><b>masked</b> - whether or not the raster map layer is to be masked
1225 by the current mask;
1226 (see manual entry <em><a href="r.mask.html">r.mask</a></em>
1227 for more information on the mask)
1228 <p><b>cats</b> - which categories should be plotted (default is all);
1229 <p><b>where</b> - select features using a SQL where statement.
1230 For example: <code>vlastnik = 'Cimrman'</code>;
1231 <p><b>label</b> - for description in <a href="#vlegend">vlegend</a>.
1232 Default is: map(mapset);
1233 <p><b>lpos</b> - position vector is plotted in legend. If lpos is
1234 0 then this vector is omitted in legend. If more vectors used the
1235 same lpos then their symbols in legend are merged and label for
1236 first vector is used.
1237 <p><b>pat</b> - full path to pattern file. The pattern file contains header and
1238 simple PostScript commands. It is similar to EPS but more limited, meaning that
1239 while each pattern file is a true EPS file, most EPS files are not useful as pattern
1240 files because they contain restricted commands. Color <!-- and width --> of patterns
1241 are set by <b>fcolor</b> (red, green, ..., none, R:G:B)<!-- no? and <b>width</b>
1242 until overwritten in the pattern file -->. Color of the boundaries remain set
1243 by the <b>color</b> instruction.
1244 Pattern may be scaled with the <b>scale</b> command. Several standard hatching
1245 patterns are provided in <code>$GISBASE/etc/paint/patterns/</code>.
1246 Demonstrative images can be found on the
1247 <a href="https://grasswiki.osgeo.org/wiki/AreaFillPatterns">GRASS Wiki site</a>.
1248
1249 You can also create your own custom pattern files in a text editor.
1250 Example of pattern file:
1251
1252 <div class="code"><pre>
1253 %!PS-Adobe-2.0 EPSF-1.2
1254 %%BoundingBox: 0 0 10 10
1255 newpath
1256 5 0 moveto
1257 5 10 lineto
1258 stroke
1259 </pre></div>
1260
1261
1262 <p><b>scale</b> - pattern scale
1263 <p><b>pwidth</b> - pattern line width, width is used by pattern until the width is overwritten
1264 in pattern file.
1265 <p>
1266 <div class="code"><pre>
1267 EXAMPLE:
1268 <b>vareas</b> forest
1269 <b>color</b> blue
1270 <b>width</b> 1
1271 <b>masked</b> y
1272 <b>cats</b> 2,5-7
1273 <b>end</b>
1274 </pre></div>
1275 <p>
1276
1277 <a name="vlines"></a>
1278 <h2>vlines</h2>
1279
1280 Selects a vector map layer for output and plots lines.
1281 <div class="code"><pre>
1282 USAGE: <b>vlines</b> vectormap
1283 <b>type</b> line and/or boundary
1284 <b>layer</b> # (layer number used with cats/where option)
1285 <b>cats</b> list of categories (e.g. 1,3,5-7)
1286 <b>where</b> SQL where statement like: vlastnik = 'Cimrman'
1287 <b>masked</b> [y|n]
1288 <b>color</b> color
1289 <b>rgbcolumn</b> column
1290 <b>width</b> #
1291 <b>cwidth</b> #
1292 <b>hcolor</b> color
1293 <b>hwidth</b> #
1294 <b>offset</b> #
1295 <b>coffset</b> #
1296 <b>ref</b> left|right
1297 <b>style</b> 00001111
1298 <b>linecap</b> style
1299 <b>label</b> label
1300 <b>lpos</b> #
1301 <b>end</b>
1302 </pre></div>
1303 The user can specify:
1304 <p><b>type</b> - the default is lines only;
1305 <p><b>color</b> - color of the vector lines or area boundaries;
1306 <p><b>rgbcolumn</b> - name of color definition column used for the vector lines
1307 or area boundaries;
1308 <p><b>width</b> - width of the vectors lines or area boundaries in points
1309 (accepts decimal points [floating points] as well as integers);
1310 <p><b>cwidth</b> - width of the vectors lines. If cwidth is used then
1311 width of line is equal to cwidth * category value and width is
1312 used in legend;
1313 <p><b>hcolor</b> - the highlight color for the vector lines;
1314 <p><b>hwidth</b> - the width of the highlight color in points;
1315 <p><b>offset</b> (experimental) - offset for the vectors lines in points (1/72")
1316 for plotting parallel lines in distance equal to offset (accepts positive or
1317 negative decimal points). Useful to print streets with several parallel lanes;
1318 <p><b>coffset</b> (experimental) - offset for the vectors lines. If coffset
1319 is used then offset of line is equal to coffset * category value and offset
1320 is used in legend;
1321 <p><b>ref</b> (experimental) - line justification.
1322 <p><b>masked</b> - whether or not the raster map layer is to be masked
1323 by the current mask;
1324 (see manual entry <em><a href="r.mask.html">r.mask</a></em>
1325 for more information on the mask);
1326 <p><b>style</b> - the line style allows the vectors to be dashed in different
1327 patterns. This is done by either typing "solid", "dashed", "dotted", or
1328 "dashdotted", or as a series of 0's and 1's in a desired sequence or pattern.
1329 The first block of repeated zeros or ones represents "draw", the second
1330 block represents "blank".
1331 An even number of blocks will repeat the pattern, an odd number of blocks
1332 will alternate the pattern.
1333 The default is "solid";
1334 <p><b>linecap</b> - the linecap specifies the look of the ends of the line,
1335 or the end of the dashes in a dashed line. The parameters are:
1336 'butt' for butt caps (default), 'round' for round caps and 'extended_butt'
1337 for extended butt caps. The shape of the round and the extended butt caps
1338 is related to the line thickness: for round butts the radius is half the
1339 linewidth, while for extended butt the line will extend for half the linewidth.
1340 <p><b>cats</b> - which categories should be plotted (default is all);
1341 <p><b>label</b> - for description in <a href="#vlegend">vlegend</a>.
1342 Default is: map(mapset);
1343 <p><b>lpos</b> - position vector is plotted in legend. If lpos is
1344 0 then this vector is omitted in legend. If more vectors used the
1345 same lpos then their symbols in legend are merged and label for
1346 first vector is used.
1347 <p>
1348 <div class="code"><pre>
1349 EXAMPLE:
1350 <b>vlines</b> streams
1351 <b>color</b> blue
1352 <b>width</b> 2
1353 <b>hcolor</b> white
1354 <b>hwidth</b> 1
1355 <b>masked</b> y
1356 <b>cats</b> 2
1357 <b>label</b> Streams - category 2
1358 <b>end</b>
1359 </pre></div>
1360 <p>
1361
1362 <a name="vpoints"></a>
1363 <h2>vpoints</h2>
1364
1365 Selects vector point data to be placed on the output map
1366 <div class="code"><pre>
1367 USAGE: <b>vpoints</b> vectormap
1368 <b>type</b> point and/or centroid
1369 <b>layer</b> # (layer number used with cats/where/sizecol options)
1370 <b>cats</b> list of categories (e.g. 1,3,5-7)
1371 <b>where</b> SQL where statement like: vlastnik = 'Cimrman'
1372 <b>masked</b> [y|n]
1373 <b>color</b> color
1374 <b>fcolor</b> color
1375 <b>rgbcolumn</b> column
1376 <b>width</b> #
1377 <b>eps</b> epsfile
1378 <b>symbol</b> symbol group/name
1379 <b>size</b> #
1380 <b>sizecolumn</b> attribute column used for symbol sizing
1381 <b>scale</b> scaling factor for sizecolumn values
1382 <b>rotate</b> #
1383 <b>rotatecolumn</b> column
1384 <b>label</b> legend label
1385 <b>lpos</b> position in legend
1386 <b>end</b>
1387 </pre></div>
1388 The user may specify the
1389 the <b>color</b> of the sites (see section on <a href="#NAMED_COLORS">NAMED COLORS</a>);
1390 either the GRASS <b>symbol</b> or
1391 the <b>eps</b> Encapsulated Postscript file to be used to represent the presence of a site
1392 (if '<b>$</b>' is used in the EPS file path it will be replaced by category number);
1393 and <b>rotate</b> (in degrees) for counter-clockwise rotation.
1394 <br>
1395 The size of the icon (number of times larger than the size it is in
1396 the icon file) is typically given by the <b>size</b> option. Alternatively
1397 the size of the symbol or EPS graphic can be taken from an attribute column
1398 by using the <b>sizecolumn</b> command. The value given by <b>sizecolumn</b> may be
1399 scaled by using the <b>scale</b> factor setting (default scaling is 1.0).
1400 In a similar manner symbol color can be read from <b>rgbcolumn</b>
1401 and the rotation angle read from <b>rotatecolumn</b>.
1402
1403 <div class="code"><pre>
1404 EXAMPLE:
1405 <b>vpoints</b> windmills
1406 <b>color</b> blue
1407 <b>symbol</b> mills/windmill
1408 <b>size</b> 10
1409 <b>end</b>
1410 </pre></div>
1411 <p>
1412 <a name="vlegend"></a>
1413 <h2>vlegend</h2>
1414
1415 Prints the portion of the map legend containing the
1416 vector information, on or below the map.
1417
1418 <div class="code"><pre>
1419 USAGE: <b>vlegend</b>
1420 <b>where</b> x y
1421 <b>font</b> font name
1422 <b>fontsize</b> font size
1423 <b>width</b> width of color symbol
1424 <b>cols</b> number of columns to print
1425 <b>span</b> column separation
1426 <b>border</b> color|none
1427 <b>end</b>
1428 </pre></div>
1429 The default location is immediately below the legend containing the
1430 scale, grid and region information, starting at the left edge of the map.
1431 If the <em>where</em> instruction is present and <em>y</em> is less than or
1432 equal to zero, the vector legend will be positioned immediately below
1433 the map, starting <em>x</em> inches from the left edge of the page.
1434 <p><em>width</em> is the width in inches of the color symbol (for lines)
1435 in front of the legend text. The default is 1/24 * fontsize inches.
1436 <p><em>cols</em> is the number of columns to split the legend into. The
1437 default is one column. The maximum number of columns is 10, or equal
1438 to the number of legend entries if there are less than 10 entries.
1439 <p><em>span</em> is the column separation distance between the left edges of
1440 two columns in a multicolumn legend. It is given in inches.
1441 The default is automatic scaling based on the left margin and the right
1442 hand side of the map box.
1443 <p><em>border</em> will draw a border around the legend using the specified color.
1444 (see <a href="#NAMED_COLORS">NAMED COLORS</a>)
1445 <p>Alternatively, the user can create a custom legend by using the
1446 <a href="#rectangle">rectangle</a>, <a href="#point">point</a>, and
1447 <a href="#text">text</a> instructions.
1448 <p>See also the <a href="#colortable">colortable</a> command for creating
1449 raster map legends.
1450 <p>This example prints the vector legend
1451 immediately below the map and starting 4.5 inches from the left edge
1452 of the page, using a 12/72 inch Helvetica font.
1453
1454 <div class="code"><pre>
1455 EXAMPLE:
1456 <b>vlegend</b>
1457 <b>where</b> 4.5 0
1458 <b>font</b> Courier
1459 <b>fontsize</b> 12
1460 <b>end</b>
1461 </pre></div>
1462 <p>
1463
1464 <a name="end"></a>
1465 <h2>end</h2>
1466
1467 Terminates input and begin painting the map.
1468
1469 <div class="code"><pre>
1470 USAGE: <b>end</b>
1471 </pre></div>
1472 <br>
1473 <p>
1474
1475 <h2>EXAMPLES</h2>
1476
1477
1478 The following are examples of <em>ps.map</em> script files.
1479 <p><h3>Simple example</h3>
1480 The file has been named <em>simple_map.txt</em>:
1481
1482 <div class="code"><pre>
1483 <i># this ps.map example draws a map of Wake county, NC</i>
1484 <b>raster</b> elevation
1485 <b>vlines</b> roadsmajor
1486 <b>color</b> 30:144:255
1487 <b>width</b> 2
1488 <b>end</b>
1489 <b>text</b> 50% 105% Wake County Terrain and Roads
1490 <b>size</b> 550
1491 <b>end</b>
1492 <b>end</b>
1493 </pre></div>
1494
1495 Generate map as Postsript file:
1496 <div class="code"><pre>
1497 ps.map input=simple_map.txt output=simple_map.ps
1498 </pre></div>
1499
1500 <center>
1501 <img src="ps_map_basic.png">
1502 <p><em>Figure: Result of for the a simple Wake county terrain and roads example</em></p>
1503 </center>
1504
1505 <h3>More complicated example</h3>
1506
1507 The following is content of a file named <em>elevation_map.txt</em>:
1508
1509 <!--
1510 regular expression for syntax highlight
1511 (replace spaces around bs by gt and lt)
1512 ^( *)([a-z]+)([ ]|$)
1513 \1 b \2 /b \3
1514 -->
1515
1516 <div class="code"><pre>
1517 <i># this ps.map example draws a map of Wake county, NC</i>
1518 <b>raster</b> elevation
1519 <b>colortable</b> y
1520 <b>where</b> 1 6.0
1521 <b>cols</b> 4
1522 <b>width</b> 4
1523 <b>font</b> Helvetica
1524 <b>end</b>
1525 <b>setcolor</b> 6,8,9 white
1526 <b>setcolor</b> 10 green
1527 <b>vlines</b> streams
1528 <b>width</b> 0.1
1529 <b>color</b> blue
1530 <b>masked</b> n
1531 <b>label</b> streams
1532 <b>end</b>
1533 <b>vlines</b> roadsmajor
1534 <b>width</b> 1.5
1535 <b>style</b> 1111
1536 <b>color</b> grey
1537 <b>masked</b> n
1538 <b>label</b> major roads
1539 <b>end</b>
1540 <b>vlegend</b>
1541 <b>where</b> 4.5 0
1542 <b>font</b> Courier
1543 <b>fontsize</b> 8
1544 <b>end</b>
1545 <b>text</b> 30% 100% Wake County Terrain
1546 <b>color</b> black
1547 <b>width</b> 1
1548 <b>background</b> white
1549 <b>size</b> 550
1550 <b>ref</b> lower left
1551 <b>end</b>
1552 <b>text</b> 92% -25% meters
1553 <b>color</b> black
1554 <b>width</b> 1
1555 <b>background</b> white
1556 <b>size</b> 550
1557 <b>ref</b> lower left
1558 <b>end</b>
1559 <b>scale</b> 1:125000
1560 <b>scalebar</b> f
1561 <b>where</b> 1.5 5.5
1562 <b>length</b> 5000
1563 <b>height</b> 0.05
1564 <b>segment</b> 5
1565 <b>numbers</b> 5
1566 <b>end</b>
1567 <b>geogrid</b> 60 s
1568 <b>color</b> gray
1569 <b>numbers</b> 2 black
1570 <b>end</b>
1571 <b>paper</b> a4
1572 <b>end</b>
1573 <b>end</b>
1574 </pre></div>
1575
1576 This script file can be entered at the command line:
1577
1578 <div class="code"><pre>
1579 # First set the region
1580 g.region raster=elevation
1581
1582 # Generate map as Postsript file
1583 ps.map input=elevation_map.txt output=elevation.ps
1584 </pre></div>
1585
1586 <center>
1587 <img src="ps_map.png">
1588 <p><em>Figure: Result of for the more complicated Wake county, NC example</em></p>
1589 </center>
1590
1591 <!--
1592 todos according to things which were in the Spearfish example
1593 TODO: now we have no example which would contain comment:
1594 # Generate comment file (or use text editor)
1595 echo "Spearfish (SD) soils" &gt; soil.cmt
1596 TODO: now we have no example with point and line
1597 line 606969.73 3423092.91 616969.73 3423092.91
1598 color yellow
1599 width 2
1600 end
1601 point 40% 60%
1602 color purple
1603 symbol basic/diamond
1604 size 25
1605 masked n
1606 end
1607 TODO: example with outline
1608 outline
1609 color black
1610 width 1
1611 end
1612 -->
1613
1614 <p>More examples can be found on the
1615 <a href="https://grasswiki.osgeo.org/wiki/Ps.map_scripts">GRASS Wiki</a>
1616 help site.
1617 <p>
1618
1619 <h2>SEE ALSO</h2>
1620
1621 <em>
1622 <a href="g.gui.psmap.html">g.gui.psmap</a>,
1623 <a href="g.region.html">g.region</a>,
1624 <a href="v.label.html">v.label</a>,
1625 <a href="wxGUI.html">wxGUI</a>
1626 </em>
1627
1628 <h2>AUTHORS</h2>
1629
1630 Paul Carlson, USDA, SCS, NHQ-CGIS<br>
1631 Modifications: Radim Blazek, Glynn Clements, Bob Covill, Hamish Bowman