NAME

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

SYNOPSIS

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

DESCRIPTION

p.map produces hardcopy color map products on your system's color output device. Output can include a raster map, any number of vector overlays, site data, text labels, and other spatial data.

This program has 2 distincts modes of operation. The command-line mode requires the user to prepare a file of mapping instructions describing the various spatial and textual information to be printed prior to running p.map. The interactive mode (i.e., no command-line arguments) will prompt the user for items to be mapped and does not require the user to prepare a file of instructions.

The command-line parameters are:

input=name
File containing mapping instructions. (or enter input=- to enter from keyboard). These instructions are described in detail below.
scale=mapscale
Scale of the output map, e.g. 1:25000
Default: 1panel

This parameter is provided as a convenience. It is identical to the scale mapping instruction described below.

Note: the user must select an output device using p.select before running p.map. Also, the preview device can be selected to view the output from p.map on the graphics monitor instead of sending it to a paper printer.

MAPPING INSTRUCTIONS

The mapping instructions allow the user to specify various spatial data to be plotted. These instructions are normally prepared in a regular text file using a system editor. Some instructions are single line instructions while others are multiple line. Multiple line instructions consist of the main instruction followed by a subsection of one or more additional instructions.

colormode

Selects the appropriate method to color raster map layers and images. 

USAGE:	colormode approx | best

There are two methods: approximate and best. From a user perspective, approximate can be used for raster map layers with few categories, such as soils, and best should be used for images like LANDSAT images or NHAP photos, or maps with many categories. The approximate 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. The default, if unspecified, is best.

This example would select the approximate colormode. The assumption is that the raster map layer being printed is 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 legend below the map 

USAGE:	colortable [y|n]

The color table will display the colors for each raster map layer category value and the category label. To get a color table, you must have previously requested a raster map layer. Omitting the colortable instruction would result in no color table. Note: Be careful about asking for color tables for raster map layers which have many categories, such as elevation. This could result in the printing of an extremely long color table!!!!!

This example would print a color table as part of the legend to the map. 

EXAMPLE:
	colortable y

comments

Prints comments beneath the map . You may submit comment text line by line during p.map execution or a via a prepared comments file. 

USAGE:	comments [commentfile]
	comments
	end

This example prints the comment "This is a comment" in the legend below the map. 

EXAMPLE:	
	comments
	This is a comment.
	end

This example prints whatever is in the file veg.comments in the legend below the map. 

EXAMPLE:
	raster vegetation
	comments veg.comments
	end

Presumably, the file veg.comments contain comments pertaining to the raster map layer vegetation, such as "This map was created by classifying a LANDSAT TM image".

defpat

Defines area fill patterns to be used in the setpat instruction. 

USAGE:	defpat name
	pattern
	color # color
	end

The pattern is given a name on the defpat instruction line. The pattern which follows is composed of a sequence of numbers 0-9 (and blanks, which are equivalent to 0). The blanks or zeros indicate holes in the pattern where the normal category color would show thru. The other number 1-9 indicate pattern pixels and can be assigned any color. The default color for all the digits will be black unless specified with the color instruction. The color option will begin by entering the word color followed by one of the digits (1-9) in the pattern, followed by one of the NAMED COLORS. This should be repeated for each of the digits specified to avoid using black. The instruction end terminates the pattern definition. Of course, the user can define more patterns by entering more defpat instructions.

NOTE: Do NOT indent the pattern. Leading blank spaces will be interpreted as 0's.

This example creates a black horizontal line pattern. 

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

This 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

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 onto the output map. 

USAGE:	grid spacing
	color color
	numbers # [color]
	end

The spacing of the grid is given (in the geographic coordinate system units) on the main instruction line. The subsection instructions allow the user to specify the color of the grid lines, whether coordinate numbers should appear on the grid lines, and if they should appear every grid line (1), every other grid line (2), etc., and what color the numbers should be. The defaults are black grid lines, unnumbered.

This example would overlay a green grid with a spacing of 10000 meters (for a metered database, like UTM) onto the output map. Alternate grid lines would be numbered with red numbers. 

EXAMPLE:
	grid 10000   
	color green
	numbers 2 red
	end

labels

Selects a labels file for output (see manual entry for p.labels). 
USAGE:	labels  labelfile|list
This example would paint labels from the labels file called town.names. Presumably, these labels would indicate the names of towns on the map. 
EXAMPLE:
	labels town.names

line

Draws lines on the output map. 
USAGE:	line east north east north
	line x% y% x% y%
	color color
	width #
	masked [y|n]
	end
The beginning and ending points of the line are entered on the main instruction. These points can be defined either by map coordinates or by using percentages of the geographic region. The user may also specify line color, width in pixels, and if the line is to be masked by the current mask. (See manual entry for r.mask for more information on the mask.)

This example would draw a yellow line from the point x=10% y=80% to the point x=30% y=70%. This line would be 2 pixels wide and would appear even if there is a mask. 

EXAMPLE:
	line 10% 80% 30% 70%
	color yellow
	width 2
	masked n
	end
