Geografic-Information-System/lib/raster/rasterlib.dox

/*! \page rasterlib GRASS Raster Library
<!-- * doxygenized from "GRASS 5 Programmer's Manual" 
       by M. Neteler 2/2004, 8/2005, 2006
     * updated to GRASS 7 by Martin Landa
  -->

by GRASS Development Team (http://grass.osgeo.org)

\tableofcontents

<b>TODO: Needs to be cleaned up. The upper GRASS 4.x and the lower
GRASS 5.x/6.x parts need to me merged and updated to GRASS 7</b>

\section gisrastintro GRASS Raster Map Processing

This library provides a suite of routines which process raster map file.
The processing of raster map files consists of determining which
raster map file or files are to be processed (specified on the module
command line), locating the raster map file in the database, opening the
raster files, dynamically allocating i/o buffers, reading or writing
the raster files, closing the raster files, and creating support files
for newly created raster maps.

Raster map data can be of type CELL, FCELL or DCELL, they are defined
in "gis.h". CELL is a 32-bit signed integer, FCELL is an IEEE
single-precision floating-point, and DCELL is an IEEE double-precision
floating-point. 3D rasters (grid3d) is treated as DCELL (see related
library).

\section Finding_Raster_Files_in_the_Database Finding Raster Files in the Database

GRASS allows the user to specify raster map names (or any other
GIS database file) either as a simple <em>unqualified</em> name, such as
"soils", or in case of input raster maps also as a <em>fully qualified</em> 
name, such as "soils@mapset", where <i>mapset</i> is the mapset where the raster
map is to be found. Often only the unqualified raster map name is
provided on the command line and searched in all mapsets indicated in
the mapset search path (SEARCH_PATH file in the actual mapset; managed
with <tt>g.mapsets</tt> command).

The following routines search the database for raster map files:

 - G_find_raster()

Looks for the raster file in the database. If found, the mapset where
the raster file lives is returned. If not found, the NULL pointer is
returned. If the user specifies a fully qualified raster map name which
exists, then G_find_raster() modifies <i>name</i> by removing
the "@<I>mapset</I>".

For example, to find a raster map in all mapsets listed the mapset search
path:

\code
char name[GNAME_MAX];
char *mapset;

if ((mapset = G_find_raster(name,"")) == NULL)
  /* not found */
\endcode

To check that the raster map exists in the current mapset:

\code
char name[GNAME_MAX];

if (G_find_raster(name, G_mapset()) == NULL)
  /* not found */
\endcode

\section Opening_an_Existing_Raster_File Opening an Existing Raster File

The following routine opens the raster map file for <em>reading</em>.

 - Rast_open_old()

This routine opens the raster map in given mapset for reading. A
nonnegative file descriptor is returned if the open is
successful. Otherwise a diagnostic message is printed and a negative
value is returned. This routine does quite a bit of work. Since GRASS
users expect that all raster maps will be resampled into the current
region (nearest neighbor method), the resampling index for the raster 
map is prepared by this routine after the map is opened. The resampling
is based on the active module region. Preparation required for reading
the various raster map formats (CELL, FCELL, DCELL) is also done.

\section Creating_and_Opening_New_Raster_Files Creating and Opening New Raster Files

The following routines create a new raster map in the current
mapset and open it for <em>writing</em>. G_legal_filename() should be
called first to make sure that raster map name is a valid name.

<b>Note:</b> It is not an error for raster map to already exist. New
raster maps are actually created as temporary files and moved into
the cell or fcell directory when closed. This allows an existing raster map
to be read at the same time that it is being rewritten. G_find_raster()
could be used to see if raster map already exists.

<b>Warning:</b> However, there is a subtle trap. The temporary file,
which is created using G_tempfile(), is named using the current
process id. If the new raster file is opened by a parent process which
exits after creating a child process using fork(), the raster file may
never get created since the temporary file would be associated with
the parent process, not the child. GRASS management automatically
removes temporary files associated with processes that are no longer
running. If fork() must be used, the safest course of action is to
create the child first, then open the raster file (see the discussion
under G_tempfile() for more details).

 - Rast_open_new()
 - Rast_open_c_new()
 - Rast_open_fp_new()

Creates and opens the raster map for writing by Rast_put_row() which
writes the file row by row in <b>sequential</b> order. The raster file data
will be compressed as it is written. A nonnegative file descriptor is
returned if the open is successful. Otherwise a diagnostic message is
printed and a negative value is returned.

 - Rast_open_new_uncompressed()
 - Rast_open_c_new_uncompressed()
 - Rast_open_fp_new_uncompressed()

Creates and opens the raster file for writing by Rast_put_row() which
writes the file row by row in sequential order. The raster file will
be in uncompressed format when closed. A nonnegative file descriptor
is returned if the open is successful. Otherwise a warning message is
printed on stderr and a negative value is returned.

General use of this routine is not recommended. This routine is
provided so the <tt>r.compress</tt> module can create uncompressed
raster files.

\section Allocating_Raster_I_O_Buffers Allocating Raster I/O Buffers

Since there is no predefined limit for the number of columns in the
region, buffers which are used for reading and writing raster data
must be dynamically allocated.

 - Rast_allocate_buf()
 - Rast_allocate_c_buf()
 - Rast_allocate_f_buf()
 - Rast_allocate_d_buf()

This routine allocates a buffer of type CELL/FCELL/DCELL just large enough
to hold one row of raster data (based on the number of columns in the active
region).

\code
int input_fd;
char inmap;
RASTER_MAP_TYPE data_type;

input_fd = Rast_open_old(inmap, "");
data_type = Rast_get_map_type(input_fd);
cell = Rast_allocate_buf(data_type);
\endcode

<i>FIXME 7/2009: next still true?</i>

If larger buffers are required, the routine G_malloc() can be
used.

If sufficient memory is not available, an error message is printed and
exit() is called.

 - G_zero_buf()

This routines assigns each member of the raster buffer array to zero.
It assumes that the buffer has been allocated using
Rast_allocate_c_buf().

\section Reading_Raster_Files Reading Raster Files

Raster data can be thought of as a two-dimensional matrix. The
routines described below read one full row of the matrix. It should be
understood, however, that the number of rows and columns in the matrix
is determined by the region, not the raster file itself. Raster data
is always read resampled (nearest neighbor) into the region. This allows 
the user to specify the coverage of the database during analyses. It also 
allows databases to consist of raster files which do not cover exactly the
same area, or do not have the same grid cell resolution. When raster
files are resampled into the region, they all "look" the same.

<b>Note:</b> The rows and columns are specified "C style", i.e.,
starting with 0.

 - Rast_get_row()

This routine reads the specified <i>row</i> from the raster file open
on file descriptor (as returned by Rast_open_old()) into the
buffer. The buffer must be dynamically allocated large enough to hold
one full row of raster data. It can be allocated using
Rast_allocate_buf(). This routine prints a diagnostic message and
returns -1 if there is an error reading the raster file. Otherwise a
nonnegative value is returned.

 - Rast_get_row_nomask()

This routine reads the specified row from the raster file open on file
descriptor into the buffer like Rast_get_row() does. The difference
is that masking is suppressed. If the user has a mask set,
Rast_get_row() will apply the mask but Rast_get_row_nomask() will
ignore it. This routine prints a diagnostic message and returns -1 if
there is an error reading the raster file. Otherwise a nonnegative
value is returned.

<b>Note:</b> Ignoring the mask is not generally acceptable. Users
expect the mask to be applied. However, in some cases ignoring the
mask is justified. For example, the GRASS modules <tt>r.describe</tt>,
which reads the raster file directly to report all data values in a
raster file, and <tt>r.slope.aspect</tt>, which produces slope and
aspect from elevation, ignore both the mask and the region. However,
the number of GRASS modules which do this should be minimal. See \ref
Mask for more information about the mask.


\subsection Writing_Raster_Files Writing Raster Files

 - Rast_put_row()

This routine writes one row of raster data from buffer to the raster
file open on file descriptor. The raster file must have been opened
with Rast_open_new(). The buffer must have been allocated large
enough for the region, perhaps using Rast_allocate_buf(). If there
is an error writing the raster file, a warning message is printed and
-1 is returned. Otherwise 1 is returned.

<b>Note:</b> The rows are written in <b>sequential</b> order. The
first call writes row 0, the second writes row 1, etc. The following
example assumes that the raster file is to be created:

\code
int fd, row, nrows, ncols;
CELL *buf;
RASTER_MAP_TYPE data_type;

fd = Rast_open_old(inmap, ""); /*...data for the row */
data_type = Rast_get_map_type(fd);

