r.support

NAME

r.support - Allows the user to create and/or modify raster map layer support files.
(GRASS Raster Program)

SYNOPSIS

r.support [-r] map=name

OPTIONS

Flag:

-r Update the stats (histogram, range)

DESCRIPTION

The GRASS program r.support allows the user to create and/or modify raster map layer support files. It may be run only on raster map layers in the user's current mapset.

Most options have to be used interactively, so the user runs the program by typing r.support, and will be queried for inputs.

Various GRASS programs depend on one or more of the following GRASS support files:

cellhd: The cell header file contains information on a map's projection, zone, regional boundaries, row and column totals, cell resolution, storage format, and compression. It describes where and how this map's raster (cell) data fits in with reference to other raster map layers' data. Without it, the raster map layer could not be displayed or analyzed properly. Using r.support, the user can change the # of columns, # of bytes per cell, and default geographic region settings. Generally, users would not change this information. Cell header files are stored under the cellhd directory under the user's current mapset.
stats: Raster map layer statistics are saved in the form of a histogram and range of the category values which occur in the map layer. Statistics files are stored in subdirectories of the cell_misc directory under the user's current mapset. This option is (currently) the only option which can be used on command line (-r flag).
cats: A category file associates each category value in the raster map layer with a category description (label). The user may add or edit the category descriptions, alter the number of categories, and add or alter the map's TITLE. Category files associated with raster map layers are stored under the cats directory in the user's current mapset.
colr: A color file associates each category value in the raster map layer with a color. Using r.support, the user may assign one of eight color table types to the raster map layer. Map color table files are stored under the colr and colr2 directories under the user's current mapset.
hist: Historical information about the raster map layer is stored in a history file. The user may add or edit the raster map's TITLE, data type, data source, data description, and include comments. (Note that the specification of map data type here is somewhat archaic, and should always be set to raster.) Map history files are stored under the hist directory under the user's current mapset.

NOTES

The r.support program attempts to verify that the information in the cell header is reasonable. The data format specified in the header is verified against the raster map layer itself. This includes checking that files which the header indicates are compressed are really compressed, and that the number of rows and columns specified in the header correspond to the actual file size.

The r.support program can also be used to determine the number of columns and rows of data in a raster map layer, in the event that no cell header is available. This is useful, for example, for importing raster map layers created by software other than GRASS.

If the file is not compressed, the file size should be the product of the number of rows and columns. If the file is compressed, this test cannot be performed since the file size will bear no relation to the product. The number of rows can still be verified, but the number of columns cannot.

To compute or correct the stats, the cell header must be correct, since the raster map layer is read to determine the stats.

If a new cats or colr (or colr2) file is required, the stats must be correct.

The user is allowed to change the number of categories specified in the category file. This should only be done if the user knows that the maximum category value in the raster map layer is different than that which is recorded in the category file. Changing the category value in the cats file allows the user to add more category labels, or to remove labels. It does NOT change the category values in the raster map layer itself.

The color file is unique among GRASS support files. While it is necessary to protect a user's original data from being modified by users working under other mapsets, these users need to be able to create color tables for maps that are stored under mapsets other than their own. Color table files meet both these objectives.

Color table files get stored in one of two directories, both under the user's current mapset. The color files created by a user for raster maps stored under that user's current mapset get stored in the directory $LOCATION/colr and cannot be modified or removed by other users. The color table files that the user modifies/creates for raster map layers not stored under the user's current mapset get stored in a secondary color file under the user's mapset. This secondary color table is stored under $LOCATION/colr2/<mapset> where <mapset> is the name of the mapset under which the raster map data are stored. In versions of GRASS prior to 3.0, this was also the case for color tables in the user's own mapset. Now, however, if a user modifies a color table associated with a raster map layer in his own current mapset, these changes will be made to the user's original color file (i.e., the user's color changes will overwrite whatever previous color table file existed for this map under the user's $LOCATION/colr directory). No secondary color files are created for raster map layers stored in the user's own mapset.

WARNING

In order to modify the cell header, the raster (cell) map layer under consideration must not be a reclass file. This is because the reclass file's header does not contain positional information, but rather a reference to another raster map layer. Thus it shares a cell header with the referenced raster map layer. In order to change the cell header, r.support must be run on the true raster file referenced.

AUTHOR

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

Last changed: $Date$