d.labels

NAME

d.labels - To create/edit GRASS paint label files for display on the graphics monitor.
(GRASS Display Program)

SYNOPSIS

d.labels

DESCRIPTION

The d.labels program allows the user to interactively create and modify paint-labels files for use with the p.map and d.paint.labels programs. The paint labels files created will be stored in the user's current mapset under the /paint/labels directory.

d.labels is fully interactive, and requires use of a graphics monitor. After the user has typed

d.labels

and has typed in the name of a new or existing paint-labels file, the user is asked to indicate label positions on the display frame using the mouse-pointer, and to edit label parameters that define the label's size, color, and other characteristics through use of a visual-ask (VASK) data entry screen. The mouse can also be used to indicate the geographic coordinates of locations within the current geographic region in the active frame. It is helpful to display a relevant data file in the active display frame before running d.labels to provide visual clues for label placement.

USER PROMPTS

You will first be prompted to enter the name of either an old paint-labels file that you wish to modify, or a new paint-labels file that you wish to create. The following is the file name prompt:

OPTION: Label text file name key: name required: YES enter option >: If you enter the name of a new (non-existent) paint-labels file, you are asked to indicate a location falling within the current geographic region in the active display frame at which the label is to be placed.

Mouse Buttons Left: Place Label Here Middle: Where Am I ? Right: Quit: Once you have indicated a position, you will be presented with a data-entry screen (also known as a VASK screen) so that you can enter the paint-label parameters that define how the label will appear on the display or on the color printer. Once you finish entering the label-parameters, and you hit the <ESC> key to proceed, the label will be displayed on the screen. If you like the appearance of the label, enter "y" to the "Look OK?" prompt; if not, enter "n" and you will again be presented with the data entry screen. Once you approve the label's appearance you will be asked to indicate the position of the next label.

If you choose to display an already-existing paint-labels file, you will be shown the labels. You will then have the option of editing a label or adding more labels.

Buttons Left: Edit Existing Labels Middle: Quit Right: Add more Labels

On-line help is available. If you are puzzled about what should go in a data entry field, just enter "help" in that field, hit the <ESC> key, and you will be presented with a short description of the field and what you may enter.

The following is a list of the different fields in the data entry screen and a short description of each.

TEXT:

The user can enter up to four lines of text.

SKIP: yes/no.

If no, label will be printed. If yes, the label will be retained in the file but not printed.

LOCATION:

Determines where the text will be located. The user specifies the easting and northing in map units, and (optionally) specifies a vertical and horizontal offset (in printer pixels) from the specified easting/northing. (The vertical (y) offset will shift the location to the south if positive, north if negative. The horizontal (x) offset will shift the location east if positive, west if negative.) These offsets are provided to allow finer placement of labels.

RESET LOCATION: yes/no.

If yes, the user will be allowed to use the mouse to select a new location for the label. The mouse buttons will function as follows:

Mouse Buttons Left: Place Label Here Middle: Where Am I ? Right: Quit

PLACEMENT:

Determines which part of the label to which the location refers. This may be specified as:

lower left (lower left corner of the text) lower right (lower right corner of the text) lower center (bottom center of the text)

upper left (upper left corner of the text) upper right (upper right corner of the text) upper center (top center of the text)

center (center of the text)

TEXT SIZE:

Determines the size of the lettering used in the label. Text size (height) is stated in units of (ground) meters; e.g., a text size of 500 sets the height of each line of text equal to 500 ground meters. Thus, text will appear to grow or shrink when displayed, depending on the user's current geographic region settings.

TEXT COLOR:

This selects the text color. This color can be specified in one of three ways:

By color name:
aqua black blue brown cyan gray green grey indigo magenta orange purple red violet white yellow
As red, green, blue percentages. For example: .5 .4 .7
(This form is not supported by d.paint.labels, but see p.map and p.labels.)
By printer color number, to get the exact printer color.
(This form is not supported by d.paint.labels, but see p.map and p.labels.)

Note. If the user sets the text color equal to the background color, the text will not appear on the graphics monitor.

WIDTH:

This determines the line thickness of the letters. The normal text width should be set to 1. Larger numbers can be used to simulate bold face. (d.paint.labels ignores this value and always uses 1.)

HIGHLIGHT COLOR:

The text can be highlighted in another color so that it appears to be in two colors. The text is drawn first in this color at a wider line width, and then redrawn in the text color at the regular line width. Highlight colors are not shown on the graphics display, they are only shown in the output from p.labels and p.map.

HIGHLIGHT WIDTH:

Specifies how far from the text lines (in pixels) the highlight color should extend. Highlight colors are not shown on the graphics display, they are only shown in the output from p.labels and p.map.

BACKGROUND COLOR:

Text may be boxed in a solid color by specifying a background color (see TEXT COLOR above to specify a color). Specify none to use no background.

OPAQUE TO VECTORS: yes/no.

This field only has meaning if a background color is selected. yes will prevent vector lines from entering the background. no will allow vector lines to enter the background.

BORDER COLOR:

Select a color for the border around the background. Specify none to suppress the border.

NOTES

This program is fully interactive and requires no command line arguments.

If the user types the word help in a data entry field while entering label information, acceptable field choices will be listed.

Labels must be placed within the current geographic region. If the user attempts to place a label outside of this region, the program will appear to loop endlessly. It is simply failing to display a label positioned beyond the boundaries of the current region; in this event, the user should simply reposition the label.

Labels created by this program are stored in ASCII files under the directory $LOCATION/paint/labels.

AUTHOR