[GRASS-SVN] r38081 - in grass/trunk/lib: . gis raster
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu Jun 25 16:10:08 EDT 2009
Author: martinl
Date: 2009-06-25 16:10:08 -0400 (Thu, 25 Jun 2009)
New Revision: 38081
Added:
grass/trunk/lib/raster/rasterlib.dox
Removed:
grass/trunk/lib/gis/gisrasterlib.dox
grass/trunk/lib/gis/gisvectorlib.dox
Modified:
grass/trunk/lib/grasslib.dox
Log:
gisrasterlib.dox moved to lib/raster
Deleted: grass/trunk/lib/gis/gisrasterlib.dox
===================================================================
--- grass/trunk/lib/gis/gisrasterlib.dox 2009-06-25 19:18:03 UTC (rev 38080)
+++ grass/trunk/lib/gis/gisrasterlib.dox 2009-06-25 20:10:08 UTC (rev 38081)
@@ -1,1851 +0,0 @@
-/*! \page gisrasterlib Raster File Processing
-<!-- doxygenized from "GRASS 5 Programmer's Manual"
- by M. Neteler 2/2004, 8/2005, 2006
- -->
-
-by GRASS Development Team (http://grass.osgeo.org)
-
-<b>TODO: this sections needs to be cleaned up. The upper GRASS 4.x and
-the lower GRASS 5.x/6.x parts need to me merged. </b>
-
-\section gisrastintro GRASS Raster File Processing
-
-Raster and vector files are the heart and soul of GRASS. Because of
-this, a suite of routines which process raster file data has been
-provided. The processing of raster files consists of determining which
-raster file or files are to be processed (specified on the module
-command line), locating the raster file in the database, opening the
-raster file, dynamically allocating i/o buffers, reading or writing
-the raster file, closing the raster file, and creating support files
-for newly created raster files.
-
-Raster file 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.
-
-- Finding_Raster_Files_in_the_Database
-- Opening_an_Existing_Raster_File
-
-\section Finding_Raster_Files_in_the_Database Finding Raster Files in
-the Database
-
-GRASS allows the user to specify raster file names (or any other
-database file) either as a simple <em>unqualified</em> name, such as
-"soils", or as a <em>fully qualified</em> name, such as
-"soils at mapset", where <i>mapset</i> is the mapset where the raster
-file is to be found. Often only the unqualified raster file name is
-provided on the command line.
-
-The following routines search the database for raster files:
-
- - G_find_cell()
-
-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 file which
-exists, then G_find_cell() modifies <i>name</i> by removing
-the "@<I>mapset</I>".
-
-For example, to find a raster file anywhere in the database:
-
-\code
-char name[GNAME_MAX];
-char *mapset;
-
-if ((mapset = G_find_cell(name,"")) == NULL)
- /* not found */
-\endcode
-
-To check that the raster file exists in the current mapset:
-
-\code
-char name[GNAME_MAX];
-
-if (G_find_cell(name, G_mapset()) == NULL)
- /* not found */
-\endcode
-
-\section Opening_an_Existing_Raster_File Opening an Existing Raster File
-
-The following routine opens the raster file for <em>reading</em>.
-
- - G_open_cell_old()
-
-This routine opens the raster file 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 files will be resampled into the current
-region, the resampling index for the raster file is prepared by this
-routine after the file is opened. The resampling is based on the
-active module region. Preparation required for reading the various
-raster file formats is also done.
-
-\section Creating_and_Opening_New_Raster_Files Creating and Opening New Raster Files
-
-The following routines create the new raster file 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 GRASS file
-name.
-
-<b>Note:</b> It is not an error for raster map to already exist. New
-raster files are actually created as temporary files and moved into
-the cell directory when closed. This allows an existing raster file to
-be read at the same time that it is being rewritten. G_find_cell()
-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).
-
- - G_open_cell_new()
-
-Creates and opens the raster file for writing by G_put_map_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.
-
- - G_open_cell_new_random()
-
-Creates and opens the raster file for writing by
-G_put_map_row_random() which allows writing the raster file in a
-<b>random</b> fashion. The file will be created uncompressed. A
-nonnegative file descriptor is returned if the open is
-successful. Otherwise a diagnostic message is printed and a negative
-value is returned.
-
- - G_open_cell_new_uncompressed()
-
-Creates and opens the raster file for writing by G_put_map_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.
-
- - G_allocate_cell_buf()
-
-This routine allocates a buffer of type CELL just large enough to hold
-one row of raster data (based on the number of columns in the active
-region).
-
-\code
-CELL *cell;
-cell = G_allocate_cell_buf(void);
-\endcode
-
-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_cell_buf()
-
-This routines assigns each member of the raster buffer array to zero.
-It assumes that the buffer has been allocated using
-G_allocate_cell_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 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.
-
-<b>THIS FUNCTION IS DEPRECATED IN GRASS 5! SEE NEXT CHAPTER!</b>
-
- - G_get_map_row()
-
-This routine reads the specified <i>row</i> from the raster file open
-on file descriptor (as returned by G_open_cell_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
-G_allocate_cell_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.
-
- - G_get_map_row_nomask()
-
-This routine reads the specified row from the raster file open on file
-descriptor into the buffer like G_get_map_row() does. The difference
-is that masking is suppressed. If the user has a mask set,
-G_get_map_row() will apply the mask but G_get_map_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
-
-
-\todo <b>Needs updating for GRASS 5!! See later in this file.</b>
-
- - G_put_map_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 G_open_cell_new(). The buffer must have been allocated large
-enough for the region, perhaps using G_allocate_cell_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;
-
-fd = G_open_cell_old("map"); /*...data for the row */
-
-G_put_map_row(fd, buf);
-\endcode
-
- - G_put_map_row_random()
-
-This routine allows random writes to the raster file open on file
-descriptor. The raster file must have been opened using
-G_open_cell_new_random(). The raster buffer contains columns of data
-and is to be written into the raster file at the specified row,
-starting at column.
-
-\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.
-
- - G_close_cell()
-
-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.
-
- - G_unopen_cell()
-
-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 contains information describing the geographic
-extent of the map layer, the grid cell resolution, and the format used
-to store the data in the raster file. The format of this file is
-described in \ref Raster_Header_Format. The routines described below
-use the <i>Cell_head</i> structure which is shown in detail in \ref
-GIS_Library_Data_Structures.
-
- - G_get_cellhd()
-
-The raster header for the raster file in the specified mapset is read
-into the <em>cellhd</em> structure. If there is an error reading the
-raster header file, a diagnostic message is printed and -1 is
-returned. Otherwise, 0 is returned.
-
-<b>Note:</b> If the raster file is a reclass file, the raster header
-for the referenced raster file is read instead. See \ref
-Reclass_Format for information about reclass files, and G_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.
-
- - G_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. If
-there was an error creating the raster header, -1 is returned. No
-diagnostic is printed. Otherwise, 1 is returned to indicate success.
-
-<b>Note:</b> Programmers should have no reason to use this routine. It
-is used by G_close_cell() 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.
-
- - G_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.
-
- - G_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
-G_put_reclass(). G_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:
-
- - G_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.
-
- - G_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).
-
- - G_get_cell_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.
-
- - G_put_cell_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:
-
- - G_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 G_get_cat() overwrite this buffer.
-
- - G_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.
-
- - G_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;
-
-G_init_cats ((CELL) 0, "", &cats);
-\endcode
-
- - G_set_cat()
-
-Copies the label into the cats structure for category.
-
- - G_set_cats_title()
-
-Copies the title is copied into the cats structure.
-
- - G_free_cats()
-
-Frees memory allocated by G_read_cats(), G_init_cats() and
-G_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.
-
- - G_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.
-
- - G_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.,
-G_init_colors() to initialize the structure and G_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.
-
- - G_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.
-
- - G_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.
-
- - G_init_colors()
-
-Initialize <i>colors</i> structure for subsequent calls
-G_add_color_rule() and G_set_color().
-
-int G_add_color_rule()
-
-This is the heart and soul of the new 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
-G_lookup_colors() G_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;
-
-G_init_colors (&colr) ;
-
-G_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
-how this routine fits into the 5.x raster color logic.
-
-<b>Note:</b> The <em>colors</em> structure must have been initialized
-by G_init_colors(). See \ref Predefined_Color_Tables for routines to
-build some predefined color tables.
-
- - G_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. G_add_color_rule() should be used whenever possible.
-
-<b>Note:</b> The <em>colors</em> structure must have been initialized
-by G_init_color().
-
- - G_get_color_range()
- - G_get_d_color_range()
-
-Get color range. Gets the minimum and maximum raster values that have
-colors associated with them.
-
- - G_free_colors()
-
-Free dynamically allocated memory associated with the <em>colors</em>
-structure.
-
-<b>Note:</b> This routine may be used after G_read_colors() as well as
-after G_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 G_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.
-
- - G_make_aspect_colors()
-
-Generates a color table for aspect data.
-
- - G_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.
-
- - G_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.
-
- - G_make_grey_scale_colors()
-
-Generates a grey scale color table. Each color is a level of grey,
-increasing from black to white.
-
- - G_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.
-
- - G_make_random_colors()
-
-Generates random colors. Good as a first pass at a color table for
-nominal data.
-
- - G_make_ryg_colors()
-
-Generates a color table that goes from red to yellow to green.
-
- - G_make_gyr_colors()
-
-Generates a color table that goes from green to yellow to red.
-
- - G_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. This
-file is discussed in \ref Raster_History_File_Format.
-
-The following routines manage this file. They use the <em>History</em>
-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.
-
- - G_read_history()
-
-Read raster history file. This routine reads the history file for the
-raster map into the <em>history</em> structure. A diagnostic message
-is printed and -1 is returned if there is an error reading the history
-file. Otherwise, 0 is returned.
-
- - G_write_history()
-
-Write raster history file. This routine writes the history file for
-the raster map in the current mapset from the <em>history</em>
-structure. A diagnostic message is printed and -1 is returned if there
-is an error writing the history file. Otherwise, 0 is returned.
-
-<b>Note:</b> The <em>history</em> structure should first be
-initialized using G_short_history().
-
- - G_short_history()
-
-Initialize history structureThis routine initializes the
-<em>history</em> 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.
-
- - G_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.
-
- - G_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:
-
- - G_init_range()
-
-Initializes the <i>range</i> structure for updates by G_update_range()
-and G_row_update_range().
-
- - G_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.
-
- - G_row_update_range()
-
-This routine updates the range data just like G_update_range().
-
-The range structure is queried using the following routine:
-
- - G_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:
-
- - G_init_cell_stats()
-
-Initialize cell stats, This routine, which must be called first,
-initializes the Cell_stats structure.
-
- - G_free_cell_stats()
-
-Free cell stats. The memory associated with structure is freed. This
-routine may be called any time after calling G_init_cell_stats().
-
-This next routine stores values in the histogram:
-
- - G_update_cell_stats()
-
-Adds data to cell stats. Once all values are stored, the structure may
-be queried either randomly (ie. search for a specific raster value) or
-sequentially (retrieve all raster values, in ascending order, and
-their related count):
-
- - G_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:
-
- - G_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.
-
- - G_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 */
-
-G_rewind_cell_stats(&s);
-
-while(G_next_cell_stat(&cat, &count, &s))
- fprintf(stdout, "%ld %ld\n", (long) cat, count);
-\endcode
-
-\section GRASS_5_raster_API GRASS 5 raster API [needs to be merged
- into above sections]
-
-\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 5.0 Changes to <TT>"gis.h"</TT>
-
-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
-
- - G_set_null_value()
-
-Set NULL value. For raster type <tt>CELL_TYPE</tt> use
-G_set_c_null_value(), for <tt>FCELL_TYPE</tt> G_set_f_null_value(),
-and for <tt>DCELL_TYPE</tt> G_set_d_null_value().
-
- - G_insert_null_values()
-
-Insert NULL value. If raster type is <tt>CELL_TYPE</tt> calls
-G_insert_c_null_values(), <tt>FCELL_TYPE</tt> calls
-G_insert_f_null_values(), and <tt>DCELL_TYPE</tt> calls
-G_insert_d_null_values().
-
- - G_is_null_value()
-
-Check NULL value. If raster type is <tt>CELL_TYPE<tt>, calls G_is_c_null_value(), <tt>FCELL_TYPE</tt> calls G_is_f_null_value(), and <tt>DCELL_TYPE</tt> calls G_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
-
- - G_allocate_null_buf()
-
-Allocates an array of char based on the number of columns in the
-current region.
-
- - G_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
-
- - G_maskfd()
-
-Test for current maskreturns file descriptor number if MASK is in use
-and -1 if no MASK is in use.
-
- - G_raster_map_is_fp()
-
-Returns true(1) if raster map is a floating-point dataset; false(0)
-otherwise.
-
- - G_raster_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)
-
- - G_open_raster_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).
-
- - G_set_fp_type()
-
-This controls the storage type for floating-point raster maps. It
-affects subsequent calls to G_open_fp_map_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.
-
- - G_open_fp_map_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 G_set_fp_type() or the default (float - unless the
-GRASS environmental variable GRASS_FP_DOUBLE is set).
-
- - G_allocate_raster_buf()
- - G_allocate_c_raster_buf()
- - G_allocate_f_raster_buf()
- - G_allocate_d_raster_buf()
-
-Allocate an arrays of CELL, FCELL, or DCELL (depending on raster type)
-based on the number of columns in the current region.
-
- - G_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 = G_incr_void_ptr(rast, G_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 += G_raster_size(data_type))
-
- - G_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).
-
- - G_raster_cmp()
-
-Compares raster values.
-
- - G_raster_cpy()
-
-Copies raster values.
-
- - G_set_raster_value_c()
-
-If G_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.
-
- - G_set_raster_value_f()
-
-If G_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.
-
- - G_set_raster_value_d()
-
-If G_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.
-
- - G_get_raster_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.
-
- - G_get_raster_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.
-
- - G_get_raster_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.
-
- - G_get_raster_row ()
-
-For CELL_TYPE raster type calls G_get_c_raster_row(), FCELL_TYPE calls
-G_get_f_raster_row(), and DCELL_TYPE G_get_d_raster_row().
-
- - G_get_raster_row_nomask().
-
-Same as G_get_f_raster_row() except no masking occurs.
-
- - G_get_f_raster_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).
-
- - G_get_f_raster_row_nomask()
-
-Same as G_get_f_raster_row() except no masking occurs.
-
- - G_get_d_raster_row()
-
-Same as G_get_f_raster_row() except that the array double.
-
- - G_get_d_raster_row_nomask()
-
-Same as G_get_d_raster_row() except no masking occurs.
-
- - G_get_c_raster_row()
-
-Reads a row of raster data and leaves the NULL values intact. (As
-opposed to the deprecated function G_get_map_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 G_set_quant_rules or stored
-in map's quant file to convert floats to integers.
-
- - G_get_c_raster_row_nomask()
-
-Same as G_get_c_raster_row() except no masking occurs.
-
- - G_put_raster_row()
-
-If raster type is CELL_TYPE, calls G_put_c_raster_row(), if FCELL_TYPE, then calls G_put_f_raster_row(), and for DCELL_TYPE, calls G_put_d_raster_row().
-
- - G_put_f_raster_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.
-
- - G_put_d_raster_row()
-
-Same as G_put_f_raster_row() except that the array is double.
-
- - G_put_c_raster_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
-G_put_map_row() which treats zero values also as NULL.)
-
- - G_zero_raster_row()
-
-Depending on raster type zeroes out G_window_cols() CELLs, FCELLs, or
-DCELLs stored in cell buffer.
-
- - G_get_raster_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.
-
- - G_close_cell()
-
-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.
-
- - G_open_cell_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
-G_get_c_raster_row(), et. al., by reading the quantization rules for
-the map using G_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 G_set_quant_rules() after the call to G_open_cell_old().
-
- - G_get_map_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 G_set_quant_rules()). NULL values are converted to zeros. <b>This
-routine is deprecated!!</b>
-
- - G_put_map_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
-G_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
-
- - G_lookup_raster_colors()
-
-If raster type is CELL_TYPE, calls G_lookup_colors(), if FCELL_TYPE,
-calls G_lookup_f_raster_colors(), and for DCELL_TYPE
-G_lookup_d_raster_colors().
-
- - G_lookup_c_raster_colors()
-
- - G_lookup_f_raster_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.
-
- - G_lookup_d_raster_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.
-
- - G_add_raster_color_rule()
-
-If raster type is CELL_TYPE, calls G_add_c_raster_color_rule(), if
-FCELL_TYPE, calls G_add_f_raster_color_rule(), and for DCELL_TYPE
-calls G_add_d_raster_color_rule().
-
- - G_get_raster_color()
-
-Looks up the rgb colors for the value in the color table.
-
- - G_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
-
- - G_set_null_value_color()
-
-Sets the color (in <em>colors</em>) for the NULL-value to <em>r,g,b</em>.
-
- - G_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
-
-
- - G_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.
-
- - G_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
-
- - G_get_raster_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 explictly cater for each of CELL, FCELL and
-DCELL types.
-
-\section Upgraded_color_functions Upgraded color functions
-
- - G_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
-G_mark_colors_as_fp().
-
- - G_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.
-
- - G_get_colors_min_max()
-
-If the color table is marked as <tt>"float"</tt>, then return the
-minimum as -(255^3 * 128) and the maximum as (255^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.
-
- - G_lookup_colors()
-
-Modified to return a color for NULL-values.
-
- - G_get_color()
-
-Modified to return a color for the NULL-value.
-
-\section Changes_to_the_Colors_structure Changes to the <TT>Colors</TT> 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 <TT>colr</TT> 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
-
- - G_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
-G_construct_default_range().
-
- - G_init_range()
-
-Must set a flag in the range structure that indicates that no min/max
-have been defined - probably a "first" boolean flag.
-
- - G_update_range()
-
-NULL-values must be detected and ignored.
-
- - G_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.
-
- - G_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
-
- - G_construct_default_range()
-
-Sets the integer range to [1,255].
-
- - G_read_raster_range()
-
-If raster type is CELL_TYPE, calls G_read_range(), otherwise calls
-G_read_fp_range().
-
- - G_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
-G_construct_default_range().
-
- - G_init_raster_range()
-
-If raster type is CELL_TYPE, calls G_init_range(), otherwise calls
-G_init_fp_range().
-
- - G_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.
-
- - G_update_f_range()
- - G_update_d_range()
-
-Updates the floating-point range from the values in NULL-values must
-be detected and ignored.
-
- - G_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.
-
- - G_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:
-
- - G_init_cell_stats()
-
-Set the count for NULL-values to zero.
-
- - G_update_cell_stats()
-
-Look for NULLs and update the NULL-value count.
-
- - G_next_cell_stat()
-
-Do not return a record for the NULL-value.
-
- - G_find_cell_stat()
-
-Allow finding the count for the NULL-value.
-
- - G_get_stats_for_null_value()
-
-Get a number of null values from stats structure. Note: when reporting
-values which appear in a map using G_next_cell_stats() , to get stats
-for null, call G_get_stats_for_null_value() first, since
-G_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:
-
- - G_write_quant()
-
-Writes the <tt>f_quant</tt> file for the raster map. If
-mapset==G_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@mapset being read using
-quant rules stored G_mapset(). See G_read_quant() for detailes.
-
- - G_set_quant_rules()
-
-Sets quant translation rules for raster map opened for reading. After
-calling this function, G_get_c_raster_row() and G_get_map_row() will
-use defined rules (instead of using rules defined in map's quant file)
-to convert floats to ints.
-
- - G_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.
-
- - G_quant_init()
-
-Initializes the Quant struct.
-
- - G_quant_free()
-
-Frees any memory allocated in Quant structure and re-initializes the
-structure by calling G_quant_init().
-
- - G_quant_truncate()
-
-Sets the quant rules to perform simple truncation on floats.
-
- - G_quant_truncate()
-
-Sets the quant rules to perform simple rounding on floats.
-
- - G_quant_organize_fp_lookup()
-
-Organizes fp_lookup table for faster (logarithmic) lookup time
-G_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
-G_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.
-
- - G_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.
-
- - G_quant_set_positive_infinite_rule()
- - G_quant_get_positive_infinite_rule()
-
-This rule has lower precedence than rules added with G_quant_add_rule().
-
- - G_quant_set_negative_infinite_rule()
-
-This rule has lower precedence than rules added with G_quant_add_rule().
-
- - G_quant_get_negative_infinite_rule()
-
- - G_quant_get_limits()
-
-Extracts the minimum and maximum floating-point and integer values
-from all the rules.
-
- - G_quant_nrules()
-
-Returns the number of rules, excluding the negative and positive
-"infinite" rules.
-
- - G_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.
-
- - G_quant_get_cell_value()
-
- - G_quant_perform_d()
-
- - G_quant_perform_f()
-
-These next two functions are convenience functions to allow applications to
-easily create quantization rules other than the defaults:
-
- - G_quantize_fp_map()
-
-Writes the <tt>f_quant</tt> file for the raster map.
-
- - G_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
-G_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 G_mark_raster_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 G_get_ith_raster_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 <TT>cats</TT> 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
-
- - G_read_raster_cats()
-
-Is the same as existing G_read_cats().
-
- - G_copy_raster_cats()
-
- - G_get_raster_cat()
- - G_get_c_raster_cat()
- - G_get_f_raster_cat()
- - G_get_d_raster_cat()
-
-Returns pointer to a string describing category.
-
- - G_set_raster_cat()
- - G_set_c_raster_cat()
- - G_set_f_raster_cat()
- - G_set_d_raster_cat()
-
-Adds the label for range in category structure.
-
- - G_number_of_raster_cats()
-
-Returns the number of labels. DO NOT use G_number_of_cats() (it
-returns max cat number).
-
- - G_get_ith_raster_cat()
- - G_get_ith_c_raster_cat()
- - G_get_ith_f_raster_cat()
- - G_get_ith_d_raster_cat()
-
-Returns i-th description and i-th data range from the list of category
-descriptions with corresponding data ranges.
-
- - G_get_raster_cats_title()
-
-Returns pointer to a string with title.
-
- - G_unmark_raster_cats()
-
-Sets marks for all categories to 0. This initializes Categories
-structure for subsequest calls to G_mark_raster_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.
-
- - G_get_next_marked_raster_cat()
- - G_get_next_marked_c_raster_cat()
- - G_get_next_marked_f_raster_cat()
- - G_get_next_marked_d_raster_cat()
-
-Finds the next label and corresponding data range in the list of
-marked categories. The category (label + data range) is marked by
-G_mark_raster_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
-G_unmark_raster_cats(), G_rewind_raster_cats() and G_mark_raster_cats
-().
-
- - G_mark_raster_cats()
- - G_mark_c_raster_cats()
- - G_mark_f_raster_cats()
- - G_mark_d_raster_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.
-
- - G_rewind_raster_cats()
-
-After call to this function G_get_next_marked_raster_cat() returns the
-first marked cat label.
-
- - G_init_raster_cats()
-
-Same as existing G_init_raster_cats() only ncats argument is
-missign. ncats has no meaning in new Categories structure and only
-stores (int) largets data value for backwards compatibility.
-
- - G_set_raster_cats_fmt()
-
-Same as existing G_set_cats_fmt().
-
- - G_set_raster_cats_title()
-
-Same as existing G_set_cats_title().
-
- - G_write_raster_cats()
-
-Same as existing G_write_cats().
-
- - G_free_raster_cats()
-
-Same as existing G_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.
-
- - G_get_map_row()
-
-To be replaced by G_get_c_raster_row().
-
- - G_get_map_row_nomask()
-
-To be replaced by G_get_c_raster_row_nomask().
-
- - G_put_map_row()
-
-To be replaced by G_put_c_raster_row().
-
-These functions are deprecated, since they can not be upgraded to
-support NULL-values, and should be eliminated from GRASS code.
-
- - G_open_map_new_random()
- - G_put_map_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_raster_modules Important hints for upgrades to raster modules
-
-In general modules that use G_get_map_row(). Should use
-G_get_c_raster_row() instead.
-
-Modules that use G_put_map_row(). Should use G_put_c_raster_row()
-instead.
-
-*/
Deleted: grass/trunk/lib/gis/gisvectorlib.dox
===================================================================
--- grass/trunk/lib/gis/gisvectorlib.dox 2009-06-25 19:18:03 UTC (rev 38080)
+++ grass/trunk/lib/gis/gisvectorlib.dox 2009-06-25 20:10:08 UTC (rev 38081)
@@ -1,282 +0,0 @@
-/*! \page gisvectorlib Vector File Processing
-<!-- doxygenized from "GRASS 5 Programmer's Manual"
- by M. Neteler 2/2004, 2006
- -->
-
-See especially \ref Vector_Library for details (extra page).
-
-- \subpage gisvectintro
-- \subpage Creating_and_Opening_New_Vector_Files
-- \subpage Vector_Category_File
-
-\section gisvectintro GRASS Vector File Processing
-Authors:
-<BR>
-(Written by CERL, with contributions from David D. Gray)
-<P>
-The <I>GIS Library</I> contains some functions related to vector file
-processing. These include prompting the user for vector files,
-locating vector files in the database, opening vector files, and a few
-others.
-
-<P>
-<B>Note.</B> Most vector file processing, however, is handled by
-routines in the <I>Vector Library</I>, which is described in
-Vector_Library.
-
-<P>
-
-
-\subsection Prompting_for_Vector_Files Prompting for Vector Files
-
-<P>
-The following routines interactively prompt the user for a vector file
-name. In each, the <B>prompt</B> string will be printed as the first
-line of the full prompt which asks the user to enter a vector file
-name. If <B>prompt</B> is the empty string "" then an appropriate
-prompt will be substituted. The name that the user enters is copied
-into the <B>name</B> buffer. The size of name should be large enough
-to hold any GRASS file name. Most systems allow file names to be quite
-long. It is recommended that name be declared <tt>char name</tt>.
-These routines have a built-in 'list' capability which allows the user
-to get a list of existing vector files.
-
-<P>
-The user is required to enter a valid vector file name, or else hit
-the RETURN key to cancel the request. If the user enters an invalid
-response, a message is printed, and the user is prompted again. If the
-user cancels the request, the NULL pointer is returned. Otherwise the
-mapset where the vector file lives or is to be created is
-returned. Both the name and the mapset are used in other routines to
-refer to the vector file.
-
-
-<P>
-char *G_ask_vector_old(char *prompt, char *name) prompt for an
-existing vector file
-
-Asks the user to enter the name of an existing vector file in any
-mapset in the database.
-
-<P>
-char *G_ask_vector_in_mapset(char *prompt, char *name) prompt for an
-existing vector file
-
-Asks the user to enter the name of an existing vector file in the
-current mapset.
-
-<P>
-char *G_ask_vector_new(char *prompt, char *name) prompt for a new
-vector file
-
-Asks the user to enter a name for a vector file which does not exist
-in the current mapset.
-
-<P>
-Here is an example of how to use these routines. Note that the
-programmer must handle the NULL return properly:
-
-\verbatim
-char *mapset;
-char name[GNAME_MAX];
-
-mapset = G_ask_vector_old("Enter vector file to be processed", name);
-
-if (mapset == NULL)
- exit(0);
-\endverbatim
-
-
-\subsection Finding_Vector_Files_in_the_Database Finding Vector Files
- in the Database
-
-
-<P>
-Noninteractive modules cannot make use of the interactive prompting
-routines described above. For example, a command line driven module
-may require a vector file name as one of the command arguments. GRASS
-allows the user to specify vector file names (or any other database
-file) either as a simple unqualified name, such as "roads", or as a
-fully qualified name, such as "roads in <I>mapset</I>", where
-<I>mapset</I> is the mapset where the vector file is to be
-found. Often only the unqualified vector file name is provided on the
-command line.
-
-<P>
-The following routines search the database for vector files:
-
-<P>
-int G_find_vector(char *name, char *mapset) find a vector file
-
-<P>
-int G_find_vector2(char *name, char *mapset) find a vector
- file
-
-Look for the vector file <B>name</B> in the database. The
-<B>mapset</B> parameter can either be the empty string "", which means
-search all the mapsets in the user's current mapset search path (see
-Mapset_Search_Path for more details about the search path), or it can
-be a specific mapset name, which means look for the vector file only
-in this one mapset (for example, in the current mapset). If found, the
-mapset where the vector file lives is returned. If not found, the NULL
-pointer is returned.
-
-<P>
-The difference between these two routines is that if the user
-specifies a fully qualified vector file which exists, then
-<I>G_find_vector2()</I> modifies <B>name</B> by removing the "in
-<I>mapset</I>" while <I>G_find_vector()</I> does not. Be warned that
-G_find_vector2() should not be used directly on a command line
-argument, since modifying argv[ ] may not be valid. The argument
-should be copied to another character buffer which is then passed to
-G_find_vector2(). Normally, the GRASS programmer need not worry about
-qualified vs. unqualified names since all library routines handle
-both forms. However, if the programmer wants the name to be returned
-unqualified (for displaying the name to the user, or storing it in a
-data file, etc.), then <I>G_find_vector2()</I> should be used.
-
-<P>
-For example, to find a vector file anywhere in the database:
-
-\verbatim
-char name[GNAME_MAX];
-char *mapset;
-
-if ((mapset = G_find_vector(name,"")) == NULL)
- /* not found */
-\endverbatim
-
-\verbatim
-
-char name[GNAME_MAX];
-
-if (G_find_vector(name,G_mapset()) == NULL)
- /* not found */
-\endverbatim
-
-To check that the vector file exists in the current mapset:
-
-
-\subsection Opening_an_Existing_Vector_File Opening an Existing Vector File
-
-
-The following routine opens the vector file <B>name</B> in
-<B>mapset</B> for reading.
-
-<P>
-The vector file <B>name</B> and <B>mapset</B> can be obtained
-interactively using <I>G_ask_vector_old()</I> or <I>
-G_ask_vector_in_mapset()</I>, and noninteractively using
-<I>G_find_vector()</I> or <I>G_find_vector2().</I>
-
-<P>
-FILE *G_fopen_vector_old(char *name, char *mapset) open an existing
-vector file
-
-This routine opens the vector file <B>name</B> in <B>mapset</B> for
-reading. A file descriptor is returned if the open is
-successful. Otherwise the NULL pointer is returned (no diagnostic
-message is printed).
-
-<P>
-The file descriptor can then be used with routines in the <I>Dig
-Library</I> to read the vector file (See \ref Vector_Library).
-
-<P>
-<B>Note.</B> This routine does not call any routines in the <I>Dig
-Library</I>; No initialization of the vector file is done by this
-routine, directly or indirectly.
-
-
-
-\section Creating_and_Opening_New_Vector_Files Creating and Opening
- New Vector Files
-
-
-The following routine creates the new vector file <B>name</B> in the
-current mapset (GRASS does not allow files to be created outside the
-current mapset. See \ref Database_Access_Rules) and opens it for
-writing. The vector file <B>name</B> should be obtained interactively
-using <I>G_ask_vector_new().</I> If obtained noninteractively (e.g.,
-from the command line), <I>G_legal_filename()</I> should be called
-first to make sure that <B>name</B> is a valid GRASS file name.
-
-<P>
-<B>Warning.</B> If <B>name</B> already exists, it will be erased and
-re-created empty. The interactive routine <I>G_ask_vector_new()</I>
-guarantees that <B>name</B> will not exist, but if <B>name</B> is
-obtained from the command line, <B>name</B> may exist. In this case
-<I>G_find_vector()</I> could be used to see if <B>name</B> exists.
-
-<P>
-FILE *G_fopen_vector_new(char *name) open a new vector file
-
-Creates and opens the vector file <B>name</B> for writing.
-
-<P>
-A file descriptor is returned if the open is successful. Otherwise the
-NULL pointer is returned (no diagnostic message is printed).
-
-<P>
-The file descriptor can then be used with routines in the <I>Dig
-Library</I> to write the <I>vector file</I> (See \ref Vector_Library.)
-
-<P>
-<B>Note.</B> This routine does not call any routines in the <I>Dig
-Library</I>; No initialization of the vector file is done by this
-routine, directly or indirectly. Also, only the vector file itself
-(i.e., the <I>dig</I> file), is created. None of the other vector
-support files are created, removed, or modified in any way.
-
-
-\subsection Reading_and_Writing_Vector_Files Reading and Writing Vector Files
-
-
-Reading and writing vector files is handled by routines in the <I>Dig
-Library.</I> See \ref Vector_Library for details.
-
-
-\section Vector_Category_File Vector Category File
-
-GRASS vector files have category labels associated with them. The
-category file is structured so that each category in the vector file
-can have a one-line description.
-
-<P>
-The routines described below read and write the vector category
-file. They use the <I>Categories structure</I> which is described in
-GIS_Library_Data_Structures.
-
-<P>
-<B>Note.</B> The vector category file has exactly the same structure
-as the raster category file. In fact, it exists so that the module
-<I>v.to.rast</I> can convert a vector file to a raster file that has
-an up-to-date category file.
-
-<P>
-The routines described in
-Querying_and_Changing_the_Categories_Structure which modify the
-<I>Categories</I> structure can therefore be used to set and change
-vector categories as well.
-
-<P>
-int G_read_vector_cats(char *name, name *mapset, struct Categories
-*cats) read vector category file
-
-The category file for vector file <B>name</B> in <B>mapset</B> is read
-into the <B>cats</B> structure. If there is an error reading the
-category file, a diagnostic message is printed and -1 is
-returned. Otherwise, 0 is returned.
-
-<P>
-int G_write_vector_cats(char *name, struct Categories *cats) write
-vector category file
-
-Writes the category file for the vector file <B>name</B> in the
-current mapset from the <B>cats</B> structure.
-
-<P>
-Returns 1 if successful. Otherwise, -1 is returned (no diagnostic is
-printed).
-
-*/
Modified: grass/trunk/lib/grasslib.dox
===================================================================
--- grass/trunk/lib/grasslib.dox 2009-06-25 19:18:03 UTC (rev 38080)
+++ grass/trunk/lib/grasslib.dox 2009-06-25 20:10:08 UTC (rev 38081)
@@ -4,8 +4,8 @@
* updated 8/2005, 2006, 2007, 2008
-->
-<a href="http://grass.osgeo.org">GRASS GIS</a> (Geographic Resources
-Analysis Support System) is an open source, Free Software
+<a href="http://grass.osgeo.org">GRASS GIS</a> (<b>Geographic Resources
+Analysis Support System</b>) is an open source, Free Software
<em>Geographical Information System</em> (GIS) with raster,
topological %vector, image processing, and graphics production
functionality that operates on various platforms through a graphical
@@ -61,10 +61,9 @@
(the name refers to the directory name in lib/ in the source code)
- - gis: \ref gislib, with following subsection
- - \ref gisrasterlib
- - \ref gisvectorlib
- - Sites File Processing (legacy, merged into \ref gisvectorlib)
+ - gis: \ref gislib
+ - raster: \ref rasterlib
+ - vector: \ref Vector_Library
\section libs Further libraries
@@ -95,7 +94,7 @@
- proj: \ref projlib (wrapper to PROJ4 projection library)
- psdriver: PostScript display driver library - \ref psdriver
- python: \ref pythonlib
- - raster: \ref rastergraphicslib (note: raster map functions are in \ref gislib)
+ - raster: \ref rasterlib
- rowio: Raster row in/out library - \ref rowio
- rst: Library for interpolation with regularized splines with tension - \ref rst
- segment: \ref segmentlib (segment library for segmented raster reading)
Copied: grass/trunk/lib/raster/rasterlib.dox (from rev 38078, grass/trunk/lib/gis/gisrasterlib.dox)
===================================================================
--- grass/trunk/lib/raster/rasterlib.dox (rev 0)
+++ grass/trunk/lib/raster/rasterlib.dox 2009-06-25 20:10:08 UTC (rev 38081)
@@ -0,0 +1,1851 @@
+/*! \page rasterlib GRASS Raster Library
+<!-- doxygenized from "GRASS 5 Programmer's Manual"
+ by M. Neteler 2/2004, 8/2005, 2006
+ -->
+
+by GRASS Development Team (http://grass.osgeo.org)
+
+<b>TODO: this sections needs to be cleaned up. The upper GRASS 4.x and
+the lower GRASS 5.x/6.x parts need to me merged. </b>
+
+\section gisrastintro GRASS Raster File Processing
+
+Raster and vector files are the heart and soul of GRASS. Because of
+this, a suite of routines which process raster file data has been
+provided. The processing of raster files consists of determining which
+raster file or files are to be processed (specified on the module
+command line), locating the raster file in the database, opening the
+raster file, dynamically allocating i/o buffers, reading or writing
+the raster file, closing the raster file, and creating support files
+for newly created raster files.
+
+Raster file 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.
+
+- Finding_Raster_Files_in_the_Database
+- Opening_an_Existing_Raster_File
+
+\section Finding_Raster_Files_in_the_Database Finding Raster Files in
+the Database
+
+GRASS allows the user to specify raster file names (or any other
+database file) either as a simple <em>unqualified</em> name, such as
+"soils", or as a <em>fully qualified</em> name, such as
+"soils at mapset", where <i>mapset</i> is the mapset where the raster
+file is to be found. Often only the unqualified raster file name is
+provided on the command line.
+
+The following routines search the database for raster files:
+
+ - G_find_cell()
+
+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 file which
+exists, then G_find_cell() modifies <i>name</i> by removing
+the "@<I>mapset</I>".
+
+For example, to find a raster file anywhere in the database:
+
+\code
+char name[GNAME_MAX];
+char *mapset;
+
+if ((mapset = G_find_cell(name,"")) == NULL)
+ /* not found */
+\endcode
+
+To check that the raster file exists in the current mapset:
+
+\code
+char name[GNAME_MAX];
+
+if (G_find_cell(name, G_mapset()) == NULL)
+ /* not found */
+\endcode
+
+\section Opening_an_Existing_Raster_File Opening an Existing Raster File
+
+The following routine opens the raster file for <em>reading</em>.
+
+ - G_open_cell_old()
+
+This routine opens the raster file 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 files will be resampled into the current
+region, the resampling index for the raster file is prepared by this
+routine after the file is opened. The resampling is based on the
+active module region. Preparation required for reading the various
+raster file formats is also done.
+
+\section Creating_and_Opening_New_Raster_Files Creating and Opening New Raster Files
+
+The following routines create the new raster file 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 GRASS file
+name.
+
+<b>Note:</b> It is not an error for raster map to already exist. New
+raster files are actually created as temporary files and moved into
+the cell directory when closed. This allows an existing raster file to
+be read at the same time that it is being rewritten. G_find_cell()
+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).
+
+ - G_open_cell_new()
+
+Creates and opens the raster file for writing by G_put_map_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.
+
+ - G_open_cell_new_random()
+
+Creates and opens the raster file for writing by
+G_put_map_row_random() which allows writing the raster file in a
+<b>random</b> fashion. The file will be created uncompressed. A
+nonnegative file descriptor is returned if the open is
+successful. Otherwise a diagnostic message is printed and a negative
+value is returned.
+
+ - G_open_cell_new_uncompressed()
+
+Creates and opens the raster file for writing by G_put_map_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.
+
+ - G_allocate_cell_buf()
+
+This routine allocates a buffer of type CELL just large enough to hold
+one row of raster data (based on the number of columns in the active
+region).
+
+\code
+CELL *cell;
+cell = G_allocate_cell_buf(void);
+\endcode
+
+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_cell_buf()
+
+This routines assigns each member of the raster buffer array to zero.
+It assumes that the buffer has been allocated using
+G_allocate_cell_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 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.
+
+<b>THIS FUNCTION IS DEPRECATED IN GRASS 5! SEE NEXT CHAPTER!</b>
+
+ - G_get_map_row()
+
+This routine reads the specified <i>row</i> from the raster file open
+on file descriptor (as returned by G_open_cell_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
+G_allocate_cell_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.
+
+ - G_get_map_row_nomask()
+
+This routine reads the specified row from the raster file open on file
+descriptor into the buffer like G_get_map_row() does. The difference
+is that masking is suppressed. If the user has a mask set,
+G_get_map_row() will apply the mask but G_get_map_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
+
+
+\todo <b>Needs updating for GRASS 5!! See later in this file.</b>
+
+ - G_put_map_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 G_open_cell_new(). The buffer must have been allocated large
+enough for the region, perhaps using G_allocate_cell_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;
+
+fd = G_open_cell_old("map"); /*...data for the row */
+
+G_put_map_row(fd, buf);
+\endcode
+
+ - G_put_map_row_random()
+
+This routine allows random writes to the raster file open on file
+descriptor. The raster file must have been opened using
+G_open_cell_new_random(). The raster buffer contains columns of data
+and is to be written into the raster file at the specified row,
+starting at column.
+
+\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.
+
+ - G_close_cell()
+
+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.
+
+ - G_unopen_cell()
+
+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 contains information describing the geographic
+extent of the map layer, the grid cell resolution, and the format used
+to store the data in the raster file. The format of this file is
+described in \ref Raster_Header_Format. The routines described below
+use the <i>Cell_head</i> structure which is shown in detail in \ref
+GIS_Library_Data_Structures.
+
+ - G_get_cellhd()
+
+The raster header for the raster file in the specified mapset is read
+into the <em>cellhd</em> structure. If there is an error reading the
+raster header file, a diagnostic message is printed and -1 is
+returned. Otherwise, 0 is returned.
+
+<b>Note:</b> If the raster file is a reclass file, the raster header
+for the referenced raster file is read instead. See \ref
+Reclass_Format for information about reclass files, and G_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.
+
+ - G_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. If
+there was an error creating the raster header, -1 is returned. No
+diagnostic is printed. Otherwise, 1 is returned to indicate success.
+
+<b>Note:</b> Programmers should have no reason to use this routine. It
+is used by G_close_cell() 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.
+
+ - G_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.
+
+ - G_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
+G_put_reclass(). G_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:
+
+ - G_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.
+
+ - G_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).
+
+ - G_get_cell_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.
+
+ - G_put_cell_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:
+
+ - G_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 G_get_cat() overwrite this buffer.
+
+ - G_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.
+
+ - G_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;
+
+G_init_cats ((CELL) 0, "", &cats);
+\endcode
+
+ - G_set_cat()
+
+Copies the label into the cats structure for category.
+
+ - G_set_cats_title()
+
+Copies the title is copied into the cats structure.
+
+ - G_free_cats()
+
+Frees memory allocated by G_read_cats(), G_init_cats() and
+G_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.
+
+ - G_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.
+
+ - G_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.,
+G_init_colors() to initialize the structure and G_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.
+
+ - G_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.
+
+ - G_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.
+
+ - G_init_colors()
+
+Initialize <i>colors</i> structure for subsequent calls
+G_add_color_rule() and G_set_color().
+
+int G_add_color_rule()
+
+This is the heart and soul of the new 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
+G_lookup_colors() G_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;
+
+G_init_colors (&colr) ;
+
+G_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
+how this routine fits into the 5.x raster color logic.
+
+<b>Note:</b> The <em>colors</em> structure must have been initialized
+by G_init_colors(). See \ref Predefined_Color_Tables for routines to
+build some predefined color tables.
+
+ - G_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. G_add_color_rule() should be used whenever possible.
+
+<b>Note:</b> The <em>colors</em> structure must have been initialized
+by G_init_color().
+
+ - G_get_color_range()
+ - G_get_d_color_range()
+
+Get color range. Gets the minimum and maximum raster values that have
+colors associated with them.
+
+ - G_free_colors()
+
+Free dynamically allocated memory associated with the <em>colors</em>
+structure.
+
+<b>Note:</b> This routine may be used after G_read_colors() as well as
+after G_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 G_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.
+
+ - G_make_aspect_colors()
+
+Generates a color table for aspect data.
+
+ - G_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.
+
+ - G_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.
+
+ - G_make_grey_scale_colors()
+
+Generates a grey scale color table. Each color is a level of grey,
+increasing from black to white.
+
+ - G_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.
+
+ - G_make_random_colors()
+
+Generates random colors. Good as a first pass at a color table for
+nominal data.
+
+ - G_make_ryg_colors()
+
+Generates a color table that goes from red to yellow to green.
+
+ - G_make_gyr_colors()
+
+Generates a color table that goes from green to yellow to red.
+
+ - G_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. This
+file is discussed in \ref Raster_History_File_Format.
+
+The following routines manage this file. They use the <em>History</em>
+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.
+
+ - G_read_history()
+
+Read raster history file. This routine reads the history file for the
+raster map into the <em>history</em> structure. A diagnostic message
+is printed and -1 is returned if there is an error reading the history
+file. Otherwise, 0 is returned.
+
+ - G_write_history()
+
+Write raster history file. This routine writes the history file for
+the raster map in the current mapset from the <em>history</em>
+structure. A diagnostic message is printed and -1 is returned if there
+is an error writing the history file. Otherwise, 0 is returned.
+
+<b>Note:</b> The <em>history</em> structure should first be
+initialized using G_short_history().
+
+ - G_short_history()
+
+Initialize history structureThis routine initializes the
+<em>history</em> 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.
+
+ - G_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.
+
+ - G_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:
+
+ - G_init_range()
+
+Initializes the <i>range</i> structure for updates by G_update_range()
+and G_row_update_range().
+
+ - G_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.
+
+ - G_row_update_range()
+
+This routine updates the range data just like G_update_range().
+
+The range structure is queried using the following routine:
+
+ - G_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:
+
+ - G_init_cell_stats()
+
+Initialize cell stats, This routine, which must be called first,
+initializes the Cell_stats structure.
+
+ - G_free_cell_stats()
+
+Free cell stats. The memory associated with structure is freed. This
+routine may be called any time after calling G_init_cell_stats().
+
+This next routine stores values in the histogram:
+
+ - G_update_cell_stats()
+
+Adds data to cell stats. Once all values are stored, the structure may
+be queried either randomly (ie. search for a specific raster value) or
+sequentially (retrieve all raster values, in ascending order, and
+their related count):
+
+ - G_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:
+
+ - G_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.
+
+ - G_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 */
+
+G_rewind_cell_stats(&s);
+
+while(G_next_cell_stat(&cat, &count, &s))
+ fprintf(stdout, "%ld %ld\n", (long) cat, count);
+\endcode
+
+\section GRASS_5_raster_API GRASS 5 raster API [needs to be merged
+ into above sections]
+
+\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 5.0 Changes to <TT>"gis.h"</TT>
+
+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
+
+ - G_set_null_value()
+
+Set NULL value. For raster type <tt>CELL_TYPE</tt> use
+G_set_c_null_value(), for <tt>FCELL_TYPE</tt> G_set_f_null_value(),
+and for <tt>DCELL_TYPE</tt> G_set_d_null_value().
+
+ - G_insert_null_values()
+
+Insert NULL value. If raster type is <tt>CELL_TYPE</tt> calls
+G_insert_c_null_values(), <tt>FCELL_TYPE</tt> calls
+G_insert_f_null_values(), and <tt>DCELL_TYPE</tt> calls
+G_insert_d_null_values().
+
+ - G_is_null_value()
+
+Check NULL value. If raster type is <tt>CELL_TYPE<tt>, calls G_is_c_null_value(), <tt>FCELL_TYPE</tt> calls G_is_f_null_value(), and <tt>DCELL_TYPE</tt> calls G_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
+
+ - G_allocate_null_buf()
+
+Allocates an array of char based on the number of columns in the
+current region.
+
+ - G_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
+
+ - G_maskfd()
+
+Test for current maskreturns file descriptor number if MASK is in use
+and -1 if no MASK is in use.
+
+ - G_raster_map_is_fp()
+
+Returns true(1) if raster map is a floating-point dataset; false(0)
+otherwise.
+
+ - G_raster_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)
+
+ - G_open_raster_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).
+
+ - G_set_fp_type()
+
+This controls the storage type for floating-point raster maps. It
+affects subsequent calls to G_open_fp_map_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.
+
+ - G_open_fp_map_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 G_set_fp_type() or the default (float - unless the
+GRASS environmental variable GRASS_FP_DOUBLE is set).
+
+ - G_allocate_raster_buf()
+ - G_allocate_c_raster_buf()
+ - G_allocate_f_raster_buf()
+ - G_allocate_d_raster_buf()
+
+Allocate an arrays of CELL, FCELL, or DCELL (depending on raster type)
+based on the number of columns in the current region.
+
+ - G_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 = G_incr_void_ptr(rast, G_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 += G_raster_size(data_type))
+
+ - G_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).
+
+ - G_raster_cmp()
+
+Compares raster values.
+
+ - G_raster_cpy()
+
+Copies raster values.
+
+ - G_set_raster_value_c()
+
+If G_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.
+
+ - G_set_raster_value_f()
+
+If G_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.
+
+ - G_set_raster_value_d()
+
+If G_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.
+
+ - G_get_raster_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.
+
+ - G_get_raster_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.
+
+ - G_get_raster_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.
+
+ - G_get_raster_row ()
+
+For CELL_TYPE raster type calls G_get_c_raster_row(), FCELL_TYPE calls
+G_get_f_raster_row(), and DCELL_TYPE G_get_d_raster_row().
+
+ - G_get_raster_row_nomask().
+
+Same as G_get_f_raster_row() except no masking occurs.
+
+ - G_get_f_raster_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).
+
+ - G_get_f_raster_row_nomask()
+
+Same as G_get_f_raster_row() except no masking occurs.
+
+ - G_get_d_raster_row()
+
+Same as G_get_f_raster_row() except that the array double.
+
+ - G_get_d_raster_row_nomask()
+
+Same as G_get_d_raster_row() except no masking occurs.
+
+ - G_get_c_raster_row()
+
+Reads a row of raster data and leaves the NULL values intact. (As
+opposed to the deprecated function G_get_map_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 G_set_quant_rules or stored
+in map's quant file to convert floats to integers.
+
+ - G_get_c_raster_row_nomask()
+
+Same as G_get_c_raster_row() except no masking occurs.
+
+ - G_put_raster_row()
+
+If raster type is CELL_TYPE, calls G_put_c_raster_row(), if FCELL_TYPE, then calls G_put_f_raster_row(), and for DCELL_TYPE, calls G_put_d_raster_row().
+
+ - G_put_f_raster_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.
+
+ - G_put_d_raster_row()
+
+Same as G_put_f_raster_row() except that the array is double.
+
+ - G_put_c_raster_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
+G_put_map_row() which treats zero values also as NULL.)
+
+ - G_zero_raster_row()
+
+Depending on raster type zeroes out G_window_cols() CELLs, FCELLs, or
+DCELLs stored in cell buffer.
+
+ - G_get_raster_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.
+
+ - G_close_cell()
+
+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.
+
+ - G_open_cell_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
+G_get_c_raster_row(), et. al., by reading the quantization rules for
+the map using G_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 G_set_quant_rules() after the call to G_open_cell_old().
+
+ - G_get_map_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 G_set_quant_rules()). NULL values are converted to zeros. <b>This
+routine is deprecated!!</b>
+
+ - G_put_map_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
+G_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
+
+ - G_lookup_raster_colors()
+
+If raster type is CELL_TYPE, calls G_lookup_colors(), if FCELL_TYPE,
+calls G_lookup_f_raster_colors(), and for DCELL_TYPE
+G_lookup_d_raster_colors().
+
+ - G_lookup_c_raster_colors()
+
+ - G_lookup_f_raster_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.
+
+ - G_lookup_d_raster_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.
+
+ - G_add_raster_color_rule()
+
+If raster type is CELL_TYPE, calls G_add_c_raster_color_rule(), if
+FCELL_TYPE, calls G_add_f_raster_color_rule(), and for DCELL_TYPE
+calls G_add_d_raster_color_rule().
+
+ - G_get_raster_color()
+
+Looks up the rgb colors for the value in the color table.
+
+ - G_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
+
+ - G_set_null_value_color()
+
+Sets the color (in <em>colors</em>) for the NULL-value to <em>r,g,b</em>.
+
+ - G_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
+
+
+ - G_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.
+
+ - G_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
+
+ - G_get_raster_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 explictly cater for each of CELL, FCELL and
+DCELL types.
+
+\section Upgraded_color_functions Upgraded color functions
+
+ - G_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
+G_mark_colors_as_fp().
+
+ - G_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.
+
+ - G_get_colors_min_max()
+
+If the color table is marked as <tt>"float"</tt>, then return the
+minimum as -(255^3 * 128) and the maximum as (255^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.
+
+ - G_lookup_colors()
+
+Modified to return a color for NULL-values.
+
+ - G_get_color()
+
+Modified to return a color for the NULL-value.
+
+\section Changes_to_the_Colors_structure Changes to the <TT>Colors</TT> 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 <TT>colr</TT> 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
+
+ - G_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
+G_construct_default_range().
+
+ - G_init_range()
+
+Must set a flag in the range structure that indicates that no min/max
+have been defined - probably a "first" boolean flag.
+
+ - G_update_range()
+
+NULL-values must be detected and ignored.
+
+ - G_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.
+
+ - G_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
+
+ - G_construct_default_range()
+
+Sets the integer range to [1,255].
+
+ - G_read_raster_range()
+
+If raster type is CELL_TYPE, calls G_read_range(), otherwise calls
+G_read_fp_range().
+
+ - G_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
+G_construct_default_range().
+
+ - G_init_raster_range()
+
+If raster type is CELL_TYPE, calls G_init_range(), otherwise calls
+G_init_fp_range().
+
+ - G_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.
+
+ - G_update_f_range()
+ - G_update_d_range()
+
+Updates the floating-point range from the values in NULL-values must
+be detected and ignored.
+
+ - G_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.
+
+ - G_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:
+
+ - G_init_cell_stats()
+
+Set the count for NULL-values to zero.
+
+ - G_update_cell_stats()
+
+Look for NULLs and update the NULL-value count.
+
+ - G_next_cell_stat()
+
+Do not return a record for the NULL-value.
+
+ - G_find_cell_stat()
+
+Allow finding the count for the NULL-value.
+
+ - G_get_stats_for_null_value()
+
+Get a number of null values from stats structure. Note: when reporting
+values which appear in a map using G_next_cell_stats() , to get stats
+for null, call G_get_stats_for_null_value() first, since
+G_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:
+
+ - G_write_quant()
+
+Writes the <tt>f_quant</tt> file for the raster map. If
+mapset==G_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@mapset being read using
+quant rules stored G_mapset(). See G_read_quant() for detailes.
+
+ - G_set_quant_rules()
+
+Sets quant translation rules for raster map opened for reading. After
+calling this function, G_get_c_raster_row() and G_get_map_row() will
+use defined rules (instead of using rules defined in map's quant file)
+to convert floats to ints.
+
+ - G_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.
+
+ - G_quant_init()
+
+Initializes the Quant struct.
+
+ - G_quant_free()
+
+Frees any memory allocated in Quant structure and re-initializes the
+structure by calling G_quant_init().
+
+ - G_quant_truncate()
+
+Sets the quant rules to perform simple truncation on floats.
+
+ - G_quant_truncate()
+
+Sets the quant rules to perform simple rounding on floats.
+
+ - G_quant_organize_fp_lookup()
+
+Organizes fp_lookup table for faster (logarithmic) lookup time
+G_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
+G_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.
+
+ - G_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.
+
+ - G_quant_set_positive_infinite_rule()
+ - G_quant_get_positive_infinite_rule()
+
+This rule has lower precedence than rules added with G_quant_add_rule().
+
+ - G_quant_set_negative_infinite_rule()
+
+This rule has lower precedence than rules added with G_quant_add_rule().
+
+ - G_quant_get_negative_infinite_rule()
+
+ - G_quant_get_limits()
+
+Extracts the minimum and maximum floating-point and integer values
+from all the rules.
+
+ - G_quant_nrules()
+
+Returns the number of rules, excluding the negative and positive
+"infinite" rules.
+
+ - G_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.
+
+ - G_quant_get_cell_value()
+
+ - G_quant_perform_d()
+
+ - G_quant_perform_f()
+
+These next two functions are convenience functions to allow applications to
+easily create quantization rules other than the defaults:
+
+ - G_quantize_fp_map()
+
+Writes the <tt>f_quant</tt> file for the raster map.
+
+ - G_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
+G_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 G_mark_raster_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 G_get_ith_raster_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 <TT>cats</TT> 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
+
+ - G_read_raster_cats()
+
+Is the same as existing G_read_cats().
+
+ - G_copy_raster_cats()
+
+ - G_get_raster_cat()
+ - G_get_c_raster_cat()
+ - G_get_f_raster_cat()
+ - G_get_d_raster_cat()
+
+Returns pointer to a string describing category.
+
+ - G_set_raster_cat()
+ - G_set_c_raster_cat()
+ - G_set_f_raster_cat()
+ - G_set_d_raster_cat()
+
+Adds the label for range in category structure.
+
+ - G_number_of_raster_cats()
+
+Returns the number of labels. DO NOT use G_number_of_cats() (it
+returns max cat number).
+
+ - G_get_ith_raster_cat()
+ - G_get_ith_c_raster_cat()
+ - G_get_ith_f_raster_cat()
+ - G_get_ith_d_raster_cat()
+
+Returns i-th description and i-th data range from the list of category
+descriptions with corresponding data ranges.
+
+ - G_get_raster_cats_title()
+
+Returns pointer to a string with title.
+
+ - G_unmark_raster_cats()
+
+Sets marks for all categories to 0. This initializes Categories
+structure for subsequest calls to G_mark_raster_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.
+
+ - G_get_next_marked_raster_cat()
+ - G_get_next_marked_c_raster_cat()
+ - G_get_next_marked_f_raster_cat()
+ - G_get_next_marked_d_raster_cat()
+
+Finds the next label and corresponding data range in the list of
+marked categories. The category (label + data range) is marked by
+G_mark_raster_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
+G_unmark_raster_cats(), G_rewind_raster_cats() and G_mark_raster_cats
+().
+
+ - G_mark_raster_cats()
+ - G_mark_c_raster_cats()
+ - G_mark_f_raster_cats()
+ - G_mark_d_raster_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.
+
+ - G_rewind_raster_cats()
+
+After call to this function G_get_next_marked_raster_cat() returns the
+first marked cat label.
+
+ - G_init_raster_cats()
+
+Same as existing G_init_raster_cats() only ncats argument is
+missign. ncats has no meaning in new Categories structure and only
+stores (int) largets data value for backwards compatibility.
+
+ - G_set_raster_cats_fmt()
+
+Same as existing G_set_cats_fmt().
+
+ - G_set_raster_cats_title()
+
+Same as existing G_set_cats_title().
+
+ - G_write_raster_cats()
+
+Same as existing G_write_cats().
+
+ - G_free_raster_cats()
+
+Same as existing G_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.
+
+ - G_get_map_row()
+
+To be replaced by G_get_c_raster_row().
+
+ - G_get_map_row_nomask()
+
+To be replaced by G_get_c_raster_row_nomask().
+
+ - G_put_map_row()
+
+To be replaced by G_put_c_raster_row().
+
+These functions are deprecated, since they can not be upgraded to
+support NULL-values, and should be eliminated from GRASS code.
+
+ - G_open_map_new_random()
+ - G_put_map_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_raster_modules Important hints for upgrades to raster modules
+
+In general modules that use G_get_map_row(). Should use
+G_get_c_raster_row() instead.
+
+Modules that use G_put_map_row(). Should use G_put_c_raster_row()
+instead.
+
+*/
More information about the grass-commit
mailing list