.TH ps.map .SH NAME \fIps.map\fR \- Hardcopy PostScript map output utility. .br .I "(GRASS Hardcopy PostScript Output Program)" .SH SYNOPSIS \fBps.map\fR .br \fBps.map help\fR .br \fBps.map\fR [\fB\*-r\fR] [\fBinput\*=\fIname\fR] [\fBscale\*=\fImapscale\fR] [\fBcopies\*=\fIn\fR] \fBoutput\*=\fIname\fR .SH DESCRIPTION .I ps.map produces an output file containing a PostScript program to produce hardcopy map products on your system's PostScript output device. Output can include a raster map, any number of vector overlays, site data, text labels, and other spatial data. This program has 2 distincts modes of operation. The command-line mode requires the user to prepare a file of mapping instructions describing the various spatial and textual information to be printed prior to running \fIps.map\fR. The interactive mode (i.e., no command-line arguments) will prompt the user for items to be mapped and does not require the user to prepare a file of instructions. The command line flag is: .IP \fB\*-r\fR 18 Rotate plot 90 degrees. .LP The command-line parameters are: .IP \fBinput\*=\fIname\fR 18 File containing mapping instructions. (or enter \fBinput\*=-\fR to enter from keyboard). These instructions are described in detail below. .IP \fBscale\*=\fImapscale\fR 18 Scale of the output map, e.g. 1:25000 .br Default: 1 panel This parameter is provided as a convenience. It is identical to the .I scale mapping instruction described below. .IP \fBoutput\*=\fIname\fR 18 Name of output the file to contain the PostScript program. .LP Note: the user must select a PostScript output device using .I ps.select before running \fIps.map\fR. .SH "MAPPING INSTRUCTIONS" The mapping instructions allow the user to specify various spatial data to be plotted. These instructions are normally prepared in a regular text file using a system editor. Some instructions are single line instructions while others are multiple line. Multiple line instructions consist of the main instruction followed by a subsection of one or more additional instructions. Instructions that may be included in the subsection under several different main instructions are: .IP \fBwhere\ \fIx\ y\fR 18 The top left corner of the bounding box of the item to be plotted is located \fIx\fR inches from the left edge of the paper and \fIy\fR inches from the top edge of the paper. If \fIx\fR is less than or equal to zero, the default horizontal location is used. If \fIy\fR is less than or equal to zero, the default vertical location is used. .IP \fBfont\ \fIfont\ name\fR 18 The name of the PostScript font. The default is \fIHelvetica\fR. .IP \fBfontsize\ \fIfont\ size\fR 18 The size of the PostScript font in 1/72 inch. The default is 10. .SH colortable Prints the color table for the raster map layer anywhere on the page. .TS ll. USAGE: \fBcolortable\fR [y\*|n] \ \ \fBwhere\fR x y \ \ \fBwidth\fR table width \ \ \fBcols\fR table columns \ \ \fBfont\fR font name \ \ \fBfontsize\fR font size \ \ \fBcolor\fR text color \ \ \fBend\fR .TE The color table will display the colors for each raster map layer category value and the category label. To get a color table, you must have previously requested a raster map layer. The default location for the colortable is immediately below any other map legend information, starting at the left margin. The default text color is black. Omitting the \fBcolortable\fR instruction would result in no color table. \fBNote\fR: Be careful about asking for color tables for raster map layers which have many categories, such as elevation. This could result in the printing of an extremely long color table!!!!! This example would print a color table immediately below any other map legend information, starting at the left margin. .TS ll. EXAMPLE: \fBcolortable\fR y .TE .SH comments Prints comments anywhere on the page. .TS ll. USAGE: \fBcomments\fR commentfile \ \ \fBwhere\fR x y \ \ \fBfont\fR font name \ \ \fBfontsize\fR font size \ \ \fBcolor\fR text color \ \ \fBend\fR .TE The default location is immediately below the last item item printed, starting at the left margin. The default text color is black. This example prints in blue whatever is in the file \fIveg.comments\fR starting at 1.5 inches from the left edge of the page and 7.25 inches from the top of the page, using a 15/72 inch Helvetica Bold font. .TS ll. EXAMPLE: \fBraster\fR vegetation \fBcomments\fR veg.comments \ \ \fBwhere\fR 1.5 7.25 \ \ \fBfont\fR Helvetica Bold \ \ \fBfontsize\fR 15 \ \ \fBcolor\fR blue \ \ \fBend\fR .TE Presumably, the file .I veg.comments contain comments pertaining to the raster map layer \fIvegetation\fR, such as "This map was created by classifying a LANDSAT TM image". .SH copies Specifies the number of copies to be printed. .TS l l. USAGE: \fBcopies\fR n .TE Each page will be printed n times. .SH greyrast Selects a raster map layer for output in shades of grey. .TS l l. USAGE: \fBgreyrast\fR mapname\*|\fIlist\fR .TE For each .I ps.map run, only one raster map layer can be requested (using either the \fIgreyrast\fR or the \fIraster\fR instruction). .SH grid Overlays a coordinate grid onto the output map. .TS l l. USAGE: \fBgrid\fR spacing \ \ \fBcolor\fR color \ \ \fBnumbers\fR # [color] \ \ \fBfont\fR font name \ \ \fBfontsize\fR font size \ \ \fBend\fR .TE The \fBspacing\fR of the grid is given (in the geographic coordinate system units) on the main instruction line. The subsection instructions allow the user to specify the \fBcolor\fR of the grid lines, whether coordinate \fBnumbers\fR should appear on the grid lines, and if they should appear every grid line (1), every other grid line (2), etc., and what color the numbers should be. The defaults are black grid lines, unnumbered. This example would overlay a green grid with a spacing of 10000 meters (for a metered database, like UTM) onto the output map. Alternate grid lines would be numbered with red numbers. .TS l l. EXAMPLE: \fBgrid\fR 10000 \ \ \fBcolor\fR green \ \ \fBnumbers\fR 2 red \ \ \fBend\fR .TE .SH header Prints the map header above the map. .TS ll. USAGE: \fBheader\fR \ \ \fBfile\fR header file \ \ \fBfont\fR font name \ \ \fBfontsize\fR font size \ \ \fBcolor\fR text color \ \ \fBend\fR .TE If the \fIheader\fR instruction or the \fIfile\fR sub-instruction is absent, the header will consist of the map title and location, each centered on the page above the map. The default text color is black. This example prints (in red) whatever is in the file \fIsoils.hdr\fR above the map, using a 20/72 inch Courier font. .TS ll. EXAMPLE: \fBheader\fR \ \ \fBfile\fR soils.hdr \ \ \fBfont\fR Courier \ \ \fBfontsize\fR 20 \ \ \fBcolor\fR red \ \ \fBend\fR .TE .SH labels Selects a labels file for output (see manual entry for .I p.labels). .TS l l. USAGE: \fBlabels\fR labelfile\*|\fIlist\fR \ \ \fBfont\fR font name \ \ \fBend\fR .TE This example would paint labels from the labels file called \fItown.names\fR. Presumably, these labels would indicate the names of towns on the map. .TS ll. EXAMPLE: \fBlabels\fR town.names .TE .SH line Draws lines on the output map. .TS l l. USAGE: \fBline\fR east north east north \fBline\fR x% y% x% y% \ \ \fBcolor\fR color \ \ \fBwidth\fR # \ \ \fBmasked\fR [y\*|n] \ \ \fBend\fR .TE The beginning and ending points of the line are entered on the main instruction. These points can be defined either by map coordinates or by using percentages of the geographic region. The user may also specify line .B color, .B width in pixels (accepts decimal points [floating points] as well as integers), and if the line is to be .B masked by the current mask. (See manual entry for \fIr.mask\fR for more information on the mask.) .LP This example would draw a yellow line from the point x\*=10% y\*=80% to the point x\*=30% y\*=70%. This line would be 2 pixels wide and would appear even if there is a mask. .TS l l. EXAMPLE: \fBline\fR 10% 80% 30% 70% \ \ \fBcolor\fR yellow \ \ \fBwidth\fR 2 \ \ \fBmasked\fR n \ \ \fBend\fR .TE Of course, multiple lines may be drawn with multiple .I line instructions. .SH mapinfo Prints the portion of the map legend containing the scale, grid and region information, on or below the map. .TS ll. USAGE: \fBmapinfo\fR \ \ \fBwhere\fR x y \ \ \fBfont\fR font name \ \ \fBfontsize\fR font size \ \ \fBcolor\fR text color \ \ \fBend\fR .TE The default location is immediately below the map, starting at the left edge of the map. The default text color is black. This example prints (in brown) the scale, grid and region information immediately below the map and starting 1.5 inches from the left edge of the page, using a 12/72 inch Courier font. .TS ll. EXAMPLE: \fBmapinfo\fR \ \ \fBwhere\fR 1.5 0 \ \ \fBfont\fR Courier \ \ \fBfontsize\fR 12 \ \ \fBcolor\fR brown \ \ \fBend\fR .TE .SH maploc Positions the map on the page. .TS ll. USAGE: \fBmaploc\fR x y [width height] .TE The upper left corner of the map will be positioned \fIx\fR inches from the left edge of the page and \fIy\fR inches from the top of the page. If \fIwidth\fR and \fIheight\fR (in inches) are present, the map will be rescaled, if necessary, to fit. This example positions the upper left corner of the map 2.0 inches from the left edge and 3.5 inches from the top edge of the map. .TS ll. EXAMPLE: \fBmaploc\fR 2.0 3.5 .TE .SH outline Outlines the areas of a raster map layer with a specified color. .TS l l. USAGE: \fBoutline\fR \ \ \fBcolor\fR color \ \ \fBwidth\fR width of line in pixels \ \ \fBend\fR .TE .LP Distinct areas of the raster map will be separated from each other visually by drawing a border (or outline) in the specified .B color (default: black). For .B width the program accepts decimal points [floating points] as well as integers. Note: it is important the user enter the instruction \fBend\fR even if a color is not chosen. (It is hoped that in the future the outline of a different raster map layer other than the one currently being painted may be placed on the map.) This example would outline the category areas of the .I soils raster map layer in grey. .TS l l. EXAMPLE: \fBraster\fR soils \fBoutline\fR \fBcolor\fR grey \fBwidth\fR 2 \fBend\fR .TE .SH point Places additional points or icons on the output map. .TS l l. USAGE: \fBpoint\fR east north \fBpoint\fR x% y% \ \ \fBcolor\fR color \ \ \fBicon\fR iconfile\*|\fIlist\fR \ \ \fBsize\fR # \ \ \fBmasked\fR [y\*|n] \ \ \fBend\fR .TE The point location is entered in the main instruction line by giving either the map coordinates or by using percentages of the geographic region. The user may also specify the point .B color, the \fBicon\fR file to be used to represent the point location (see the the manual entry for .I ps.icons), the \fBsize\fR of the icon as a multiple of the size of the pattern in the icon file (default is 1.0, aprroximately equivalent to a 10 point character), and whether the point is to be \fBmasked\fR by the current mask. (See manual entry for \fIr.mask\fR for more information on the mask.) This example would place a purple diamond (from icon file \fIdiamond\fR) at the point (E456000 N7890000). This diamond would be the approximately the size of a 15 point character and would not be masked by the current mask. .TS l l. EXAMPLE: \fBpoint\fR 456000 7890000 \ \ \fBcolor\fR purple \ \ \fBicon\fR diamond \ \ \fBsize\fR 1.5 \ \ \fBmasked\fR n \ \ \fBend\fR .TE Of course, multiple points may be drawn with multiple .I point instructions. .SH psfile Copies a file containing PostScript commands into the output file. .B Note: .I ps.map will not search for this file. The user must be in the correct directory or specify the full path on the \fBpsfile\fR instruction. (Note to /bin/csh users: ~ won't work with this instruction). .TS l l. USAGE: \fBpsfile\fR filename .TE This example copies the file "logo.ps" into the output file. .TS l l. EXAMPLE: \fBpsfile\fR logo.ps .TE .SH raster Selects a raster map layer for output. .TS l l. USAGE: \fBraster\fR mapname\*|\fIlist\fR .TE For each .I ps.map run, only one raster map layer can be requested. If no raster map layer is requested, a completely white map will be produced. It can be useful to select no raster map layer in order to provide a white background for vector images. This example would paint a map of the raster map layer \fIsoils\fR. .TS l l. EXAMPLE: \fBraster\fR soils .TE .SH read Provides \fIps.map\fR with a previously prepared input stream. .TS l l. USAGE: \fBread\fR previously prepared UNIX file .TE Mapping instructions can be placed into a file and read into .I ps.map. .B Note: .I ps.map will not search for this file. The user must be in the correct directory or specify the full path on the \fBread\fR instruction. (Note to /bin/csh users: ~ won't work with this instruction). This example reads the UNIX file \fIpmap.roads\fR into \fIps.map\fR. This file may contain all the \fIps.map\fR instructions for placing the vector map layer \fIroads\fR onto the output map. .TS l l. EXAMPLE: \fBread\fR pmap.roads .TE The user may have created this file because this vector map layer is particularly useful for many \fIps.map\fR outputs. By using the \fBread\fR option, the user need not enter all the input for the \fBvector\fR instruction, but simply \fBread\fR the previously prepared file with the correct instructions. .SH region Places the outline of a smaller geographic region on the output. .TS l l. USAGE: \fBregion\fR regionfile\*|\fIlist\fR \ \ \fBcolor\fR color \ \ \fBwidth\fR # \ \ \fBend\fR .TE Geographic region settings are created and saved using \fIg.region\fR. The \fIps.map\fR \fIregion\fR option can be used to show an outline of a smaller region which was printed on a separate run of \fIps.map\fR on other user-created maps. The user can specify the \fBcolor\fR and the \fBwidth\fR in pixel units (accepts decimal points [floating points] as well as integers) of the outline. The default is a black border of one pixel width. .LP This example would place a white outline, 2 pixels wide, of the geographic region called \fIfire.zones\fR onto the output map. This geographic region would have been created and saved using \fIg.region\fR. .TS l l. EXAMPLE: \fBregion\fR fire.zones \ \ \fBcolor\fR white \ \ \fBwidth\fR 2 \ \ \fBend\fR .TE .SH scale Selects a scale for the output map. .TS l l. USAGE: \fBscale\fR \fIscale\fR .TE The scale can be selected either as: .IP a relative ratio, e.g. 1:25000; .IP an absolute width of the printed map, e.g. 10 inches; .IP the number of printed paper panels, e.g. 3 panels .I (at the present time, only 1 panel is supported); .IP the number of miles per inch, e.g. 1 inch equals 4 miles. .LP This example would set the scale of the map to 1 unit \*= 25000 units. .TS l l. EXAMPLE: \fBscale\fR 1:25000 .TE .SH setcolor Overrides the color assigned to one or more categories of the raster map layer. .TS l l. USAGE: \fBsetcolor\fR cat(s) color .TE This example would set the color for categories 2,5 and 8 of the raster map layer \fIwatersheds\fR to white and category 10 to green. (\fBNOTE\fR: no spaces are inserted between the category values.) .TS l l. EXAMPLE: \fBraster\fR watersheds \fBsetcolor\fR 2,5,8 white \fBsetcolor\fR 10 green .TE Of course, .I setcolor can be requested more than once to override the default color for additional categories. More than one category can be changed for each request by listing all the category values separated by commas (but with no spaces). .SH sites Selects sites data to be placed on the output map (see manual entry for \fIs.menu\fR). .TS l l. USAGE: \fBsites\fR sitemap\*|\fIlist\fR \ \ \fBcolor\fR color \ \ \fBicon\fR iconfile\*|\fIlist\fR \ \ \fBsize\fR # \ \ \fBdesc\fR [y\*|n] \ \ \fBfont\fR font name \ \ \fBend\fR .TE The user may specify the the \fBcolor\fR of the sites (see section on NAMED COLORS below); the \fBicon\fR to be used to represent the presence of a site (see the manual entry for \fIp.icons\fR); the \fBsize\fR of the icon (number of times larger than the size it is in the icon file); and whether or not the \fBdesc\fRription associated with each site is also to be printed. If the \fBdesc\fRription is to be printed, the \fBfont\fR name may be specified. The size of the font is proportional to the icon \fBsize\fR. This example would paint a sites map with blue windmills (from an icon file created by the user using the .I p.icons GRASS command) placed at all windmill locations (from a sites list). These windmills would be two times larger than the size of the icon in the icon file and have descriptions from the sites list file printed beside them. .TS l l. EXAMPLE: \fBsites\fR windmills \ \ \fBcolor\fR blue \ \ \fBicon\fR windmill \ \ \fBsize\fR 2 \ \ \fBdesc\fR y \ \ \fBend\fR .TE .SH text Places text on the map. .TS l l. USAGE: \fBtext\fR east north text \fBtext\fR x% y% text \ \ \fBfont\fR fontname \ \ \fBcolor\fR color\*|none \ \ \fBwidth\fR # \ \ \fBhcolor\fR color\*|none \ \ \fBhwidth\fR # \ \ \fBbackground\fR color\*|none \ \ \fBborder\fR color\*|none \ \ \fBsize\fR # \ \ \fBref\fR reference point \ \ \fBxoffset\fR # \ \ \fByoffset\fR # \ \ \fBopaque\fR [y\*|n] \ \ \fBend\fR .TE The user specifies where the text will be placed by providing map coordinates or percentages of the geographic region map. The text follows these coordinates on the same instruction line. More than one line of text can be specified by notating the end of a line with .B \en (e.g. USA\|\enCERL). The user can then specify various text features: .B font: cyrilc gothgbt gothgrt gothitt greekc greekcs greekp greeks italicc italiccs italict romanc romancs romand romans romant scriptc scripts (The default font is romans); .B color (see NAMED COLORS); .B width of the lines used to draw the text to make thicker letters (accepts decimal points [floating points] as well as integers); .B size as the vertical height of the letters in meters on the ground (text size will grow or shrink depending on the scale at which the map is painted); the highlight color (\fBhcolor\fR) and the width of the highlight color (\fBhwidth\fR); the text-enclosing-box \fBbackground\fR color; the text box \fBborder\fR color; .B ref. This reference point specifies the text handle - what part of the text should be placed on the location specified by the map coordinates. Reference points can refer to: [lower\*|upper\*|center]\ [left\*|right\*|center] of the text to be printed; .B yoffset, which provides finer placement of text by shifting the text a vertical distance in pixels from the specified north. The vertical offset will shift the location to the south if positive, north if negative; .B xoffset, which shifts the text a horizontal distance in pixels from the specified east The horizontal offset will shift the location east if positive, west if negative; whether or not the text should be \fBopaque\fR to vectors. Entering \fBno\fR to the opaque option will allow the user to see any vectors which go through the text's background box. Otherwise, they will end at the box's edge. .LP This example would place the text \fISPEARFISH LAND COVER\fR at the coordinates E650000 N7365000. The text would be a total of 3 pixels wide (2 pixels of red text and 1 pixel black highlight), have a white background enclosed in a red box, and be 500 meters in size. The lower right corner of the text would be centered over the coordinates provided. All vectors on the map would stop at the border of this text. .TS l l. EXAMPLE: \fBtext\fR 650000 7365000 SPEARFISH LAND COVER \ \ \fBfont\fR romand \ \ \fBcolor\fR red \ \ \fBwidth\fR 2 \ \ \fBhcolor\fR black \ \ \fBhwidth\fR 1 \ \ \fBbackground\fR white \ \ \fBborder\fR red \ \ \fBsize\fR 500 \ \ \fBref\fR lower left \ \ \fBopaque\fR y \ \ \fBend\fR .TE .SH vector Selects a vector map layer for output. .TS l l. USAGE: \fBvector\fR vectormap\*|\fIlist\fR \ \ \fBcolor\fR color \ \ \fBwidth\fR # \ \ \fBhcolor\fR color \ \ \fBhwidth\fR # \ \ \fBmasked\fR [y\*|n] \ \ \fBstyle\fR 0-9 \ \ \fBend\fR .TE The user can specify the \fBcolor\fR of the vectors; the \fBwidth\fR of the vectors lines in pixels (accepts decimal points [floating points] as well as integers); the highlight color (\fBhcolor\fR) for the vector lines; the width of the highlight color (\fBhwidth\fR) in pixels; whether or not the raster map layer is to be \fBmasked\fR by the current mask (see manual entry \fIr.mask\fR for more information on the mask); and the line \fBstyle\fR. The line style allows the vectors to be dashed in different patterns. This is done by typing a series of numbers (0's and 1's) in a desired sequence or pattern. Blanks and non-digit characters are recognized as 0's. Using 0 would allow the colors of the raster map layer (or the background color if no raster map layer was selected) to show through. .LP This example would paint a map of the vector map layer named \fIstreams\fR. These streams would be a total of 3 pixels wide (the inner two pixels blue and the outer highlight pixel white). The map would not show streams outside of the current mask. .TS l l. EXAMPLE: \fBvector\fR streams \ \ \fBcolor\fR blue \ \ \fBwidth\fR 2 \ \ \fBhcolor\fR white \ \ \fBhwidth\fR 1 \ \ \fBmasked\fR y \ \ \fBend\fR .TE .SH verbose Changes the amount of talking \fIps.map\fR will do. .TS l l. USAGE: \fBverbose\fR [0\*|1\*|2] .TE A higher value implies more chatter. The default is 2. This example sets the amount of chatter to a minimum. .TS l l. EXAMPLE: \fBverbose\fR 0 .TE .SH vlegend Prints the portion of the map legend containing the vector information, on or below the map. .TS ll. USAGE: \fBvlegend\fR \ \ \fBwhere\fR x y \ \ \fBfont\fR font name \ \ \fBfontsize\fR font size \ \ \fBend\fR .TE The default location is immediately below the legend containing the scale, grid and region information, starting at the left edge of the map. If the \fIwhere\fR instruction is present and \fIy\fR is less than or equal to zero, the vector legend will be positioned immediately below the map, starting \fIx\fR inches from the left edge of the page. This example prints the vector legend immediately below the map and starting 4.5 inches from the left edge of the page, using a 12/72 inch Helvetica font. .TS ll. EXAMPLE: \fBvlegend\fR \ \ \fBwhere\fR 4.5 0 \ \ \fBfont\fR Courier \ \ \fBfontsize\fR 12 \ \ \fBend\fR .TE .SH end Terminates input and begin painting the map. .TS ll. USAGE: \fBend\fR .TE .SH NAMED COLORS The following are the colors that are accepted by \fIps.map\fR: aqua black blue brown cyan gray green grey indigo magenta orange purple red violet white yellow .if t .bp .SH EXAMPLE ps.map INPUT FILE The following is an example of a \fIps.map\fR script file. The file has been named \fIspear.soils\fR. For the purposes of illustration, the file is in two columns. This script file can be entered at the command line: .RS \fBps.map input\*=spear.soils output\*=soils.ps\fR .RE .TS lw(18) lw(42) lw(20) lw(42). (cont.) \fBraster\fR soils \fBvlegend\fR \fBvector\fR roads \fBwhere\fR 4.5 0 \fBwidth\fR 2 \fBend\fR \fBstyle\fR 0011 \fBtext\fR 608000.00 3476004.73 SPEARFISH SOILS MAP \fBcolor\fR 1 black \fBcolor\fR red \fBcolor\fR 2 red \fBwidth\fR 2 \fBmasked\fR n \fBhcolor\fR black \fBend\fR \fBhwidth\fR 1 \fBlabels\fR town.names \fBbackground\fR white \fBregion\fR subregion \fBborder\fR red \fBcolor\fR white \fBsize\fR 500 \fBwidth\fR 2 \fBref\fR lower left \fBend\fR \fBopaque\fR y \fBgrid\fR 10000 \fBend\fR \fBcolor\fR green \fBline\fR 606969.73 3423092.91 616969.73 3423092.91 \fBnumbers\fR 2 red \fBcolor\fR yellow \fBend\fR \fBwidth\fR 2 \fBoutline\fR \fBopaque\fR yes \fBcolor\fR black \fBend\fR \fBend\fR \fBpoint\fR 40% 60% \fBcolortable\fR\ y \fBcolor\fR purple \fBcomments\fR soil.cmt \fBicon\fR diamond \fBfont\fR Helvetica \fBsize\fR 2 \fBend\fR \fBmasked\fR n \fBscale\fR 1:25000 \fBend\fR \fBsetcolor\fR 6,8,9 white \fBend\fR \fBsetcolor\fR 10 green .TE .SH "INTERACTIVE MODE" If the user simply enters .I ps.map without arguments, then a simple prompting session occurs. Some, but not all of the non-interactive requests are available at this level. .SH "SEE ALSO" .I ps.icons, .I ps.select .SH AUTHOR Paul Carlson, USDA, SCS, NHQ-CGIS