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

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 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

USAGE:	colormode  approx| 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

USAGE:	colortable  [y| n]

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

H2>comments Prints comments beneath the map on hardcopy output.

USAGE:	comments  [commentfile]
	comments
	end

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

EXAMPLE:
	comments
	This is a comment.
	end

EXAMPLE:
	raster  vegetation
	comments  veg.comments
	end

defpat

USAGE:	defpat  name
	pattern
	color  #  color
	end

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

EXAMPLE:	
	defpat  vert
	1000
	color  1 green
	end

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

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

USAGE:	end

An end instruction completes the entire input to . 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

EXAMPLE:	
	endpanel 4

grid

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 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

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

labels

USAGE:	labels  labelfile| list

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

EXAMPLE:	
	labels  town.names

legend

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 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

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

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.mask for 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

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

outline

USAGE:	outline
	color  color
	end

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

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

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.icons or 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.mask for 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

USAGE:	raster  rastermap| list

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

USAGE:	read  filename

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

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.mask for 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

USAGE:	scale  scale

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

EXAMPLE:
	scale  15 centimeters

setcolor

USAGE:	setcolor  cat(s) color

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

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

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

EXAMPLE:	
	raster  soils
	read  horiz.pat
	setpat  5 horiz

EXAMPLE:	
	raster  soils
	setpat  builtin

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

sites

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

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.icons or 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

EXAMPLE:	
	startpanel 2

text

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 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

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

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.mask for 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

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

verbose

USAGE: verbose  0| 1| 2

This example sets the amount of feedback to a minimum.

EXAMPLE:	
	verbose  0

VALID COLOR NAMES

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

VALID FONT NAMES

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

ICONS VS. PATTERNS

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.icons command or a system editor.

EXAMPLE p.map.new INPUT FILE

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

SEE ALSO

AUTHOR