Rast_put_row(fd, buf, data_type);
\endcode


\subsection Closing_Raster_Files Closing Raster Files

All raster files are closed by one of the following routines, whether
opened for reading or for writing.

 - Rast_close()

The raster file opened on file descriptor is closed. Memory allocated
for raster processing is freed. If open for writing, skeletal support
files for the new raster file are created as well.

<b>Note:</b> If a module wants to explicitly write support files
(e.g., a specific color table) for a raster file it creates, it must
do so after the raster file is closed. Otherwise the close will
overwrite the support files. See \ref Raster_Map_Layer_Support_Routines 
for routines which write raster support files.

 - Rast_unopen()

The raster file opened on file descriptor is closed. Memory allocated
for raster processing is freed. If open for writing, the raster file
is not created and the temporary file created when the raster file was
opened is removed (see \ref Creating_and_Opening_New_Raster_Files).

This routine is useful when errors are detected and it is desired to
not create the new raster file. While it is true that the raster file
will not be created if the module exits without closing the file, the
temporary file will not be removed at module exit. GRASS database
management will eventually remove the temporary file, but the file can
be quite large and will take up disk space until GRASS does remove
it. Use this routine as a courtesy to the user.

\section Raster_Map_Layer_Support_Routines Raster Map Layer Support Routines

GRASS map layers have a number of support files associated with
them. These files are discussed in detail in \ref Raster_Maps. The
support files are the <em>raster header</em>, the <em>category</em>
file, the <em>color</em> table, the <em>history</em> file, and the
<em>range</em> file. Each support file has its own data structure and
associated routines.


\section Raster_Header_File Raster Header File

The raster header file (<tt>cellhd</tt>) contains information
describing the geographic extent of the raster map, the grid cell
resolution, the format used to store the data in the raster file, see
Cell_head structure for details. The routines described below use the
Cell_head structure which is shown in detail in \ref
GIS_Library_Data_Structures.

 - Rast_get_cellhd()

The raster header for the raster file in the specified mapset is read
into the Cell_head structure.

<b>Note:</b> If the raster file is a reclassified, the raster header
for the referenced raster file is read instead. See Rast_is_reclass()
for distinguishing reclass files from regular raster files.

<b>Note:</b> It is not necessary to get the raster header for a map
layer in order to read the raster file data. The routines which read
raster file data automatically retrieve the raster header information
and use it for resampling the raster file data into the active
region. If it is necessary to read the raster file directly without
resampling into the active region, then the raster header can be used
to set the active region using G_set_window().

 - G_adjust_Cell_head()

This function fills in missing parts of the input cell header (or
region). It also makes projection-specific adjustments.

 - Rast_put_cellhd()

This routine writes the information from the Cell_head structure to
the raster header file for the map layer in the current mapset.

<b>Note:</b> Programmers should have no reason to use this routine. It
is used by Rast_close() to give new raster files correct header
files, and by the <tt>r.support</tt> module to give users a means of
creating or modifying raster headers.

 - Rast_is_reclass()

This function determines if the raster file is a reclass file. Returns
1 if raster file is a reclass file, 0 if it is not, and -1 if there
was a problem reading the raster header.

 - Rast_is_reclassed_to()

This function generates a child reclass maps list from the
cell_misc/reclassed_to file which stores this list. The
cell_misc/reclassed_to file is written by
Rast_put_reclass(). Rast_is_reclassed_to() is used by <tt>g.rename</tt>,
<tt>g.remove</tt> and <tt>r.reclass</tt> to prevent accidentally
deleting the parent map of a reclassed raster map.


\section Raster_Category_File Raster Category File

GRASS map layers have category labels associated with them. The
category file is structured so that each category in the raster file
can have a one-line description. The format of this file is described
in \ref Raster_Category_File_Format.

The routines described below manage the category file. Some of them
use the <i>Categories</i> structure which is described in \ref
GIS_Library_Data_Structures.


\section Reading_and_Writing_the_Raster_Category_File Reading and Writing the Raster Category File

The following routines read or write the category file itself:

 - Rast_read_cats()

The category file for raster file is read into the <i>cats</i>
structure. If there is an error reading the category file, a
diagnostic message is printed and -1 is returned. Otherwise, 0 is
returned.

 - Rast_write_cats()

Writes the category file for the raster file in the current mapset
from the <i>cats</i> structure. Returns 1 if successful. Otherwise, -1
is returned (no diagnostic is printed).

 - Rast_get_title()

If only the map layer title is needed, it is not necessary to read the
entire category file into memory. This routine gets the title for
raster file directly from the category file, and returns a pointer to
the title. A legal pointer is always returned. If the map layer does
not have a title, then a pointer to the empty string "" is returned.

 - Rast_put_title()

If it is only desired to change the title for a map layer, it is not
necessary to read the entire category file into memory, change the
title, and rewrite the category file. This routine changes the title
for the raster file in the current mapset directly in the category
file. It returns a pointer to the title.


\section Querying_and_Changing_the_Categories_Structure Querying and Changing the Categories Structure

The following routines query or modify the information contained in
the category structure:

 - Rast_get_cat()

This routine looks up category in the cats structure and returns a
pointer to a string which is the label for the category. A legal
pointer is always returned. If the category does not exist in cats
then a pointer to the empty string "" is returned.

<b>Warning:</b> The pointer that is returned points to a hidden static
buffer. Successive calls to Rast_get_cat() overwrite this buffer.

 - Rast_get_cats_title()

Map layers store a one-line title in the category structure as
well. This routine returns a pointer to the title contained in the
cats structure. A legal pointer is always returned. If the map layer
does not have a title, then a pointer to the empty string "" is
returned.

 - Rast_init_cats()

To construct a new category file, the structure must first be
initialized.  This routine initializes the cats structure, and copies
the title into the structure.

For example:

\code
struct Categories cats;

Rast_init_cats ((CELL) 0, "", &cats);
\endcode

 - Rast_set_cat()

Copies the label into the cats structure for category.

 - Rast_set_cats_title()

Copies the title is copied into the cats structure.

 - Rast_free_cats()

Frees memory allocated by Rast_read_cats(), Rast_init_cats() and
Rast_set_cat().


\section Raster_Color_Table Raster Color Table

GRASS map layers have colors associated with them. The color tables
are structured so that each category in the raster file has its own
color. The format of this file is described in
\ref Raster_Color_Table_Format.

The routines that manipulate the raster color file use the
<i>Colors</i> structure which is described in detail in 
\ref GIS_Library_Data_Structures.


\section Reading_and_Writing_the_Raster_Color_File Reading and Writing the Raster Color File

The following routines read, create, modify, and write color tables.

 - Rast_read_colors()

The color table for the raster file in the specified mapset is read
into the <em>colors</em> structure. If the data layer has no color
table, a default color table is generated and 0 is returned. If there
is an error reading the color table, a diagnostic message is printed
and -1 is returned. If the color table is read ok, 1 is returned.

 - Rast_write_colors()

Write map layer color table. The color table is written for the raster
file in the specified mapset from the <em>colors</em> structure. If
there is an error, -1 is returned. No diagnostic is
printed. Otherwise, 1 is returned.

The <em>colors</em> structure must be created properly, i.e.,
Rast_init_colors() to initialize the structure and Rast_add_color_rule() to
set the category colors.

<b>Note:</b> The calling sequence for this function deserves special
attention. The <em>mapset</em> parameter seems to imply that it is
possible to overwrite the color table for a raster file which is in
another mapset. However, this is not what actually happens. It is very
useful for users to create their own color tables for raster files in
other mapsets, but without overwriting other users' color tables for
the same raster file. If <em>mapset</em> is the current mapset, then
the color file for <em>name</em> will be overwritten by the new color
table. But if <em>mapset</em> is not the current mapset, then the
color table is actually written in the current mapset under the
<tt>colr2</tt> element as: <tt>colr2/mapset/name</tt>.


\section Lookup_Up_Raster_Colors Lookup Up Raster Colors

These routines translates raster values to their respective colors.

 - Rast_lookup_colors()

Extracts colors for an array of raster values. The colors from the
raster array are stored in the red, green, and blue arrays.

<b>Note:</b> The red, green, and blue intensities will be in the range
0-255.

 - Rast_get_color()

Get a category color. The red, green, and blue intensities for the
color associated with category are extracted from the colors
structure. The intensities will be in the range 0-255.


\section Creating_and_or_Modifying_the_Color_Table Creating and/or Modifying the Color Table

These routines allow the creation of customized color tables as well as the
modification of existing tables.

 - Rast_init_colors()

Initialize <i>colors</i> structure for subsequent calls
Rast_add_color_rule() and Rast_set_color().

 - Rast_add_color_rule()

