## NAME

p.map.new - Color map output utility.
(GRASS Hardcopy Output Program)

## SYNOPSIS

p.map.new
p.map.new [input= name] [scale= mapscale]

## DESCRIPTION

The 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 input parameter. The p.map.new instructions would then be entered via the keyboard.

The command-line parameters are:

input=name
  File containing mapping instructions (or enter input=- to enter instructions from the keyboard). These instructions are described in detail below.
scale=mapscale
  Scale of the output map, e.g. 1:25000
  Default: 1 panel
  The options for this parameter are identical to the scale mapping instruction described below. If a scale instruction is present in an input file, it is superseded by the command-line scale parameter.

An output device can be selected using p.select before running p.map.new. Valid devices include on-line hardcopy devices, plus preview, preview2, and ppm. See manual entry for p.select.

The current geographic region determines the area that is mapped using p.map.new

## 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 end terminator.

Some instructions, such as those using data layers, icons, or labels, access files via the current mapset search path.

## barscale

Places a barscale on the output map.

    USAGE:  barscale  east north
            barscale  x% y%
            unit  ft| mi| m| km
            length  #
            interval  #
            style  dash| tick
            width  #
            color  color
            textsize  #
            textcolor  color| none
            textfont  font
            background  color| none
            border  color| none
            end

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 unit of measurement, the total length using that unit, and the length of one interval (a smaller length evenly divisible into the total length).

The style of the scale bar can be specified. The dash style has solid lines representing each interval, separated by gaps. The tick style has a solid total length with vertical ticks marking each interval.

The user can also specify the width of the bar in pixels, its color (see VALID COLORS NAMES), the textcolor, textsize in geographic units, textfont (see VALID FONT NAMES), background color, and border color.

The barscale instruction set must be completed with the end 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.

    EXAMPLE:
            barscale  605000 4915000
            unit  km
            length  2
            interval  1
            style  tick
            width  2
            color  black
            textcolor  black
            textsize  150
            background  white
            border  red
            end

## colormode

Selects the method to portray the colors of the raster map layer or image.

    USAGE:  colormode  approx| best

There are two options for colormode: approx and best. The approx option should be used for raster map layers with few categories, and best should be used for images like LANDSAT images or NHAP photos, or maps with very many categories. The approx mode treats each pixel independently, giving it the printer color that best approximates the true color. The 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 best.

This example would select the approx colormode. The assumption is that the raster map layer being printed has few colors or that the colors would not look good dithered.

    EXAMPLE:
            colormode  approx

## colortable

Includes the color table for the raster map layer in the area below the map on hardcopy output.

    USAGE:  colortable  [y| n]

The color table will display the colors for each raster map layer category and the category value. The colortable instruction can not precede the raster instruction in the 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.

    EXAMPLE:
            colortable  y

## comments

Prints comments beneath the map on hardcopy output.

    USAGE:  comments  [commentfile]
            comments
            end

Comment text can be entered in the p.map.new file or from a separate, previously prepared file. Comments are not shown when the output device is the color monitor. The comments instruction set must be completed by the end terminator.

This example prints the comment "This is a comment" below the data area on the the map.

    EXAMPLE:
            comments
            This is a comment.
            end

This example prints the text in a file called "veg.comments" in the current directory.

    EXAMPLE:
            raster  vegetation
            comments  veg.comments
            end

## defpat

Defines an area fill pattern to be used in setpat instructions.

    USAGE:  defpat  name
            pattern
            color  #  color
            end

An area fill pattern is given a name on the defpat instruction line. This name can then be used in subsequent setpat instructions. The defpat 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 color 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 color option.

The defpat instruction set must be completed by the end terminator.

In the p.map.new input, the defpat instruction must precede any setpat 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.

    EXAMPLE:
            defpat  horiz
            1
            0
            0
            0
            color  1 black
            end

This example creates a green vertical line pattern.

    EXAMPLE:
            defpat  vert
            1000
            color  1 green
            end

The following example creates a red diagonal line pattern.

    EXAMPLE:
            defpat  diag
            00001
            0001
            001
            01
            1
            color  1 red
            end

This example creates a two-toned tree pattern with orange "trunks" and green "leaves".

    EXAMPLE:
            defpat  tree
                 2
                222
               22122
              22 1 22
                  1

                           2
                          222
                         22122
                        22 1 22
                            1
            color  1 orange
            color  2 black
            end

## end