Of course, multiple lines may be drawn with multiple line instructions.

outline

Outlines the areas of a raster map layer with a specified color. 
USAGE:	outline
	color  color
	end
Distinct areas of the raster map will be separated from each other visually by drawing a border (or outline) in the specified color (default: black). Note: it is important the user enter the instruction end even if a color is not chosen. (It is hoped that in the future the outline of a different raster map layer other than the one currently being painted may be placed on the map.)

This example would outline the category areas of the soils raster map layer in grey. 

EXAMPLE:
	raster soils
	outline   
	color grey
	end

point

Places additional points or icons on the output map. 

USAGE:	point east north
	point x% y%
	color color
	icon iconfile|list
	size #
	masked [y|n]
	end
The point location is entered in the main instruction line by giving either the map coordinates or by using percentages of the geographic region. The user may also specify the point color, the icon file to be used to represent the point location (see the the manual entry for p.icons), the size of the icon in integer multiples of the pattern in the icon file, and whether the point is to be masked by the current mask. (See manual entry for r.mask for more information on the mask.)

This example would place a purple diamond (from icon file diamond) at the point (E456000 N7890000). This diamond would be the same size it is in the diamond icon file and would not be masked by the current mask. 

EXAMPLE:
	point 456000 7890000
	color purple     
	icon diamond
	size 1
	masked n
	end
Of course, multiple points may be drawn with multiple point instructions.

raster

Selects a raster map layer for output. 
USAGE:	raster mapname|list
For each p.map run, only one raster map layer can be requested. If no raster map layer is requested, a completely white map will be produced. It can be useful to select no raster map layer in order to provide a white background for vector images.

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

EXAMPLE:	
	raster soils

read

Provides p.map with a previously prepared input stream. 
USAGE:	read previously prepared UNIX file
Mapping instructions can be placed into a file and read into p.map.

