d.icons

NAME

d.icons - Displays points, as icons, at user-defined locations in the active display frame on the graphics monitor.
(GRASS Display Program)

SYNOPSIS

d.icons
d.icons help
d.icons [-r] icon=name [color=name] [size=value] [points=name]

DESCRIPTION

d.icons graphically displays point (site) locations as icons in the active frame on the graphics monitor. Geographic coordinates are read either from standard input or from an input file whose name is stated by the user. At each site location, a user-defined icon is displayed.

OPTIONS

The user must enter at least the name of an icon file storing a graphic representation of the icon to be displayed, and the geographic coordinates of the points at which they will appear.

The user can run this program either non-interactively or interactively. The program will be run non-interactively if the user specifies the name of an icon file and (optionally) any other desired parameters on the command line, using the form:

d.icons [-r] icon=name [color=name] [size=value] [points=name]

If the user fails to specify the name of a points file on the command line, the program will prompt the user to enter geographic coordinates from standard input. If the user specifies at least the name of an icon file on the command line, any other parameter values left unspecified by the user will be set to their default values (see below).

Alternately, the user can simply type:

d.icons

on the command line, without program arguments. In this case, the user will be prompted for needed parameter values using the standard GRASS user interface described in the manual entry for parser. The geographic coordinates at which icons are to be displayed can still be input from an input file (points) in interactive use.

Flag:

-r: Coordinates are input in reverse order (i.e., as northing easting).

Parameters:

icon=name: The name of an existing file containing a graphic representation of the icon to be drawn. icon files can be created by the user using the p.icons command and are stored under the icons directory under the user's current mapset.
color=name: Sets the current icon color to the name stated.
Options: red, orange, yellow, green, blue, indigo, violet, gray, white, and black
Default: white
size=value: The icon scaling factor.
Options: 1-1000
Default: 1
points=name: The name of a UNIX file containing the geographic coordinates of sites at which icons are to be drawn. Since this is a UNIX file, the user should specify the name using standard UNIX file naming conventions. If this file is not in the user's current working directory, its pathname should be specified. The file contents should consist of a series of geographic coordinates that fall within the boundaries of the current geographic region. Each site location should be stated on a separate line as an easting and northing (in that order) separated by a single blank space. If no points file is specified by the user, input is taken from standard input and should be given in the same form; to end standard input, type end (or press control-d).

EXAMPLE

An icons file contains a graphic representation of the icon to be displayed. Here, spaces represent areas of no color, and x's represent areas of color. For example, the user might construct an icon resembling a cross in the following way:

  x 
  x 
xxxxx 
  x 
  x 
  x

This icon might be stored in a file called cross (under the user's $LOCATION/icons directory). If the user specified that this be the icon file used while running d.icons, this cross would then appear in the color and size specified by the user, at each site location named in the points file.

Note: icons are created with the p.icons command.

The points file lists the geographic coordinates of site locations (at which icons will be displayed). This file should take the form:

easting northing 
easting northing 
easting northing 
...

If the user sets the -r flag, the order of these coordinates should be reversed (i.e., coordinates should be given as northing easting).

If the points file is not specified, then the corrdinates are read from the keyboard or across a pipe. This feature allows users to enter the coordinates by hand, or, more usefully, to get then from another program. For example, to display icons at locations specified in a sites list:

s.out.ascii name | d.icons icon=cross

where name is the name of a site list, and cross is the name of an icon.

AUTHOR

Contributed by:

Dave Johnson
DBA Systems, Inc.
10560 Arrowhead Drive
Fairfax, Virginia 22030

Modified by:

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