Terminates input and begins the painting of the map to the output device.

    USAGE:  end

An end instruction completes the entire input to p.map.new. It is normally the last line in an input file, but it can be moved forward to eliminate any instructions following its position.

The end instruction for the entire input should not be confused with end terminators that are required with all multiple-line instruction sets.

## endpanel

Specifies which panel number to end printing. The default is 0, and will print all panels from the startpanel to the last panel.

    EXAMPLE:
            endpanel 4

This example would end output at panel 4.

## grid

Overlays a coordinate grid on the output map.

    USAGE:  grid  spacing
            pattern  notick| tick # #
            masked  [data| nodata| all]
            style  sequence
            width  #
            color  color
            numbers  #  [color] [in| out]
            numbersbg  color| none
            numbersize  #
            end

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 pattern parameter. The notick option is for a complete net of intersecting lines. The tick option is for smaller tick marks where grid intervals intersect. The horizontal and vertical lengths, in pixels, must be specified with the tick option.

The user can control the areas covered by the grid by using the masked parameter. With the data option of masked, the grid will be seen over all areas of the map's raster layer except the no-data (category 0) areas. With the nodata option, the grid will be seen only over the no-data areas. The entire grid is seen with the all option to masked.

The grid line style 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 width (in pixels) and color of the grid lines can also be specified.

The user can control the placement and look of grid label numbers using the numbers, numbersbg, and numbersize parameters. The numbers 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 numbersbg parameter. The user controls the grid label size using the numbersize parameter, in geographic units.

The grid instruction set must be concluded by the end 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.

    EXAMPLE:
            grid  5000
            pattern  tick 10 10
            masked  all
            width  1
            color  purple
            numbers  1 purple in
            numbersbg  none
            numbersize  350
            end

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.

    EXAMPLE:
            grid  1000
            pattern  notick
            masked  nodata
            style  11111100
            width  1
            color  black
            numbers  2 black in
            numbersbg  white
            numbersize  200
            end

## labels

Selects a labels file for output.

    USAGE:  labels  labelfile| list

The labels instruction includes previously prepared label specifications. See manual entry for p.labelsfor correct format of the labels file. The labels file must be accessible via the current mapset search path. The list option is available in keyboard mode.

This example would paint labels from a labels file called town.names.

    EXAMPLE:
            labels  town.names

## legend

Places a user-designed map legend on the output.

    USAGE:  legend  east north
            legend  x% y%
            height  #
            width  #
            vlen  #
            textcolor  color
            textsize  #
            textwidth  #
            xspace  #
            yspace  #
            background  color
            border  color
            beginrast
            ramp  value| label vertical| horizontal
            catnum  cat description
            end
            beginvect
            vectname  vectormap description
            vectTITLE  vectormap
            end
            beginsite
            sitename  sitemap description
            end
            end

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 height and width 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 vlen parameter. The user controls horizontal spacing between legend symbols and legend text using xspace. The yspace 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 textcolor, textsize, and textwidth parameters. Colors are listed in the VALID COLOR NAMES section of this manual entry. The textsize is specified in pixels. The textwidth is also specified in pixels.

The user can specify the color for the background box containing the entire legend. If a color is chosen, underlying map elements are opaqued. The user can also specify a border color for the legend box.

The user specifies the symbols to be included in the legend using the beginrast, beginvect, and beginsite parameters. Each of these parameters starts a subsection of the legend instruction that must be completed by an end terminator. These should not be confused with the end terminator for the entire legend instruction set.

If the user simply uses the beginrast parameter followed by end, 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 cats file. The user can include specific categories and optional labels by using one or more catnum lines, each including a category number and the accompanying legend text. If the map's raster layer portrays a continuous range of data, a ramp in the legend might be appropriate. The ramp can be vertical or horizontal, and it's accompanying text can be either the smallest and largest category values, or the cats labels associated with the smallest and largest categories. The beginrast subsection must be completed with an end terminator.

Symbols for vector data on the map can be included in the legend by using the beginvect parameter. If the user simply follows beginvect with end, 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 vectname line one or more times, each including a vector layer name and an accompanying description. The vector layer TITLEs as written in dig_cats files can be included as the legend text by using the vectTITLE line one or more times. The beginvect subsection must be completed with an end terminator.

Site symbols are included in the legend by using one or more sitename lines in the beginsite subsection. Each line includes the name of the site list and an accompanying description. The beginsite subsection must be completed with an end terminator.