This is the heart and soul of the color logic. It adds a color
rule to the <em>colors</em> structure. The colors defined by the red,
green, and blue values are assigned to the categories
respectively. Colors for data values between two categories are not
stored in the structure but are interpolated when queried by
Rast_lookup_colors() and Rast_get_color(). The color components must be in the
range 0-255.

For example, to create a linear grey scale for the range 200-1000:

\code
struct Colors colr;

Rast_init_colors (&colr) ;

Rast_add_color_rule ((CELL) 200, 0,0,0,(CELL) 1000, 255,255,255) ;
\endcode

The programmer is encouraged to review \ref Raster_Color_Table_Format.

<b>Note:</b> The <em>colors</em> structure must have been initialized
by Rast_init_colors(). See \ref Predefined_Color_Tables for routines to
build some predefined color tables.

 - Rast_set_color()

Set a category color. The red, green, and blue intensities for the
color associated with category The intensities must be in the range 
0-255. Values below zero are set as zero, values above 255 are set as
255.

<b>Warning:</b> Use of this routine is discouraged because it defeats
the new color logic. It is provided only for backward
compatibility. Overuse can create large color
tables. Rast_add_color_rule() should be used whenever possible.

<b>Note:</b> The <em>colors</em> structure must have been initialized
by Rast_init_color().

 - Rast_get_color_range()
 - Rast_get_d_color_range()

Get color range. Gets the minimum and maximum raster values that have
colors associated with them.

 - Rast_free_colors()

Free dynamically allocated memory associated with the <em>colors</em>
structure.

<b>Note:</b> This routine may be used after Rast_read_colors() as well as
after Rast_init_colors().


\section Predefined_Color_Tables Predefined Color Tables

The following routines generate entire color tables. The tables are
loaded into a <i>colors</i> structure based on a range of category
values from minimum to maximum value. The range of values for a raster
map can be obtained, for example, using Rast_read_range().

<b>Note:</b> The color tables are generated without information about
any particular raster file.

These color tables may be created for a raster map, but they may also
be generated for loading graphics colors. These routines return -1 if
minimum value is greater than maximum value, 1 otherwise.

 - Rast_make_aspect_colors()

Generates a color table for aspect data.

 - Rast_make_ramp_colors()

Generates a color table with 3 sections: red only, green only, and
blue only, each increasing from none to full intensity. This table is
good for continuous data, such as elevation.

 - Rast_make_wave_colors()

Generates a color table with 3 sections: red only, green only, and
blue only, each increasing from none to full intensity and back down
to none. This table is good for continuous data like elevation.

 - Rast_make_grey_scale_colors()

Generates a grey scale color table. Each color is a level of grey,
increasing from black to white.

 - Rast_make_rainbow_colors()

Generates a "shifted" rainbow color table - yellow to green to cyan to
blue to magenta to red. The color table is based on rainbow
colors. (Normal rainbow colors are red, orange, yellow, green, blue,
indigo, and violet.)  This table is good for continuous data, such as
elevation.

 - Rast_make_random_colors()

Generates random colors. Good as a first pass at a color table for
nominal data.

 - Rast_make_ryg_colors()

Generates a color table that goes from red to yellow to green.

 - Rast_make_gyr_colors()

Generates a color table that goes from green to yellow to red.

 - Rast_make_histogram_eq_colors()

Generates a histogram contrast-stretched grey scale color table that goes
from the, histogram information.


\section Raster_History_File Raster History File

The history file contains documentary information about the raster
file: who created it, when it was created, what was the original data
source, what information is contained in the raster file, etc.

The following routines manage this file. They use the History
structure which is described in \ref GIS_Library_Data_Structures.

<b>Note:</b> This structure has existed relatively unmodified since
the inception of GRASS. It is in need of overhaul. Programmers should
be aware that future versions of GRASS may no longer support either
the routines or the data structure which support the history file.

 - Rast_read_history()

Reads raster history file. This routine reads the history file for the
raster map into the History structure.

 - Rast_write_history()

Writes raster history file. This routine writes the history file for
the raster map in the current mapset from the History structure.

<b>Note:</b> The History structure should first be
initialized using Rast_short_history().

 - Rast_short_history()

This routine initializes History structure, recording the date, user,
module name and the raster map.

<b>Note:</b> This routine only initializes the data structure. It does
not write the history file.

\section Raster_Range_File Raster Range File

The following routines manage the raster range file. This file
contains the minimum and maximum values found in the raster file. The
format of this file is described in \ref Raster_Range_File_Format.

The routines below use the <i>Range</i> data structure which is
described in \ref GIS_Library_Data_Structures.

 - Rast_read_range()

Reads raster range. This routine reads the range information for the
raster map into the <i>range</i> structure. A diagnostic message is
printed and -1 is returned if there is an error reading the range
file. Otherwise, 0 is returned.

 - Rast_write_range()

Write raster range file. This routine writes the range information for
the raster map in the current mapset from the <i>range</i>
structure. A diagnostic message is printed and -1 is returned if there
is an error writing the range file. Otherwise, 0 is returned.

The range structure must be initialized and updated using the following
routines:

 - Rast_init_range()

Initializes the <i>range</i> structure for updates by Rast_update_range()
and Rast_row_update_range().

 - Rast_update_range()

Compares the category value with the minimum and maximum values in the
<i>range</i> structure, modifying the range if the value extends the
range.

 - Rast_row_update_range()

This routine updates the range data just like Rast_update_range().

The range structure is queried using the following routine:

 - Rast_get_range_min_max()

Get range minimum and maximum value.


\section Raster_Histograms Raster Histograms

The following routines provide a relatively efficient mechanism for
computing and querying a histogram of raster data. They use the
<b>Cell_stats</b> structure to hold the histogram information. The
histogram is a count associated with each unique raster value
representing the number of times each value was inserted into the
structure.

These next two routines are used to manage the Cell_stats structure:

 - Rast_init_cell_stats()

Initialize cell stats, This routine, which must be called first,
initializes the Cell_stats structure.

 - Rast_free_cell_stats()

Free cell stats. The memory associated with structure is freed. This
routine may be called any time after calling Rast_init_cell_stats().

This next routine stores values in the histogram:

 - Rast_update_cell_stats()

Adds data to cell stats. Once all values are stored, the structure may
be queried either randomly (i.e., search for a specific raster value) or
sequentially (retrieve all raster values, in ascending order, and
their related count):

 - Rast_find_cell_stat()

Random query of cell stats. This routine allows a random query of the
Cell_stats structure. The routine returns 1 if <B>cat</B> was found in
the structure, 0 otherwise.

Sequential retrieval is accomplished using these next 2 routines:

 - Rast_rewind_cell_stats()

Reset/rewind cell stats. The structure is rewound (i.e., positioned at
the first raster category) so that sorted sequential retrieval can
begin.

 - Rast_next_cell_stat()

Retrieve sorted cell stats. Retrieves the next <i>cat, count</i>
combination from the structure. Returns 0 if there are no more items,
non-zero if there are more.

For example:

\code
struct Cell_stats s;
CELL cat;
long count;

/* updating s occurs here */

Rast_rewind_cell_stats(&s);

while(Rast_next_cell_stat(&cat, &count, &s))
  fprintf(stdout, "%ld %ld\n", (long) cat, count);
\endcode

\section  GRASS_5_raster_API GRASS 5 raster API

<em>Needs to be merged into above sections.</em>

\subsection The_CELL_Data_Type The CELL Data Type

GRASS integer raster map data is defined to be of type CELL. This data
type is defined in the "gis.h" header file. Programmers must declare
all variables and buffers which will hold raster data or category
codes as type CELL. Under GRASS the CELL data type is declared to be
"int", but the programmer should not assume this. What should be
assumed is that CELL is a signed integer type. It may be changed
sometime to short or long. This implies that use of CELL data with
routines which do not know about this data type (e.g.,
<tt>fprintf(stdout, ...), sscanf()</tt>, etc.) must use an
intermediate variable of type long. To print a CELL value, it must be
cast to long. For example:

\code
CELL c; /* raster value to be printed */

/* some code to get a value for c */
fprintf(stdout, "%ld\n", (long) c); /* cast c to long to print */
\endcode

To read a CELL value, for example from user typed input, it is
necessary to read into a long variable, and then assign it to the CELL
variable. For example (this example does not check for valid inputs,
EOF, etc., which good code must do):

\code
char userbuf[128];
CELL c;
long x;

