.TH p.map.new .SH NAME \fIp.map.new\fR \- Color map output utility. .br .I "(GRASS Hardcopy Output Program)" .SH SYNOPSIS \fBp.map.new\fR .br \fBp.map.new\fR [\fBinput\fR=\fI name\fR] [\fBscale\fR=\fI mapscale\fR] .SH DESCRIPTION The .I p.map.new command produces color maps for output on a color hardcopy device or a graphics monitor. Output can include a raster map, any number of vector overlays, site data, text labels, and other map elements. This command has three modes of operation. The command-line mode requires a previously prepared file of mapping instructions describing the map elements to be printed. 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 keyboard mode is started by entering a hyphen ( - ) for the \fBinput\fR parameter. The \fIp.map.new\fR instructions would then be entered via the keyboard. The command-line parameters are: .IP \fBinput\fR=\fIname\fR 18 File containing mapping instructions (or enter \fBinput\fR=\fB-\fR to enter instructions from the keyboard). These instructions are described in detail below. .IP \fBscale\fR=\fImapscale\fR 18 Scale of the output map, e.g. 1:25000 .br Default: 1 panel .br The options for this parameter are identical to the .I scale mapping instruction described below. If a .I scale instruction is present in an input file, it is superseded by the command-line \fBscale\fR parameter. .LP An output device can be selected using .I p.select before running \fIp.map.new\fR. Valid devices include on-line hardcopy devices, plus .I preview, preview2, and \fIppm\fR. See manual entry for \fIp.select\fR. The current geographic region determines the area that is mapped using .I p.map.new. .SH "NON-INTERACTIVE MAPPING INSTRUCTIONS" Mapping instructions allow the user to specify various map elements to be plotted. These instructions are normally prepared in an ASCII text file using a system editor. All of the listed mapping instructions are usable in a prepared file in the command-line mode. Not all of them are available in the interactive and keyboard modes. 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. All multiple-line instructions must be completed by the \fBend\fR terminator. Some instructions, such as those using data layers, icons, or labels, access files via the current mapset search path. .SH barscale Places a barscale on the output map. .TS l l. USAGE: \fBbarscale\fR east north \fBbarscale\fR x\fI%\fR y\fI%\fR \ \ \fBunit\fR \fIft\fR| \fImi\fR| \fIm\fR| \fIkm\fR \ \ \fBlength\fR # \ \ \fBinterval\fR # \ \ \fBstyle\fR \fIdash\fR| \fItick\fR \ \ \fBwidth\fR # \ \ \fBcolor\fR color \ \ \fBtextsize\fR # \ \ \fBtextcolor\fR color| \fInone\fR \ \ \fBtextfont\fR font \ \ \fBbackground\fR color| \fInone\fR \ \ \fBborder\fR color| \fInone\fR \ \ \fBend\fR .TE The location of the zero point of the scale bar is entered on the first instruction line. The location can be defined either by map coordinates or by percentages of the map area, where 0% 0% is the lower left corner of the map. The user specifies the barscale \fBunit\fR of measurement, the total \fBlength\fR using that unit, and the length of one \fBinterval\fR (a smaller length evenly divisible into the total length). The \fBstyle\fR of the scale bar can be specified. The \fIdash\fR style has solid lines representing each interval, separated by gaps. The \fItick\fR style has a solid total length with vertical ticks marking each interval. The user can also specify the \fBwidth\fR of the bar in pixels, its \fBcolor\fR (see VALID COLORS NAMES), the \fBtextcolor\fR, \fBtextsize\fR in geographic units, \fBtextfont\fR (see VALID FONT NAMES), \fBbackground\fR color, and \fBborder\fR color. The \fBbarscale\fR instruction set must be completed with the \fBend\fR terminator. This example would result in a scale bar representing two kilometers. Vertical ticks would be placed at the scale origin, the mid-point, and at the end. The black bar and its accompanying black text would overlay a white box trimmed be a red border. .TS l l. EXAMPLE: \fBbarscale\fR 605000 4915000 \ \ \fBunit\fR km \ \ \fBlength\fR 2 \ \ \fBinterval\fR 1 \ \ \fBstyle\fR tick \ \ \fBwidth\fR 2 \ \ \fBcolor\fR black \ \ \fBtextcolor\fR black \ \ \fBtextsize\fR 150 \ \ \fBbackground\fR white \ \ \fBborder\fR red \ \ \fBend\fR .TE .SH colormode Selects the method to portray the colors of the raster map layer or image. .TS ll. USAGE: \fBcolormode\fR \fIapprox\fR| \fIbest\fR .TE There are two options for \fBcolormode\fR: \fIapprox\fR and \fIbest\fR. The .I approx option should be used for raster map layers with few categories, and .I best should be used for images like LANDSAT images or NHAP photos, or maps with very many categories. The .I approx mode treats each pixel independently, giving it the printer color that best approximates the true color. The .I best mode "blends" colors from pixel to pixel using a dithering technique to simulate more colors than the printer can actually print. If unspecified, the default is .I best. This example would select the .I approx colormode. The assumption is that the raster map layer being printed has few colors or that the colors would not look good dithered. .TS ll. EXAMPLE: \fBcolormode\fR approx .TE .SH colortable Includes the color table for the raster map layer in the area below the map on hardcopy output. .TS ll. USAGE: \fBcolortable\fR [\fIy\fR| \fIn\fR] .TE The color table will display the colors for each raster map layer category and the category value. The \fBcolortable\fR instruction can not precede the \fBraster\fR instruction in the .I p.map.new input. The color table is not shown when the output device is the color monitor. The user should be careful about asking for color tables for raster map layers that have very many categories, such as an elevation layer. This could result in the printing of an extremely long and generally useless color table! This example would print a color table below the data area of the map. .TS ll. EXAMPLE: \fBcolortable\fR y .TE .SH comments Prints comments beneath the map on hardcopy output. .TS ll. USAGE: \fBcomments\fR [commentfile] comments \fBend\fR .TE Comment text can be entered in the .I p.map.new file or from a separate, previously prepared file. Comments are not shown when the output device is the color monitor. The \fBcomments\fR instruction set must be completed by the \fBend\fR terminator. This example prints the comment "This is a comment" below the data area on the the map. .TS ll. EXAMPLE: \fBcomments\fR This is a comment. \fBend\fR .TE This example prints the text in a file called "veg.comments" in the current directory. .TS ll. EXAMPLE: \fBraster\fR vegetation \fBcomments\fR veg.comments \ \ \fBend\fR .TE .SH defpat Defines an area fill pattern to be used in \fBsetpat\fR instructions. .TS ll. USAGE: \fBdefpat\fR name pattern \ \ \fBcolor\fR # color \ \ \fBend\fR .TE An area fill pattern is given a name on the \fBdefpat\fR instruction line. This name can then be used in subsequent \fIsetpat\fR instructions. The \fBdefpat\fR instruction can be used more than once to specify multiple patterns. The specified pattern is composed of a sequence of numbers (0-9, and blanks, which are equivalent to 0) on one or more lines. The zeros and blanks indicate areas in the pattern where the normal category colors are visible. The other digits, 1-9, indicate pattern pixels and can be assigned any valid color. The \fBcolor\fR option specifies a non-zero digit in the pattern, followed by a valid color name. It can be repeated for each of the non-zero digits in the pattern. The default color for all non-zero digits is black unless specified with the \fBcolor\fR option. The \fBdefpat\fR instruction set must be completed by the \fBend\fR terminator. In the \fIp.map.new\fR input, the \fBdefpat\fR instruction must precede any \fBsetpat\fR instruction using the specified pattern. Note: Indented pattern specifications will be interpreted as having leading blanks. This example creates a black horizontal line pattern called "horiz". Each black line in the pattern would be one pixel wide and would be three pixels from neighboring lines. .TS ll. EXAMPLE: \fBdefpat\fR horiz 1 0 0 0 \fBcolor\fR 1 black \fBend\fR .TE This example creates a green vertical line pattern. .TS ll. EXAMPLE: \fBdefpat\fR vert 1000 \fBcolor\fR 1 green \fBend\fR .TE The following example creates a red diagonal line pattern. .TS ll. EXAMPLE: \fBdefpat\fR diag 00001 0001 001 01 1 \fBcolor\fR 1 red \fBend\fR .TE This example creates a two-toned tree pattern with orange "trunks" and green "leaves". .TS ll. EXAMPLE: \fBdefpat\fR tree 2 222 22122 22 1 22 1 2 222 22122 22 1 22 1 \fBcolor\fR 1 orange \fBcolor\fR 2 black \fBend\fR .TE .SH end Terminates input and begins the painting of the map to the output device. .TS ll. USAGE: \fBend\fR .TE An \fBend\fR instruction completes the entire input to \fIp.map.new\fR. It is normally the last line in an input file, but it can be moved forward to eliminate any instructions following its position. The \fBend\fR instruction for the entire input should not be confused with \fBend\fR terminators that are required with all multiple-line instruction sets. .SH endpanel Specifies which panel number to end printing. The default is 0, and will print all panels from the startpanel to the last panel. .TS ll. EXAMPLE: \fBendpanel\fR 4 .TE This example would end output at panel 4. .SH grid Overlays a coordinate grid on the output map. .TS l l. USAGE: \fBgrid\fR spacing \ \ \fBpattern\fR \fInotick\fR| \fItick\fR # # \ \ \fBmasked\fR [\fIdata\fR| \fInodata\fR| \fIall\fR] \ \ \fBstyle\fR sequence \ \ \fBwidth\fR # \ \ \fBcolor\fR color \ \ \fBnumbers\fR # [color] [\fIin\fR| \fIout\fR] \ \ \fBnumbersbg\fR color| \fInone\fR \ \ \fBnumbersize\fR # \ \ \fBend\fR .TE The spacing of the grid in geographic coordinate system units must be be specified on the first instruction line. The user can specify the overall look of the grid using the \fBpattern\fR parameter. The \fInotick\fR option is for a complete net of intersecting lines. The \fItick\fR option is for smaller tick marks where grid intervals intersect. The horizontal and vertical lengths, in pixels, must be specified with the \fItick\fR option. The user can control the areas covered by the grid by using the \fBmasked\fR parameter. With the \fIdata\fR option of \fBmasked\fR, the grid will be seen over all areas of the map's raster layer except the no-data (category 0) areas. With the \fInodata\fR option, the grid will be seen only over the no-data areas. The entire grid is seen with the \fIall\fR option to \fBmasked\fR. The grid line \fBstyle\fR can be specified using a series of 1's and 0's. The 1's represent the visible dashes and the 0's represent gaps between the dashes. The default is solid lines. The \fBwidth\fR (in pixels) and \fBcolor\fR of the grid lines can also be specified. The user can control the placement and look of grid label numbers using the \fBnumbers\fR, \fBnumbersbg\fR, and \fBnumbersize\fR parameters. The \fBnumbers\fR parameter is used to include grid labels, to specify which labels should be shown (where 1 is every grid label, 2 is every other grid label, etc.), and to specify the label color. It is also used to place the labels inside or outside the current region. The background color behind each label is specified by the \fBnumbersbg\fR parameter. The user controls the grid label size using the \fBnumbersize\fR parameter, in geographic units. The \fBgrid\fR instruction set must be concluded by the \fBend\fR parameter. When used in a metric location, this example would produce grid ticks every 5000 meters. The purple ticks would have "arms" ten pixels long and would be visible over the entire map area. The purple grid numbers would be 350 meters high (to scale), inside the current region map area, and have no background color. A grid label would appear every 5000 meters. .TS l l. EXAMPLE: \fBgrid\fR 5000 \ \ \fBpattern\fR tick 10 10 \ \ \fBmasked\fR all \ \ \fBwidth\fR 1 \ \ \fBcolor\fR purple \ \ \fBnumbers\fR 1 purple in \ \ \fBnumbersbg\fR none \ \ \fBnumbersize\fR 350 \ \ \fBend\fR .TE The following example would produce black grid lines every 1000 meters. The lines would be visible only in the areas of category 0, and they would be dashed, with one long dash for every short gap. Every other grid label would be shown, each with a white background. .TS l l. EXAMPLE: \fBgrid\fR 1000 \ \ \fBpattern\fR notick \ \ \fBmasked\fR nodata \ \ \fBstyle\fR 11111100 \ \ \fBwidth\fR 1 \ \ \fBcolor\fR black \ \ \fBnumbers\fR 2 black in \ \ \fBnumbersbg\fR white \ \ \fBnumbersize\fR 200 \ \ \fBend\fR .TE .SH labels Selects a labels file for output. .TS l l. USAGE: \fBlabels\fR labelfile| \fIlist\fR .TE The \fBlabels\fR instruction includes previously prepared label specifications. See manual entry for \fIp.labels\fR for correct format of the labels file. The labels file must be accessible via the current mapset search path. The \fIlist\fR option is available in keyboard mode. This example would paint labels from a labels file called \fItown.names\fR. .TS ll. EXAMPLE: \fBlabels\fR town.names .TE .SH legend Places a user-designed map legend on the output. .TS l l. USAGE: \fBlegend\fR east north \fBlegend\fR x\fI%\fR y\fI%\fR \ \ \fBheight\fR # \ \ \fBwidth\fR # \ \ \fBvlen\fR # \ \ \fBtextcolor\fR color \ \ \fBtextsize\fR # \ \ \fBtextwidth\fR # \ \ \fBxspace\fR # \ \ \fByspace\fR # \ \ \fBbackground\fR color \ \ \fBborder\fR color \ \ \fBbeginrast\fR \ \ \ \ \ \fBramp\fR \fIvalue\fR| \fIlabel\fR \fIvertical\fR| \fIhorizontal\fR \ \ \ \ \ \fBcatnum\fR cat description \ \ \ \ \ \fBend\fR \ \ \fBbeginvect\fR \ \ \ \ \ \fBvectname\fR vectormap description \ \ \ \ \ \fBvecttitle\fR vectormap \ \ \ \ \ \fBend\fR \ \ \fBbeginsite\fR \ \ \ \ \ \fBsitename\fR sitemap description \ \ \ \ \ \fBend\fR \ \ \fBend\fR .TE The location of the upper left corner of the legend must be entered on the first instruction line. The location can be defined either by map coordinates or by percentages of the map area, where 0% 0% is the lower left corner of the map. The user specifies the \fBheight\fR and \fBwidth\fR of the boxes that will show raster category colors and/or patterns. The length of line segments that will show vector line colors and patterns is specified with the \fBvlen\fR parameter. The user controls horizontal spacing between legend symbols and legend text using \fBxspace\fR. The \fByspace\fR parameter is used to control vertical spacing between legend symbols. All of these measurements are in pixels. The user designs the legend text using the \fBtextcolor\fR, \fBtextsize\fR, and \fBtextwidth\fR parameters. Colors are listed in the VALID COLOR NAMES section of this manual entry. The \fBtextsize\fR is specified in pixels. The \fBtextwidth\fR is also specified in pixels. The user can specify the color for the \fBbackground\fR box containing the entire legend. If a color is chosen, underlying map elements are opaqued. The user can also specify a \fBborder\fR color for the legend box. The user specifies the symbols to be included in the legend using the \fBbeginrast\fR, \fBbeginvect\fR, and \fBbeginsite\fR parameters. Each of these parameters starts a subsection of the \fBlegend\fR instruction that must be completed by an \fBend\fR terminator. These should not be confused with the \fBend\fR terminator for the entire \fBlegend\fR instruction set. If the user simply uses the \fBbeginrast\fR parameter followed by \fBend\fR, all categories of the map's raster layer will be shown in individual boxes, and the legend labels will be the corresponding category names in the layer's \fIcats\fR file. The user can include specific categories and optional labels by using one or more \fBcatnum\fR lines, each including a category number and the accompanying legend text. If the map's raster layer portrays a continuous range of data, a \fBramp\fR in the legend might be appropriate. The \fBramp\fR can be vertical or horizontal, and it's accompanying text can be either the smallest and largest category values, or the \fIcats\fR labels associated with the smallest and largest categories. The \fBbeginrast\fR subsection must be completed with an \fBend\fR terminator. Symbols for vector data on the map can be included in the legend by using the \fBbeginvect\fR parameter. If the user simply follows \fBbeginvect\fR with \fBend\fR, all vector layers in the map will be included in the legend. The user can include specific vector layers in the legend by using the \fBvectname\fR line one or more times, each including a vector layer name and an accompanying description. The vector layer titles as written in \fIdig_cats\fR files can be included as the legend text by using the \fBvecttitle\fR line one or more times. The \fBbeginvect\fR subsection must be completed with an \fBend\fR terminator. Site symbols are included in the legend by using one or more \fBsitename\fR lines in the \fBbeginsite\fR subsection. Each line includes the name of the site list and an accompanying description. The \fBbeginsite\fR subsection must be completed with an \fBend\fR terminator. The entire \fBlegend\fR instruction set must be completed by an \fBend\fR terminator. In the \fIp.map.new\fR input, the \fBlegend\fR instruction can not precede the instructions for any of the map elements that are to be shown in the legend. This example would produce a legend with five symbols: a point symbol, the colors and patterns for three raster categories, and a line representing one vector layer, in that order. The background of the legend would be white and surrounded by a red border. All text in the legend would be black. .TS l l. EXAMPLE: \fBlegend\fR 589000 4921200 \ \ \fBheight\fR 10 \ \ \fBwidth\fR 20 \ \ \fBvlen\fR 20 \ \ \fBxspace\fR 10 \ \ \fByspace\fR 7 \ \ \fBtextcolor\fR black \ \ \fBtextsize\fR 250 \ \ \fBtextwidth\fR 1 \ \ \fBbackground\fR white \ \ \fBborder\fR red \ \ \fBbeginsite\fR \ \ \ \ \fBsitename\fR archsites Arch. site \ \ \ \ \fBend\fR \ \ \fBbeginrast\fR \ \ \ \ \fBcatnum\fR 4 Sandstone \ \ \ \ \fBcatnum\fR 5 Limestone \ \ \ \ \fBcatnum\fR 6 Shale \ \ \ \ \fBend\fR \ \ \fBbeginvect\fR \ \ \ \ \fBvectname\fR roads Road \ \ \ \ \fBend\fR \ \ \fBend\fR .TE The following example would produce a legend with a vertical ramp showing all the colors in the map's raster layer. The labels of the first and last categories would be included. .TS l l. EXAMPLE: \fBlegend\fR 589000 4921200 \ \ \fBheight\fR 10 \ \ \fBwidth\fR 20 \ \ \fBxspace\fR 10 \ \ \fBtextcolor\fR black \ \ \fBtextsize\fR 250 \ \ \fBtextwidth\fR 1 \ \ \fBbackground\fR gray \ \ \fBborder\fR black \ \ \fBbeginrast\fR \ \ \ \fBramp\fR label vertical \ \ \ \fBend\fR \ \ \fBend\fR .TE .SH line Draws a line that is independent of any vector map layer on the output map. .TS l l. USAGE: \fBline\fR east north east north \fBline\fR x\fI%\fR y\fI%\fR x\fI%\fR y\fI%\fR \ \ \fBstyle\fR sequence \ \ \fBcolor\fR [# ] color \ \ \fBwidth\fR # \ \ \fBhcolor\fR color \ \ \fBhwidth\fR # \ \ \fBmasked\fR [\fIy\fR| \fIn\fR] \ \ \fBend\fR .TE The beginning and ending points of the line are entered on the main instruction line. These points can be defined either by map coordinates or by using percentages of the geographic region, where 0% 0% is the lower left corner of the map. The default line style is a continuous, solid line, but the user can specify a dashed line using the \fBstyle\fR parameter. The \fBstyle\fR parameter can contain a sequence of digits (0-9) that represent a colored pattern on the desired line. Colors can be assigned to each non-zero digit by using the \fBcolor\fR parameter multiple times. If the \fBcolor\fR parameter is used without a specified digit, the named color will be assigned to the entire line. Colors are listed in the VALID COLOR NAMES section in this manual entry. The user can specify line \fBwidth\fR in pixels. A highlight color can be assigned with \fBhcolor\fR, and the highlight's width in pixels can be assigned with \fBhwidth\fR. The user can also specify 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.) The \fBline\fR instruction set must be completed by an \fBend\fR terminator. The \fBline\fR instruction can be used more than once to create multiple lines. This example would draw a blue line from the point x= 10% y= 80% to the point x= 30% y= 70%. The line would be two pixels wide and would appear even if there is a mask. .TS l l. EXAMPLE: \fBline\fR 10% 80% 30% 70% \ \ \fBcolor\fR blue \ \ \fBwidth\fR 2 \ \ \fBmasked\fR n \ \ \fBend\fR .TE The following example would draw a line with yellow dashes on a black background. .TS l l. EXAMPLE: \fBline\fR 605000 4915000 595300 4918200 \ \ \fBstyle\fR 1111100 \ \ \fBcolor\fR 1 yellow \ \ \fBwidth\fR 1 \ \ \fBhcolor\fR black \ \ \fBhwidth\fR 1 \ \ \fBend\fR .TE .SH outline Outlines areas of a raster map layer with a specified color. .TS l l. USAGE: \fBoutline\fR \ \ \fBcolor\fR color \ \ \fBend\fR .TE .LP The \fBoutline\fR instruction can be used to place a border around all contiguous groups of same-value cells in a raster map layer. A valid color name can be specified with the optional \fBcolor\fR parameter. The default color is black. The \fBoutline\fR instruction set must be completed by the \fBend\fR terminator, even if the \fBcolor\fR parameter is not used. The \fBoutline\fR instruction can not precede a \fBraster\fR instruction in a \fIp.map.new\fR input file. The instruction sequence in this example would outline in grey the category areas of a raster map layer called "soils". .TS l l. EXAMPLE: \fBraster\fR soils \fBoutline\fR \ \ \fBcolor\fR grey \ \ \fBend\fR .TE .SH point Places a point symbol on the output map. .TS l l. USAGE: \fBpoint\fR east north \fBpoint\fR x\fI%\fR y\fI%\fR \ \ \fBicon\fR iconfile| \fIlist\fR \ \ \fBcolor\fR color \ \ \fBsize\fR # \ \ \fBmasked\fR [\fIy\fR| \fIn\fR] \ \ \fBend\fR .TE The user enters a point symbol location on the main instruction line. The location can be defined either by map coordinates or by percentages of the map area, where 0% 0% is the lower left corner of the map. The icon to be used can be specified with the \fBicon\fR parameter. The user can use any icon in an \fIicons\fR directory within the current mapset search path. Icons can be created using \fIp.icons\fR or by simply using a system editor. The default icon is a diamond. The \fIlist\fR option for \fBicon\fR is available in keyboard mode. The user can specify the symbol \fBcolor\fR. Colors are listed in the VALID COLOR NAMES section of this manual entry. The icon \fBsize\fR is a positive, floating-point scaling factor of the pattern in the icon file. A size of 1 produces an icon with the same number of pixels (at the output device's resolution) as ASCII characters in the icon file. The user can also specify whether the point symbol is to be \fBmasked\fR by the current mask. (See manual entry for \fIr.mask\fR for more information on the mask.) The \fBpoint\fR instruction set must be completed be an \fBend\fR terminator. Multiple points may be drawn with multiple \fBpoint\fR instructions. This example would access an icon file called "box" within the current mapset search path. The red box symbol would be placed at the point E603000, N4921750. The box would have the same number of pixels as characters in the icon file. It would not be masked by the current mask. .TS l l. EXAMPLE: \fBpoint\fR 603000 4921750 \ \ \fBicon\fR box \ \ \fBcolor\fR red \ \ \fBsize\fR 1 \ \ \fBmasked\fR n \ \ \fBend\fR .TE .SH raster Selects a raster map layer for output. .TS l l. USAGE: \fBraster\fR rastermap| \fIlist\fR .TE Only one GRASS raster map layer can be specified in a \fIp.map.new\fR input file. If no raster map layer is requested, a white background will be produced. The \fIlist\fR option is available in keyboard mode. The raster layer must be accessible within the current mapset search path. In a \fIp.map.new\fR input file, the \fBraster\fR instruction must precede these instructions: \fBcolortable\fR, \fBoutline\fR, \fBsetcolor\fR, and \fBsetpat\fR. It also must precede any \fBlegend\fR instruction set that applies to the raster map layer. This example would paint a map of the raster map layer \fIsoils\fR. .TS l l. EXAMPLE: \fBraster\fR soils .TE .SH read Provides input to \fIp.map.new\fR from a previously prepared instruction file. .TS l l. USAGE: \fBread\fR filename .TE Mapping instructions can be placed in a file and read as input to .I p.map.new. If a certain set of mapping instructions are used in many different maps, they can be placed in one separate file and efficiently accessed by each map's instructions using the \fBread\fR instruction. Note: \fIp.map.new\fR will not search for the file to be read. The file must be in the current directory or a full path needs to be specified on the \fBread\fR instruction line. (Note to /bin/csh users: the tilde [ ~ ] path alias will not work with this instruction). This example reads the ASCII file "pmap.roads" into \fIp.map.new\fR. .TS l l. EXAMPLE: \fBread\fR pmap.roads .TE .SH region Places the outline of a geographic region on the output map. .TS l l. USAGE: \fBregion\fR regionfile| \fIlist\fR \ \ \fBstyle\fR sequence \ \ \fBcolor\fR [# ] color \ \ \fBwidth\fR # \ \ \fBhcolor\fR color \ \ \fBhwidth\fR # \ \ \fBmasked\fR [\fIy\fR| \fIn\fR] \ \ \fBend\fR .TE The user can place the outline of a saved geographic region on the map using \fBregion\fR. The named region file must be in a \fIwindows\fR directory within the current mapset search path. Geographic region settings can be created and saved using \fIg.region\fR. The \fIlist\fR option is available in keyboard mode. The default region outline style is a continuous, solid line, but the user can specify a dashed line using the \fBstyle\fR parameter. The \fBstyle\fR parameter can contain a sequence of digits (0-9) that represent a colored pattern on the desired line. Colors can be assigned to each non-zero digit by using the \fBcolor\fR parameter multiple times. If the \fBcolor\fR parameter is used without a specified digit, the named color will be assigned to the entire region outline. Colors are listed in the VALID COLOR NAMES section in this manual entry. The user can specify the region outline \fBwidth\fR in pixels. A highlight color can be assigned with \fBhcolor\fR, and the highlight's width can be assigned with \fBhwidth\fR. The user can also specify if the outline is to be .B masked by the current mask. (See manual entry for \fIr.mask\fR for more information on the mask.) The \fBregion\fR instruction set must be completed by an \fBend\fR terminator. The \fBregion\fR instruction can be used more than once to show multiple regions. This example would produce a white outline, two pixels wide, showing the geographic region called "fire.zones". .TS l l. EXAMPLE: \fBregion\fR fire.zones \ \ \fBcolor\fR white \ \ \fBwidth\fR 2 \ \ \fBend\fR .TE .SH scale Specifies the scale of the hardcopy output map. .TS l l. USAGE: \fBscale\fR scale .TE The scale of the output map can be specified in one of several different forms: .IP relative ratio e.g. 1:25000 .IP number of geographic units per map unit e.g. 1 inch equals 4 miles .IP absolute width of the printed map e.g. 10 inches .IP width in number of printed panels e.g. 3 panels .LP Map inches can be equated with these geographic units: miles, kilometers, and meters. Valid width units are inches, centimeters, and panels. One panel is the single-sheet maximum width available on the hardcopy medium. The final size of the hardcopy map output is determined by the combination of the specified scale and the current geographic region. The \fBscale\fR instruction does not affect output to the \fIpreview\fR device. If used, the command-line \fIscale\fR parameter overrides the \fBscale\fR instruction. This example would set the scale of the map to one map unit represents 25,000 geographic units. .TS l l. EXAMPLE: \fBscale\fR 1:25000 .TE The following example would specify an output map that would be fifteen centimeters wide. .TS l l. EXAMPLE: \fBscale\fR 15 centimeters .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 The user can assign a desired color to categories in a raster map layer by using \fBsetcolor\fR. Categories are specified on the parameter line before a valid color name. One or more category numbers can appear on the parameter line, separated by commas (with no spaces), or in ranges using hyphens. The \fBsetcolor\fR instruction can be used more than once for assignment of multiple colors. In the input \fIp.map.new\fR file, the \fBsetcolor\fR instruction must follow the \fBraster\fR instruction. Colors are listed in the VALID COLOR NAMES section of this manual entry. In this example, the color for raster map categories 1 through 3, plus category 5, would be set to green, categories 4, 6, and 8 would be set to blue, and category 7 would be set to red, regardless of their assigned colors in the database. .TS l l. EXAMPLE: \fBraster\fR watersheds \fBsetcolor\fR 1-3,5 green \fBsetcolor\fR 4,6,8 blue \fBsetcolor\fR 7 red .TE .SH setpat Assigns a previously defined pattern to one or more raster map layer categories. .TS l l. USAGE: \fBsetpat\fR cat(s) name \fBsetpat\fR cat(s) \fI#\fRnumber \fBsetpat\fR \fIall\fR| \fIbuiltin\fR .TE The user can assign a pattern to categories in a raster map layer by using \fBsetpat\fR. Categories are specified on the parameter line before the name of a pattern defined earlier using \fBdefpat\fR, or before the number signifying a built-in \fIp.map.new\fR pattern. One or more category numbers can appear on the parameter line, separated by commas (with no spaces), or in ranges using hyphens. The built-in patterns are defined in etc/paint/patterns in the compiled GRASS code directory. Each built-in pattern has an assigned number. These numbers can be used following a pound sign ( # ) on a \fBsetpat\fR instruction line. By using the \fIbuiltin\fR option, each category in a raster map layer can be assigned the correspondingly numbered builtin pattern. All raster map categories can be assigned the same defined pattern if the \fIall\fR option is used. In this case, only one pattern should be defined within the \fIp.map.new\fR mapping instruction file. The \fBsetpat\fR instruction can be used more than once for assignment of multiple patterns. In the input \fIp.map.new\fR file, the \fBsetpat\fR instruction must follow the \fBraster\fR instruction, as well as the \fBdefpat\fR instruction defining the pattern that is used. This example assigns a pattern called "vert" to categories 3 and 4 of the raster map layer "vegetation" and a pattern called "tree" to category 10. .TS l l. EXAMPLE: \fBraster\fR veg \fBsetpat\fR 3-4 vert \fBsetpat\fR 10 tree .TE This example reads a previously prepared ASCII file called .I horiz.pat containing \fBdefpat\fR instructions for creating a black, horizontal pattern called "horiz", and assigns that pattern to category 5 of the raster map layer "soils". .TS l l. EXAMPLE: \fBraster\fR soils \fBread\fR horiz.pat \fBsetpat\fR 5 horiz .TE This example assigns built-in pattern 1 to category 1 of the "soils" raster layer, pattern 2 to category 2, and so on. .TS l l. EXAMPLE: \fBraster\fR soils \fBsetpat\fR builtin .TE This example assigns built-in pattern 1 to categories 5 through 7 in the "soils" raster map layer, and built-in pattern 2 to categories 10 and 12. .TS l l. EXAMPLE: \fBraster\fR soils \fBsetpat\fR 5-7 # 1 \fBsetpat\fR 10,12 # 2 .TE .SH sites Selects sites data to be placed on the output map. .TS l l. USAGE: \fBsites\fR sitemap| \fIlist\fR \ \ \fBicon\fR iconfile| \fIlist\fR \ \ \fBcolor\fR color \ \ \fBsize\fR # \ \ \fBdesc\fR [\fIy| \fIn\fR] \ \ \fBtextcolor\fR color \ \ \fBtextsize\fR # \ \ \fBend\fR .TE GRASS sites data can be portrayed on the map using the \fBsites\fR instruction. The user can specify the point symbol to be used, and whether labels are to appear next to the symbols. The sites data must be accessible via the current mapset search path. The \fIlist\fR option is available in keyboard mode. An icon can be specified with the \fBicon\fR parameter. The user can use any icon in an \fIicons\fR directory within the current mapset search path. Icons can be created using \fIp.icons\fR or by simply using a system editor. The default icon is a diamond. The \fIlist\fR option for \fBicon\fR is available in keyboard mode. The user can specify the symbol \fBcolor\fR. Colors are listed in the VALID COLOR NAMES section of this manual entry. The icon \fBsize\fR is a positive, floating-point scaling factor of the pattern in the icon file. A size of 1 produces an icon with the same number of pixels (at the output device's resolution) as ASCII characters in the icon file. The \fBdesc\fR parameter is used to specify whether or not the description of each site in the \fIsite_lists\fR file is also to be printed. These labels will appear directly to the right of each site symbol. The user controls the color of the labels using the \fBtextcolor\fR parameters. Valid colors are listed in the named colors section of this manual entry. The label size is specified in geographic units using \fBtextsize\fR. The \fBsites\fR instruction set must be completed by the \fBend\fR terminator. This instruction can be used more than once to portray multiple site lists. This example would produce point symbols representing the data in a \fIsite_lists\fR file called "windmills". An icon called "windmill" would be placed at each site location. These symbols would be two times larger than the size of the icon in the icon file (twice as many pixels as there are characters in the icon file). Descriptions from the sites list file would not be produced in this example. .TS l l. EXAMPLE: \fBsites\fR windmills \ \ \fBicon\fR windmill \ \ \fBcolor\fR blue \ \ \fBsize\fR 2 \ \ \fBdesc\fR n \ \ \fBend\fR .TE .SH startpanel Specifies at which panel number to begin printing. Default is 0 and would start printing from the first panel. .TS l l. EXAMPLE: \fBstartpanel\fR 2 .TE This example would begin printing at panel 2. .SH text Places text at a user-specified location on the map. .TS l l. USAGE: \fBtext\fR east north text \fBtext\fR x\fI%\fR y\fI%\fR text \ \ \fBtextfont\fR font \ \ \fBsize\fR # \ \ \fBcolor\fR color| \fInone\fR \ \ \fBwidth\fR # \ \ \fBhcolor\fR color| \fInone\fR \ \ \fBhwidth\fR # \ \ \fBref\fR reference_point \ \ \fBrotation\fR # \ \ \fBxoffset\fR # \ \ \fByoffset\fR # \ \ \fBbackground\fR color| \fInone\fR \ \ \fBopaque\fR [\fIy\fR| \fIn\fR] \ \ \fBborder\fR color| \fInone\fR \ \ \fBend\fR .TE The user specifies where text will be placed by providing map coordinates or percentages of the map area, where 0% 0% is the lower left corner of the map. The text follows the locational information on the same instruction line. Multiple lines of text can be specified by notating the end of a line with .B \en (e.g., USA\|\enCERL). Leading blanks an be inserted by preceding the text string with a backslash and the blanks (e.g., text 600000 4920500\|\e See\|\enWall Drug ). The user can control the appearance of the text, its location, and the appearance of its background box. The user can specify \fBtextfont\fR (see VALID FONT NAMES in this manual entry), \fBsize\fR in geographic units, \fBcolor\fR (see VALID COLOR NAMES), and \fBwidth\fR in pixels. The user can further control the text appearance by specifying a highlight color (\fBhcolor\fR) and the width of the highlight color (\fBhwidth\fR). The text is located at the specified coordinate or percentage pair in relation to a reference point on the text string. This point, specified with the \fBref\fR parameter, has two parts. The first part refers to a vertical location on the text string. Valid choices are \fIlower\fR, \fIcenter\fR, and \fIupper\fR. The second part refers to a horizontal location: \fIleft\fR, \fIcenter\fR, and \fIright\fR. The text string can be rotated at the reference point by using the \fBrotation\fR parameter. The value specified will be the counter-clockwise rotation in degrees from the horizontal. The .B xoffset parameter provides finer placement of text by shifting the text a horizontal distance in pixels from the specified easting. The \fBxoffset\fR will shift the text location east if positive and west if negative. The .B yoffset parameter shifts the text a vertical distance in pixels from the specified northing. The \fByoffset\fR will shift the location to the south if positive, north if negative. The user can specify if a \fBbackground\fR box is present, and what color it should be. The user can also specify whether or not the background box is \fBopaque\fR to other map elements. The color of the \fBborder\fR of this box can be specified. .LP This example would place the text "SPEARFISH LAND COVER" at the coordinates E650000, N7365000. The text would be a total of three pixels wide (one pixel of red text and one pixel of black on each side), have a white background enclosed in a red box, and be 500 meters in size (to scale). The lower left corner of the text would be placed at the coordinates provided. All other map elements would not be seen under the text. .TS l l. EXAMPLE: \fBtext\fR 650000 7365000 SPEARFISH LAND COVER \ \ \fBtextfont\fR romand \ \ \fBcolor\fR red \ \ \fBwidth\fR 1 \ \ \fBsize\fR 500 \ \ \fBref\fR lower left \ \ \fBhcolor\fR black \ \ \fBhwidth\fR 1 \ \ \fBbackground\fR white \ \ \fBborder\fR red \ \ \fBopaque\fR y \ \ \fBend\fR .TE .SH vector Selects a vector map layer for output. .TS l l. USAGE: \fBvector\fR vectormap| \fIlist\fR \ \ \fBstyle\fR sequence \ \ \fBcolor\fR [# ] color \ \ \fBwidth\fR # \ \ \fBhcolor\fR color \ \ \fBhwidth\fR # \ \ \fBmasked\fR [\fIy\fR| \fIn\fR] \ \ \fBend\fR .TE GRASS vector data can be portrayed on the map using the \fBvector\fR instruction. The name of the vector layer is specified on the first instruction line. The named vector layer must be accessible via the current mapset search path. The \fIlist\fR option is available in keyboard mode. The default vector line style is a continuous, solid line, but the user can specify a dashed line using the \fBstyle\fR parameter. The \fBstyle\fR parameter can contain a sequence of digits (0-9) that represent a colored pattern on the vectors. Colors can be assigned to each non-zero digit by using the \fBcolor\fR parameter multiple times. If the \fBcolor\fR parameter is used without a specified digit, the named color will be assigned to the entire lengths of the vectors. Colors are listed in the VALID COLOR NAMES section in this manual entry. The user can specify the vector line \fBwidth\fR in pixels. A highlight color can be assigned with \fBhcolor\fR, and the highlight's width in pixels can be assigned with \fBhwidth\fR. The user can also specify if the vectors are to be .B masked by the current mask. (See manual entry for \fIr.mask\fR for more information on the mask.) The \fBvector\fR instruction set must be completed by an \fBend\fR terminator. The \fBvector\fR instruction can be used more than once to portray multiple vector data layers. .LP This example would include a vector map layer named "streams" in the output map. These streams would be a total of four pixels wide (two blue pixels with a white outer highlight one pixel wide on each side). 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 The following example would portray a vector map layer named "roads". These roads would be two pixels wide and would be dashed blank-black-red (the blank areas would show other map elements under the roads). The roads would be visible inside and outside of the current mask. .TS l l. EXAMPLE: \fBvector\fR roads \ \ \fBwidth\fR 2 \ \ \fBstyle\fR 001122 \ \ \fBcolor\fR 1 black \ \ \fBcolor\fR 2 red \ \ \fBmasked\fR n \ \ \fBend\fR .TE .SH verbose Sets the amount of feedback sent out by \fIp.map.new\fR. .TS l l. USAGE: \fBverbose\fR \fI0\fR| \fI1\fR| \fI2\fR .TE A higher value set using \fBverbose\fR results in more feedback. The default is 2. This example sets the amount of feedback to a minimum. .TS l l. EXAMPLE: \fBverbose\fR 0 .TE .bp .SH VALID COLOR NAMES The following are the valid color names in \fIp.map.new\fR: .TS l l l l. aqua cyan indigo red black gray magenta violet blue green orange white brown grey purple yellow .TE any integer from 0 through 124, representing printer color numbers (see \fIp.colors\fR manual entry) .SH VALID FONT NAMES The following are the valid font names in \fIp.map.new\fR: .TS l l l l. cyrilc greekcs italict romant gothgbt greekp romanc scriptc gothgrt greeks romancs scripts gothitt italicc romand greekc italiccs romans (default) .TE .SH ICONS VS. PATTERNS Icons and patterns as used in \fIp.map.new\fR are not the same things. Patterns can only be used to cover the extended areas of a raster map layer category. A pattern will repeat above, below and adjacent to itself. Icons are used to represent single points. Patterns can be defined directly within .I p.map.new using the .B defpat instruction, while icons are created outside of \fIp.map.new\fR using the .I p.icons command or a system editor. .if t .bp .SH EXAMPLE p.map.new INPUT FILE The following is an example of a \fIp.map.new\fR script file. The file has been named "spear.soils". For the purposes of illustration only, the file is shown in two columns. This script file can be entered at the command line. \fBp.map.new input= spear.soils\fR .TS lw(18) lw(10) lw(50) lw(20) lw(10) lw(50). (cont.) \fBraster\fR soils \fBdefpat\fR diag \fBvector\fR streams 000001 \fBcolor\fR blue 00001 \fBwidth\fR 2 0001 \fBhcolor\fR white 001 \fBhwidth\fR 1 01 \fBmasked\fR y 1 \fBend\fR \fBcolor\fR 1 red \fBvector\fR roads \fBend\fR \fBwidth\fR 2 \fBsetpat\fR 4 diag \fBstyle\fR 001122 \fBtext\fR 608000 3476004 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 3423092 616969 3423092 \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 \fBicon\fR diamond This is a comment \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 enters .I p.map.new on the command-line without arguments, a prompting session occurs. Some, but not all, of the non-interactive requests are available in this mode. .SH "SEE ALSO" .I g.mapsets, .I g.region, .I p.chart, .I p.colors, .I p.icons, .I p.labels, .I p.ppm, .I p.select, .I r.mask .SH AUTHOR Michael Shapiro, U.S. Army Construction Engineering Research Laboratories .br Joo Joo Chia, U.S. Army Construction Engineering Research Laboratories