The entire legend instruction set must be completed by an end terminator.

In the ps.map.new input, the legend 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.

    EXAMPLE:
            legend  589000 4921200
            height  10
            width  20
            vlen  20
            xspace  10
            yspace  7
            textcolor  black
            textsize  250
            textwidth  1
            background  white
            border  red
            beginsite
            sitename  archsites Arch. site
            end
            beginrast
            catnum  4 Sandstone
            catnum  5 Limestone
            catnum  6 Shale
            end
            beginvect
            vectname  roads Road
            end
            end

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.

    EXAMPLE:
            legend  589000 4921200
            height  10
            width  20
            xspace  10
            textcolor  black
            textsize  250
            textwidth  1
            background  gray
            border  black
            beginrast
            ramp  label vertical
            end
            end

## line

Draws a line that is independent of any vector map layer on the output map.

    USAGE:  line  east north east north
            line  x% y% x% y%
            style  sequence
            color  [# ] color
            width  #
            hcolor  color
            hwidth  #
            masked  [y| n]
            end

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 style parameter. The style 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 color parameter multiple times. If the color 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 width in pixels. A highlight color can be assigned with hcolor, and the highlight's width in pixels can be assigned with hwidth. The user can also specify if the line is to be masked by the current mask. (See manual entry for r.maskfor more information on the mask.)

The line instruction set must be completed by an end terminator.

The line 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.

    EXAMPLE:
            line  10% 80% 30% 70%
            color  blue
            width  2
            masked  n
            end

The following example would draw a line with yellow dashes on a black background.

    EXAMPLE:
            line  605000 4915000 595300 4918200
            style  1111100
            color  1 yellow
            width  1
            hcolor  black
            hwidth  1
            end

## outline

Outlines areas of a raster map layer with a specified color.

    USAGE:  outline
            color  color
            end

The outline 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 color parameter. The default color is black.

The outline instruction set must be completed by the end terminator, even if the color parameter is not used.

The outline instruction can not precede a raster instruction in a p.map.new input file.

The instruction sequence in this example would outline in grey the category areas of a raster map layer called "soils".

    EXAMPLE:
            raster  soils
            outline
            color  grey
            end

## point

Places a point symbol on the output map.

    USAGE:  point  east north
            point  x% y%
            icon  iconfile| list
            color  color
            size  #
            masked  [y| n]
            end

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 icon parameter. The user can use any icon in an icons directory within the current mapset search path. Icons can be created using p.iconsor by simply using a system editor. The default icon is a diamond. The list option for icon is available in keyboard mode.

The user can specify the symbol color. Colors are listed in the VALID COLOR NAMES section of this manual entry.

The icon size 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 masked by the current mask. (See manual entry for r.maskfor more information on the mask.)

The point instruction set must be completed be an end terminator. Multiple points may be drawn with multiple point 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.

    EXAMPLE:
            point  603000 4921750
            icon  box
            color  red
            size  1
            masked  n
            end

## raster

Selects a raster map layer for output.

    USAGE:  raster  rastermap| list

Only one GRASS raster map layer can be specified in a p.map.new input file. If no raster map layer is requested, a white background will be produced. The list option is available in keyboard mode.

The raster layer must be accessible within the current mapset search path. In a p.map.new input file, the raster instruction must precede these instructions: colortable, outline, setcolor, and setpat. It also must precede any legend instruction set that applies to the raster map layer.

This example would paint a map of the raster map layer soils.

    EXAMPLE:
            raster  soils

## read

Provides input to p.map.new from a previously prepared instruction file.

    USAGE:  read  filename

Mapping instructions can be placed in a file and read as input to 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 read instruction.

Note: p.map.new 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 read 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 p.map.new.

    EXAMPLE:
            read  pmap.roads

## region

Places the outline of a geographic region on the output map.

    USAGE:  region  regionfile| list
            style  sequence
            color  [# ] color
            width  #
            hcolor  color
            hwidth  #
            masked  [y| n]
            end

The user can place the outline of a saved geographic region on the map using region. The named region file must be in a windows directory within the current mapset search path. Geographic region settings can be created and saved using g.region. The list 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 style parameter. The style 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 color parameter multiple times. If the color 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 width in pixels. A highlight color can be assigned with hcolor, and the highlight's width can be assigned with hwidth. The user can also specify if the outline is to be masked by the current mask. (See manual entry for r.maskfor more information on the mask.)

The region instruction set must be completed by an end terminator.

The region 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".

    EXAMPLE:
            region  fire.zones
            color  white
            width  2
            end

## scale

Specifies the scale of the hardcopy output map.

    USAGE:  scale  scale

The scale of the output map can be specified in one of several different forms:

  relative ratio e.g. 1:25000
  number of geographic units per map unit e.g. 1 inch equals 4 miles
  absolute width of the printed map e.g. 10 inches
  width in number of printed panels e.g. 3 panels

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 scale instruction does not affect output to the preview device. If used, the command-line scale parameter overrides the scale instruction.

This example would set the scale of the map to one map unit represents 25,000 geographic units.

    EXAMPLE:
            scale  1:25000

The following example would specify an output map that would be fifteen centimeters wide.

    EXAMPLE:
            scale  15 centimeters

## setcolor

Overrides the color assigned to one or more categories of the raster map layer.

    USAGE:  setcolor  cat(s) color

The user can assign a desired color to categories in a raster map layer by using setcolor. 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 setcolor instruction can be used more than once for assignment of multiple colors.

In the input p.map.new file, the setcolor instruction must follow the raster 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.

    EXAMPLE:
            raster  watersheds
            setcolor  1-3,5 green
            setcolor  4,6,8 blue
            setcolor  7 red

## setpat

Assigns a previously defined pattern to one or more raster map layer categories.

    USAGE:  setpat  cat(s) name
            setpat  cat(s) #number
            setpat  all| builtin

The user can assign a pattern to categories in a raster map layer by using setpat. Categories are specified on the parameter line before the name of a pattern defined earlier using defpat, or before the number signifying a built-in p.map.new 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 setpat instruction line. By using the builtin 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 all option is used. In this case, only one pattern should be defined within the p.map.new mapping instruction file.

The setpat instruction can be used more than once for assignment of multiple patterns.

In the input p.map.new file, the setpat instruction must follow the raster instruction, as well as the defpat 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.

    EXAMPLE:
            raster  veg
            setpat  3-4 vert
            setpat  10 tree

This example reads a previously prepared ASCII file called horiz.pat containing defpat instructions for creating a black, horizontal pattern called "horiz", and assigns that pattern to category 5 of the raster map layer "soils".

    EXAMPLE:
            raster  soils
            read  horiz.pat
            setpat  5 horiz

This example assigns built-in pattern 1 to category 1 of the "soils" raster layer, pattern 2 to category 2, and so on.

    EXAMPLE:
            raster  soils
            setpat  builtin

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.

    EXAMPLE:
            raster  soils
            setpat  5-7 # 1
            setpat  10,12 # 2

## sites

Selects sites data to be placed on the output map.

    USAGE:  sites  sitemap| list
            icon  iconfile| list
            color color
            size  #
            desc  [y| n]
            textcolor  color
            textsize  #
            end

GRASS sites data can be portrayed on the map using the sites 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 list option is available in keyboard mode.

An icon can be specified with the icon parameter. The user can use any icon in an icons directory within the current mapset search path. Icons can be created using p.iconsor by simply using a system editor. The default icon is a diamond. The list option for icon is available in keyboard mode.

The user can specify the symbol color. Colors are listed in the VALID COLOR NAMES section of this manual entry.

The icon size 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 desc parameter is used to specify whether or not the description of each site in the site_lists 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 textcolor parameters. Valid colors are listed in the named colors section of this manual entry. The label size is specified in geographic units using textsize.

The sites instruction set must be completed by the end 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 site_lists 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.

    EXAMPLE:
            sites  windmills
            icon  windmill
            color  blue
            size  2
            desc  n
            end

## startpanel

Specifies at which panel number to begin printing. Default is 0 and would start printing from the first panel.

    EXAMPLE:
            startpanel 2

This example would begin printing at panel 2.

## text

Places text at a user-specified location on the map.

    USAGE:  text  east north text
            text  x% y%  text
            textfont  font
            size  #
            color  color| none
            width  #
            hcolor  color| none
            hwidth  #
            ref  reference_point
            rotation  #
            xoffset  #
            yoffset  #
            background  color| none
            opaque  [y| n]
            border  color| none
            end

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 \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 textfont (see VALID FONT NAMES in this manual entry), size in geographic units, color (see VALID COLOR NAMES), and width in pixels. The user can further control the text appearance by specifying a highlight color (hcolor) and the width of the highlight color (hwidth).

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 ref parameter, has two parts. The first part refers to a vertical location on the text string. Valid choices are lower, center, and upper. The second part refers to a horizontal location: left, center, and right.

The text string can be rotated at the reference point by using the rotation parameter. The value specified will be the counter-clockwise rotation in degrees from the horizontal.

The xoffset parameter provides finer placement of text by shifting the text a horizontal distance in pixels from the specified easting. The xoffset will shift the text location east if positive and west if negative. The yoffset parameter shifts the text a vertical distance in pixels from the specified northing. The yoffset will shift the location to the south if positive, north if negative.

The user can specify if a background box is present, and what color it should be. The user can also specify whether or not the background box is opaque to other map elements. The color of the border of this box can be specified.

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.

    EXAMPLE:
            text  650000 7365000 SPEARFISH LAND COVER
            textfont  romand
            color  red
            width  1
            size  500
            ref  lower left
            hcolor  black
            hwidth  1
            background  white
            border  red
            opaque  y
            end

## vector

Selects a vector map layer for output.

    USAGE:  vector  vectormap| list
            style  sequence
            color  [# ] color
            width  #
            hcolor  color
            hwidth  #
            masked  [y| n]
            end

GRASS vector data can be portrayed on the map using the vector 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 list 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 style parameter. The style 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 color parameter multiple times. If the color 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 width in pixels. A highlight color can be assigned with hcolor, and the highlight's width in pixels can be assigned with hwidth. The user can also specify if the vectors are to be masked by the current mask. (See manual entry for r.maskfor more information on the mask.)

The vector instruction set must be completed by an end terminator.

The vector instruction can be used more than once to portray multiple vector data layers.

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.

    EXAMPLE:
            vector  streams
            color  blue
            width  2
            hcolor  white
            hwidth  1
            masked  y
            end

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.

    EXAMPLE:
            vector  roads
            width  2
            style  001122
            color  1 black
            color  2 red
            masked  n
            end

## verbose

Sets the amount of feedback sent out by p.map.new.

    USAGE: verbose  0| 1| 2

A higher value set using verbose results in more feedback. The default is 2.

This example sets the amount of feedback to a minimum.

    EXAMPLE:
            verbose  0

## VALID COLOR NAMES

The following are the valid color names in p.map.new:

    aqua    cyan    indigo  red
    black   gray    magenta violet
    blue    green   orange  white
    brown   grey    purple  yellow

any integer from 0 through 124, representing printer color numbers (see p.colorsmanual entry)

## VALID FONT NAMES

The following are the valid font names in p.map.new:

    cyrilc  greekcs italict romant
    gothgbt greekp  romanc  scriptc
    gothgrt greeks  romancs scripts
    gothitt italicc romand
    greekc  italiccs        romans (default)

## ICONS VS. PATTERNS

Icons and patterns as used in p.map.new 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 p.map.new using the defpat instruction, while icons are created outside of p.map.new using the p.iconscommand or a system editor.

## EXAMPLE p.map.new INPUT FILE

The following is an example of a p.map.new 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.

p.map.new input=spear.soils

                    (cont.)
    raster soils            defpat diag
    vector streams          000001
       color blue           00001
       width 2              0001
       hcolor white         001
       hwidth 1             01
       masked y             1
       end                     color 1 red
    vector roads               end
       width 2              setpat 4 diag
       style 001122         text 608000 3476004 SPEARFISH SOILS MAP
       color 1 black           color red
       color 2 red             width 2
       masked n                hcolor black
       end                     hwidth 1
    labels town.names          background white
    region subregion           border red
       color white             size 500
       width 2                 ref lower left
       end                     opaque y
    grid 10000                 end
       color green          line 606969 3423092 616969 3423092
       numbers 2 red          color yellow
       end                     width 2
    outline                    opaque yes
       color black             end
       end                  point 40% 60%
    colortable\ y              color purple
    comments                   icon diamond
       This is a comment       size 2
       end                     masked n
    scale 1:25000              end
    setcolor 6,8,9 white    end
    setcolor 10 green

## INTERACTIVE MODE

If the user enters 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.

## SEE ALSO

g.mapsets
g.region
p.chart
p.colors
p.icons
p.labels
p.ppm
p.select
r.mask

## AUTHOR

Michael Shapiro, U.S.Army Construction Engineering Research Laboratory
Joo Joo Chia, U.S. Army Construction Engineering Research Laboratories

Last changed: $Date: 2002/01/25 05:45:33 $