fprintf (stdout, "Which category? "); /* prompt user */
gets(userbuf);                        /* get user response * /
sscanf (userbuf,"%ld", &x);           /* scan category into long variable */
c = (CELL) x;                         /* assign long value to CELL value */
\endcode

Of course, with GRASS library routines that are designed to handle the
CELL type, this problem does not arise. It is only when CELL data must
be used in routines which do not know about the CELL type, that the
values must be cast to or from long.

\subsection GRASS_5_raster_API_gish Changes to gis.h

The "gis.h" contains 5 new items:

\code
        typedef float FCELL;
        typedef double DCELL;
        typedef int RASTER_MAP_TYPE;
        #define CELL_TYPE  0
        #define FCELL_TYPE 1
        #define DCELL_TYPE 2
\endcode

Also "gis.h" contains the definitions for new structures:

\code
      struct FPReclass;
      struct FPRange;
      struct Quant;
\endcode

Some of the old structures such as

\code
      struct Categories
      struct Cell_stats;
      struct Range;
      struct _Color_Rule_;
      struct _Color_Info_;
      struct Colors;
\endcode

were modified, so it is very important to use functional interface to
access and set elements of these structures instead of accessing
elements of the structures directly. Because some former elements such
as for example <tt>(struct Range range.pmin)</tt> do not exist
anymore. It was made sure non of the former elements have different
meaning, so that the programs which do access the old elements
directly either do not compile or work exactly the same way as prior
to change.

\subsection NULL_value_functions NULL-value functions

 - Rast_set_null_value()

Set NULL value. For raster type <tt>CELL_TYPE</tt> use
Rast_set_c_null_value(), for <tt>FCELL_TYPE</tt> Rast_set_f_null_value(),
and for <tt>DCELL_TYPE</tt> Rast_set_d_null_value().

 - Rast_insert_null_values()

Insert NULL value. If raster type is <tt>CELL_TYPE</tt> calls
Rast_insert_c_null_values(), <tt>FCELL_TYPE</tt> calls
Rast_insert_f_null_values(), and <tt>DCELL_TYPE</tt> calls
Rast_insert_d_null_values().

 - Rast_is_null_value()

Check NULL value. If raster type is <tt>CELL_TYPE</tt>, calls
Rast_is_c_null_value(), <tt>FCELL_TYPE</tt> calls
Rast_is_f_null_value(), and <tt>DCELL_TYPE</tt> calls
Rast_is_d_null_value().

It isn't good enough to test for a particular NaN bit pattern since
the machine code may change this bit pattern to a different NaN. The
test will be

\code
if(fcell == 0.0) return 0;
if(fcell >  0.0) return 0;
if(fcell <  0.0) return 0;
return 1;
\endcode

or (as suggested by Mark Line) 

\code
return(FCELL != fcell) ;
\endcode

 - Rast_allocate_null_buf()

Allocates an array of char based on the number of columns in the
current region.

 - Rast_get_null_value_row()

Reads a row from NULL value bitmap file for the raster map open for
read. If there is no bitmap file, then this routine simulates the read
as follows: non-zero values in the raster map correspond to non-NULL;
zero values correspond to NULL. When MASK exists, masked cells are set
to null.

\subsection Floating_point_and_type_independent_functions Floating-point and type-independent functions

 - Rast_maskfd()

Test for current maskreturns file descriptor number if MASK is in use
and -1 if no MASK is in use.

 - Rast_map_is_fp()

Returns true(1) if raster map is a floating-point dataset; false(0)
otherwise.

 - Rast_map_type()

Returns the storage type for raster map:
 - <tt>CELL_TYPE</tt> for integer raster map
 - <tt>FCELL_TYPE</tt> for floating-point raster map
 - <tt>DCELL_TYPE</tt> for floating-point raster map (double precision)

 - Rast_open_new()

Creates new raster map in the current mapset. Calls G_open_map_new()
for raster type <tt>CELL_TYPE</tt>, G_open_fp_map_new() for
floating-point raster map. The use of this routine by applications is
discouraged since its use would override user preferences (what
precision to use).

 - Rast_set_fp_type()

This controls the storage type for floating-point raster maps. It
affects subsequent calls to Rast_open_fp_new(). The <em>type</em>
must be one of <tt>FCELL_TYPE</tt> (float) or <tt>DCELL_TYPE</tt>
(double). The use of this routine by applications is discouraged since
its use would override user preferences.

 - Rast_open_fp_new()

Creates a new floating-point raster map (in <tt>.tmp</tt>) and returns
a file descriptor. The storage type (float or double) is determined by
the last call to Rast_set_fp_type() or the default (float - unless the
GRASS environmental variable GRASS_FP_DOUBLE is set).

 - Rast_allocate_buf()
 - Rast_allocate_c_buf()
 - Rast_allocate_f_buf()
 - Rast_allocate_d_buf()

Allocate an arrays of CELL, FCELL, or DCELL (depending on raster type)
based on the number of columns in the current region.

 - Rast_incr_void_ptr()

Advances void pointer by n bytes. Returns new pointer value. Usefull
in raster row processing loops, substitutes

\code
CELL *cell;
cell += n;
\endcode

Now 

\code
rast = Rast_incr_void_ptr(rast, Rast_raster_size(data_type));
\endcode

Where <i>rast</i> is void* and data_type is RASTER_MAP_TYPE can be
used instead of rast++.) Very usefull to generalize the row processing
- loop (i.e. void * buf_ptr += Rast_raster_size(data_type))

 - Rast_raster_size()

If <i>data_type</i> is CELL_TYPE, returns sizeof(CELL), for FCELL_TYPE
returns sizeof(FCELL), and for <EM>data_type</EM> is DCELL_TYPE,
returns sizeof(DCELL).

 - Rast_raster_cmp()

Compares raster values.

 - Rast_raster_cpy()

Copies raster values.

 - Rast_set_value_c()

If Rast_is_c_null_value() is true, sets value to null value. Converts
CELL value to raster data type value and stores the result. Used for
assigning CELL values to raster cells of any type.

 - Rast_set_value_f()

If Rast_is_f_null_value() is true, sets value to null value. Converts
FCELL val to raster data type and stores the result. Used for
assigning FCELL values to raster cells of any type.

 - Rast_set_value_d()

If Rast_is_d_null_value() is true, sets value to null value. Converts
DCELL val to raster data type and stores the result. Used for
assigning DCELL values to raster cells of any type.
 
 - Rast_get_value_c()

Retrieves the value of raster type, converts it to CELL type and
returns the result. If null value is stored, returns CELL null
value. Used for retreiving CELL values from raster cells of any type.

Note: when data_type != CELL_TYPE, no quantization is used, only type conversion.

 - Rast_get_value_f()

Retrieves the value of raster type, converts it to FCELL type and
returns the result. If null value is stored, returns FCELL null
value. Used for retreiving FCELL values from raster cells of any type.

 - Rast_get_value_d()

Retrieves the value of raster type, converts it to DCELL type and
returns the result. If null value is stored, returns DCELL null
value. Used for retreiving DCELL values from raster cells of any type.

 - Rast_get_row ()

For CELL_TYPE raster type calls Rast_get_c_row(), FCELL_TYPE calls
Rast_get_f_row(), and DCELL_TYPE Rast_get_d_row().

 - Rast_get_row_nomask().

Same as Rast_get_f_row() except no masking occurs.

 - Rast_get_f_row()

Read a row from the raster map performing type conversions as
necessary based on the actual storage type of the map. Masking,
resampling into the current region. NULL-values are always embedded
(never converted to a value).

 - Rast_get_f_row_nomask()

Same as Rast_get_f_row() except no masking occurs.

 - Rast_get_d_row()

Same as Rast_get_f_row() except that the array double.

 - Rast_get_d_row_nomask()

Same as Rast_get_d_row() except no masking occurs.

 - Rast_get_c_row()

Reads a row of raster data and leaves the NULL values intact. (As
opposed to the deprecated function Rast_get_row() which converts NULL
values to zero.)

<b>Note:</b> When the raster map is old and null file doesn't exist,
it is assumed that all 0-cells are no-data. When map is floating
point, uses quant rules set explicitly by Rast_set_quant_rules or stored
in map's quant file to convert floats to integers.

 - Rast_get_c_row_nomask()

Same as Rast_get_c_row() except no masking occurs.

 - Rast_put_row()

If raster type is CELL_TYPE, calls Rast_put_c_row(), if FCELL_TYPE, then calls Rast_put_f_row(), and for DCELL_TYPE, calls Rast_put_d_row().

 - Rast_put_f_row()

Write the next row of the raster map performing type conversion to the
actual storage type of the resultant map. Keep track of the range of
floating-point values. Also writes the NULL-value bitmap from the
NULL-values embedded in the data array.

 - Rast_put_d_row()