Note: p.map will not search for this file. The user must be in the correct directory or specify the full path on the read instruction. (Note to /bin/csh users: ~ won't work with this instruction).

This example reads the UNIX file pmap.roads into p.map. This file may contain all the p.map instructions for placing the vector map layer roads onto the output map. 

EXAMPLE: 
	read pmap.roads
The user may have created this file because this vector map layer is particularly useful for many p.map outputs. By using the read option, the user need not enter all the input for the vector instruction, but simply read the previously prepared file with the correct instructions.

region

Places the outline of a smaller geographic region on the output. 
USAGE:	region regionfile | list
	color color
	width #
	end
Geographic region settings are created and saved using g.region. The p.map region option can be used to show an outline of a smaller region which was printed on a separate run of p.map on other user-created maps.

The user can specify the color and the width (in pixel units) of the outline. The default is a black border of one pixel width.

This example would place a white outline, 2 pixels wide, of the geographic region called fire.zones onto the output map. This geographic region would have been created and saved using g.region. 

EXAMPLE:
	region fire.zones
	color white
	width 2
	end

scale

Selects a scale for the output map. 
USAGE:	scale scale

The scale can be selected either as:

a relative ratio, e.g. 1:25000;
an absolute width of the printed map, e.g. 10 inches;
the number of printed paper panels, e.g. 3 panels;
the number of miles per inch, e.g. 1 inch equals 4 miles.

This example would set the scale of the map to 1 unit = 25000 units. 

EXAMPLE:
	scale 1:25000

setcolor

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

USAGE:	setcolor cat(s) color

This example would set the color for categories 2,5 and 8 of the raster map layer watersheds to white and category 10 to green. (NOTE: no spaces are inserted between the category values.) 

EXAMPLE:	
	raster watersheds
	setcolor 2,5,8 white
	setcolor 10 green

Of course, setcolor can be requested more than once to override the default color for additional categories. More than one category can be changed for each request by listing all the category values separated by commas (but with no spaces).

setpat

Assigns a (previously defined) pattern on a raster map layer category. 
USAGE:	setpat cat name
  or	setpat builtin
  or	setpat all
The user can choose to use: the name of a specific pattern created using defpat (see above); the patterns built into p.map; or all the patterns the user may have created.

This example assigns the vertical pattern created using defpat (see example in defpat above) to category 3 of the raster map layer vegetation and the tree pattern (see example in defpat above) to category 10. 

EXAMPLE:
	raster veg
	setpat 3 vert
	setpat 10 tree
This example reads a previously prepared UNIX file horiz.pat with the correct defpat instructions for creating a black horizontal pattern (see example in defpat above) and assigns that pattern to category 5 of the raster map layer soils via the setpat instruction. 
EXAMPLE:
	raster soils
	read horiz.pat
	setpat 5 horiz
To select the builtin patterns: 
EXAMPLE:	
	raster soils
	setpat builtin
To select individual builtin patterns: 
EXAMPLE:
	raster soils
	setpat 5 #1
	setpat 10 #2

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.

sites

Selects sites data to be placed on the output map (see manual entry for s.menu). 
USAGE:	sites sitemap |list
	color color
	icon iconfile |list
	size #
	desc [y|n]
	end
The user may specify the the color of the sites (see section on NAMED COLORS below); the icon to be used to represent the presence of a site (see the manual entry for p.icons); the size of the icon (number of times larger than the size it is in the icon file); and whether or not the description associated with each site is also to be printed.

This example would paint a sites map with blue windmills (from an icon file created by the user using the p.icons GRASS command) placed at all windmill locations (from a sites list). These windmills would be two times larger than the size of the icon in the icon file and have descriptions from the sites list file printed beside them. 

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

text

Places text on the map. 

USAGE:	text  east north text
	text  x% y% text
	font fontname
	color color|none
	width #
	hcolor color|none
	hwidth #
	background color|none
	border color|none
	size #
	ref reference point
	xoffset #
	yoffset #
	opaque [y|n]
	end
The user specifies where the text will be placed by providing map coordinates or percentages of the geographic region map. The text follows these coordinates on the same instruction line. More than one line of text can be specified by notating the end of a line with \en (e.g. USA\|\enCERL).

The user can then specify various text features:

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

color (see NAMED COLORS);

width of the lines used to draw the text (to make thicker letters);

size as the vertical height of the letters in meters on the ground (text size will grow or shrink depending on the scale at which the map is painted);

the highlight color (hcolor) and the width of the highlight color (hwidth);

the text-enclosing-box background color; the text box border color;

ref. This reference point specifies the text handle - what part of the text should be placed on the location specified by the map coordinates. Reference points can refer to: [lower|upper|center]\ [left|right|center] of the text to be printed;

yoffset, which provides finer placement of text by shifting the text a vertical distance in pixels from the specified north. The vertical offset will shift the location to the south if positive, north if negative;

xoffset, which shifts the text a horizontal distance in pixels from the specified east The horizontal offset will shift the location east if positive, west if negative;

whether or not the text should be opaque to vectors. Entering no to the opaque option will allow the user to see any vectors which go through the text's background box. Otherwise, they will end at the box's edge.

This example would place the text SPEARFISH LAND COVER at the coordinates E650000 N7365000. The text would be a total of 3 pixels wide (2 pixels of red text and 1 pixel black highlight), have a white background enclosed in a red box, and be 500 meters in size. The lower right corner of the text would be centered over the coordinates provided. All vectors on the map would stop at the border of this text. 

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

vector

Selects a vector map layer for output. 
USAGE:	vector vectormap|list
	color [#] color
	width #
	hcolor color
	hwidth #
	masked [y|n]
	style  0-9
	end

The user can specify the color of the vectors; the width of the vectors lines in pixels; the highlight color (hcolor) for the vector.lines; the width of the highlight color (hwidth) in pixels; whether or not the raster map layer is to be masked by the current mask (see manual entry r.mask for more information on the mask); and the line style. The line style allows the vectors to be dashed in different patterns and colors. This is done by typing a series of numbers (0-9) in a desired sequence or pattern. Colors for the numbers (1-9) can be assigned using the color instruction. Blanks and non-digit characters are recognized as 0's. Using 0 would allow the colors of the raster map layer (or the background color if no raster map layer was selected) to show through.

This example would paint a map of the vector map layer named streams. These streams would be a total of 3 pixels wide (the inner two pixels blue and the outer highlight pixel white). The map would not show streams outside of the current mask. 

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

This example would paint a map of the vector map layer roads. These roads would be 2 pixels wide and would be dashed blank-black-red (the blank areas would show what lies under the roads). This map would show roads inside and outside of the current mask. 

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

verbose

Changes the amount of talking p.map will do. 

USAGE: verbose [0|1|2]
A higher value implies more chatter. The default is 2. This example sets the amount of chatter to a minimum. 
EXAMPLE:
	verbose 0

end

Terminates input and begin painting the map. 
USAGE:	end

NAMED COLORS

The following are the colors that are accepted by p.map: 
	aqua
	black
	blue
	brown
	cyan
	gray
	green
	grey
	indigo
	magenta
	orange
	purple
	red
	violet
	white
	yellow

ICONS VS. PATTERNS

Icons and patterns as used in p.map are not the same thing. Patterns are defined and are normally used to cover those extended areas covered by a raster map layer category. A pattern will repeat above, below and adjacent to itself. Icons are used to represent a single point.

Patterns are supported directly within p.map using the defpat instruction, while icons must be created using the p.icons program.

EXAMPLE p.map INPUT FILE

The following is an example of a p.map script file. The file has been name spear.soils. For the purposes of illustration, the file is in two columns. This script file can be entered at the command line:

p.map 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.00 3476004.73 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.73 3423092.91 616969.73 3423092.91
   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 simply enter p.map without arguments, then a simple prompting session occurs. Some, but not all of the non-interactive requests are available at this level.

SEE ALSO

p.chart
p.icons
p.labels
p.select

AUTHOR

Michael Shapiro, U.S.Army Construction Engineering Research Laboratory