Same as Rast_put_f_row() except that the array is double.

 - Rast_put_c_row()

Writes a row of raster data and a row of the null-value bitmap, only
treating NULL as NULL. (As opposed to the deprecated function
Rast_put_row() which treats zero values also as NULL.)

 - Rast_zero_row()

Depending on raster type zeroes out Rast_window_cols() CELLs, FCELLs, or
DCELLs stored in cell buffer.

 - Rast_get_sample()

Extracts a cell value from raster map at given position with nearest neighbor interpolation, bilinear interpolation or cubic interpolation.

\section Upgrades_to_Raster_Functions Upgrades to Raster Functions (comparing to GRASS 4.x)


These routines will be modified (internally) to work with
floating-point and NULL-values.

 - Rast_close()

If the map is a new floating point, move the <TT>.tmp</TT> file into
the <TT>fcell</TT> element, create an empty file in the <TT>cell</TT>
directory; write the floating-point range file; write a default
quantization file quantization file is set here to round fp numbers
(this is a default for now). Create an empty category file, with max
cat = max value (for backwards compatibility). Move the <TT>.tmp</TT>
NULL-value bitmap file to the <TT>cell_misc</TT> directory.

 - Rast_open_old()

Arrange for the NULL-value bitmap to be read as well as the raster
map. If no NULL-value bitmap exists, arrange for the production of
NULL-values based on zeros in the raster map.

If the map is floating-point, arrange for quantization to integer for
Rast_get_c_row(), et. al., by reading the quantization rules for
the map using Rast_read_quant().

If the programmer wants to read the floating point map using uing
quant rules other than the ones stored in map's quant file, he/she
should call Rast_set_quant_rules() after the call to Rast_open_old().

 - Rast_get_row()

If the map is floating-point, quantize the floating-point values to
integer using the quantization rules established for the map when the
map was opened for reading (this quantization is read from
cell_misc/name/f_quant file, but can be reset after opening raster map
by Rast_set_quant_rules()). NULL values are converted to zeros. <b>This
routine is deprecated!!</b>

 - Rast_put_row()

Zero values are converted to NULLs. Write a row of the NULL value bit
map. <b>This routine is deprecated!!</b>

\section Null_no_data NULL (no data) handling


The <tt>null</tt> file is stored in <tt>cell_misc/name/null file</tt>.

-2^31 (= 0x80000000 = -2147483648) is the null value for the CELL
type, so you'll never see that value in a map.

The FP nulls are the all-ones bit patterns. These corresponds to NaN
according to the IEEE-754 formats, although it isn't the "default" NaN
pattern generated by most architectures (which is usually 7fc00000 or
ffc00000 for float and 7ff8000000000000 or fff8000000000000 for
double, i.e. an all-ones exponent, the top-bit of the mantissa set,
and either sign).

So far as arithmetic is concerned, any value with an all-ones exponent
and a non-zero mantissa is treated as NaN. But the GRASS
Rast_is_[fd]_null_value() functions only consider the all-ones bit
pattern to be null. I intend to change this in 7.x so that all FP NaN
values are treated as null. This will mean that code which can
generate NaNs doesn't have to explicitly convert them to the GRASS
null value.

<b>Presence or absence of <tt>null</tt> file:</b>

For an integer map, any cells which were null will become zero, but
any zeroes (cells which were previously either null or zero) will be
treated as nulls (this is for compatibility with GRASS 4.x, which
didn't have a <tt>null</tt> file, but typically used zero to indicate
a null value).

For a floating-point map, any cells which were null will become zero
(when writing FP data, a null has a zero written to the fcell/\<map\>
file, and the corresponding bit is set in the <tt>null</tt> file).

\section Color_Functions Color Functions (new and upgraded)


\subsection Upgraded_Colors_structures Upgraded Colors structures

\code
struct _Color_Rule_
{
struct
{
    int version;                                   /* set by read_colors: -1=old,1=new */
    DCELL shift;
    int invert;
    int is_float;                                  /* defined on floating point raster data? */
    int null_set;                                  /* the colors for null are set? */
    unsigned char null_red, null_grn, null_blu;
    int undef_set;                                 /* the colors for cells not in range are set? */
    unsigned char undef_red, undef_grn, undef_blu;
    struct _Color_Info_ fixed, modular;
    DCELL cmin, cmax;
};
\endcode

\section New_functions_to_support_colors_for_floating_point New functions to support colors for floating-point

 - Rast_lookup_colors()

If raster type is CELL_TYPE, calls Rast_lookup_colors(), if FCELL_TYPE,
calls Rast_lookup_f_colors(), and for DCELL_TYPE
Rast_lookup_d_colors().

 - Rast_lookup_c_colors()

 - Rast_lookup_f_colors()

Converts the floating-point values in the float data array to their
<em>r,g,b</em> color components. Embedded NULL-values are handled
properly as well.

 - Rast_lookup_d_colors()

Converts the floating-point values in the double data array to their
<em>r,g,b</em> color components. Embedded NULL-values are handled
properly as well.

 - Rast_add_color_rule()

If raster type is CELL_TYPE, calls Rast_add_c_color_rule(), if
FCELL_TYPE, calls Rast_add_f_color_rule(), and for DCELL_TYPE
calls Rast_add_d_color_rule().

 - Rast_get_color()

Looks up the rgb colors for the value in the color table.

 - Rast_mark_colors_as_fp()

Sets a flag in the <em>colors</em> structure that indicates that these
colors should only be looked up using floating-point raster data (not
integer data).


\section New_functions_to_support_a_colors_for_the_NULL_value New functions to support a color for the NULL-value

 - Rast_set_null_value_color()

Sets the color (in <em>colors</em>) for the NULL-value to <em>r,g,b</em>.

 - Rast_get_null_value_color()

Puts the red, green, and blue components of the color for the
NULL-value into <em>r,g,b</em>.

\section New_functions_to_support_a_default_color New functions to support a default color


 - Rast_set_default_color()

Sets the default color (in <em>colors</em>) to <em>r,g,b</em>. This is
the color for values which do not have an explicit rule.

 - Rast_get_default_color()

Puts the red, green, and blue components of the <tt>"default"</tt>
color into <em>r,g,b</em>.

\section New_functions_to_support_treating_a_raster_layer_as_a_color_image New functions to support treating a raster layer as a color image

 - Rast_get_row_colors()

Reads a row of raster data and converts it to red, green and blue
components according to the colors.

This provides a convenient way to treat a raster layer as a color
image without having to explicitly cater for each of CELL, FCELL and
DCELL types.

\section Upgraded_color_functions Upgraded color functions

 - Rast_read_colors()

This routine reads the rules from the color file. If the input raster
map is is a floating-point map (FCELL or DCELL) it calls
Rast_mark_colors_as_fp().

 - Rast_write_colors()

The rules are written out using floating-point format, removing
trailing zeros (possibly producing integers). The flag marking the
colors as floating-point is <b>not</b> written.

 - Rast_get_colors_min_max()

If the color table is marked as <tt>"float"</tt>, then return the
minimum as -(255&#94;3 * 128) and the maximum as (255&#94;3 *
128). This is to simulate a very <em>large</em> range so that GRASS
doesn't attempt to use <em>colormode float</em> to allow interactive
toggling of colors.

 - Rast_lookup_colors()

Modified to return a color for NULL-values.

 - Rast_get_color()

Modified to return a color for the NULL-value.

\section Changes_to_the_Colors_structure Changes to the Colors structure


Modifications to the Colors structure to support colors for
floating-point data and the NULL-value consist of

 - the _Color_Rule_ struct was changed to have DCELL value (instead of
CELL cat) to have the range be floating-point values instead of
integer cats.
 - a color for NULL was added
 - the special color for zero was eliminated
 - a default color for values which have no assigned color was added
 - a flag was added to the Colors structure to indicate if either the
map itself is floating-point (If the map is integer and the floating
point functions are used to lookup colors, the values are checked to
see if they are integer, and if they are, the integer mechanism is
used)
 - fp_lookup - a lookup table for floating point numbers is added. It
orders the end points of fp intervals into array with a pointer to a
color rule for each inteval, and the binary search is then used when
looking up colors instead of linearly searching through all color
rules.

\section Changes_to_the_colr_file Changes to the \c colr file


 - The rules are written out using floating-point format, removing trailing zeros (possibly producing integers) . For example, to ramp from red to green for the range [1.3,5.0]:
\verbatim
            1.3:255:0:0  5:0:255:0
\endverbatim

 - The NULL-value color is written as:
\verbatim
            nv:red:grn:blu
\endverbatim

 - The default color (for values that don't have an explicit rule) is written
as:
\verbatim
            *:red:grn:blu
\endverbatim


\section Range_functions Range functions (new and upgraded)

\subsection Modified_range_functions Modified range functions

 - Rast_read_range()

Old range file (those with 4 numbers) should treat zeros in this file
as NULL-values. New range files (those with just 2 numbers) should
treat these numbers as real data (zeros are real data in this case).

An empty range file indicates that the min, max are undefined. This is
a valid case, and the result should be an initialized range struct
with no defined min/max.

If the range file is missing and the map is a floating-point map, this
function will create a default range by calling
Rast_construct_default_range().

 - Rast_init_range()

Must set a flag in the range structure that indicates that no min/max
have been defined - probably a "first" boolean flag.

 - Rast_update_range()

NULL-values must be detected and ignored.

 - Rast_get_range_min_max()

If the range structure has no defined min/max (first!=0) there will
not be a valid range. In this case the min and max returned must be
the NULL-value.

 - Rast_write_range()

This routine only writes 2 numbers (min,max) to the range file,
instead of the 4 (pmin,pmax,nmin,nmax) previously written. If there is
no defined min,max, an empty file is written.

\section New_range_functions New range functions

 - Rast_construct_default_range()

Sets the integer range to [1,255].

 - Rast_read_range()

If raster type is CELL_TYPE, calls Rast_read_range(), otherwise calls
Rast_read_fp_range().

 - Rast_read_fp_range()

Read the floating point range file <tt>f_range</tt>. This file is
written in binary using XDR format. If there is no defined min/max in
FPRange structure, an empty <tt>f_range</tt> file is created.

An empty range file indicates that the min, max are undefined. This is
a valid case, and the result should be an initialized range struct
with no defined min/max.

If the range file is missing and the map is a floating-point map, this
function will create a default range by calling
Rast_construct_default_range().

 - Rast_init_range()

If raster type is CELL_TYPE, calls Rast_init_range(), otherwise calls
Rast_init_fp_range().

 - Rast_init_fp_range()

Must set a flag in the range structure that indicates that no min/max
have been defined - probably a "first" boolean flag.

 - Rast_update_f_range()
 - Rast_update_d_range()

Updates the floating-point range from the values in NULL-values must
be detected and ignored.

 - Rast_get_fp_range_min_max()

Extract the min/max from the FPRange structure. If the range structure
has no defined min/max (first!=0) there will not be a valid range. In
this case the min and max returned must be the NULL-value.

 - Rast_write_fp_range()

Write the floating point range file <tt>f_range</tt>. This file is
written in binary using XDR format. If there is no defined min/max in
<EM>r</EM>, an empty <tt>f_range</tt> file is created.

\section New_and_Upgraded_Cell_stats_functions New and Upgraded Cell_stats functions

Modified Cell_stats functions to handle NULL-values:

 - Rast_init_cell_stats()

Set the count for NULL-values to zero.

 - Rast_update_cell_stats()

Look for NULLs and update the NULL-value count.

 - Rast_next_cell_stat()

Do not return a record for the NULL-value.

 - Rast_find_cell_stat()

Allow finding the count for the NULL-value.

 - Rast_get_stats_for_null_value()

Get a number of null values from stats structure. Note: when reporting
values which appear in a map using Rast_next_cell_stats() , to get stats
for null, call Rast_get_stats_for_null_value() first, since
Rast_next_cell_stats() does not report stats for null.

\section New_Quantization_Functions New Quantization Functions

New functions to support quantization of floating-point to integer:

 - Rast_write_quant()

Writes the <tt>f_quant</tt> file for the raster map. If
mapset==Rast_mapset() i.e. the map is in current mapset, then the
original quant file in <tt>cell_misc/map/f_quant</tt> is
written. Othewise is written into <tt>quant2/mapset/name</tt> (much
like colr2 element). This results in map&#64;mapset being read using
quant rules stored Rast_mapset(). See Rast_read_quant() for detailes.

 - Rast_set_quant_rules()

Sets quant translation rules for raster map opened for reading. After
calling this function, Rast_get_c_row() and Rast_get_row() will
use defined rules (instead of using rules defined in map's quant file)
to convert floats to ints.

 - Rast_read_quant()

Reads quantization rules for raster map and stores them in the
quantization structure. If the map is in another mapset, first checks
for quant2 table for this map in current mapset.

 - Rast_quant_init()

Initializes the Quant struct.

 - Rast_quant_free()

Frees any memory allocated in Quant structure and re-initializes the
structure by calling Rast_quant_init().

 - Rast_quant_truncate()

Sets the quant rules to perform simple truncation on floats.

 - Rast_quant_truncate()

Sets the quant rules to perform simple rounding on floats.

 - Rast_quant_organize_fp_lookup()

Organizes fp_lookup table for faster (logarithmic) lookup time
Rast_quant_organize_fp_lookup() creates a list of min and max for each
quant rule, sorts this list, and stores the pointer to quant rule that
should be used inbetween any 2 numbers in this list Also it stores
extreme points for 2 infinite rules, if exist After the call to
Rast_quant_organize_fp_lookup() instead of linearly searching through
list of rules to find a rule to apply, quant lookup will perform a
binary search to find an interval containing floating point value, and
then use the rule associated with this interval. When the value
doesn't fall within any interval, check for the infinite rules.

 - Rast_quant_add_rule()

Add the rule that the floating-point range produces an integer in the
range by linear interpolation. Rules that are added later have higher
precedence when searching. If any of of the values is the NULL-value,
this rule is not added and 0 is returned. Otherwise return 1. if the
fp_lookup is organized, destroy it.

 - Rast_quant_set_positive_infinite_rule()
 - Rast_quant_get_positive_infinite_rule()

This rule has lower precedence than rules added with Rast_quant_add_rule().

 - Rast_quant_set_negative_infinite_rule()

This rule has lower precedence than rules added with Rast_quant_add_rule().

 - Rast_quant_get_negative_infinite_rule()

 - Rast_quant_get_limits()

Extracts the minimum and maximum floating-point and integer values
from all the rules.

 - Rast_quant_nrules()

Returns the number of rules, excluding the negative and positive
"infinite" rules.

 - Rast_quant_get_rule()

The order of the rules returned by increasing <i>n</i> is the order
in which the rules are applied when quantizing a value - the first
rule applicable is used.

 - Rast_quant_get_cell_value()

 - Rast_quant_perform_d()

 - Rast_quant_perform_f()

These next two functions are convenience functions to allow applications to
easily create quantization rules other than the defaults:

 - Rast_quantize_fp_map()

Writes the <tt>f_quant</tt> file for the raster map.

 - Rast_quantize_fp_map_range()

Writes the <tt>f_quant</TT> file for the raster map with one rule. 


\section Categories_Labeling_Functions Categories Labeling Functions (new and upgraded)

\subsection Upgraded_Categories_structure Upgraded Categories structure

All the new programs which are using Categories structure directly
have to be modified to use API functions to update and retrieve info
from Categories structure. Both new and old API function can be used,
since old functions still have exact same functionality (even though
internally they are implemented very differently). New function names
end with raster_cats(); old function names end with _cats().

We made sure that all old fields in Categories structure are either
missing in new Categories structure or have exactly the same
meaning. We did it so that the modules using Categories structure
directly either do not compile with new gis library or work exactly
the same as bnefore.  A programmer might want to read the data in a
floating point map in a way that each cell value stores index of it's
category label and data range. The way to do it is to call
Rast_set_quant_rules() after openning the map.

This is helpful when trying to collect statistics (how many cells of
each category are in the map. (although there is another new mechanism
to collect such stats - see Rast_mark_cats()) . Another reason to
get a category index instead of fp values is that this index will be
the FID into GRASS-DBMS link. Also he can use Rast_get_ith_cat()
to get the category information for each cell using this index.

Here is the new Categories structure defined in gis.h:

\code
struct Categories
{
    CELL ncats            ;   /* total number of categories              */
    CELL num              ;   /* the highest cell values. Only exists
                                 for backwards compatibility = (CELL)
                                 max_fp_values in quant rules            */
    char *title           ;   /* name of data layer                      */
    char *fmt             ;   /* printf-like format to generate labels   */
    float m1              ;   /* Multiplication coefficient 1            */
    float a1              ;   /* Addition coefficient 1                  */
    float m2              ;   /* Multiplication coefficient 2            */
    float a2              ;   /* Addition coefficient 2                  */
    struct Quant q        ;   /* rules mapping cell values to index in
                                 list of labels                          */
    char **labels         ;   /* array of labels of size num             */
    int * marks           ;   /* was the value with this label was used? */
    int nalloc;
    int last_marked_rule  ;
} ;
\endcode

\section Changes_to_the_cats_file Changes to the \c cats file

The format of explicit label entries is the same for integer maps.

\verbatim
    cat:description
\endverbatim

In addition label entries of new format is supported for floating point maps.
\verbatim
    val:descr (where val is a floating point number) 
\endverbatim
or
\verbatim
    val1:val2:descr (where val1, val2 is a floating point range) 
\endverbatim

Internally the labels are stored for fp ranges of data. However when
the cats file is written, all the decimal zeros are stripped so that
integer values appear as integers in the file. Also if values are the
same, only 1 value is written (i.e. first format).

This way even though the old cats files will be processed differently
internally, the user or application programmer will not notice this
difference as long as the proper api is used and the elements of
Categories structure are not accessed directly without API calls.

\section Range_functions Range functions (new and upgraded)

\section New_Functions_to_read_write_access_and_modify_Categories_structure New Functions to read/write access and modify Categories structure

 - Rast_read_cats()

Is the same as existing Rast_read_cats().

 - Rast_copy_cats()

 - Rast_get_cat()
 - Rast_get_c_cat()
 - Rast_get_f_cat()
 - Rast_get_d_cat()

Returns pointer to a string describing category.

 - Rast_set_cat()
 - Rast_set_c_cat()
 - Rast_set_f_cat()
 - Rast_set_d_cat()

Adds the label for range in category structure.

 - Rast_number_of_cats()

Returns the number of labels. DO NOT use Rast_number_of_cats() (it
returns max cat number).

 - Rast_get_ith_cat()
 - Rast_get_ith_c_cat()
 - Rast_get_ith_f_cat()
 - Rast_get_ith_d_cat()

Returns i-th description and i-th data range from the list of category
descriptions with corresponding data ranges.

 - Rast_get_cats_title()

Returns pointer to a string with title.

 - Rast_unmark_cats()

Sets marks for all categories to 0. This initializes Categories
structure for subsequest calls to Rast_mark_cats () for each row
of data, where non-zero mark for i-th label means that some of the
cells in rast_row are labeled with i-th label and fall into i-th data
range.

These marks help determine from the Categories structure which labels
were used and which weren't.

 - Rast_get_next_marked_cat()
 - Rast_get_next_marked_c_cat()
 - Rast_get_next_marked_f_cat()
 - Rast_get_next_marked_d_cat()

Finds the next label and corresponding data range in the list of
marked categories. The category (label + data range) is marked by
Rast_mark_cats(). End points of the data range are converted to
raster type and returned. The number of times value from i-th
cat. data range appeared so far is returned in stats. See
Rast_unmark_cats(), Rast_rewind_cats() and Rast_mark_cats
().

 - Rast_mark_cats()
 - Rast_mark_c_cats()
 - Rast_mark_f_cats()
 - Rast_mark_d_cats()

Looks up the category label for each raster value in the raster row
(row of raster cell value) and updates the marks for labels found.

Note: non-zero mark for i-th label stores the number of of raster
cells read so far which are labeled with i-th label and fall into i-th
data range.

 - Rast_rewind_cats()

After call to this function Rast_get_next_marked_cat() returns the
first marked cat label.

 - Rast_init_cats()

Same as existing Rast_init_cats() only ncats argument is
missign. ncats has no meaning in new Categories structure and only
stores (int) largets data value for backwards compatibility.

 - Rast_set_cats_fmt()

Same as existing Rast_set_cats_fmt().

 - Rast_set_cats_title()

Same as existing Rast_set_cats_title().

 - Rast_write_cats()

Same as existing Rast_write_cats().

 - Rast_free_cats()

Same as existing Rast_free_cats().

\section Library_Functions_that_are_Deprecated Library Functions that are Deprecated

These functions are deprecated, since they imply that the application
that uses them has not been upgraded to handle NULL-values and should
be eliminated from GRASS code.

 - Rast_get_row()

To be replaced by Rast_get_c_row().

 - Rast_get_row_nomask()

To be replaced by Rast_get_c_row_nomask().

 - Rast_put_row()

To be replaced by Rast_put_c_row().

These functions are deprecated, since they can not be upgraded to
support NULL-values, and should be eliminated from GRASS code.

 - Rast_open_map_new_random()
 - Rast_put_row_random()

<b>Also, no support for random writing of floating-point rasters will be provided.</b>

\section Guidelines_for_upgrading_GRASS_4_x_Modules Guidelines for upgrading GRASS 4.x Modules

 - Modules that process raster maps as <em>continuous</em> data should
read raster maps as floating-point. Modules that process raster maps
as <em>nominal</em> data should read raster maps as integer.

<em>Exception:</em> Modules that process raster colors or the modules
which report on raster categories labels should either always read the
maps as floating-point, or read the maps as integer if the map is
integer and floating-point if the map is floating-point.

 - The quantization of floating-point to integer should NOT change the
   color table. The color lookup should have its own separate
   quantization.

 - The quantization of floating-point to integer should NOT change the
   Categories table. The Categories structure should have its own
   separate quantization.

 - Modules that read or write floating-point raster maps should use
<tt>double</tt> (<tt>DCELL</tt>) arrays instead of <tt>float</tt>
(<tt>FCELL</tt>) arrays.

 - Modues should process NULL values in a well defined (consistent)
   manner. Modules that processed zero as the pseudo NULL-value should
   be changed to use the true NULL-value for this and process zero as
   normal value.

 - Modules should process non-NULL values as normal numbers and not
   treat any particular numbers (e.g. zero) as special.

\section Important_hints_for_upgrades_to_modules Important hints for upgrades to raster modules

In general modules that use Rast_get_row(). Should use
Rast_get_c_row() instead.

Modules that use Rast_put_row(). Should use Rast_put_c_row()
instead.

\section Loading_the_Raster_Library Loading the Raster Library

The library is loaded by specifying

\verbatim
$(RASTERLIB)
\endverbatim

in the <tt>Makefile</tt>.

\section listOfFunctios List of functions

<b>TODO: Reorder functions</b>

\subsection MemoryAllocation Memory allocation
 - Rast_allocate_c_buf()
 - Rast_allocate_f_buf()
 - Rast_allocate_d_buf()
 - Rast_allocate_null_buf()

TODO: used in r.null and r.support, why Rast__ and not Rast_?
 - Rast__allocate_null_bits()
 - Rast__null_bitstream_size()

\subsection RasterMask Raster Mask
 - Rast_suppress_masking()
 - Rast_unsuppress_masking()

\subsection RasterStatistics Raster statistics
 - Rast_cell_size()
 - Rast_init_cell_stats()
 - Rast_update_cell_stats()
 - Rast_find_cell_stat()
 - Rast_rewind_cell_stats()
 - Rast_next_cell_stat()
 - Rast_get_stats_for_null_value()
 - Rast_free_cell_stats()
 - Rast_cell_stats_histo_eq()
 - Rast_get_cell_title()
 - Rast_cell_stats_histo_eq()

\subsection RasterCategories Raster category management
 - Rast_read_cats()
 - Rast_get_max_cat()
 - Rast_get_cats_title()
 - Rast_get_c_cat()
 - Rast_get_f_cat()
 - Rast_get_d_cat()
 - Rast_get_cat()
 - Rast_unmark_cats()
 - Rast_mark_c_cats()
 - Rast_mark_f_cats()
 - Rast_mark_d_cats()
 - Rast_mark_cats()
 - Rast_rewind_cats()
 - Rast_get_next_marked_d_cat()
 - Rast_get_next_marked_f_cat()
 - Rast_get_next_marked_c_cat()
 - Rast_get_next_marked_cat()
 - Rast_set_c_cat()
 - Rast_set_f_cat()
 - Rast_set_d_cat()
 - Rast_write_cats()
 - Rast_get_ith_d_cat()
 - Rast_get_ith_f_cat()
 - Rast_get_ith_c_cat()
 - Rast_get_ith_cat()
 - Rast_init_cats()
 - Rast_set_cats_title()
 - Rast_set_cats_fmt()
 - Rast_free_cats()
 - Rast_copy_cats()
 - Rast_number_of_cats()
 - Rast_sort_cats()

\subsection RasterFileManagement Raster file management
 - Rast_close()
 - Rast_unopen()

\subsection ColorFunctions Color functions
 - Rast_make_ryg_colors()
 - Rast_make_ryg_fp_colors()
 - Rast_make_aspect_colors()
 - Rast_make_aspect_fp_colors()
 - Rast_make_byr_colors()
 - Rast_make_byr_fp_colors()
 - Rast_make_bgyr_colors()
 - Rast_make_bgyr_fp_colors()
 - Rast_make_byg_colors()
 - Rast_make_byg_fp_colors()
 - Rast_make_grey_scale_colors()
 - Rast_make_grey_scale_fp_colors()
 - Rast_make_gyr_colors()
 - Rast_make_gyr_fp_colors()
 - Rast_make_rainbow_colors()
 - Rast_make_rainbow_fp_colors()
 - Rast_make_ramp_colors()
 - Rast_make_ramp_fp_colors()
 - Rast_make_wave_colors()
 - Rast_make_wave_fp_colors()
 - Rast_free_colors()
 - Rast_get_color()
 - Rast_get_c_color()
 - Rast_get_f_color()
 - Rast_get_d_color()
 - Rast_get_null_value_color()
 - Rast_get_default_color()
 - Rast_make_histogram_eq_colors()
 - Rast_make_histogram_log_colors()
 - Rast_init_colors()
 - Rast_invert_colors()
 - Rast_lookup_c_colors()
 - Rast_lookup_f_colors()
 - Rast_lookup_d_colors()
 - Rast_lookup_colors()
 - Rast_make_random_colors()
 - Rast_set_c_color_range()
 - Rast_set_d_color_range()
 - Rast_get_c_color_range()
 - Rast_get_d_color_range()
 - Rast_read_colors()
 - Rast_mark_colors_as_fp()
 - Rast_remove_colors()
 - Rast_add_d_color_rule()
 - Rast_add_f_color_rule()
 - Rast_add_c_color_rule()
 - Rast_add_color_rule()
 - Rast_add_modular_d_color_rule()
 - Rast_add_modular_f_color_rule()
 - Rast_add_modular_c_color_rule()
 - Rast_add_modular_color_rule()
 - Rast_colors_count()
 - Rast_get_fp_color_rule()
 - Rast_parse_color_rule()
 - Rast_parse_color_rule_error()
 - Rast_read_color_rule()
 - Rast_read_color_rules()
 - Rast_load_colors()
 - Rast_load_fp_colors()
 - Rast_make_colors()
 - Rast_make_fp_colors()
 - Rast_set_c_color()
 - Rast_set_d_color()
 - Rast_set_null_value_color()
 - Rast_set_default_color()
 - Rast_shift_c_colors()
 - Rast_shift_d_colors()
 - Rast_write_colors()

\subsection RasterFloatingPointManagement Raster floating point management
 - Rast_fpreclass_clear()
 - Rast_fpreclass_reset()
 - Rast_fpreclass_init()
 - Rast_fpreclass_set_domain()
 - Rast_fpreclass_set_range()
 - Rast_fpreclass_get_limits()
 - Rast_fpreclass_nof_rules()
 - Rast_fpreclass_get_ith_rule()
 - Rast_fpreclass_set_neg_infinite_rule()
 - Rast_fpreclass_get_neg_infinite_rule()
 - Rast_fpreclass_set_pos_infinite_rule()
 - Rast_fpreclass_get_pos_infinite_rule()
 - Rast_fpreclass_add_rule()
 - Rast_fpreclass_reverse_rule_order()
 - Rast_fpreclass_get_cell_value()
 - Rast_fpreclass_perform_di()
 - Rast_fpreclass_perform_df()
 - Rast_fpreclass_perform_dd()
 - Rast_fpreclass_perform_fi()
 - Rast_fpreclass_perform_ff()
 - Rast_fpreclass_perform_fd()
 - Rast_fpreclass_perform_ii()
 - Rast_fpreclass_perform_if()
 - Rast_fpreclass_perform_id()

\subsection RasterMapReading Raster map reading
 - Rast_get_cellhd()
 - Rast_get_row_nomask()
 - Rast_get_c_row_nomask()
 - Rast_get_f_row_nomask()
 - Rast_get_d_row_nomask()
 - Rast_get_row()
 - Rast_get_c_row()
 - Rast_get_f_row()
 - Rast_get_d_row()
 - Rast_get_null_value_row()
 - Rast_get_row_colors()

\subsection RasterMapHistogram Raster map histogram
 - Rast_histogram_eq()
 - Rast_init_histogram()
 - Rast_read_histogram()
 - Rast_write_histogram()
 - Rast_write_histogram_cs()
 - Rast_make_histogram_cs()
 - Rast_get_histogram_num()
 - Rast_get_histogram_cat()
 - Rast_get_histogram_count()
 - Rast_free_histogram()
 - Rast_sort_histogram()
 - Rast_sort_histogram_by_count()
 - Rast_remove_histogram()
 - Rast_add_histogram()
 - Rast_set_histogram()
 - Rast_extend_histogram()
 - Rast_zero_histogram()
 - Rast_want_histogram()

\subsection RasterMapHistory Raster map history
 - Rast_read_history()
 - Rast_write_history()
 - Rast_short_history()
 - Rast_command_history()

\subsection RasterMapInterpolation Raster map interpolation
 - Rast_interp_linear()
 - Rast_interp_bilinear()
 - Rast_interp_cubic()
 - Rast_interp_bicubic()

\subsection RasterMapQuantization Raster map quantization
 - Rast_quant_clear()
 - Rast_quant_free()
 - Rast_quant_init()
 - Rast_quant_is_truncate()
 - Rast_quant_is_round()
 - Rast_quant_truncate()
 - Rast_quant_round()
 - Rast_quant_get_limits()
 - Rast_quant_nof_rules()
 - Rast_quant_get_ith_rule()
 - Rast_quant_set_neg_infinite_rule()
 - Rast_quant_get_neg_infinite_rule()
 - Rast_quant_set_pos_infinite_rule()
 - Rast_quant_get_pos_infinite_rule()
 - Rast_quant_add_rule()
 - Rast_quant_reverse_rule_order()
 - Rast_quant_get_cell_value()
 - Rast_quant_perform_d()
 - Rast_quant_perform_f()
 - Rast_quantize_fp_map()
 - Rast_quantize_fp_map_range()
 - Rast_write_quant()
 - Rast_read_quant()

\subsection ToDo yet unsorted functions
 - Rast_maskfd()
 - Rast_mask_info()
 - Rast_set_null_value()
 - Rast_set_c_null_value()
 - Rast_set_f_null_value()
 - Rast_set_d_null_value()
 - Rast_is_null_value()
 - Rast_is_c_null_value()
 - Rast_is_f_null_value()
 - Rast_is_d_null_value()
 - Rast_insert_null_values()
 - Rast_insert_c_null_values()
 - Rast_insert_f_null_values()
 - Rast_insert_d_null_values()
 - Rast_open_old()
 - Rast_open_c_new()
 - Rast_open_c_new_uncompressed()
 - Rast_set_cell_format()
 - Rast_get_cell_format()
 - Rast_open_fp_new()
 - Rast_open_fp_new_uncompressed()
 - Rast_set_fp_type()
 - Rast_map_is_fp()
 - Rast_map_type()
 - Rast_get_map_type()
 - Rast_open_new()
 - Rast_open_new_uncompressed()
 - Rast_set_quant_rules()
 - Rast_put_cellhd()
 - Rast_put_row()
 - Rast_put_c_row()
 - Rast_put_f_row()
 - Rast_put_d_row()
 - Rast_put_cell_title()
 - Rast_truncate_fp_map()
 - Rast_round_fp_map()
 - Rast_construct_default_range()
 - Rast_read_fp_range()
 - Rast_read_range()
 - Rast_write_range()
 - Rast_write_fp_range()
 - Rast_update_range()
 - Rast_update_fp_range()
 - Rast_row_update_range()
 - Rast_row_update_fp_range()
 - Rast_init_range()
 - Rast_get_range_min_max()
 - Rast_init_fp_range()
 - Rast_get_fp_range_min_max()
 - Rast_raster_cmp()
 - Rast_raster_cpy()
 - Rast_set_c_value()
 - Rast_set_f_value()
 - Rast_set_d_value()
 - Rast_get_c_value()
 - Rast_get_f_value()
 - Rast_get_d_value()
 - Rast_read_units()
 - Rast_read_vdatum()
 - Rast_write_units()
 - Rast_write_vdatum()
 - Rast_is_reclass()
 - Rast_is_reclassed_to()
 - Rast_get_reclass()
 - Rast_free_reclass()
 - Rast_put_reclass()
 - Rast_get_sample_nearest()
 - Rast_get_sample_bilinear()
 - Rast_get_sample_cubic()
 - Rast_get_sample()
 - Rast_zero_c_buf()
 - Rast_zero_buf()

*/