[GRASS-SVN] r37793 - in grass/trunk/lib: . gis
svn_grass at osgeo.org
svn_grass at osgeo.org
Tue Jun 9 14:40:28 EDT 2009
Author: martinl
Date: 2009-06-09 14:40:28 -0400 (Tue, 09 Jun 2009)
New Revision: 37793
Modified:
grass/trunk/lib/gis/adj_cellhd.c
grass/trunk/lib/gis/alloc_cell.c
grass/trunk/lib/gis/cats.c
grass/trunk/lib/gis/cell_stats.c
grass/trunk/lib/gis/closecell.c
grass/trunk/lib/gis/color_compat.c
grass/trunk/lib/gis/color_free.c
grass/trunk/lib/gis/color_get.c
grass/trunk/lib/gis/color_hist.c
grass/trunk/lib/gis/color_init.c
grass/trunk/lib/gis/color_look.c
grass/trunk/lib/gis/color_range.c
grass/trunk/lib/gis/color_read.c
grass/trunk/lib/gis/color_rule.c
grass/trunk/lib/gis/color_set.c
grass/trunk/lib/gis/color_write.c
grass/trunk/lib/gis/find_cell.c
grass/trunk/lib/gis/get_cellhd.c
grass/trunk/lib/gis/get_row.c
grass/trunk/lib/gis/gislib.dox
grass/trunk/lib/gis/gisrasterlib.dox
grass/trunk/lib/gis/history.c
grass/trunk/lib/gis/maskfd.c
grass/trunk/lib/gis/null_val.c
grass/trunk/lib/gis/opencell.c
grass/trunk/lib/gis/progrm_nme.c
grass/trunk/lib/gis/put_cellhd.c
grass/trunk/lib/gis/range.c
grass/trunk/lib/gis/raster.c
grass/trunk/lib/gis/reclass.c
grass/trunk/lib/gis/timestamp.c
grass/trunk/lib/gis/whoami.c
grass/trunk/lib/grasslib.dox
grass/trunk/lib/loc_struct.png
Log:
major gislib.dox update (still not complete, r37744)
various minor doxygen fixes
Modified: grass/trunk/lib/gis/adj_cellhd.c
===================================================================
--- grass/trunk/lib/gis/adj_cellhd.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/adj_cellhd.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,45 +1,43 @@
-
-/**
- * \file adj_cellhd.c
+/*!
+ * \file gis/adj_cellhd.c
*
* \brief GIS Library - CELL header adjustment.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
#include <grass/glocale.h>
-
-/**
+/*!
* \brief Adjust cell header.
*
- * This function fills in missing parts of the input
- * cell header (or region). It also makes projection-specific adjustments. The
- * <b>cellhd</b> structure must have its <i>north, south, east, west</i>,
- * and <i>proj</i> fields set.
+ * This function fills in missing parts of the input cell header (or
+ * region). It also makes projection-specific adjustments. The
+ * <i>cellhd</i> structure must have its <i>north, south, east,
+ * west</i>, and <i>proj</i> fields set.
*
- * If <b>row_flag</b> is true, then the north-south resolution is computed
- * from the number of <i>rows</i> in the <b>cellhd</b> structure. Otherwise the number of
- * <i>rows</i> is computed from the north-south resolution in the structure, similarly for
- * <b>col_flag</b> and the number of columns and the east-west resolution.
+ * If <i>row_flag</i> is true, then the north-south resolution is
+ * computed from the number of <i>rows</i> in the <i>cellhd</i>
+ * structure. Otherwise the number of <i>rows</i> is computed from the
+ * north-south resolution in the structure, similarly for
+ * <i>col_flag</i> and the number of columns and the east-west
+ * resolution.
*
* <b>Note:</b> 3D values are not adjusted.
*
- * \param[in,out] cellhd
- * \param[in] row_flag
- * \param[in] col_flag
+ * \param[in,out] cellhd pointer to Cell_head structure
+ * \param row_flag compute n-s resolution
+ * \param col_flag compute e-w resolution
+
* \return NULL on success
- * \return Localized text string on error
+ * \return localized text string on error
*/
-
const char *G_adjust_Cell_head(struct Cell_head *cellhd, int row_flag, int col_flag)
{
if (!row_flag) {
@@ -163,34 +161,33 @@
return NULL;
}
-
-/**
+/*!
* \brief Adjust cell header for 3D values.
*
- * This function fills in missing parts of the input
- * cell header (or region). It also makes projection-specific adjustments. The
- * <b>cellhd</b> structure must have its <i>north, south, east, west</i>,
- * and <i>proj</i> fields set.
+ * This function fills in missing parts of the input cell header (or
+ * region). It also makes projection-specific adjustments. The
+ * <i>cellhd</i> structure must have its <i>north, south, east,
+ * west</i>, and <i>proj</i> fields set.
*
- * If <b>row_flag</b> is true, then the north-south resolution is computed
- * from the number of <i>rows</i> in the <b>cellhd</b> structure.
+ * If <i>row_flag</i> is true, then the north-south resolution is computed
+ * from the number of <i>rows</i> in the <i>cellhd</i> structure.
* Otherwise the number of <i>rows</i> is computed from the north-south
- * resolution in the structure, similarly for <b>col_flag</b> and the
+ * resolution in the structure, similarly for <i>col_flag</i> and the
* number of columns and the east-west resolution.
*
- * If <b>depth_flag</b> is true, top-bottom resolution is calculated
+ * If <i>depth_flag</i> is true, top-bottom resolution is calculated
* from depths.
- * If <b>depth_flag</b> are false, number of depths is calculated from
+ * If <i>depth_flag</i> are false, number of depths is calculated from
* top-bottom resolution.
*
- * \param[in,out] cellhd
- * \param[in] row_flag
- * \param[in] col_flag
- * \param[in] depth_flag
+ * \param[in,out] cellhd pointer to Cell_head structure
+ * \param row_flag compute n-s resolution
+ * \param col_flag compute e-w resolution
+ * \param depth_flag compute t-b resolution
+ *
* \return NULL on success
- * \return Localized text string on error
+ * \return localized text string on error
*/
-
const char *G_adjust_Cell_head3(struct Cell_head *cellhd, int row_flag,
int col_flag, int depth_flag)
{
Modified: grass/trunk/lib/gis/alloc_cell.c
===================================================================
--- grass/trunk/lib/gis/alloc_cell.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/alloc_cell.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,17 +1,14 @@
-
-/**
- * \file alloc_cell.c
+/*!
+ * \file gis/alloc_cell.c
*
* \brief GIS Library - Raster allocation routines.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <math.h>
@@ -23,16 +20,16 @@
static const int type_size[3] = { sizeof(CELL), sizeof(FCELL), sizeof(DCELL) };
-
-/**
+/*!
* \brief Returns size of a raster CELL in bytes.
*
- * If <b>data_type</b> is CELL_TYPE, returns sizeof(CELL)
- * If <b>data_type</b> is FCELL_TYPE, returns sizeof(FCELL)
- * If <b>data_type</b> is DCELL_TYPE, returns sizeof(DCELL)
+ * - If <i>data_type</i> is CELL_TYPE, returns sizeof(CELL)
+ * - If <i>data_type</i> is FCELL_TYPE, returns sizeof(FCELL)
+ * - If <i>data_type</i> is DCELL_TYPE, returns sizeof(DCELL)
*
- * \param[in] data_type
- * \return int
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return raster type size
*/
size_t G_raster_size(RASTER_MAP_TYPE data_type)
@@ -40,134 +37,124 @@
return (type_size[F2I(data_type)]);
}
-
-/**
+/*!
* \brief Allocate memory for a CELL type raster map.
*
* 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.<br>
+ * active region.
+ *
\code
CELL *cell;
- cell = G_allocate_cell_buf ();
+ cell = G_allocate_cell_buf();
\endcode
- * If larger buffers are required, the routine <i>G_malloc</i> can be used.
- * The routine is generally used with each open cell file.<br>
- * <b>Note:</b> <i>G_allocate_raster_buf()</i> or
- * <i>G_alloc_c_raster_buf()</i> is preferred over
- * <i>G_allocate_cell_buf()</i>.
*
- * \return CELL * Pointer to allocated buffer
- * \return Prints error message and calls <i>exit()</i> on error
+ * If larger buffers are required, the routine G_malloc() can be used.
+ * The routine is generally used with each open cell file.
+ *
+ * <b>Note:</b> G_allocate_raster_buf() or G_alloc_c_raster_buf() is
+ * preferred over G_allocate_cell_buf().
+ *
+ * Prints error message and calls exit() on error.
+ *
+ * \return CELL * pointer to allocated buffer
*/
-
CELL *G_allocate_cell_buf(void)
{
return (CELL *) G_calloc(G_window_cols() + 1, sizeof(CELL));
}
-
-/**
- * \brief Allocate memory for a raster map of type <b>data_type</b>.
+/*!
+ * \brief Allocate memory for a raster map of given type
*
- * Allocate an array of CELL, FCELL, or DCELL (depending on
- * <b>data_type</b>) based on the number of columns in the current
+ * Allocate an array of CELL, FCELL, or DCELL (depending on
+ * <i>data_type</i>) based on the number of columns in the current
* region.
*
- * \param[in] data_type
- * \return void *
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return pointer to allocated buffer
*/
-
void *G_allocate_raster_buf(RASTER_MAP_TYPE data_type)
{
return (void *)G_calloc(G_window_cols() + 1, G_raster_size(data_type));
}
-
-/**
+/*!
* \brief Allocates memory for a raster map of type CELL.
*
- * Allocate an array of CELL based on the number of columns in the
+ * Allocate an array of CELL based on the number of columns in the
* current region.
*
- * \return CELL *
+ * \return pointer to allocated buffer
*/
-
CELL *G_allocate_c_raster_buf(void)
{
return (CELL *) G_calloc(G_window_cols() + 1, sizeof(CELL));
}
-
-/**
+/*!
* \brief Allocates memory for a raster map of type FCELL.
*
* Allocate an array of FCELL based on the number of columns in the
* current region.
*
- * \return FCELL *
+ * \return pointer to allocated buffer
*/
-
FCELL *G_allocate_f_raster_buf(void)
{
return (FCELL *) G_calloc(G_window_cols() + 1, sizeof(FCELL));
}
-
-/**
+/*!
* \brief Allocates memory for a raster map of type DCELL.
*
- * Allocate an array of DCELL based on the number of columns in the
+ * Allocate an array of DCELL based on the number of columns in the
* current region.
*
- * \return DCELL *
+ * \return pointer to allocated buffer
*/
-
DCELL *G_allocate_d_raster_buf(void)
{
return (DCELL *) G_calloc(G_window_cols() + 1, sizeof(DCELL));
}
-
-/**
+/*!
* \brief Allocates memory for a null buffer.
*
* Allocate an array of char based on the number of columns in the
* current region.
*
- * \return char *
+ * \return pointer to allocated buffer
*/
-
char *G_allocate_null_buf(void)
{
return (char *)G_calloc(G_window_cols() + 1, sizeof(char));
}
-
-/**
+/*!
* \brief Allocates memory for null bits.
*
- * Allocates an array of unsigned char based on <b>cols</b>.
+ * Allocates an array of unsigned char based on <i>cols</i>.
*
- * \param[in] cols number of columns in region
- * \return unsigned char *
+ * \param cols number of columns in region
+ *
+ * \return pointer to allocated buffer
*/
-
unsigned char *G__allocate_null_bits(int cols)
{
return (unsigned char *)G_calloc(G__null_bitstream_size(cols) + 1,
sizeof(unsigned char));
}
-
-/**
+/*!
* \brief Determines null bitstream size.
*
- * \param[in] cols number of columns
- * \return -1 if <b>cols</b> is invalid (<= 0)
+ * \param cols number of columns
+ *
+ * \return -1 if <i>cols</i> is invalid (<= 0)
* \return size of null bistream
*/
-
int G__null_bitstream_size(int cols)
{
if (cols <= 0)
Modified: grass/trunk/lib/gis/cats.c
===================================================================
--- grass/trunk/lib/gis/cats.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/cats.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,6 +1,8 @@
-
-/**********************************************************************
+/*!
+ * \file gis/cats.c
*
+ * \brief GIS Library - Raster categories management
+ *
* Code in this file works with category files. There are two formats:
* Pre 3.0 direct category encoding form:
*
@@ -57,268 +59,14 @@
* since i-th rule and i-th label are entered at the same time, we
* know that i-th rule maps fp range to i, thus we know for sure
* that cats.labels[i] corresponds to i-th quant rule
- *
- **********************************************************************
*
- * G_read_[raster]_cats (name, mapset, pcats)
- * const char *name name of cell file
- * const char *mapset mapset that cell file belongs to
- * struct Categories *pcats structure to hold category info
+ * (C) 2001-2009 by the GRASS Development Team
*
- * Reads the category information associated with cell file "name"
- * in mapset "mapset" into the structure "pcats".
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * returns: 0 if successful
- * -1 on fail
- *
- * note: a warning message is printed if the file is
- * "missing" or "invalid".
- **********************************************************************
- *
- * G_copy_raster_cats (pcats_to, pcats_from)
- * struct Categories *pcats_to
- * const struct Categories *pcats_from
- *
- * Allocates NEW space for quant rules and labels and copies
- * all info from "from" cats to "to" cats
- *
- * returns: 0 if successful
- * -1 on fail
- *
- **********************************************************************
- *
- * G_read_vector_cats (name, mapset, pcats)
- * const char *name name of vector map
- * const char *mapset mapset that vector map belongs to
- * struct Categories *pcats structure to hold category info
- *
- *
- * returns: 0 if successful
- * -1 on fail
- *
- * note: a warning message is printed if the file is
- * "missing" or "invalid".
- **********************************************************************
- * Returns pointer to a string describing category.
- **********************************************************************
- *
- * G_number_of_cats(name, mapset)
- * returns the largest category number in the map.
- * -1 on error
- * WARING: do not use for fp maps!
- **********************************************************************
- *
- * char *
- * G_get_c/f/d_raster_cat (num, pcats)
- * [F/D]CELL *val pointer to cell value
- * struct Categories *pcats structure to hold category info
- *
- * Returns pointer to a string describing category.
- *
- **********************************************************************
- *
- * char *
- * G_get_raster_cat (val, pcats, data_type)
- * void *val pointer to cell value
- * struct Categories *pcats structure to hold category info
- * RASTER_MAP_TYPE data_type type of raster cell
- *
- * Returns pointer to a string describing category.
- *
- **********************************************************************
- *
- * char *
- * G_get_ith_c/f/d_raster_cat (pcats, i, rast1, rast2)
- * [F/D]CELL *rast1, *rast2 cat range
- * struct Categories *pcats structure to hold category info
- *
- * Returns pointer to a string describing category.
- *
- **********************************************************************
- *
- * int
- * G_number_of_raster_cats (pcats)
- * struct Categories *pcats structure to hold category info
- *
- * Returns pcats->ncats number of labels
- *
- **********************************************************************
- *
- * char *
- * G_get_ith_raster_cat (pcats, i, rast1, rast2, data_type)
- * void *rast1, *rast2 cat range
- * struct Categories *pcats structure to hold category info
- * RASTER_MAP_TYPE data_type type of raster cell
- *
- * Returns pointer to a string describing category.
- *
- **********************************************************************
- *
- * char *
- * G_get_[raster]_cats_title (pcats)
- * struct Categories *pcats structure to hold category info
- *
- * Returns pointer to a string with title
- *
- **********************************************************************
- *
- * G_init_cats (ncats, title, pcats)
- * CELL ncats number of categories
- * const char *title cell title
- * struct Categories *pcats structure to hold category info
- *
- * Initializes the cats structure for subsequent calls to G_set_cat()
- **********************************************************************
- *
- * G_unmark_raster_cats (pcats)
- * struct Categories *pcats structure to hold category info
- *
- * initialize cats.marks: the statistics of how many values of map
- * have each label
- *
- **********************************************************************
- *
- * G_rewind_raster_cats (pcats)
- * struct Categories *pcats structure to hold category info
- *
- * after calll to this function G_get_next_marked_raster_cat() returns
- * rhe first marked cat label.
- *
- **********************************************************************
- *
- * char* G_get_next_marked_raster_cat(pcats, rast1, rast2, stats, data_type)
- * struct Categories *pcats structure to hold category info
- * void *rast1, *rast2; pointers to raster range
- * long *stats;
- * RASTER_MAP_TYPE data_type
- *
- * returns the next marked label.
- * NULL if none found
- *
- **********************************************************************
- *
- * char* G_get_next_marked_f/d/craster_cat(pcats, rast1, rast2, stats)
- * struct Categories *pcats structure to hold category info
- * [D/F]CELL *rast1, *rast2; pointers to raster range
- * long *stats;
- *
- * returns the next marked label.
- * NULL if none found
- *
- **********************************************************************
- *
- * G_mark_raster_cats (rast_row, ncols, pcats, data_type)
- * void *raster_row; raster row to update stats
- * struct Categories *pcats structure to hold category info
- * RASTER_MAP_TYPE data_type;
- * Finds the index of label for each raster cell in a row, and
- * increases pcats->marks[index]
- * Note: if there are no explicit cats: only rules for cats, no
- * marking is done.
- *
- **********************************************************************
- *
- * G_mark_c/d/f_raster_cats (rast_row, ncols, pcats)
- * int ncols;
- * [D?F]CELL *raster_row; raster row to update stats
- * struct Categories *pcats structure to hold category info
- *
- * Finds the index of label for each raster cell in a row, and
- * increases pcats->marks[index]
- *
- **********************************************************************
- *
- * G_init_raster_cats (title, pcats)
- * const char *title cell title
- * struct Categories *pcats structure to hold category info
- *
- * Initializes the cats structure for subsequent calls to G_set_cat()
- *
- **********************************************************************
- *
- * G_set_[raster]_cats_fmt (fmt, m1, a1, m2, a2, pcats)
- * const char *fmt user form of the equation format
- * float m1,a1,m2,a2 coefficients
- * struct Categories *pcats structure to hold category info
- *
- * configures the cats structure for the equation. Must be called
- * after G_init_cats().
- *
- **********************************************************************
- *
- * G_set_[raster]_cats_title (title, pcats)
- * const char *title cell file title
- * struct Categories *pcats structure holding category info
- *
- * Store title as cell file in cats structure
- * Returns nothing.
- *
- **********************************************************************
- *
- * G_set_cat (num, label, pcats)
- * CELL num category number
- * const char *label category label
- * struct Categories *pcats structure to hold category info
- *
- * Adds the string buff to represent category "num" in category structure
- * pcats.
- *
- * Returns: 0 is cat is null value -1 too many cats, 1 ok.
- *
- **********************************************************************
- *
- * G_set_[f/d/c]_raster_cat (&val1, &val2, label, pcats)
- * [D/F]CELL *val1, *val2; pointers to raster values
- * const char *label category label
- * struct Categories *pcats structure to hold category info
- *
- * Adds the label for range val1 through val2 in category structure
- * pcats.
- *
- * Returns: 0 if cat is null value -1 too many cats, 1 ok.
- *
- **********************************************************************
- *
- * G_set_raster_cat (val1, val2, label, pcats, data_type)
- * void *val1, *val2; pointers to raster values
- * const char *label category label
- * struct Categories *pcats structure to hold category info
- * RASTER_MAP_TYPE data_type type of raster cell
- *
- * Adds the label for range val1 through val2 in category structure
- * pcats.
- *
- * Returns: 0 if cat is null value -1 too many cats, 1 ok.
- *
- **********************************************************************
- *
- * G_write_[raster]_cats (name, pcats)
- * const char *name name of cell file
- * struct Categories *pcats structure holding category info
- *
- * Writes the category information associated with cell file "name"
- * into current mapset from the structure "pcats".
- *
- * returns: 1 if successful
- * -1 on fail
- **********************************************************************
- *
- * G_write_vector_cats (name, pcats)
- * const char *name name of vector map
- * struct Categories *pcats structure holding category info
- *
- * Writes the category information associated with vector map "name"
- * into current mapset from the structure "pcats".
- *
- * returns: 1 if successful
- * -1 on fail
- **********************************************************************
- *
- * G_free_[raster]_cats (pcats)
- * struct Categories *pcats structure holding category info
- *
- * Releases memory allocated for the cats structure
- **********************************************************************/
+ * \author Original author CERL
+ */
#include <stdlib.h>
#include <string.h>
@@ -334,38 +82,46 @@
const char *name,
const char *mapset, struct Categories * pcats, int full);
+static struct Categories save_cats;
+
/*!
- * \brief read raster category file
+ * \brief Read raster category file
*
- * The category file for raster map
- * <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.
+ * \todo Remove, the function G_read_raster_cats()
*
- * \param name
- * \param mapset
- * \param cats
- * \return int
+ * The category file for raster map <i>name</i> in <i>mapset</i> 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.
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] cats pointer to Cats structure
+ *
+ * \return -1 on error
+ * \return 0 on success
*/
-
int G_read_cats(const char *name,
const char *mapset, struct Categories *pcats)
{
return G_read_raster_cats(name, mapset, pcats);
}
-
/*!
- * \brief
+ * \brief Read raster category file
*
- * Is the same as existing G_read_cats()
+ * The category file for raster map <i>name</i> in <i>mapset</i> 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.
*
- * \param name
- * \param mapset
- * \param pcats
- * \return int
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] cats pointer to Cats structure
+ *
+ * \return -1 on error
+ * \return 0 on success
*/
-
int G_read_raster_cats(const char *name,
const char *mapset, struct Categories *pcats)
{
@@ -382,26 +138,28 @@
return 0;
}
- G_warning(_("category support for [%s] in mapset [%s] %s"),
+ G_warning(_("Category support for <%s@%s> %s"),
name, mapset, type);
return -1;
}
-
/*!
- * \brief read vector category file
+ * \brief Read vector category file
*
- * The category file for vector map
- * <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.
+ * <b>Note:</b> This function works with <b>old</b> vector format.
+
+ * The category file for vector map <i>name</i> in <i>mapset</i> 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.
*
- * \param name
- * \param mapset
- * \param cats
- * \return int
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] cats pointer to Cats structure
+ *
+ * \return -1 on error
+ * \return 0 on success
*/
-
int G_read_vector_cats(const char *name,
const char *mapset, struct Categories *pcats)
{
@@ -418,11 +176,20 @@
return 0;
}
- G_warning(_("category support for vector map [%s] in mapset [%s] %s"),
+ G_warning(_("Category support for vector map <%s@%s> %s"),
name, mapset, type);
return -1;
}
+/*!
+ \brief Get number of categories
+
+ \param name map name
+ \param mapset mapset name
+
+ \return -1 on error
+ \return number of cats
+*/
CELL G_number_of_cats(const char *name, const char *mapset)
{
struct Range range;
@@ -532,18 +299,21 @@
return -1;
}
-
/*!
- * \brief get title from category structure struct
+ * \brief Get title from category structure struct
*
- * Map layers store a one-line title in the category structure
- * as well. This routine returns a pointer to the title contained in the
- * <b>cats</b> 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.
+ * \todo Remove from GIS Library, replace by G_get_raster_cats_title().
*
- * \param cats
- * \return char *
+ * Map layers store a one-line title in the category structure as
+ * well. This routine returns a pointer to the title contained in the
+ * <i>cats</i> 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.
+ *
+ * \param cats pointer to Categories structure
+ *
+ * \return title
+ * \return "" if missing
*/
char *G_get_cats_title(const struct Categories *pcats)
@@ -551,14 +321,15 @@
return G_get_raster_cats_title(pcats);
}
-
/*!
- * \brief get raster cats title
+ * \brief Get raster cats title
*
* Returns pointer to a string with title.
*
- * \param pcats
- * \return char *
+ * \param pcats pointer to Categories structure
+ *
+ * \return title
+ * \return "" if missing
*/
char *G_get_raster_cats_title(const struct Categories *pcats)
@@ -566,91 +337,124 @@
return pcats->title ? pcats->title : "";
}
-
/*!
- * \brief get a category label
+ * \brief Get a raster category label
*
- * This routine looks up category <b>n</b> in the <b>cats</b>
- * 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 <b>cats,</b> 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.
+ * \todo Remove from GIS Library, replaced by G_get_c_raster_cat().
*
- * \param n
- * \param cats
- * \return char *
+ * This routine looks up category <i>num</i> in the <i>pcats</i>
+ * 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 <i>pcats</i>, 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.
+ *
+ * \param num cell value
+ * \param pcats pointer to Categories structure
+ *
+ * \return pointer to category label
+ * \return "" if category is not found
*/
-
char *G_get_cat(CELL num, struct Categories *pcats)
{
return G_get_c_raster_cat(&num, pcats);
}
-
/*!
- * \brief
+ * \brief Get a raster category label (CELL)
*
- * given a CELL value <em>val</em> Returns pointer to a string describing
- * category.
+ * This routine looks up category <i>rast</i> in the <i>pcats</i>
+ * 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 <i>pcats</i>, then a pointer to the empty string
+ * "" is returned.
*
- * \param val
- * \param pcats
- * \return char *
+ * <b>Warning:</b> The pointer that is returned points to a hidden
+ * static buffer. Successive calls to G_get_cat() overwrite this
+ * buffer.
+ *
+ * \param rast cell value
+ * \param pcats pointer to Categories structure
+ *
+ * \return pointer to category label
+ * \return "" if category is not found
*/
-
char *G_get_c_raster_cat(CELL * rast, struct Categories *pcats)
{
return G_get_raster_cat(rast, pcats, CELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Get a raster category label (FCELL)
*
- * given a FCELL value <em>val</em> Returns pointer to a string
- * describing category.
+ * This routine looks up category <i>rast</i> in the <i>pcats</i>
+ * 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 <i>pcats</i>, then a pointer to the empty string
+ * "" is returned.
*
- * \param val
- * \param pcats
- * \return char *
+ * <b>Warning:</b> The pointer that is returned points to a hidden
+ * static buffer. Successive calls to G_get_cat() overwrite this
+ * buffer.
+ *
+ * \param rast cell value
+ * \param pcats pointer to Categories structure
+ *
+ * \return pointer to category label
+ * \return "" if category is not found
*/
-
char *G_get_f_raster_cat(FCELL * rast, struct Categories *pcats)
{
return G_get_raster_cat(rast, pcats, FCELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Get a raster category label (DCELL)
*
- * given a DCELL value <em>val</em> Returns pointer to a string
- * describing category.
+ * This routine looks up category <i>rast</i> in the <i>pcats</i>
+ * 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 <i>pcats</i>, then a pointer to the empty string
+ * "" is returned.
*
- * \param val
- * \param pcats
- * \return char *
+ * <b>Warning:</b> The pointer that is returned points to a hidden
+ * static buffer. Successive calls to G_get_cat() overwrite this
+ * buffer.
+ *
+ * \param rast cell value
+ * \param pcats pointer to Categories structure
+ *
+ * \return pointer to category label
+ * \return "" if category is not found
*/
-
char *G_get_d_raster_cat(DCELL * rast, struct Categories *pcats)
{
return G_get_raster_cat(rast, pcats, DCELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Get a raster category label
*
- * given a raster value <em>val</em> of type <em>data_type</em> Returns pointer to a string
- * describing category.
+ * This routine looks up category <i>rast</i> in the <i>pcats</i>
+ * 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 <i>pcats</i>, then a pointer to the empty string
+ * "" is returned.
*
- * \param val
- * \param pcats
- * \param data_type
- * \return char *
+ * <b>Warning:</b> The pointer that is returned points to a hidden
+ * static buffer. Successive calls to G_get_cat() overwrite this
+ * buffer.
+ *
+ * \param rast cell value
+ * \param pcats pointer to Categories structure
+ * \param data_type map type (CELL, FCELL, DCELL)
+ *
+ * \return pointer to category label
+ * \return "" if category is not found
*/
-
char *G_get_raster_cat(void *rast,
struct Categories *pcats, RASTER_MAP_TYPE data_type)
{
@@ -714,112 +518,108 @@
return label;
}
-
/*!
- * \brief
+ * \brief Sets marks for all categories to 0.
*
- * Sets marks
- * for all categories to 0. This initializes Categories structure for subsequest
- * calls to G_mark_raster_cats (rast_row,...) 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.
+ * 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.
*
- * \param pcats
- * \return
+ * \param pcats pointer to Categories structure
*/
-
void G_unmark_raster_cats(struct Categories *pcats)
-{ /* structure to hold category info */
+{
int i;
for (i = 0; i < pcats->ncats; i++)
pcats->marks[i] = 0;
}
-
/*!
- * \brief
+ * \brief Looks up the category label for each raster value (CELL).
+ *
+ * Looks up the category label for each raster value in the
+ * <i>rast_row</i> and updates the marks for labels found.
*
- * Looks up the category label for each raster value in
- * the <em>rast_row</em> 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.
+ * <b>Note:</b> 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.
*
- * \param rast_row
- * \param ncols
- * \param pcats
- * \return
+ * \param rast_row raster row to update stats
+ * \param ncols number of columns
+ * \param pcats pointer to Categories structure
+ *
*/
-
-void G_mark_c_raster_cats(const CELL * rast_row, /* raster row to update stats */
+void G_mark_c_raster_cats(const CELL * rast_row,
int ncols, struct Categories *pcats)
-{ /* structure to hold category info */
+{
G_mark_raster_cats(rast_row, ncols, pcats, CELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Looks up the category label for each raster value (FCELL).
+ *
+ * Looks up the category label for each raster value in the
+ * <i>rast_row</i> and updates the marks for labels found.
*
- * Looks up the category label for each raster value in
- * the <em>rast_row</em> 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.
+ * <b>Note:</b> 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.
*
- * \param rast_row
- * \param ncols
- * \param pcats
- * \return
+ * \param rast_row raster row to update stats
+ * \param ncols number of columns
+ * \param pcats pointer to Categories structure
+ *
*/
-
-void G_mark_f_raster_cats(const FCELL * rast_row, /* raster row to update stats */
+void G_mark_f_raster_cats(const FCELL * rast_row,
int ncols, struct Categories *pcats)
-{ /* structure to hold category info */
+{
G_mark_raster_cats(rast_row, ncols, pcats, FCELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Looks up the category label for each raster value (DCELL).
+ *
+ * Looks up the category label for each raster value in the
+ * <i>rast_row</i> and updates the marks for labels found.
*
- * Looks up the category label for each raster value in
- * the <em>rast_row</em> 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.
+ * <b>Note:</b> 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.
*
- * \param rast_row
- * \param ncols
- * \param pcats
- * \return
+ * \param rast_row raster row to update stats
+ * \param ncols number of columns
+ * \param pcats pointer to Categories structure
+ *
*/
-
-void G_mark_d_raster_cats(const DCELL * rast_row, /* raster row to update stats */
+void G_mark_d_raster_cats(const DCELL * rast_row,
int ncols, struct Categories *pcats)
-{ /* structure to hold category info */
+{
G_mark_raster_cats(rast_row, ncols, pcats, DCELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Looks up the category label for each raster value (DCELL).
+ *
+ * Looks up the category label for each raster value in the
+ * <i>rast_row</i> and updates the marks for labels found.
*
- * Looks up the category
- * label for each raster value in the <em>rast_row</em> (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.
+ * <b>Note:</b> 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.
*
- * \param rast_row
- * \param ncols
- * \param pcats
- * \param data_type
- * \return int
+ * \param rast_row raster row to update stats
+ * \param ncols number of columns
+ * \param pcats pointer to Categories structure
+ *
+ * \return -1 on error
+ * \return 1 on success
*/
-
-int G_mark_raster_cats(const void *rast_row, /* raster row to update stats */
- int ncols, struct Categories *pcats, /* structure to hold category info */
+int G_mark_raster_cats(const void *rast_row,
+ int ncols, struct Categories *pcats,
RASTER_MAP_TYPE data_type)
{
CELL i;
@@ -837,25 +637,31 @@
return 1;
}
-
/*!
- * \brief
+ * \brief Rewind raster categories
*
- * after call to
- * this function G_get_next_marked_raster_cat() returns the first marked
- * cat label.
+ * After call to this function G_get_next_marked_raster_cat() returns
+ * the first marked cat label.
*
- * \param pcats
- * \return
+ * \param pcats pointer to Categories structure
*/
-
void G_rewind_raster_cats(struct Categories *pcats)
{
pcats->last_marked_rule = -1;
}
-char *G_get_next_marked_d_raster_cat(struct Categories *pcats, /* structure to hold category info */
- DCELL * rast1, DCELL * rast2, /* pointers to raster range */
+/*!
+ \brief Get next marked raster categories (DCELL)
+
+ \param pcats pointer to Categories structure
+ \param rast1, rast2 cell values (raster range)
+ \param[out] count count
+
+ \return NULL if not found
+ \return description if found
+*/
+char *G_get_next_marked_d_raster_cat(struct Categories *pcats,
+ DCELL * rast1, DCELL * rast2,
long *count)
{
char *descr = NULL;
@@ -863,13 +669,12 @@
found = 0;
/* pcats->ncats should be == G_quant_nof_rules(&pcats->q) */
- /* DEBUG
- fprintf (stderr, "last marked %d nrules %d\n", pcats->last_marked_rule, G_quant_nof_rules(&pcats->q));
- */
- for (i = pcats->last_marked_rule + 1; i < G_quant_nof_rules(&pcats->q);
- i++) {
+
+ G_debug(3, "last marked %d nrules %d\n", pcats->last_marked_rule, G_quant_nof_rules(&pcats->q));
+
+ for (i = pcats->last_marked_rule + 1; i < G_quant_nof_rules(&pcats->q); i++) {
descr = G_get_ith_d_raster_cat(pcats, i, rast1, rast2);
- /* DEBUG fprintf (stderr, "%d %d\n", i, pcats->marks[i]); */
+ G_debug(5, "%d %d", i, pcats->marks[i]);
if (pcats->marks[i]) {
found = 1;
break;
@@ -884,24 +689,55 @@
return descr;
}
-char *G_get_next_marked_c_raster_cat(struct Categories *pcats, /* structure to hold category info */
- CELL * rast1, CELL * rast2, /* pointers to raster range */
+/*!
+ \brief Get next marked raster categories (CELL)
+
+ \param pcats pointer to Categories structure
+ \param rast1, rast2 cell values (raster range)
+ \param[out] count count
+
+ \return NULL if not found
+ \return description if found
+*/
+char *G_get_next_marked_c_raster_cat(struct Categories *pcats,
+ CELL * rast1, CELL * rast2,
long *count)
{
return G_get_next_marked_raster_cat(pcats, rast1, rast2, count,
CELL_TYPE);
}
-char *G_get_next_marked_f_raster_cat(struct Categories *pcats, /* structure to hold category info */
- FCELL * rast1, FCELL * rast2, /* pointers to raster range */
+/*!
+ \brief Get next marked raster categories (FCELL)
+
+ \param pcats pointer to Categories structure
+ \param rast1, rast2 cell values (raster range)
+ \param[out] count count
+
+ \return NULL if not found
+ \return description if found
+*/
+char *G_get_next_marked_f_raster_cat(struct Categories *pcats,
+ FCELL * rast1, FCELL * rast2,
long *count)
{
return G_get_next_marked_raster_cat(pcats, rast1, rast2, count,
FCELL_TYPE);
}
-char *G_get_next_marked_raster_cat(struct Categories *pcats, /* structure to hold category info */
- void *rast1, void *rast2, /* pointers to raster range */
+/*!
+ \brief Get next marked raster categories
+
+ \param pcats pointer to Categories structure
+ \param rast1, rast2 cell values (raster range)
+ \param[out] count count
+ \param data_type map type
+
+ \return NULL if not found
+ \return description if found
+*/
+char *G_get_next_marked_raster_cat(struct Categories *pcats,
+ void *rast1, void *rast2,
long *count, RASTER_MAP_TYPE data_type)
{
DCELL val1, val2;
@@ -982,17 +818,21 @@
/*!
- * \brief set a category label
+ * \brief Set a raster category label
*
- * The <b>label</b> is copied into the <b>cats</b> structure
- * for category <b>n.</b>
+ * \todo To be removed, replaced by G_set_c_raster_cat().
*
- * \param n
- * \param label
- * \param cats
- * \return int
+ * The <i>label</i> is copied into the <i>pcats</i> structure for
+ * category <i>num</i>.
+ *
+ * \param num raster cell
+ * \param label category label
+ * \param pcats pointer to Categories structure
+ *
+ * \return -1 on error
+ * \return 0 if null value detected
+ * \return 1 on success
*/
-
int G_set_cat(CELL num, const char *label, struct Categories *pcats)
{
return G_set_c_raster_cat(&num, &num, label, pcats);
@@ -1000,55 +840,57 @@
/*!
- * \brief
+ * \brief Set a raster category label (CELL)
*
- * Adds the label for range <em>rast1</em> through <em>rast2</em> in
- * category structure <em>pcats</em>.
+ * Adds the label for range <i>rast1</i> through <i>rast2</i> in
+ * category structure <i>pcats</i>.
*
- * \param rast1
- * \param rast2
- * \param pcats
- * \return int
+ * \param rast1, rast2 raster values (range)
+ * \param label category label
+ * \param pcats pointer to Categories structure
+ *
+ * \return -1 on error
+ * \return 0 if null value detected
+ * \return 1 on success
*/
-
int G_set_c_raster_cat(const CELL * rast1, const CELL * rast2,
const char *label, struct Categories *pcats)
{
return G_set_raster_cat(rast1, rast2, label, pcats, CELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Set a raster category label (FCELL)
*
- * Adds the label for range <em>rast1</em> through <em>rast2</em>
- * in category structure <em>pcats</em>.
+ * Adds the label for range <i>rast1</i> through <i>rast2</i> in
+ * category structure <i>pcats</i>.
*
- * \param rast1
- * \param rast2
- * \param pcats
- * \return int
+ * \param rast1, rast2 raster values (range)
+ * \param label category label
+ * \param pcats pointer to Categories structure
+ *
+ * \return
*/
-
int G_set_f_raster_cat(const FCELL * rast1, const FCELL * rast2,
const char *label, struct Categories *pcats)
{
return G_set_raster_cat(rast1, rast2, label, pcats, FCELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Set a raster category label (DCELL)
*
- * Adds the label for range <em>rast1</em> through <em>rast2</em>
- * in category structure <em>pcats</em>.
+ * Adds the label for range <i>rast1</i> through <i>rast2</i> in
+ * category structure <i>pcats</i>.
*
- * \param rast1
- * \param rast2
- * \param pcats
- * \return int
+ * \param rast1, rast2 raster values (range)
+ * \param label category label
+ * \param pcats pointer to Categories structure
+ *
+ * \return -1 on error
+ * \return 0 if null value detected
+ * \return 1 on success
*/
-
int G_set_d_raster_cat(const DCELL * rast1, const DCELL * rast2,
const char *label, struct Categories *pcats)
{
@@ -1139,15 +981,19 @@
/*!
- * \brief
+ * \brief Set a raster category label (DCELL)
*
- * Adds the label for range <em>rast1</em> through <em>rast2</em> in category structure <em>pcats</em>.
+ * Adds the label for range <i>rast1</i> through <i>rast2</i> in
+ * category structure <i>pcats</i>.
*
- * \param rast1
- * \param rast2
- * \param pcats
- * \param data_type
- * \return int
+ * \param rast1, rast2 raster values (range)
+ * \param label category label
+ * \param pcats pointer to Categories structure
+ * \param data_type map type
+ *
+ * \return -1 on error
+ * \return 0 if null value detected
+ * \return 1 on success
*/
int G_set_raster_cat(const void *rast1, const void *rast2,
@@ -1161,56 +1007,55 @@
return G_set_d_raster_cat(&val1, &val2, label, pcats);
}
-
/*!
- * \brief write raster category file
+ * \brief Write raster category file
*
- * Writes the category file for the raster map <b>name</b> in
- * the current mapset from the <b>cats</b> structure.
- * Returns 1 if successful. Otherwise, -1 is returned (no diagnostic is
- * printed).
+ * \todo To be removed, replaced by G_write_raster_cats().
*
- * \param name
- * \param cats
- * \return int
+ * Writes the category file for the raster map <i>name</i> in the
+ * current mapset from the <i>cats</i> structure.
+ *
+ * \param name map name
+ * \param cats pointer to Categories structure
+ *
+ * \return 1 on success
+ * \return -1 is returned (no diagnostic is printed)
*/
-
int G_write_cats(const char *name, struct Categories *cats)
{
return write_cats("cats", name, cats);
}
-
/*!
- * \brief
+ * \brief Write raster category file
*
- * Same as existing G_write_cats()
+ * \todo To be removed, replaced by G_write_raster_cats().
*
- * \param name
- * \param pcats
- * \return int
+ * Writes the category file for the raster map <i>name</i> in the
+ * current mapset from the <i>cats</i> structure.
+ *
+ * \param name map name
+ * \param cats pointer to Categories structure
+ *
+ * \return 1 on success
+ * \return -1 is returned (no diagnostic is printed)
*/
-
int G_write_raster_cats(const char *name, struct Categories *cats)
{
return write_cats("cats", name, cats);
}
-
/*!
- * \brief write
- * vector category file
+ * \brief Write vector category file
*
- * Writes the category file for the vector map
- * <b>name</b> in the current mapset from the <b>cats</b> structure.
- * Returns 1 if successful. Otherwise, -1 is returned (no diagnostic is
- * printed).
+ * <b>Note:</b> Used for only old vector format!
*
- * \param name
- * \param cats
- * \return int
+ * \param name map name
+ * \param cats pointer to Categories structure
+ *
+ * \return 1 on success
+ * \return -1 is returned (no diagnostic is printed)
*/
-
int G_write_vector_cats(const char *name, struct Categories *cats)
{
return write_cats("dig_cats", name, cats);
@@ -1270,21 +1115,20 @@
return (1);
}
-
/*!
- * \brief
+ * \brief Get category description (DCELL)
*
- * Returns i-th description and i-th data range
- * from the list of category descriptions with corresponding data ranges. end
- * points of data interval in <em>rast1</em> and <em>rast2</em>.
+ * Returns i-th description and i-th data range from the list of
+ * category descriptions with corresponding data ranges. end points of
+ * data interval in <i>rast1</i> and <i>rast2</i>.
*
- * \param pcats
- * \param i
- * \param rast1
- * \param rast2
- * \return char *
+ * \param pcats pointer to Categories structure
+ * \param i index
+ * \param rast1, rast2 raster values (range)
+ *
+ * \return "" on error
+ * \return pointer to category description
*/
-
char *G_get_ith_d_raster_cat(const struct Categories *pcats,
int i, DCELL * rast1, DCELL * rast2)
{
@@ -1299,21 +1143,20 @@
return pcats->labels[index];
}
-
/*!
- * \brief
+ * \brief Get category description (FCELL)
*
- * Returns i-th description and i-th data range
- * from the list of category descriptions with corresponding data ranges. end
- * points of data interval in <em>rast1</em> and <em>rast2</em>.
+ * Returns i-th description and i-th data range from the list of
+ * category descriptions with corresponding data ranges. end points of
+ * data interval in <i>rast1</i> and <i>rast2</i>.
*
- * \param pcats
- * \param i
- * \param rast1
- * \param rast2
- * \return char *
+ * \param pcats pointer to Categories structure
+ * \param i index
+ * \param rast1, rast2 raster values (range)
+ *
+ * \return "" on error
+ * \return pointer to category description
*/
-
char *G_get_ith_f_raster_cat(const struct Categories *pcats,
int i, void *rast1, void *rast2)
{
@@ -1327,21 +1170,20 @@
return tmp;
}
-
/*!
- * \brief
+ * \brief Get category description (CELL)
*
- * Returns i-th description and i-th data range
- * from the list of category descriptions with corresponding data ranges. end
- * points of data interval in <em>rast1</em> and <em>rast2</em>.
+ * Returns i-th description and i-th data range from the list of
+ * category descriptions with corresponding data ranges. end points of
+ * data interval in <i>rast1</i> and <i>rast2</i>.
*
- * \param pcats
- * \param i
- * \param rast1
- * \param rast2
- * \return char *
+ * \param pcats pointer to Categories structure
+ * \param i index
+ * \param rast1, rast2 raster values (range)
+ *
+ * \return "" on error
+ * \return pointer to category description
*/
-
char *G_get_ith_c_raster_cat(const struct Categories *pcats,
int i, void *rast1, void *rast2)
{
@@ -1355,23 +1197,21 @@
return tmp;
}
-
/*!
- * \brief
+ * \brief Get category description
*
- * Returns i-th
- * description and i-th data range from the list of category descriptions with
- * corresponding data ranges. Stores end points of data interval in <em>rast1</em>
- * and <em>rast2</em> (after converting them to <em>data_type</em>.
+ * Returns i-th description and i-th data range from the list of
+ * category descriptions with corresponding data ranges. end points of
+ * data interval in <i>rast1</i> and <i>rast2</i>.
*
- * \param pcats
- * \param i
- * \param rast1
- * \param rast2
- * \param data_type
- * \return char *
+ * \param pcats pointer to Categories structure
+ * \param i index
+ * \param rast1, rast2 raster values (range)
+ * \param data_type map type
+ *
+ * \return "" on error
+ * \return pointer to category description
*/
-
char *G_get_ith_raster_cat(const struct Categories *pcats, int i, void *rast1,
void *rast2, RASTER_MAP_TYPE data_type)
{
@@ -1384,44 +1224,40 @@
return tmp;
}
-
/*!
- * \brief initialize category structure
+ * \brief Initialize category structure
*
- * To construct a new category file, the
- * structure must first be initialized. This routine initializes the
- * <b>cats</b> structure, and copies the <b>title</b> into the structure.
- * The number of categories is set initially to <b>n.</b>
+ * To construct a new category file, the structure must first be
+ * initialized. This routine initializes the <i>cats</i> structure,
+ * and copies the <i>title</i> into the structure. The number of
+ * categories is set initially to <i>n</i>.
+ *
* For example:
\code
struct Categories cats;
- G_init_cats ( (CELL)0, "", &cats);
+ G_init_cats ((CELL)0, * "", &cats);
\endcode
*
- * \param n
- * \param title
- * \param cats
+ * \param num raster value
+ * \param title title
+ * \param pcats pointer to Categories structure
*/
-
void G_init_cats(CELL num, const char *title, struct Categories *pcats)
{
G_init_raster_cats(title, pcats);
pcats->num = num;
}
-
/*!
- * \brief
+ * \brief Initialize category structure
*
* 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.
+ * missign. ncats has no meaning in new Categories structure and only
+ * stores (int) largets data value for backwards compatibility.
*
- * \param title
- * \param pcats
- * \return
+ * \param title title
+ * \param pcats pointer to Categories structure
*/
-
void G_init_raster_cats(const char *title, struct Categories *pcats)
{
G_set_raster_cats_title(title, pcats);
@@ -1438,34 +1274,29 @@
G_quant_init(&pcats->q);
}
-
/*!
- * \brief set title in category structure
+ * \brief Set title in category structure
*
- * The <b>title</b> is copied into the
- * <b>cats</b> structure.
+ * \todo To be removed, replaced by G_set_raster_cats_title().
*
- * \param title
- * \param cats
- * \return
+ * The <i>title</i> is copied into the <i>pcats</i> structure.
+ *
+ * \param title title
+ * \param pcats pointer to Categories structure
*/
-
void G_set_cats_title(const char *title, struct Categories *pcats)
{
G_set_raster_cats_title(title, pcats);
}
-
/*!
- * \brief
+ * \brief Set title in category structure
*
- * Same as existing G_set_cats_title()
+ * The <i>title</i> is copied into the <i>pcats</i> structure.
*
- * \param title
- * \param pcats
- * \return
+ * \param title title
+ * \param pcats pointer to Categories structure
*/
-
void G_set_raster_cats_title(const char *title, struct Categories *pcats)
{
if (title == NULL)
@@ -1475,28 +1306,34 @@
G_strip(pcats->title);
}
+/*!
+ \brief Set category fmt (?)
+
+ \todo To be removed, replaced by G_set_raster_cats_fmt().
+
+ \param fmt
+ \param m1,
+ \param a1,m2,a2
+ \param pcats pointer to Categories structure
+*/
void G_set_cats_fmt(const char *fmt, double m1, double a1, double m2,
double a2, struct Categories *pcats)
{
G_set_raster_cats_fmt(fmt, m1, a1, m2, a2, pcats);
}
-
/*!
- * \brief
- *
- * Same as existing G_set_cats_fmt()
- *
- * \param fmt
- * \param m1
- * \param a1
- * \param m2
- * \param a2
- * \param pcats
- */
+ \brief Set category fmt (?)
+ \todo To be removed, replaced by G_set_raster_cats_fmt().
+
+ \param fmt
+ \param m1,
+ \param a1,m2,a2
+ \param pcats pointer to Categories structure
+*/
void G_set_raster_cats_fmt(const char *fmt, double m1, double a1, double m2,
- double a2, struct Categories *pcats)
+ double a2, struct Categories *pcats)
{
pcats->m1 = m1;
pcats->a1 = a1;
@@ -1508,32 +1345,31 @@
G_strip(pcats->fmt);
}
-
/*!
- * \brief free category structure memory
+ * \brief Free category structure memory
*
- * Frees memory allocated by<i>G_read_cats, G_init_cats</i>
- * and<i>G_set_cat.</i>
+ * \todo To be removed, replaced by G_free_raster_cats().
*
- * \param cats
- * \return
+ * Frees memory allocated by G_read_cats(), G_init_cats() and
+ * G_set_cat().
+ *
+ * \param pcats pointer to Categories structure
*/
-
void G_free_cats(struct Categories *pcats)
{
G_free_raster_cats(pcats);
}
-
/*!
- * \brief
+ * \brief Free category structure memory
*
- * Same as existing G_free_cats()
+ * \todo To be removed, replaced by G_free_raster_cats().
*
- * \param pcats
- * \return
+ * Frees memory allocated by G_read_cats(), G_init_cats() and
+ * G_set_cat().
+ *
+ * \param pcats pointer to Categories structure
*/
-
void G_free_raster_cats(struct Categories *pcats)
{
int i;
@@ -1559,21 +1395,16 @@
pcats->nalloc = 0;
}
-
/*!
- * \brief
+ * \brief Copy raster categories
*
- * Allocates NEW space for quant rules and labels n
- * <em>pcats_to</em> and copies all info from <em>pcats_from</em> cats to <em>pcats_to</em> cats.
- * returns:
- * 0 if successful
- * -1 on fail
+ * Allocates NEW space for quant rules and labels n <i>pcats_to</i>
+ * and copies all info from <i>pcats_from</i> cats to
+ * <i>pcats_to</i> cats.
*
- * \param pcats_to
- * \param pcats_from
- * \return
+ * \param pcats_to pointer to destination Categories structure
+ * \param pcats_from pointer to source Categories structure
*/
-
void G_copy_raster_cats(struct Categories *pcats_to,
const struct Categories *pcats_from)
{
@@ -1588,13 +1419,26 @@
}
}
+/*!
+ \brief Get number of raster categories
+
+ \param pcats pointer to Categories structure
+
+ \return number of categories
+*/
int G_number_of_raster_cats(struct Categories *pcats)
{
return pcats->ncats;
}
-static struct Categories save_cats;
+/*!
+ \brief Sort categories
+ \param pcats pointer to Categories structure
+
+ \return -1 on error (nothing to sort)
+ \return 0 on success
+*/
int G_sort_cats(struct Categories *pcats)
{
int *indexes, i, ncats;
@@ -1605,7 +1449,7 @@
return -1;
ncats = pcats->ncats;
- /* DEBUG fprintf(stderr,"G_sort_cats(): Copying to save cats buffer\n"); */
+ G_debug(3, "G_sort_cats(): Copying to save cats buffer");
G_copy_raster_cats(&save_cats, pcats);
G_free_raster_cats(pcats);
@@ -1617,13 +1461,11 @@
G_init_raster_cats(save_cats.title, pcats);
for (i = 0; i < ncats; i++) {
descr = G_get_ith_d_raster_cat(&save_cats, indexes[i], &d1, &d2);
- /* DEBUG fprintf(stderr,"G_sort_cats(): Write sorted cats, pcats = %p pcats->labels = %p\n",pcats,pcats->labels); */
+ G_debug(4, " Write sorted cats, pcats = %p pcats->labels = %p",
+ pcats, pcats->labels);
G_set_d_raster_cat(&d1, &d2, descr, pcats);
- /* DEBUG fflush(stderr); */
}
G_free_raster_cats(&save_cats);
- /* DEBUG fprintf(stderr,"G_sort_cats(): Done\n"); */
- /* fflush(stderr); */
return 0;
}
Modified: grass/trunk/lib/gis/cell_stats.c
===================================================================
--- grass/trunk/lib/gis/cell_stats.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/cell_stats.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,3 +1,16 @@
+/*!
+ * \file gis/cell_stats.c
+ *
+ * \brief GIS Library - Raster cell statistics
+ *
+ * (C) 2001-2009 GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <grass/gis.h>
#include <stdlib.h>
@@ -11,26 +24,16 @@
static int next_node(struct Cell_stats *);
static void init_node(NODE *, int, int);
-
/*!
- * \brief initialize cell stats
+ * \brief Initialize cell stats
*
- * This routine, which must be called first, initializes the Cell_stats
- * structure <b>s.</b>
+ * This routine, which must be called first, initializes the
+ * Cell_stats structure.
*
- * \param s
- * \return int
- */
-
-
-/*!
- * \brief
- *
* Set the count for NULL-values to zero.
*
- * \return
+ * \param s pointer to Cell_stats structure
*/
-
void G_init_cell_stats(struct Cell_stats *s)
{
s->N = 0;
@@ -39,29 +42,21 @@
s->null_data_count = 0;
}
-
/*!
- * \brief add data to cell stats
+ * \brief Sdd data to cell stats
*
- * The <b>n</b> CELL values in the <b>data</b>
- * array are inserted (and counted) in the Cell_stats structure <b>s.</b>
+ * The <i>n</i> CELL values in the <i>data</i> array are inserted (and
+ * counted) in the Cell_stats structure.
*
- * \param data
- * \param n
- * \param s
- * \return int
- */
-
-
-/*!
- * \brief
+ * Look for NULLs and update the NULL-value count.
*
- * Look for NULLs and update the
- * NULL-value count.
+ * \param cell raster values
+ * \param n number of values
+ * \param s pointer to Cell_stats structure which holds cell stats info
*
- * \return int
+ * \return 1 on failure
+ * \return 0 on success
*/
-
int G_update_cell_stats(const CELL * cell, int n, struct Cell_stats *s)
{
CELL cat;
@@ -174,29 +169,22 @@
/*!
- * \brief random query of cell stats
+ * \brief Random query of cell stats
*
- * This routine allows a random query of the
- * Cell_stats structure <b>s.</b> The <b>count</b> associated with the
- * raster value <b>cat</b> is set. The routine returns 1 if <b>cat</b> was
- * found in the structure, 0 otherwise.
+ * This routine allows a random query of the Cell_stats structure. The
+ * <i>count</i> associated with the raster value <i>cat</i> is
+ * set. The routine returns 1 if <i>cat<i> was found in the
+ * structure, 0 otherwise.
*
- * \param cat
- * \param count
- * \param s
- * \return int
- */
-
-
-/*!
- * \brief
+ * Allow finding the count for the NULL-value.
*
- * Allow finding the count for the
- * NULL-value
+ * \param cat raster value
+ * \param[out] count count
+ * \param s pointer to Cell_stats structure which holds cell stats info
*
- * \return int
+ * \return 1 if found
+ * \return 0 if not found
*/
-
int G_find_cell_stat(CELL cat, long *count, const struct Cell_stats *s)
{
int q;
@@ -247,17 +235,16 @@
return 0;
}
-
/*!
- * \brief reset/rewind cell stats
+ * \brief Reset/rewind cell stats
*
- * The structure <b>s</b> is rewound (i.e., positioned at the first
+ * The structure <i>s</i> is rewound (i.e., positioned at the first
* raster category) so that sorted sequential retrieval can begin.
*
- * \param s
- * \return int
+ * \param s pointer to Cell_stats structure which holds cell stats info
+ *
+ * \return 0
*/
-
int G_rewind_cell_stats(struct Cell_stats *s)
{
int q;
@@ -294,14 +281,12 @@
return 1;
}
-
/*!
- * \brief retrieve sorted cell stats
+ * \brief Retrieve sorted cell stats
*
- * Retrieves the next <b>cat,count</b>
- * combination from the structure <b>s.</b> Returns 0 if there are no more
- * items, non-zero if there are more.
- * For example:
+ * 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;
@@ -315,22 +300,15 @@
fprintf(stdout, "%ld %ld\n", (long) cat, count);
\endcode
*
- * \param cat
- * \param count
- * \param s
- * \return int
- */
-
-
-/*!
- * \brief
+ * Do not return a record for the NULL-value
*
- * Do not return a record for the
- * NULL-value
+ * \param cat raster value
+ * \param[out] count
+ * \param s pointer to Cell_stats structure which holds cell stats info
*
- * \return int
+ * \return 0 if there are no more items
+ * \return non-zero if there are more
*/
-
int G_next_cell_stat(CELL * cat, long *count, struct Cell_stats *s)
{
int idx;
@@ -377,34 +355,31 @@
/*!
- * \brief
+ * \brief Get number of null values.
*
- * 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.
+ * Get a number of null values from stats structure.
*
- * \param count
- * \param s
- * \return
+ * 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.
+ *
+ * \param count count
+ * \param s pointer to Cell_stats structure which holds cell stats info
*/
-
void G_get_stats_for_null_value(long *count, const struct Cell_stats *s)
{
*count = s->null_data_count;
}
-
/*!
- * \brief free cell stats
+ * \brief Free cell stats structure
*
- * The memory associated with structure <b>s</b> is freed. This routine may be
- * called any time after calling<i>G_init_cell_stats.</i>
+ * The memory associated with structure <i>s</i> is freed. This
+ * routine may be called any time after calling G_init_cell_stats().
*
- * \param s
- * \return
+ * \param s pointer to Cell_stats structure
*/
-
void G_free_cell_stats(struct Cell_stats *s)
{
int i;
Modified: grass/trunk/lib/gis/closecell.c
===================================================================
--- grass/trunk/lib/gis/closecell.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/closecell.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,25 +1,16 @@
-
-/***********************************************************************
+/*!
+ * \file gis/closecell.c
+ *
+ * \brief GIS Library - Close raster file
*
- * G_close_cell(fd)
- * Closes and does housekeeping on an opened cell file
+ * (C) 1999-2009 by the GRASS Development Team
*
- * G_unopen_cell(fd)
- * Closes and does housekeeping on an opened cell file
- * without creating the cell file
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
*
- * parms:
- * int fd open cell file
- *
- * returns:
- * -1 on fail
- * 0 on success
- *
- * note:
- * On closing of a cell file that was open for writing, dummy cats
- * and history files are created. Histogram and range info are written.
- *
- **********************************************************************/
+ * \author USACERL and many others
+ */
#ifdef __MINGW32__
# include <windows.h>
@@ -45,37 +36,34 @@
static int write_fp_format(int fd);
/*!
- * \brief close a raster map
+ * \brief Close a raster map
*
- * The raster map
- * opened on file descriptor <b>fd</b> is closed. Memory allocated for raster
- * processing is freed. If open for writing, skeletal support files for the new
- * raster map 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 map it creates, it must do so after the
- * raster map is closed. Otherwise the close will overwrite the support files.
- * See Raster_Map_Layer_Support_Routines for routines which write
- * raster support files.
+ * The raster map opened on file descriptor <i>fd</i> is
+ * closed. Memory allocated for raster processing is freed. If open
+ * for writing, skeletal support files for the new raster map are
+ * created as well.
*
- * \param fd
- * \return int
- */
-
-
-/*!
- * \brief
+ * <b>Note:</b> If a module wants to explicitly write support files
+ * (e.g., a specific color table) for a raster map it creates, it must
+ * do so after the raster map is closed. Otherwise the close will
+ * overwrite the support files. See \ref
+ * Raster_Map_Layer_Support_Routines for routines which write raster
+ * support files.
*
- * 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.
+ * 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.
*
- * \return int
+ * \param fd file descriptor
+ *
+ * \return -1 on error
+ * \return 1 on success
*/
-
int G_close_cell(int fd)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -88,27 +76,27 @@
return close_new(fd, 1);
}
-
/*!
- * \brief unopen a raster map
+ * \brief Unopen a raster map
*
- * The raster map
- * opened on file descriptor <b>fd</b> is closed. Memory allocated for raster
- * processing is freed. If open for writing, the raster map is not created and
- * the temporary file created when the raster map was opened is removed (see
- * Creating_and_Opening_New_Raster_Files).
- * This routine is useful when errors are detected and it is desired to not
- * create the new raster map. While it is true that the raster map 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.
+ * The raster map opened on file descriptor <i>fd</i> is
+ * closed. Memory allocated for raster processing is freed. If open
+ * for writing, the raster map is not created and the temporary file
+ * created when the raster map 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
+ * map. While it is true that the raster map 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.
*
- * \param fd
- * \return int
+ * \param fd file descriptor
+ *
+ * \return -1 on error
+ * \return 1 on success
*/
-
int G_unopen_cell(int fd)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -383,7 +371,7 @@
close(null_fd);
if (rename(fcb->null_temp_name, path)) {
- G_warning(_("closecell: can't move %s\nto null file %s"),
+ G_warning(_("Unable to renae null file '%s'"),
fcb->null_temp_name, path);
stat = -1;
}
@@ -405,7 +393,7 @@
int cell_fd;
if (write_fp_format(fd) != 0) {
- G_warning(_("Error writing floating point format file for map %s"),
+ G_warning(_("Error writing floating point format file for map <%s>"),
fcb->name);
stat = -1;
}
@@ -453,7 +441,7 @@
G__file_name(path, CELL_DIR, fcb->name, fcb->mapset);
remove(path);
if (rename(fcb->temp_name, path)) {
- G_warning(_("closecell: can't move %s\nto cell file %s"),
+ G_warning(_("Unable to rename cell file '%s'"),
fcb->temp_name, path);
stat = -1;
}
Modified: grass/trunk/lib/gis/color_compat.c
===================================================================
--- grass/trunk/lib/gis/color_compat.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_compat.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,188 +1,313 @@
-
-/****************************************************************************
+/*!
+ * \file gis/color_compat.c
*
- * MODULE: gis library
- * AUTHOR(S): Glynn Clements <glynn at gclements.plus.com>
- * COPYRIGHT: (C) 2007 Glynn Clements and the GRASS Development Team
+ * \brief GIS Library - Predefined color tables
*
- * NOTE: Compatibility wrappers for G_make_*[_fp]_colors()
+ * (C) 2007-2009 Glynn Clements and the GRASS Development Team
*
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- *****************************************************************************/
+ * \author Glynn Clements <glynn at gclements.plus.com>
+ */
#include <grass/gis.h>
-
/*!
- * \brief make color wave
+ * \brief Make color wave (integer)
*
- * 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.
+ * 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.
*
- * \param colors
- * \param min
- * \param max
- * \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
*/
-
void G_make_wave_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "wave", min, max);
}
+/*!
+ * \brief Make color wave (floating-point)
+ *
+ * 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.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_wave_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "wave", min, max);
}
-
+/*!
+ * \brief Create RYG color table (integer)
+ *
+ * Generates a color table red-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_ryg_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "ryg", min, max);
}
+/*!
+ * \brief Create RYG color table (floating-point)
+ *
+ * Generates a color table red-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_ryg_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "ryg", min, max);
}
/*!
- * \brief make color ramp
+ * \brief Make color ramp (integer)
*
- * 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.
+ * 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.
*
- * \param colors
- * \param min
- * \param max
- * \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
*/
-
void G_make_ramp_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "ramp", min, max);
}
+/*!
+ * \brief Make color ramp (floating-point)
+ *
+ * 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.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_ramp_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "ramp", min, max);
}
/*!
- * \brief make rainbow colors
+ * \brief Make rainbow colors (integer)
*
- * 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.
+ * 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.
*
- * \param colors
- * \param min
- * \param max
- * \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
*/
-
void G_make_rainbow_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "rainbow", min, max);
}
+/*!
+ * \brief Make rainbow colors (floating-point)
+ *
+ * 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.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_rainbow_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "rainbow", min, max);
}
-
+/*!
+ * \brief Create GYR color table (integer)
+ *
+ * Generates a color table green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_gyr_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "gyr", min, max);
}
+/*!
+ * \brief Create GYR color table (floating-point)
+ *
+ * Generates a color table green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_gyr_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "gyr", min, max);
}
/*!
- * \brief make linear grey scale
+ * \brief Make linear grey scale (integer)
*
- * Generates a grey scale color table. Each color
- * is a level of grey, increasing from black to white.
+ * Generates a grey scale color table. Each color is a level of grey,
+ * increasing from black to white.
*
- * \param colors
- * \param min
- * \param max
- * \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
*/
-
void G_make_grey_scale_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "grey", min, max);
}
+/*!
+ * \brief Make linear grey scale (floating-point)
+ *
+ * Generates a grey scale color table. Each color is a level of grey,
+ * increasing from black to white.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_grey_scale_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "grey", min, max);
}
+/*!
+ * \brief Create BYR color table (integer)
+ *
+ * Generates a color table blue-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_byr_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "byr", min, max);
}
+/*!
+ * \brief Create BYR color table (floating-point)
+ *
+ * Generates a color table blue-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_byr_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "byr", min, max);
}
+/*!
+ * \brief Create BGYR color table (integer)
+ *
+ * Generates a color table blue-green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_bgyr_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "bgyr", min, max);
}
+/*!
+ * \brief Create BGYR color table (floating-point)
+ *
+ * Generates a color table blue-green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_bgyr_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "bgyr", min, max);
}
+/*!
+ * \brief Create BYG color table (integer)
+ *
+ * Generates a color table blue-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_byg_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "byg", min, max);
}
+/*!
+ * \brief Create BYG color table (floating-point)
+ *
+ * Generates a color table blue-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_byg_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "byg", min, max);
}
/*!
- * \brief make aspect colors
+ * \brief Make aspect colors (integer)
*
* Generates a color table for aspect data.
*
- * \param colors
- * \param min
- * \param max
- * \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
*/
-
void G_make_aspect_colors(struct Colors *colors, CELL min, CELL max)
{
G_make_colors(colors, "aspect", min, max);
}
+/*!
+ * \brief Make aspect colors (floating-point)
+ *
+ * Generates a color table for aspect data.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
void G_make_aspect_fp_colors(struct Colors *colors, DCELL min, DCELL max)
{
G_make_fp_colors(colors, "aspect", min, max);
Modified: grass/trunk/lib/gis/color_free.c
===================================================================
--- grass/trunk/lib/gis/color_free.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_free.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,30 +1,43 @@
+/*!
+ * \file gis/color_free.c
+ *
+ * \brief GIS Library - Free Colors structure
+ *
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <stdlib.h>
#include <grass/gis.h>
-
/*!
- * \brief free color structure memory
+ * \brief Free color structure memory
*
- * The dynamically allocated memory associated with the <b>colors</b>
+ * The dynamically allocated memory associated with the <i>colors</i>
* structure is freed.
- * <b>Note.</b> This routine may be used after <i>G_read_colors</i> as
- * well as after <i>G_init_colors.</i>
*
- * \param colors
- * \return
+ * <b>Note:</b> This routine may be used after G_read_colors() as well
+ * as after G_init_colors().
+ *
+ * \param colors pointer to Colors structure
*/
-
void G_free_colors(struct Colors *colors)
{
G__color_reset(colors);
G_init_colors(colors);
}
-/*******************************************
- * G__color* routines only to be used by other routines in this
- * library
- *******************************************/
+/*!
+ \brief Free color rules structure
+ Note: Only for internal use.
+
+ \param cp pointer to _Color_Info structure
+*/
void G__color_free_rules(struct _Color_Info_ *cp)
{
struct _Color_Rule_ *rule, *next;
@@ -36,6 +49,13 @@
cp->rules = NULL;
}
+/*!
+ \brief Free color rules structure
+
+ Note: Only for internal use.
+
+ \param cp pointer to _Color_Info structure
+*/
void G__color_free_lookup(struct _Color_Info_ *cp)
{
if (cp->lookup.active) {
@@ -47,6 +67,13 @@
}
}
+/*!
+ \brief Free color rules structure
+
+ Note: Only for internal use.
+
+ \param cp pointer to _Color_Info structure
+*/
void G__color_free_fp_lookup(struct _Color_Info_ *cp)
{
if (cp->fp_lookup.active) {
@@ -57,6 +84,15 @@
}
}
+/*!
+ \brief Reset colors structure
+
+ Note: Only for internal use.
+
+ This routine should NOT init the colors.
+
+ \param colors pointer to Colors structure
+*/
void G__color_reset(struct Colors *colors)
{
G__color_free_lookup(&colors->fixed);
@@ -64,5 +100,4 @@
G__color_free_rules(&colors->fixed);
G__color_free_rules(&colors->modular);
colors->version = 0;
- /* this routine should NOT init the colors */
}
Modified: grass/trunk/lib/gis/color_get.c
===================================================================
--- grass/trunk/lib/gis/color_get.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_get.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,38 +1,37 @@
-
-/**
- * \file color_get.c
+/*!
+ * \file gis/color_get.c
*
- * \brief GIS Library - Functions to get colors from a raster map.
+ * \brief GIS Library - Get colors from a raster map.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
-
-/**
+/*!
* \brief Get a category color.
*
- * The <b>red, green</b>, and
- * <b>blue</b> intensities for the color associated with category <b>n</b>
- * are extracted from the <b>colors</b> structure. The intensities will be in
- * the range 0 - 255. Also works for null cells.
+ * \todo To be removed, replaced by G_get_raster_color().
*
- * \param[in] n CELL to get color from
- * \param[out] red red value
- * \param[out] grn green value
- * \param[out] blu blue value
- * \param[in] colors Colors struct
- * \return int
+ * The <i>red, green</i>, and <i>blue</i> intensities for the color
+ * associated with category <i>n</i> are extracted from the
+ * <i>colors</i> structure. The intensities will be in the range 0 -
+ * 255. Also works for null cells.
+ *
+ * \param n cell to get color from
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
*/
-
int G_get_color(CELL n, int *red, int *grn, int *blu, struct Colors *colors)
{
CELL cat;
@@ -48,22 +47,22 @@
return (int)set;
}
-
-/**
- * \brief Gets color from raster.
+/*!
+ * \brief Gets color from raster map
*
- * Looks up the rgb colors for
- * <em>rast</em> in the color table <em>colors</em>
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
*
- * \param[in] rast input raster map
- * \param[out] red red value
- * \param[out] grn green value
- * \param[out] blu blue value
- * \param[in] colors Colors struct
- * \param[in] map_type type of map (CELL_TYPE,FCELL_TYPE,DCELL_TYPE)
- * \return int
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ * \param map_type map type (CELL, FCELL, DCELL)
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
*/
-
int G_get_raster_color(const void *rast,
int *red, int *grn, int *blu,
struct Colors *colors, RASTER_MAP_TYPE map_type)
@@ -79,83 +78,80 @@
return (int)set;
}
-
-/**
- * \brief Gets color for a CELL raster.
+/*!
+ * \brief Gets color from raster map (CELL)
*
- * Looks up the rgb colors for CELL
- * <em>rast</em> in the color table <em>colors</em>
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
*
- * \param[in] rast input CELL raster
- * \param[out] red red value
- * \param[out] grn green value
- * \param[out] blu blue value
- * \param[in] colors Colors struct
- * \return int
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
*/
-
int G_get_c_raster_color(const CELL * rast,
int *red, int *grn, int *blu, struct Colors *colors)
{
return G_get_raster_color(rast, red, grn, blu, colors, CELL_TYPE);
}
-
-/**
- * \brief Gets color for a FCELL raster.
+/*!
+ * \brief Gets color from raster map (FCELL)
*
- * Looks up the rgb colors for FCELL <em>rast</em> in the color table
- * <em>colors</em>
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
*
- * \param[in] rast input FCELL raster
- * \param[out] red red value
- * \param[out] grn green value
- * \param[out] blu blue value
- * \param[in] colors Colors struct
- * \return int
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
*/
-
int G_get_f_raster_color(const FCELL * rast,
int *red, int *grn, int *blu, struct Colors *colors)
{
return G_get_raster_color(rast, red, grn, blu, colors, FCELL_TYPE);
}
-
-/**
- * \brief Gets color for a DCELL raster.
+/*!
+ * \brief Gets color from raster map (DCELL)
*
- * Looks up the rgb colors for DCELL <em>rast</em> in the color table
- * <em>colors</em>
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
*
- * \param[in] rast input DCELL raster
- * \param[out] red red value
- * \param[out] grn green value
- * \param[out] blu blue value
- * \param[in] colors Colors struct
- * \return int
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
*/
-
int G_get_d_raster_color(const DCELL * rast,
int *red, int *grn, int *blu, struct Colors *colors)
{
return G_get_raster_color(rast, red, grn, blu, colors, DCELL_TYPE);
}
-
-/**
- * \brief Gets color for null value.
+/*!
+ * \brief Gets color for null value.
*
- * Puts the red, green, and blue components of <b>colors</b> for the
- * NULL-value into <b>red, grn, and blu</b>.
+ * Puts the red, green, and blue components of <i>colors</i> for the
+ * NULL-value into <i>red, grn, and blu</i>.
*
- * \param[out] red red value
- * \param[out] grn green value
- * \param[out] blu blue value
- * \param[in] colors Colors struct
- * \return
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_get_null_value_color(int *red, int *grn, int *blu,
const struct Colors *colors)
{
@@ -173,20 +169,17 @@
*red = *blu = *grn = 255; /* white */
}
-
-/**
+/*!
* \brief Gets default color.
*
- * Puts the red, green, and blue components of the
- * <tt>"default"</tt> color into <b>red, grn, and blu</b>.
+ * Puts the red, green, and blue components of the <tt>"default"</tt>
+ * color into <i>red, grn, and blu</i>.
*
- * \param[out] red red value
- * \param[out] grn green value
- * \param[out] blu blue value
- * \param[in] colors Colors struct
- * \return
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_get_default_color(int *red, int *grn, int *blu,
const struct Colors *colors)
{
Modified: grass/trunk/lib/gis/color_hist.c
===================================================================
--- grass/trunk/lib/gis/color_hist.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_hist.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,44 +1,31 @@
-
-/**********************************************************************
+/*!
+ * \file gis/color_hist.c
*
- * G_make_histogram_eq_colors (colors, statf)
+ * \brief GIS Library - histogram grey scale colors
*
- * struct Colors *colors struct to hold colors
- * struct Cell_stats *statf cell stats info
+ * (C) 2007-2009 Glynn Clements and the GRASS Development Team
*
- * Generates histogram equalized grey scale from
- * cell stats structure info.
- * Color range is 0-255.
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- **********************************************************************
- *
- * G_make_histogram_log_colors (colors, statf, min, max)
- *
- * struct Colors *colors struct to hold colors
- * struct Cell_stats *statf cell stats info
- *
- * Generates histogram with normalized log transformed grey scale from
- * cell stats structure info.
- * Color range is 0-255.
- *
- **********************************************************************/
-#include <grass/gis.h>
+ * \author Glynn Clements <glynn at gclements.plus.com>
+ */
+
#include <math.h>
+#include <grass/gis.h>
-
/*!
- * \brief make histogram-stretched grey colors
+ * \brief Make histogram-stretched grey colors
*
- * Generates a histogram
- * contrast-stretched grey scale color table that goes from the ,histogram
- * information in the Cell_stats structure <b>s.</b> (See
- * Raster_Histograms).
+ * Generates a histogram contrast-stretched grey scale color table
+ * that goes from the, histogram information in the Cell_stats
+ * structure (see \ref Raster_Histograms).
*
- * \param colors
- * \param s
- * \return
+ * Color range is 0-255.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param stalf pointer to Cell_stats structure which holds cell stats info
*/
-
void G_make_histogram_eq_colors(struct Colors *colors,
struct Cell_stats *statf)
{
@@ -96,6 +83,17 @@
}
}
+/*!
+ \brief Generates histogram with normalized log transformed grey scale.
+
+ Generates histogram with normalized log transformed grey scale from
+ cell stats structure info. Color range is 0-255.
+
+ \param colors pointer to Colors structure which holds color info
+ \param stalf pointer to Cell_stats structure which holds cell stats info
+ \param min minimum value
+ \param max maximum value
+*/
void G_make_histogram_log_colors(struct Colors *colors,
struct Cell_stats *statf, int min, int max)
{
Modified: grass/trunk/lib/gis/color_init.c
===================================================================
--- grass/trunk/lib/gis/color_init.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_init.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,25 +1,26 @@
-
-/**********************************************************************
+/*!
+ * \file gis/color_init.c
*
- * G_init_colors (colors)
- * struct Colors *colors structure to hold color info
+ * \brief GIS Library - Initialize Colors structure
*
- * Initializes the color structure for subsequent calls to G_add_color_rule()
- *********************************************************************/
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
#include <grass/gis.h>
-
/*!
- * \brief initialize color structure
+ * \brief Initialize color structure
*
- * The <b>colors</b> structure is initialized for subsequent calls
- * to <i>G_add_color_rule</i> and<i>G_set_color.</i>
+ * The <i>colors</i> structure is initialized for subsequent calls
+ * to G_add_color_rule() and G_set_color().
*
- * \param colors
- * \return
+ * \param colors pointer to Colors structure
*/
-
void G_init_colors(struct Colors *colors)
{
colors->version = 0;
Modified: grass/trunk/lib/gis/color_look.c
===================================================================
--- grass/trunk/lib/gis/color_look.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_look.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,40 +1,47 @@
-#include <math.h>
-#include <grass/gis.h>
-
-/* old 4.1 routine */
-
/*!
- * \brief lookup an array of colors
+ * \file gis/color_lookup.c
+ *
+ * \brief GIS Library - Lookup array of colors
*
- * Extracts colors for an array of <b>raster</b> values. The
- * colors for the <b>n</b> values in the <b>raster</b> array are stored in
- * the <b>red, green</b>, and <b>blue</b> arrays. The values in the
- * <b>set</b> array will indicate if the corresponding <b>raster</b> value
- * has a color or not (1 means it does, 0 means it does not). The programmer
- * must allocate the <b>red, green, blue</b>, and <b>set</b> arrays to be at
- * least dimension <b>n.</b>
- * <b>Note.</b> The <b>red, green</b>, and <b>blue</b> intensities will be
- * in the range 0 - 255.
+ * (C) 1999-2009 by the GRASS Development Team
*
- * \param raster
- * \param red
- * \param green
- * \param blue
- * \param set
- * \param n
- * \param colors
- * \return int
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author USACERL and many others
*/
+#include <math.h>
+#include <grass/gis.h>
/*!
- * \brief
+ * \brief Lookup an array of colors
*
+ * \todo To be removed, replaced by G_lookup_c_raster_colors().
+ *
+ * Extracts colors for an array of <i>cell</i> values. The colors
+ * for the <i>n</i> values in the <i>cell</i> array are stored in
+ * the <i>red, green</i>, and <i>blue</i> arrays. The values in the
+ * <i>set</i> array will indicate if the corresponding <i>cell</i>
+ * value has a color or not (1 means it does, 0 means it does not).
+ *
+ * The programmer must allocate the <i>red, green, blue</i>, and
+ * <b>set</b> arrays to be at least dimension <i>n</i>.
+ *
+ * <b>Note:</b> The <i>red, green</i>, and <i>blue</i> intensities
+ * will be in the range 0 - 255.
+ *
* Modified to return a color for NULL-values.
*
- * \return
+ * \param cell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_lookup_colors(const CELL * cell,
unsigned char *red, unsigned char *grn,
unsigned char *blu, unsigned char *set, int n,
@@ -43,34 +50,31 @@
G_lookup_c_raster_colors(cell, red, grn, blu, set, n, colors);
}
-/* I don't think it should exist, because it requires openning
- of raster map every time Olga
- int G_lookup_rgb_colors(map, mapset, r, g, b)
- char *name, *mapset;
- unsigned char *r, *g, *b;
- {
- RASTER_MAP_TYPE map_type;
- void *rast;
- ....
- }
- */
-
-
/*!
- * \brief
+ * \brief Lookup an array of colors
*
- * The same as G_lookup_colors(cell, r, g, b, set, n, colors).
+ * Extracts colors for an array of <i>cell</i> values. The colors
+ * for the <i>n</i> values in the <i>cell</i> array are stored in
+ * the <i>red, green</i>, and <i>blue</i> arrays. The values in the
+ * <i>set</i> array will indicate if the corresponding <i>cell</i>
+ * value has a color or not (1 means it does, 0 means it does not).
*
- * \param cell
- * \param r
- * \param g
- * \param b
- * \param set
- * \param n
- * \param colors
- * \return
+ * The programmer must allocate the <i>red, green, blue</i>, and
+ * <b>set</b> arrays to be at least dimension <i>n</i>.
+ *
+ * <b>Note:</b> The <i>red, green</i>, and <i>blue</i> intensities
+ * will be in the range 0 - 255.
+ *
+ * Modified to return a color for NULL-values.
+ *
+ * \param cell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_lookup_c_raster_colors(const CELL * cell,
unsigned char *red, unsigned char *grn,
unsigned char *blu, unsigned char *set, int n,
@@ -89,28 +93,22 @@
CELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Lookup an array of colors
*
- * If the <em>cell_type</em> is CELL_TYPE, calls G_lookup_colors((CELL *)cell, r,
- * g, b, set, n, colors);
- * If the <em>cell_type</em> is FCELL_TYPE, calls
- * G_lookup_f_raster_colors(FCELL *)cell, r, g, b, set, n, colors);
- * If the <em>cell_type</em> is DCELL_TYPE, calls
- * G_lookup_d_raster_colors(DCELL *)cell, r, g, b, set, n, colors);
+ * - If the <em>map_type</em> is CELL_TYPE, calls G_lookup_colors()
+ * - If the <em>map_type</em> is FCELL_TYPE, calls G_lookup_f_raster_colors()
+ * - If the <em>map_type</em> is DCELL_TYPE, calls G_lookup_d_raster_colors()
*
- * \param rast
- * \param r
- * \param g
- * \param b
- * \param set
- * \param n
- * \param colors
- * \param cell_type
- * \return
+ * \param raster raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
+ * \param map_type raster type (CELL, FCELL, DCELL)
*/
-
void G_lookup_raster_colors(const void *raster,
unsigned char *red, unsigned char *grn,
unsigned char *blu, unsigned char *set, int n,
@@ -128,24 +126,21 @@
G__lookup_colors(raster, red, grn, blu, set, n, colors, 1, 0, map_type);
}
-
/*!
- * \brief
+ * \brief Lookup an array of colors (FCELL)
*
- * Converts the <em>n</em>
- * floating-point values in the <em>fcell</em> array to their <em>r,g,b</em> color
- * components. Embedded NULL-values are handled properly as well.
+ * Converts the <em>n</em> floating-point values in the <em>fcell</em>
+ * array to their <em>r,g,b</em> color components. Embedded
+ * NULL-values are handled properly as well.
*
- * \param fcell
- * \param r
- * \param g
- * \param b
- * \param set
- * \param n
- * \param colors
- * \return
+ * \param fcell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_lookup_f_raster_colors(const FCELL * fcell, unsigned char *red,
unsigned char *grn, unsigned char *blu,
unsigned char *set, int n, struct Colors *colors)
@@ -164,24 +159,21 @@
FCELL_TYPE);
}
-
/*!
- * \brief
+ * \brief Lookup an array of colors (DCELL)
*
- * Converts the <em>n</em>
- * floating-point values in the <em>dcell</em> array to their <em>r,g,b</em> color
+ * Converts the <em>n</em> double-precision values in the
+ * <em>dcell</em> array to their <em>r,g,b</em> color
* components. Embedded NULL-values are handled properly as well.
*
- * \param dcell
- * \param r
- * \param g
- * \param b
- * \param set
- * \param n
- * \param colors
- * \return
+ * \param dcell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_lookup_d_raster_colors(const DCELL * dcell, unsigned char *red,
unsigned char *grn, unsigned char *blu,
unsigned char *set, int n, struct Colors *colors)
@@ -217,7 +209,20 @@
return 0;
}
-
+/*!
+ * \brief Lookup an array of colors
+ *
+ * \param raster raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
+ * \param mod
+ * \param rules_only
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ */
void G__lookup_colors(const void *raster, unsigned char *red,
unsigned char *grn, unsigned char *blu,
unsigned char *set, int n, struct Colors *colors,
@@ -431,6 +436,15 @@
}
}
+/*!
+ \brief Interpolate color rules
+
+ \param val raster cell value
+ \param[out] red red value
+ \param[out] grn green value
+ \param[out] blu blue value
+ \param rule pointer to _Color_Rule which holds color rules info
+*/
void G__interpolate_color_rule(DCELL val, unsigned char *red,
unsigned char *grn, unsigned char *blu,
const struct _Color_Rule_ *rule)
Modified: grass/trunk/lib/gis/color_range.c
===================================================================
--- grass/trunk/lib/gis/color_range.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_range.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,6 +1,27 @@
+/*!
+ * \file gis/color_range.c
+ *
+ * \brief GIS Library - Color range functions.
+ *
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <math.h>
#include <grass/gis.h>
+/*!
+ \brief Set color range (CELL version)
+
+ \todo Rename to G_set_c_color_range() ?
+
+ \param min,max minimum and maximum value
+ \param colors pointer to Colors structure which holds color info
+*/
void G_set_color_range(CELL min, CELL max, struct Colors *colors)
{
if (min < max) {
@@ -13,6 +34,12 @@
}
}
+/*!
+ \brief Set color range (DCELL version)
+
+ \param min,max minimum and maximum value
+ \param colors pointer to Colors structure which holds color info
+*/
void G_set_d_color_range(DCELL min, DCELL max, struct Colors *colors)
{
if (min < max) {
@@ -25,18 +52,18 @@
}
}
-/* returns min and max category in the range or huge numbers
- if the co,lor table is defined on floating cell values and
- not on categories */
+/*!
+ \brief Get color range values (CELL)
+ \todo Rename to G_get_c_color_range() ?
+
+ Returns min and max category in the range or huge numbers if the
+ color table is defined on floating cell values and not on
+ categories.
-/*!
- * \brief
- *
- * \param G_get_color_range
- * \return int
+ \param[out] min,max minimum and maximum value
+ \param colors pointer to Colors structure which holds color info
*/
-
void G_get_color_range(CELL * min, CELL * max, const struct Colors *colors)
{
if (!colors->is_float) {
@@ -49,7 +76,16 @@
}
}
-/* returns min and max values in the range */
+/*!
+ \brief Get color range values (DELL)
+
+ Returns min and max category in the range or huge numbers if the
+ color table is defined on floating cell values and not on
+ categories.
+
+ \param[out] min,max minimum and maximum value
+ \param colors pointer to Colors structure which holds color info
+ */
void G_get_d_color_range(DCELL * min, DCELL * max, const struct Colors *colors)
{
*min = colors->cmin;
Modified: grass/trunk/lib/gis/color_read.c
===================================================================
--- grass/trunk/lib/gis/color_read.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_read.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,26 +1,16 @@
-
-/**********************************************************************
+/*!
+ * \file gis/color_read.c
+ *
+ * \brief GIS Library - Read color table of raster map
*
- * G_read_colors (name, mapset, colors)
- * char *name name of map
- * char *mapset mapset that map belongs to
- * struct Colors *colors structure to hold color info
+ * (C) 1999-2009 by the GRASS Development Team
*
- * Reads the color information associated with map layer "map"
- * in mapset "mapset" into the structure "colors".
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
*
- * returns: 1 if successful
- * 0 if missing, but default colors generated
- * -1 on fail
- *
- * note: If a secondary color file for map name "name" exists
- * in the current project, that color file is read. This
- * allows the user to define their own color lookup tables
- * for cell maps found in other mapsets.
- *
- * Warning message is printed if the color file is
- * missing or invalid.
- *********************************************************************/
+ * \author USACERL and many others
+ */
#include <grass/gis.h>
#include <grass/glocale.h>
@@ -33,32 +23,35 @@
/*!
- * \brief read map layer color table
+ * \brief Read raster map layer color table
*
- * The color table for the raster map
- * <b>name</b> in the specified <b>mapset</b> is read into the
- * <b>colors</b> 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.
+ * The color table for the raster map <i>name</i> in the specified
+ * <i>mapset</i> is read into the <i>colors</i> 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.
*
- * \param name
- * \param mapset
- * \param colors
- * \return int
- */
-
-
-/*!
- * \brief
+ * This routine reads the rules from the color file. If the input
+ * raster map is is a floating-point map it calls
+ * G_mark_colors_as_fp().
*
- * This routine reads the rules from the color
- * file. If the input raster map is is a floating-point map it calls <tt>G_mark_colors_as_fp()</tt>.
+ * Note: If a secondary color file for map name <i>name</i> exists in
+ * the current project, that color file is read. This allows the
+ * user to define their own color lookup tables for cell maps found
+ * in other mapsets.
*
- * \return int
+ * Warning message is printed if the color file is
+ * missing or invalid.
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] colors pointer to Colors structure
+ *
+ * \return -1 on error
+ * \return 0 if missing, but default colors generated
+ * \return 1 on success
*/
-
int G_read_colors(const char *name, const char *mapset, struct Colors *colors)
{
int fp;
@@ -104,16 +97,16 @@
return 0;
}
}
- err = "missing";
+ err = _("missing");
break;
case -1:
- err = "invalid";
+ err = _("invalid");
break;
default:
return 1;
}
- G_warning(_("color support for [%s] in mapset [%s] %s"), name, mapset,
+ G_warning(_("Color support for <%s@%s> %s"), name, mapset,
err);
return -1;
}
@@ -303,9 +296,8 @@
G_add_color_rule((CELL) cat1, r1, g1, b1,
(CELL) cat2, r2, g2, b2, colors);
}
- /*
- fprintf (stderr, "adding rule %d=%.2lf %d %d %d %d=%.2lf %d %d %d\n", cat1,val1, r1, g1, b1, cat2, val2, r2, g2, b2);
- */
+ G_debug(3, "adding rule %d=%.2lf %d %d %d %d=%.2lf %d %d %d",
+ cat1, val1, r1, g1, b1, cat2, val2, r2, g2, b2);
}
return 1;
}
@@ -380,19 +372,17 @@
return 0;
}
-
/*!
- * \brief
+ * \brief Mark colors as floating-point.
*
- * 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).
- * In particular if this flag is set, the routine <tt>G_get_colors_min_max()</tt> should return min=-255$^3$ and max=255$^3$.
+ * Sets a flag in the <i>colors</i> structure that indicates that
+ * these colors should only be looked up using floating-point raster
+ * data (not integer data). In particular if this flag is set, the
+ * routine G_get_colors_min_max() should return min=-255$^3$ and
+ * max=255$^3$.
*
- * \param colors
- * \return int
+ * \param colors pointer to Colors structure
*/
-
void G_mark_colors_as_fp(struct Colors *colors)
{
colors->is_float = 1;
Modified: grass/trunk/lib/gis/color_rule.c
===================================================================
--- grass/trunk/lib/gis/color_rule.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_rule.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,17 +1,14 @@
-
-/**
- * \file color_rule.c
+/*!
+ * \file gis/color_rule.c
*
* \brief GIS Library - Color rules.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
@@ -36,11 +33,9 @@
* \param[in,out] colors pointer to color table structure
* \return
*/
-
-void G_add_d_raster_color_rule(
- const DCELL * val1, int r1, int g1, int b1,
- const DCELL * val2, int r2, int g2, int b2,
- struct Colors *colors)
+void G_add_d_raster_color_rule(const DCELL * val1, int r1, int g1, int b1,
+ const DCELL * val2, int r2, int g2, int b2,
+ struct Colors *colors)
{
add_color_rule(val1, r1, g1, b1, val2, r2, g2, b2, &colors->fixed,
colors->version, &colors->cmin, &colors->cmax, DCELL_TYPE);
@@ -59,11 +54,9 @@
* \param[in,out] colors pointer to color table structure
* \return
*/
-
-void G_add_f_raster_color_rule(
- const FCELL * cat1, int r1, int g1, int b1,
- const FCELL * cat2, int r2, int g2, int b2,
- struct Colors *colors)
+void G_add_f_raster_color_rule(const FCELL * cat1, int r1, int g1, int b1,
+ const FCELL * cat2, int r2, int g2, int b2,
+ struct Colors *colors)
{
add_color_rule(cat1, r1, g1, b1, cat2, r2, g2, b2, &colors->fixed,
colors->version, &colors->cmin, &colors->cmax, FCELL_TYPE);
@@ -82,11 +75,9 @@
* \param[in,out] colors pointer to color table structure
* \return
*/
-
-void G_add_c_raster_color_rule(
- const CELL * cat1, int r1, int g1, int b1,
- const CELL * cat2, int r2, int g2, int b2,
- struct Colors *colors)
+void G_add_c_raster_color_rule(const CELL * cat1, int r1, int g1, int b1,
+ const CELL * cat2, int r2, int g2, int b2,
+ struct Colors *colors)
{
add_color_rule(cat1, r1, g1, b1, cat2, r2, g2, b2, &colors->fixed,
colors->version, &colors->cmin, &colors->cmax, CELL_TYPE);
@@ -115,10 +106,9 @@
* \return
*/
-void G_add_raster_color_rule(
- const void *val1, int r1, int g1, int b1,
- const void *val2, int r2, int g2, int b2,
- struct Colors *colors, RASTER_MAP_TYPE data_type)
+void G_add_raster_color_rule(const void *val1, int r1, int g1, int b1,
+ const void *val2, int r2, int g2, int b2,
+ struct Colors *colors, RASTER_MAP_TYPE data_type)
{
add_color_rule(val1, r1, g1, b1, val2, r2, g2, b2, &colors->fixed,
colors->version, &colors->cmin, &colors->cmax, data_type);
@@ -138,17 +128,21 @@
* components <b>r1,g1,b1</b> and <b>r2,g2,b2</b> 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);
+ G_add_color_rule ((CELL)200, 0,0,0, (CELL) 1000, 255,255,255);
\endcode
- * The programmer is encouraged to review Raster_Color_Table_Format how
- * this routine fits into the 5.x raster color logic.
- * <b>Note.</b> The <b>colors</b> structure must have been initialized by
- * <i>G_init_colors.</i> See Predefined_Color_Tables for routines to
- * build some predefined color tables.
*
+ * 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 <i>colors</i> structure must have been initialized
+ * by G_init_colors(). See \ref Predefined_Color_Tables for routines
+ * to build some predefined color tables.
+ *
* \param cat1 cell value
* \param r1,g1,b1 color value
* \param cat2 cell value
@@ -156,18 +150,16 @@
* \param[in,out] colors pointer to color table structure
* \return
*/
-
-void G_add_color_rule(
- CELL cat1, int r1, int g1, int b1,
- CELL cat2, int r2, int g2,
- int b2, struct Colors *colors)
+void G_add_color_rule(CELL cat1, int r1, int g1, int b1,
+ CELL cat2, int r2, int g2,
+ int b2, struct Colors *colors)
{
add_color_rule((void *)&cat1, r1, g1, b1, (void *)&cat2, r2, g2, b2,
&colors->fixed, colors->version, &colors->cmin,
&colors->cmax, CELL_TYPE);
}
-/**
+/*!
* \brief Add modular color rule (DCELL version)
*
* \param val1 cell value
@@ -179,10 +171,9 @@
* \return -1 on failure
* \return 1 on success
*/
-int G_add_modular_d_raster_color_rule(
- const DCELL * val1, int r1, int g1, int b1,
- const DCELL * val2, int r2, int g2, int b2,
- struct Colors *colors)
+int G_add_modular_d_raster_color_rule(const DCELL * val1, int r1, int g1, int b1,
+ const DCELL * val2, int r2, int g2, int b2,
+ struct Colors *colors)
{
DCELL min, max;
@@ -198,7 +189,7 @@
return 1;
}
-/**
+/*!
* \brief Add modular color rule (FCELL version)
*
* \param val1 cell value
@@ -210,10 +201,9 @@
* \return -1 on failure
* \return 1 on success
*/
-int G_add_modular_f_raster_color_rule(
- const FCELL * val1, int r1, int g1, int b1,
- const FCELL * val2, int r2, int g2, int b2,
- struct Colors *colors)
+int G_add_modular_f_raster_color_rule(const FCELL * val1, int r1, int g1, int b1,
+ const FCELL * val2, int r2, int g2, int b2,
+ struct Colors *colors)
{
DCELL min, max;
@@ -229,7 +219,7 @@
return 1;
}
-/**
+/*!
* \brief Add modular color rule (CCELL version)
*
* \param val1 cell value
@@ -241,20 +231,19 @@
* \return -1 on failure
* \return 1 on success
*/
-int G_add_modular_c_raster_color_rule(
- const CELL * val1, int r1, int g1, int b1,
- const CELL * val2, int r2, int g2, int b2,
- struct Colors *colors)
+int G_add_modular_c_raster_color_rule(const CELL * val1, int r1, int g1, int b1,
+ const CELL * val2, int r2, int g2, int b2,
+ struct Colors *colors)
{
return G_add_modular_color_rule(*val1, r1, g1, b1, *val2, r2, g2, b2,
colors);
}
-/**
+/*!
* \brief Add modular color rule
*
- * Question: shouldn't this function call
- * G_add_modular_<data_type>_raster_color_rule() instead???
+ * \todo Question: shouldn't this function call
+ * G_add_modular_<data_type>_raster_color_rule() instead?
*
* \param val1 cell value
* \param r1,g1,b1 color value
@@ -285,10 +274,10 @@
return 1;
}
-/**
+/*!
* \brief Add modular color rule
*
- * This function seems to be same as
+ * \todo This function seems to be same as
* G_add_modular_raster_color_rule(). Can be removed?
*
* \param val1 cell value
@@ -301,10 +290,9 @@
* \return -1 on failure
* \return 1 on success
*/
-int G_add_modular_color_rule(
- CELL cat1, int r1, int g1,
- int b1, CELL cat2, int r2,
- int g2, int b2, struct Colors *colors)
+int G_add_modular_color_rule(CELL cat1, int r1, int g1,
+ int b1, CELL cat2, int r2,
+ int g2, int b2, struct Colors *colors)
{
CELL min, max;
Modified: grass/trunk/lib/gis/color_set.c
===================================================================
--- grass/trunk/lib/gis/color_set.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_set.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,30 +1,42 @@
+/*!
+ * \file gis/color_set.c
+ *
+ * \brief GIS Library - Set colors for raster maps.
+ *
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <grass/gis.h>
-/* for convenience, but to be avoided if possible */
-
/*!
- * \brief set a category color
+ * \brief Set a category color (CELL)
*
- * The <b>red, green</b>, and
- * <b>blue</b> intensities for the color associated with category <b>cat</b>
- * are set in the <b>colors</b> structure. The intensities must be in the
- * range 0 - 255. Values below zero are set as zero, values above 255 are set as
- * 255.
- * <b>Use of this routine is discouraged because it defeats the new color
- * logic.</b> It is provided only for backward compatibility. Overuse can create
- * large color tables. <i>G_add_color_rule</i> should be used whenever
+ * The <i>red, green</i>, and <i>blue</i> intensities for the color
+ * associated with category <i>cat</i> are set in the <i>colors</i>
+ * structure. 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: Use of this routine is discouraged because it defeats the new
+ * color logic.</b>
+ *
+ * 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 <b>colors</b> structure must have been initialized by
- * <i>G_init_color.</i>
*
- * \param cat
- * \param red
- * \param green
- * \param blue
- * \param colors
- * \return
+ * <b>Note:</b> The <i>colors</i> structure must have been
+ * initialized by G_init_color().
+ *
+ * \param cat raster cell value
+ * \param r red value
+ * \param g green value
+ * \param b blue value
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_set_color(CELL cat, int r, int g, int b, struct Colors *colors)
{
if (G_is_c_null_value(&cat))
@@ -33,6 +45,17 @@
G_add_color_rule(cat, r, g, b, cat, r, g, b, colors);
}
+/*!
+ * \brief Set a category color (DCELL)
+ *
+ * See G_set_color() for detailed information.
+ *
+ * \param cat raster cell value
+ * \param r red value
+ * \param g green value
+ * \param b blue value
+ * \param colors pointer to Colors structure which holds color info
+ */
void G_set_d_color(DCELL val, int r, int g, int b, struct Colors *colors)
{
if (G_is_d_null_value(&val))
@@ -41,19 +64,17 @@
G_add_d_raster_color_rule(&val, r, g, b, &val, r, g, b, colors);
}
-
/*!
- * \brief
+ * \brief Set color for NULL-value
*
- * Sets the color (in <em>colors</em>) for the NULL-value to <em>r,g,b</em>.
+ * Sets the color (in <i>colors</i>) for the NULL-value to
+ * <i>red, green, blue</i>.
*
- * \param r
- * \param g
- * \param b
- * \param colors
- * \return
+ * \param red red value
+ * \param grn green value
+ * \param blu blue value
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_set_null_value_color(int red, int grn, int blu, struct Colors *colors)
{
colors->null_red = red;
@@ -62,20 +83,18 @@
colors->null_set = 1;
}
-
/*!
- * \brief
+ * \brief Set default color value
*
- * 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.
+ * Sets the default color (in <i>colors</i>) to <i>red, green,
+ * blue</i>. This is the color for values which do not have an
+ * explicit rule.
*
- * \param r
- * \param g
- * \param b
- * \param colors
- * \return
+ * \param red red value
+ * \param grn green value
+ * \param blu blue value
+ * \param colors pointer to Colors structure which holds color info
*/
-
void G_set_default_color(int red, int grn, int blu, struct Colors *colors)
{
colors->undef_red = red;
Modified: grass/trunk/lib/gis/color_write.c
===================================================================
--- grass/trunk/lib/gis/color_write.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/color_write.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,28 +1,24 @@
-
-/**********************************************************************
- * G_write_colors (name, mapset, colors)
- * char *name name of map
- * char *mapset mapset that map belongs to
- * struct Colors *colors structure holding color info
+/*!
+ * \file gis/color_write.c
+ *
+ * \brief GIS Library - Write color table of raster map
*
- * Writes the color information associated with map layer "map"
- * in mapset "mapset" from the structure "colors".
+ * (C) 1999-2009 by the GRASS Development Team
*
- * returns: 1 if successful
- * -1 on fail
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
*
- * If the environment variable FORCE_GRASS3_COLORS is set (to anything at all)
- * then the output format is 3.0, even if the structure contains 4.0 rules.
- * This allows users to create 3.0 color files for export to sites which
- * don't yet have 4.0
- ***********************************************************************/
+ * \author USACERL and many others
+ */
+
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <grass/gis.h>
+
#define PRECISION 30
-#define THRESHOLD .0000000000000000000000000000005
-/* .5 * 10 ^(-30) */
+#define THRESHOLD .0000000000000000000000000000005 /* .5 * 10 ^(-30) */
static void write_rules(FILE *, struct _Color_Rule_ *, DCELL, DCELL);
static void write_new_colors(FILE *, struct Colors *);
@@ -31,49 +27,50 @@
static void format_min(char *, double);
static void format_max(char *, double);
-
/*!
- * \brief write map layer color table
+ * \brief Write map layer color table
*
- * The color table is written for the
- * raster map <b>name</b> in the specified <b>mapset</b> from the
- * <b>colors</b> structure.
- * If there is an error, -1 is returned. No diagnostic is printed. Otherwise, 1
- * is returned.
- * The <b>colors</b> structure must be created properly, i.e.,
- * <i>G_init_colors</i> to initialize the structure and
- * <i>G_add_color_rule</i> to set the category colors.\remarks{These
- * routines are called by higher level routines which read or create entire
- * color tables, such as<i>G_read_colors</i> or
- * <i>G_make_ramp_colors.</i>}
- * <b>Note.</b> The calling sequence for this function deserves special
- * attention. The <b>mapset</b> parameter seems to imply that it is possible
- * to overwrite the color table for a raster map 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 maps in other mapsets, but without
- * overwriting other users' color tables for the same raster map. If
- * <b>mapset</b> is the current mapset, then the color file for <b>name</b>
- * will be overwritten by the new color table. But if <b>mapset</b> is not the
- * current mapset, then the color table is actually written in the current
- * mapset under the <b>colr2</b> element as: colr2/mapset/name.
+ * The color table is written for the raster map <i>name</i> in the
+ * specified <i>mapset</i> from the <i>colors</i> structure.
*
- * \param name
- * \param mapset
- * \param colors
- * \return int
- */
-
-
-/*!
- * \brief
+ * If there is an error, -1 is returned. No diagnostic is
+ * printed. Otherwise, 1 is returned.
*
- * 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.
+ * The <i>colors</i> structure must be created properly, i.e.,
+ * G_init_colors() to initialize the structure and G_add_color_rule()
+ * to set the category colors. These routines are called by
+ * higher level routines which read or create entire color tables,
+ * such as G_read_colors() or G_make_ramp_colors().
*
- * \return int
+ * <b>Note:</b> The calling sequence for this function deserves
+ * special attention. The <i>mapset</i> parameter seems to imply that
+ * it is possible to overwrite the color table for a raster map 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 maps in other mapsets, but without overwriting
+ * other users' color tables for the same raster map. If <i>mapset</i>
+ * is the current mapset, then the color file for <i>name</i> will be
+ * overwritten by the new color table. But if <i>mapset</i> 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>.
+ *
+ * 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.
+ *
+ * If the environment variable FORCE_GRASS3_COLORS is set (to anything at all)
+ * then the output format is 3.0, even if the structure contains 4.0 rules.
+ * This allows users to create 3.0 color files for export to sites which
+ * don't yet have 4.0
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param colors pointer to structure Colors which holds color info
+ *
+ * \return 1 on success
+ * \return -1 on failure
*/
-
int G_write_colors(const char *name, const char *mapset,
struct Colors *colors)
{
@@ -104,6 +101,12 @@
return 1;
}
+/*!
+ * \brief Write map layer color table
+ *
+ * \param fd file descriptor
+ * \param colors pointer to Colors structure which holds color info
+ */
void G__write_colors(FILE * fd, struct Colors *colors)
{
if (getenv("FORCE_GRASS3_COLORS"))
Modified: grass/trunk/lib/gis/find_cell.c
===================================================================
--- grass/trunk/lib/gis/find_cell.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/find_cell.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,43 +1,34 @@
-/*
- **********************************************************************
- * char *
- * G_find_cell (name, mapset)
- * char *name file name to look for
- * char *mapset mapset to search. if mapset is ""
- * will search in mapset search list
+/*!
+ * \file strings.c
+ *
+ * \brief GIS Library - Find raster map
*
- * searches for a cell file from the mapset search list
- * or in a specified mapset.
- * returns the mapset name where the cell file was found.
+ * (C) 1999-2009 by the GRASS Development Team
*
- * returns:
- * char * pointer to a string with name of mapset
- * where cell file was found, or NULL if not found
- * note:
- * rejects all names that begin with .
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
*
- * if name is of the form nnn in ppp then
- * name = nnn and mapset = ppp
- **********************************************************************/
+ * \author Original author CERL
+ */
#include <grass/gis.h>
-
/*!
- * \brief find a raster map
+ * \brief Find a raster map
*
- * Looks for the raster map <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,
- * \remarks{See Mapset_Search_Path for more details about the search path.}
- * or it can be a specific mapset name, which means look for the raster map
- * only in this one mapset (for example, in the current mapset). If found,
- * the mapset where the raster map lives is returned. If not found, the NULL
- * pointer is returned.
+ * Looks for the raster map <i>name</i> in the database. The
+ * <i>mapset</i> parameter can either be the empty string "", which
+ * means search all the mapsets in the user's current mapset search
+ * path (see \ref Mapset_Search_Path for more details about the search
+ * path) or it can be a specific mapset name, which means look for the
+ * raster map only in this one mapset (for example, in the current
+ * mapset). If found, the mapset where the raster map lives is
+ * returned. If not found, the NULL pointer is returned.
*
- * NOTE: If the user specifies a fully qualified raster map which exists,
- * then <i>G_find_cell(~)</i> modifies <b>name</b> by removing the
- * "@<i>mapset</i>".
+ * Note: If the user specifies a fully qualified raster map which
+ * exists, then G_find_cell() modifies <i>name</i> by removing
+ * the "@<i>mapset</i>".
*
* For example, to find a raster map anywhere in the database:
\code
@@ -51,35 +42,36 @@
*
\code
char name[GNAME_MAX];
- if (G_find_cell(name,G_mapset( )) == NULL)
+ if (G_find_cell(name, G_mapset()) == NULL)
// not found
\endcode
*
- * \param name
- * \param mapset
- * \return char *
+ * \param[in,out] name map name
+ * \param mapset mapset name or ""
+ *
+ * \return mapset where raster map was found
+ * \return NULL if not found
*/
-
const char *G_find_cell(char *name, const char *mapset)
{
return G_find_file("cell", name, mapset);
}
-
/*!
- * \brief find a raster map (look but don't touch)
+ * \brief Find a raster map (look but don't touch)
*
* The same as G_find_cell() but doesn't remove the "@<i>mapset</i>"
- * qualification from <b>name</b>, if present.
+ * qualification from <i>name</i>, if present.
*
* Returns NULL if the map wasn't found, or the mapset the raster was
* found in if it was.
*
- * \param name
- * \param mapset
- * \return char *
+ * \param name map name
+ * \param mapset mapset name or ""
+ *
+ * \return mapset where raster map was found
+ * \return NULL if not found
*/
-
const char *G_find_cell2(const char *name, const char *mapset)
{
return G_find_file2("cell", name, mapset);
Modified: grass/trunk/lib/gis/get_cellhd.c
===================================================================
--- grass/trunk/lib/gis/get_cellhd.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/get_cellhd.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -3,7 +3,7 @@
\brief GIS library - Read raster map header
- (C) 2001-2008 by the GRASS Development Team
+ (C) 2001-2009 by the GRASS Development Team
This program is free software under the GNU General Public License
(>=v2). Read the file COPYING that comes with GRASS for details.
@@ -20,28 +20,26 @@
\brief Read the raster header
The raster header for the raster map <i>name</i> in the specified
- <i>mapset</i> is read into the <i>cellhd</i> structure. If there is
+ <i>mapset</i> is read into the <i>cellhd</i> 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>:a warning message for errors encountered.
- Cell header files may contain either grid cell header
- information or reclass information. If it is a reclass
- file, it will specify the map and mapset names of the actual
- grid cell file being reclassed. G_get_cellhd(), upon
- reading reclass information will go read the cell header
- information for the referenced file. Only one reference is
- allowed.
+ Cell header files may contain either grid cell header information or
+ reclass information. If it is a reclass file, it will specify the
+ map and mapset names of the actual grid cell file being
+ reclassed. G_get_cellhd(), upon reading reclass information will go
+ read the cell header information for the referenced file. Only one
+ reference is allowed.
\param name name of map
\param mapset mapset that map belongs to
- \param cellhd structure to hold cell header info
+ \param[out] cellhd structure to hold cell header info
\return 0 on success
\return -1 on error
*/
-
int G_get_cellhd(const char *name, const char *mapset,
struct Cell_head *cellhd)
{
Modified: grass/trunk/lib/gis/get_row.c
===================================================================
--- grass/trunk/lib/gis/get_row.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/get_row.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,16 +1,14 @@
/*!
- \file get_row.c
+ \file gis/get_row.c
- \brief GIS library - get raster row
+ \brief GIS library - Get raster row
- (C) 2003-2008 by the GRASS Development Team
+ (C) 2003-2009 by the GRASS Development Team
- This program is free software under the
- GNU General Public License (>=v2).
- Read the file COPYING that comes with GRASS
- for details.
+ This program is free software under the GNU General Public License
+ (>=v2). Read the file COPYING that comes with GRASS for details.
- \author Original author CERL
+ \author Original author CERL
*/
#include <string.h>
@@ -25,16 +23,10 @@
#include "G.h"
-/*--------------------------------------------------------------------------*/
-
#define NULL_FILE "null"
-/*--------------------------------------------------------------------------*/
-
static int embed_nulls(int, void *, int, RASTER_MAP_TYPE, int, int);
-/*--------------------------------------------------------------------------*/
-
static int compute_window_row(int fd, int row, int *cellRow)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -63,8 +55,6 @@
return 1;
}
-/*--------------------------------------------------------------------------*/
-
static void do_reclass_int(int fd, void *cell, int null_is_zero)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -96,8 +86,6 @@
}
}
-/*--------------------------------------------------------------------------*/
-
static int read_data_fp_compressed(int fd, int row, unsigned char *data_buf,
int *nbytes)
{
@@ -118,8 +106,6 @@
return 0;
}
-/*--------------------------------------------------------------------------*/
-
static void rle_decompress(unsigned char *dst, const unsigned char *src,
int nbytes, int size)
{
@@ -183,8 +169,6 @@
return 0;
}
-/*--------------------------------------------------------------------------*/
-
static int read_data_uncompressed(int fd, int row, unsigned char *data_buf,
int *nbytes)
{
@@ -202,8 +186,6 @@
return 0;
}
-/*--------------------------------------------------------------------------*/
-
#ifdef HAVE_GDAL
static int read_data_gdal(int fd, int row, unsigned char *data_buf, int *nbytes)
{
@@ -238,10 +220,6 @@
}
#endif
-/*--------------------------------------------------------------------------*/
-
-/* Actually read a row of data in */
-
static int read_data(int fd, int row, unsigned char *data_buf, int *nbytes)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -262,10 +240,7 @@
return read_data_fp_compressed(fd, row, data_buf, nbytes);
}
-/*--------------------------------------------------------------------------*/
-
/* copy cell file data to user buffer translated by window column mapping */
-
static void cell_values_int(int fd, const unsigned char *data,
const COLUMN_MAPPING * cmap, int nbytes,
void *cell, int n)
@@ -311,8 +286,6 @@
}
}
-/*--------------------------------------------------------------------------*/
-
static void cell_values_float(int fd, const unsigned char *data,
const COLUMN_MAPPING * cmap, int nbytes,
void *cell, int n)
@@ -352,8 +325,6 @@
}
}
-/*--------------------------------------------------------------------------*/
-
static void cell_values_double(int fd, const unsigned char *data,
const COLUMN_MAPPING * cmap, int nbytes,
void *cell, int n)
@@ -393,14 +364,7 @@
}
}
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
#ifdef HAVE_GDAL
-
-/*--------------------------------------------------------------------------*/
-
static void gdal_values_int(int fd, const unsigned char *data,
const COLUMN_MAPPING *cmap, int nbytes,
CELL *cell, int n)
@@ -439,8 +403,6 @@
}
}
-/*--------------------------------------------------------------------------*/
-
static void gdal_values_float(int fd, const float *data,
const COLUMN_MAPPING *cmap, int nbytes,
FCELL *cell, int n)
@@ -465,8 +427,6 @@
}
}
-/*--------------------------------------------------------------------------*/
-
static void gdal_values_double(int fd, const double *data,
const COLUMN_MAPPING *cmap, int nbytes,
DCELL *cell, int n)
@@ -490,13 +450,8 @@
cmapold = cmap[i];
}
}
-
-/*--------------------------------------------------------------------------*/
-
#endif
-/*--------------------------------------------------------------------------*/
-
/* transfer_to_cell_XY takes bytes from fcb->data, converts these bytes with
the appropriate procedure (e.g. XDR or byte reordering) into type X
values which are put into array work_buf.
@@ -506,9 +461,6 @@
work_buf might be ommited. check the appropriate function for XY to
determine the procedure of conversion.
*/
-
-/*--------------------------------------------------------------------------*/
-
static void transfer_to_cell_XX(int fd, void *cell)
{
static void (*cell_values_type[3]) () = {
@@ -531,8 +483,6 @@
G__.window.cols);
}
-/*--------------------------------------------------------------------------*/
-
static void transfer_to_cell_fi(int fd, void *cell)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -565,8 +515,6 @@
G__freea(work_buf);
}
-/*--------------------------------------------------------------------------*/
-
static void transfer_to_cell_if(int fd, void *cell)
{
CELL *work_buf = G__alloca(G__.window.cols * sizeof(CELL));
@@ -593,8 +541,6 @@
G__freea(work_buf);
}
-/*--------------------------------------------------------------------------*/
-
static void transfer_to_cell_id(int fd, void *cell)
{
CELL *work_buf = G__alloca(G__.window.cols * sizeof(CELL));
@@ -621,11 +567,6 @@
G__freea(work_buf);
}
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
/*
* works for all map types and doesn't consider
* null row corresponding to the requested row
@@ -676,8 +617,6 @@
return 1;
}
-/*--------------------------------------------------------------------------*/
-
static int get_map_row_no_reclass(int fd, void *rast, int row,
RASTER_MAP_TYPE data_type, int null_is_zero,
int with_mask)
@@ -695,8 +634,6 @@
return 1;
}
-/*--------------------------------------------------------------------------*/
-
static int get_map_row(int fd, void *rast, int row, RASTER_MAP_TYPE data_type,
int null_is_zero, int with_mask)
{
@@ -746,12 +683,6 @@
return 1;
}
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
/*!
* \brief Read raster row without masking (this routine is deprecated)
*
@@ -783,7 +714,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_map_row_nomask(int fd, CELL * buf, int row)
{
return get_map_row(fd, buf, row, CELL_TYPE, 1, 0);
@@ -803,7 +733,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_raster_row_nomask(int fd, void *buf, int row,
RASTER_MAP_TYPE data_type)
{
@@ -824,7 +753,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_c_raster_row_nomask(int fd, CELL * buf, int row)
{
return G_get_raster_row_nomask(fd, buf, row, CELL_TYPE);
@@ -844,7 +772,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_f_raster_row_nomask(int fd, FCELL * buf, int row)
{
return G_get_raster_row_nomask(fd, buf, row, FCELL_TYPE);
@@ -864,14 +791,11 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_d_raster_row_nomask(int fd, DCELL * buf, int row)
{
return G_get_raster_row_nomask(fd, buf, row, DCELL_TYPE);
}
-/*--------------------------------------------------------------------------*/
-
/*!
* \brief Get raster row (this routine is deprecated!)
*
@@ -891,7 +815,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_map_row(int fd, CELL * buf, int row)
{
return get_map_row(fd, buf, row, CELL_TYPE, 1, 1);
@@ -939,7 +862,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_raster_row(int fd, void *buf, int row, RASTER_MAP_TYPE data_type)
{
return get_map_row(fd, buf, row, data_type, 0, 1);
@@ -966,7 +888,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_c_raster_row(int fd, CELL * buf, int row)
{
return G_get_raster_row(fd, buf, row, CELL_TYPE);
@@ -989,7 +910,6 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_f_raster_row(int fd, FCELL * buf, int row)
{
return G_get_raster_row(fd, buf, row, FCELL_TYPE);
@@ -1009,18 +929,11 @@
* \return 0 row requested not within window
* \return -1 on error
*/
-
int G_get_d_raster_row(int fd, DCELL * buf, int row)
{
return G_get_raster_row(fd, buf, row, DCELL_TYPE);
}
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
static int open_null_read(int fd)
{
struct fileinfo *fcb = &G__.fileinfo[fd];
Modified: grass/trunk/lib/gis/gislib.dox
===================================================================
--- grass/trunk/lib/gis/gislib.dox 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/gislib.dox 2009-06-09 18:40:28 UTC (rev 37793)
@@ -3,33 +3,89 @@
by M. Neteler 2/2004, 2005, 2006
-->
+by GRASS Development Team (http://grass.osgeo.org)
+
This chapter is divided in the following pages:
+
- \subpage gislibintro
- \subpage gisrasterlib
- \subpage gisvectorlib
-\section gislibintro Introduction
-
This sections is divided as follows:
+
- \subpage gislibintro
-- \subpage Raster_File_Processing
-- \subpage Vector_File_Processing
+ - \subpage init
+ - \subpage diag
+ - \subpage envir
+
+- \subpage dbaseaccess
+ - \subpage Fully_Qualified_File_Names
+ - \subpage finding
+ - \subpage Legal_File_Names
+ - \subpage Opening_an_Existing_Database_File_for_Reading
+ - \subpage Opening_an_Existing_Database_File_for_Update
+ - \subpage Creating_and_Opening_a_New_Database_File
+ - \subpage Database_File_Management
+
+- \subpage The_Region
+ - \subpage The_Database_Region
+ - \subpage The_Active_Module_Region
+
+- \subpage Projection_Information
+ - \subpage Latitude_Longitude_Databases
+ - \subpage Coordinates
+ - \subpage Global_Wraparound
+ - \subpage Miscellaneous
+
+- \subpage Calculations
+ - \subpage Raster_Area_Calculations
+ - \subpage Polygonal_Area_Calculations
+ - \subpage Distance_Calculations
+
- \subpage General_Plotting_Routines
+
- \subpage Temporary_Files
+
- \subpage Command_Line_Parsing
-- \subpage Full_Module_Example
-- \subpage Compiling_and_Installing_GRASS_Modules
-- \subpage Multiple_Architecture_Conventions
-- \subpage Full_Structure_Members_Description
-- \subpage Complete_Structure_Members_Table
-- \subpage Description_of_Complex_Structure_Members
+ - \subpage Description
+ - \subpage Structures
+ - \subpage Option_structure
+ - \subpage Flag_structure
+ - \subpage Parser_Routines
+ - \subpage Parser_Programming_Examples
+ - \subpage Step_by_Step_Use_of_the_Parser
+ - \subpage Full_Module_Example
+ - \subpage Complete_Structure_Members_Table
+ - \subpage Description_of_Complex_Structure_Members
+ - \subpage Answer_member_of_the_Flag_and_Option_structures
+ - \subpage Multiple_and_Answers_Members
+ - \subpage key_desc_Member
+ - \subpage gisprompt_Member
+ - \subpage Common_Questions
+
- \subpage String_Manipulation_Functions
+
- \subpage Enhanced_UNIX_Routines
+ - \subpage Running_in_the_Background
+ - \subpage Partially_Interruptible_System_Call
+ - \subpage ENDIAN_test
+ - \subpage Miscellaneous
+
- \subpage GIS_Library_Data_Structures
+ - \subpage struct_Cell_head
+ - \subpage struct_Categories
+ - \subpage struct_Colors
+ - \subpage struct_History
+ - \subpage struct_Range
+
- \subpage Loading_the_GIS_Library
+
- \subpage TimeStamp_functions
-- \subpage GRASS_GIS_Library_Overview
+- \subpage Memory_Allocation
+
+\section gislibintro Introduction
+
The <em>GIS Library</em> is the primary programming library provided
with the GRASS system. <b>Programs must use this libary to access the
GIS database.</b> It contains the routines which locate, create, open,
@@ -243,7 +299,7 @@
writes the new value to the user's GRASS environment file.
-\subsection dbaseaccess Fundamental Database Access Routines
+\section dbaseaccess Fundamental Database Access Routines
The routines described in this section provide the low-level interface
to the GRASS database. They search the database for files, prompt the
@@ -451,45 +507,8 @@
remove these other files as well, specific calls must be made for each
related <i>element</i>.
+\section The_Region The Region
-\subsection Memory_Allocation Memory Allocation
-
-The following routines provide memory allocation capability. They are
-simply calls to the UNIX suite of memory allocation routines malloc(),
-realloc() and calloc(), except that if there is not enough memory,
-they print a diagnostic message to that effect and then call exit().
-
- - G_malloc ()
-
-Allocates a block of memory at least <i>size</i> bytes which is
-aligned properly for all data types. A pointer to the aligned block is
-returned.
-
- - G_realloc()
-
-Changes the <i>size</i> of a previously allocated block of memory at
-<i>ptr</i> and returns a pointer to the new block of memory. The
-<i>size</i> may be larger or smaller than the original size. If the
-original block cannot be extended "in place", then a new block is
-allocated and the original block copied to the new block.
-
-<b>Note:</b> If <i>ptr</i> is NULL, then this routine simply allocates
-a block of <i>size</i> bytes. This routine works around broken
-realloc() routines, which do not handle a NULL <i>ptr</i>.
-
- - G_calloc()
-
-Allocates a properly aligned block of memory <i>n</i>*<i>size</i>
-bytes in length, initializes the allocated memory to zero, and returns
-a pointer to the allocated block of memory.
-
- - G_free()
-
-Use the G_free() routine to release memory allocated by
-these routines.
-
-\subsection The_Region The Region
-
The region concept is explained in \ref Region. It can be thought of as a
two-dimensional matrix with known boundaries and rectangular cells.
@@ -667,7 +686,7 @@
<b>Note:</b> the result is a double. Casting it to an integer will
give the row number.
-\subsection Projection_Information Projection Information
+\section Projection_Information Projection Information
The following routines return information about the cartographic
projection and zone. See \ref Region for more information about these
@@ -790,7 +809,94 @@
/* This last example forces floating-point ASCII format */
\endcode
+\subsection Global_Wraparound Global Wraparound
+
+These next routines provide a mechanism for determining the relative
+position of a pair of longitudes. Since longitudes of ±360 are
+equivalent, but GRASS requires the east to be bigger than the west,
+some adjustment of coordinates is necessary.
+
+ - G_adjust_easting()
+
+Returns east larger than west. If the region projection is
+PROJECTION_LL, then this routine returns an equivalent <i>east</i>
+that is larger, but no more than 360 degrees larger, than the
+coordinate for the western edge of the region. Otherwise no adjustment
+is made and the original <i>east</i> is returned.
+
+ - G_adjust_east_longitude()
+
+This routine returns an equivalent <i>east</i> that is larger, but no
+more than 360 larger than the <i>west</i> coordinate.
+
+This routine should be used only with latitude-longitude coordinates.
+
+ - G_shortest_way()
+
+Returns shortest way between eastings.
+
+\subsection Miscellaneous Miscellaneous
+
+
+ - G_ellipsoid_name()
+
+This routine returns a pointer to a string containing the name for the
+ellipsoid in the GRASS ellipsoid table. It can be used as follows:
+
+\code
+int n;
+char *name;
+
+for(n = 0; name = G_ellipsoid_name(n); n++)
+ fprintf(stdout, "%s\n", name);
+\endcode
+
+ - G_get_ellipsoid_by_name()
+
+This routine returns the semi-major axis (in meters) and
+eccentricity squared for the named ellipsoid.
+
+ - G_get_ellipsoid_parameters()
+
+This routine returns the semi-major axis (in meters) and the
+eccentricity squared for the ellipsoid associated with the
+database. If there is no ellipsoid explicitly associated with the
+database, it returns the values for the WGS 84 ellipsoid.
+
+- G_meridional_radius_of_curvature()
+
+Returns the meridional radius of curvature at a given longitude:
+
+\f$
+\rho = \frac{a (1-e^2)}{(1-e^2\sin^2 lon)^{3/2}}
+\f$
+
+ - G_transverse_radius_of_curvature()
+
+Returns the transverse radius of curvature at a given longitude:
+
+\f$
+\nu = \frac{a}{(1-e^2\sin^2 lon)^{1/2}}
+\f$
+
+ - G_radius_of_conformal_tangent_sphere()
+
+Returns the radius of the conformal sphere tangent to ellipsoid at a
+given longitude:
+
+\f$
+r = \frac{a (1-e^2)^{1/2}}{(1-e^2\sin^2 lon)}
+\f$
+
+ - G_pole_in_polygon()
+
+For latitude-longitude coordinates, this routine determines if the
+polygon contains one of the poles.
+
+
+\section Calculations Calculations
+
\subsection Raster_Area_Calculations Raster Area Calculations
The following routines perform area calculations for raster maps.
@@ -878,7 +984,7 @@
vertices (as opposed to geodesics).
-\subsection Distance Calculations Distance Calculations
+\subsection Distance_Calculations Distance Calculations
Two routines perform distance calculations for any projection.
@@ -913,102 +1019,7 @@
Calculates the geodesic distance between two points set by
G_set_geodesic_distance_latl() and G_set_geodesic_distance_lat2().
-\subsection Global_Wraparound Global Wraparound
-
-These next routines provide a mechanism for determining the relative
-position of a pair of longitudes. Since longitudes of ±360 are
-equivalent, but GRASS requires the east to be bigger than the west,
-some adjustment of coordinates is necessary.
-
- - G_adjust_easting()
-
-Returns east larger than west. If the region projection is
-PROJECTION_LL, then this routine returns an equivalent <i>east</i>
-that is larger, but no more than 360 degrees larger, than the
-coordinate for the western edge of the region. Otherwise no adjustment
-is made and the original <i>east</i> is returned.
-
- - G_adjust_east_longitude()
-
-This routine returns an equivalent <i>east</i> that is larger, but no
-more than 360 larger than the <i>west</i> coordinate.
-
-This routine should be used only with latitude-longitude coordinates.
-
- - G_shortest_way()
-
-Returns shortest way between eastings.
-
-\subsection Miscellaneous Miscellaneous
-
-
- - G_ellipsoid_name()
-
-This routine returns a pointer to a string containing the name for the
-ellipsoid in the GRASS ellipsoid table. It can be used as follows:
-
-\code
-int n;
-char *name;
-
-for(n = 0; name = G_ellipsoid_name(n); n++)
- fprintf(stdout, "%s\n", name);
-\endcode
-
- - G_get_ellipsoid_by_name()
-
-This routine returns the semi-major axis (in meters) and
-eccentricity squared for the named ellipsoid.
-
- - G_get_ellipsoid_parameters()
-
-This routine returns the semi-major axis (in meters) and the
-eccentricity squared for the ellipsoid associated with the
-database. If there is no ellipsoid explicitly associated with the
-database, it returns the values for the WGS 84 ellipsoid.
-
-- G_meridional_radius_of_curvature()
-
-Returns the meridional radius of curvature at a given longitude:
-
-\f$
-\rho = \frac{a (1-e^2)}{(1-e^2\sin^2 lon)^{3/2}}
-\f$
-
- - G_transverse_radius_of_curvature()
-
-Returns the transverse radius of curvature at a given longitude:
-
-\f$
-\nu = \frac{a}{(1-e^2\sin^2 lon)^{1/2}}
-\f$
-
- - G_radius_of_conformal_tangent_sphere()
-
-Returns the radius of the conformal sphere tangent to ellipsoid at a
-given longitude:
-
-\f$
-r = \frac{a (1-e^2)^{1/2}}{(1-e^2\sin^2 lon)}
-\f$
-
- - G_pole_in_polygon()
-
-For latitude-longitude coordinates, this routine determines if the
-polygon contains one of the poles.
-
-\section Raster_File_Processing GRASS Raster File Processing
-
-Please refer to GRASS Raster File Processing in Chapter \ref gisrastintro.
-
-
-\section Vector_File_Processing GRASS Vector File Processing
-
-Please refer to GRASS Vector File Processing in Chapter \ref
-gisvectintro. Note, that the old "sites" are stored as vector points
-since GRASS 6.
-
\section General_Plotting_Routines General Plotting Routines
@@ -1390,7 +1401,7 @@
The flag "-t" is set.
\endverbatim
-\section Full_Module_Example Full Module Example
+\subsection Full_Module_Example Full Module Example
The following code demonstrates some of the basic capabilities of the
@@ -1468,157 +1479,8 @@
}
\endcode
-\section Compiling_and_Installing_GRASS_Modules Compiling and Installing GRASS Modules
+\subsection Complete_Structure_Members_Table Complete Structure Members Table
-
-GRASS modules are compiled and installed using the UNIX <tt>make</tt>
-command, which reads a file named <tt>Makefile</tt> (see \ref
-Multiple_Architecture_Conventions for more information) and then runs
-the compiler. The GRASS compilation process allows for
-multiple-architecture compilation from a single copy of the source
-code (for instance, if the source code is NFS mounted to various
-machines with differing architectures). This chapter assumes that the
-programmer is familiar with <tt>make</tt> and its accompanying
-Makefile.
-
-\todo Explain ''auto-conf''
-
-\todo Include contents of SUBMITTING and INSTALL files from source code
-
-To compile enter following:
-
-\verbatim
-./configure
-make
-make install
-\endverbatim
-
-Then the code will be compiled into "/usr/local/grass-7.x.y" directory. The start
-script "grass7x" will be placed into "/usr/local/bin/".
-
-Optionally other target directories can be specified while "configuring":
-
-\verbatim
-./configure --prefix=/opt/grass-7.x.y --with-bindir=/usr/bin
-make
-make install
-\endverbatim
-
-This will store the GRASS binaries into the directory
-"/opt/grass-7.x.y" and the script mentioned above into "/usr/bin".
-
-The script "make" is required to compile single modules. The
-compilation process and requirements are discussed in more detail now.
-
-\subsection Makefile_Variables Makefile Variables
-
-\todo Update the list.
-
-<b>GRASS Libraries</b>. The following variables name the various GRASS
-libraries:
-
- - <i>GISLIB</i> - This names the <b>GIS Library</b>, which is the
-principal GRASS library. See \ref GIS_Library for details about this
-library, and \ref Loading_the_GIS_Library for a sample Makefile which
-loads this library.
-
- - <i>SEGMENTLIB</i> - This names the <b>Segment Library</b>, which
-manages large matrix data. See \ref Segment_Library for details about
-this library, and \ref Loading_the_Vask_Library for a sample
-<i>Makefile</i> which loads this library.
-
- - <i>RASTERLIB</i> - This names the <b>Raster Graphics Library</b>,
-which communicates with GRASS graphics drivers. See \ref
-Raster_Graphics_Library for details about this library, and \ref
-Loading_the_Raster_Graphics_Library for a sample <i>Makefile</i> which
-loads this library.
-
- - <i>DISPLAYLIB</i> - This names the <b>Display Graphics Library</b>,
-which provides a higher level graphics interface to
-<i>RASTERLIB</i>. See Display_Graphics_Library for details about this
-library, and Loading_the_Display_Graphics_Library for a sample
-<i>Makefile</i> which loads this library.
-
-<b>UNIX Libraries:</b> The following variables name some useful UNIX
-system libraries:
-
- - <i>MATHLIB</i> This names the math library. It should be used
-instead of the -lm loader option.
-
- - <i>CURSES</i> This names both the curses and termcap libraries. It
-should be used instead of the -lcurses/-lncurses and
--ltermcap loader options. Do not use <tt>$CURSES</tt> if you use
-<tt>$VASK</tt>.
-
- - <i>TERMLIB</i> This names the termcap library. It should be used
--instead of the ltermcap or -ltermlib loader options. Do not use
--<tt>$TERMLIB</tt> if you use <tt>$VASK</tt> or <tt>$CURSES</tt>.
-
-<b>Compiler and loader variables.</b> The following variables are
-related to compiling and loading C programs:
-
- - <i>EXTRA\_CFLAGS</i> This variable can be used to add additional
-options to <tt>$CFLAGS</tt>. It has no predefined values. It is
-usually used to specify additional -I include directories, or -D
-preprocessor defines.
-
-\subsection Constructing_a_Makefile Constructing a Makefile
-
-
-The complete syntax for a <i>Makefile</i> is discussed in the UNIX
-documentation for <tt>make</tt> and will not be repeated here. The
-essential idea is that a target (e.g. a GRASS module) is to be built
-from a list of dependencies (e.g. object files, libraries, etc.). The
-relationship between the target, its dependencies, and the rules for
-constructing the target is expressed according to the following
-syntax:
-
-\code
-target: dependencies
-
-actions
-
-more actions
-\endcode
-
-If the target does not exist, or if any of the dependencies have a newer
-date than the target (i.e., have changed), the actions will be executed to
-build the target. The actions must be indented using a TAB. <tt>make</tt> is
-picky about this. It does not like spaces in place of the TAB.
-
-\section Multiple_Architecture_Conventions Multiple-Architecture Conventions
-
-
-The following conventions allow for multiple architecture compilation on a
-machine that uses a common or networked GRASS source code directory tree.
-
-Object files and library archives are compiled into subdirectories
-that represent the architecture that they were compiled on. These
-subdirectories are created in the $SRC directory as OBJ.<tt>arch</tt>
-and LIB.<tt>arch</tt>, where <tt>arch</tt> represents the architecture
-of the compiling machine. Thus, for example, $SRC/OBJ.sun4 would
-contain the object files for Sun/4 and SPARC architectures, and
-<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
-Linux architectures. Likewise, <tt>$SRC/OBJ.686-pc-linux-gnu</tt>
-would contain the object files for Linux architectures, and
-<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
-Linux architectures.
-
-Note that 'arch' is defined for a specific architecture during setup and
-compilation of GRASS, it is not limited to sun4 or any specific string.
-
-\section Full_Structure_Members_Description Full Structure Members Description
-
-
-There are many members to the <b>Option</b> and <b>Flag</b>
-structures. The following tables and descriptions summarize all
-defined members of both the Option and Flag structures.
-
-An in-depth summary of the more complex structure members is presented
-in \ref Description_of_Complex_Structure_Members.
-
-\section Complete_Structure_Members_Table Complete Structure Members Table
-
<v>struct Flag</v>
<table border=1>
<tr>
@@ -1769,7 +1631,7 @@
</tr>
</table>
-\section Description_of_Complex_Structure_Members Description of Complex Structure Members
+\subsection Description_of_Complex_Structure_Members Description of Complex Structure Members
What follows are explanations of possibly confusing structure
@@ -1871,7 +1733,7 @@
opt->required = NO;
opt->key_desc = "x,y"
opt->multiple = NO;
-\endverbatim
+\endcode
The answer to this option would <i>not</i> be stored in the answer
member, but in the answers member. If the user entered
@@ -2122,7 +1984,7 @@
sometimes undesirable. The routines here provide the same functions as
their corresponding UNIX routine, but with different side effects.
-\subsection Running in the Background Running in the Background
+\subsection Running_in_the_Background Running in the Background
The standard UNIX fork() routine creates a child process which is a
@@ -2220,140 +2082,94 @@
for (row = 0; row < nrows; row++)
G_percent(row, nrows, 10);
-\endverbatim
+\endcode
This will print completion messages at 10% increments; i.e., 10%, 20%,
30%, etc., up to 100%. Each message does not appear on a new line, but
rather erases the previous message. After 100%, a new line is printed.
- - G_program_name() return module name
+ - G_program_name()
Routine returns the name of the module as set by the call to
-<I>G_gisinit().</I>
+G_gisinit().
-<P>
-char * G_whoami() user's name
+ - G_whoami()
Returns a pointer to a string which is the user's login name.
-<P>
-int G_yes() ask a yes/no question
-
-This routine prints a <B>question</B> to the user, and expects the
-user to respond either yes or no. (Invalid responses are rejected and
-the process is repeated until the user answers yes or no.)
-
-<P>
-The <B>default</B> indicates what the RETURN key alone should mean. A
-<B>default</B> of 1 indicates that RETURN means yes, 0 indicates that
-RETURN means no, and -1 indicates that RETURN alone is not a valid
-response.
-
-<P>
-The <B>question</B> will be appended with "(y/n) ", and, if
-<B>default</B> is not -1, with "[y] " or "[n] ", depending on the
-<B>default.</B>
-
-<P>
-<I>G_yes()</I> returns 1 if the user said yes, and 0 if the user said no.
-
-<P>
-
\section GIS_Library_Data_Structures GIS Library Data Structures
-<P>
Some of the data structures, defined in the "gis.h" header file and used
by routines in this library, are described in the sections below.
-<P>
-
\subsection struct_Cell_head struct Cell_head
-<P>
The raster header data structure is used for two purposes. It is used
for raster header information for map layers. It also used to hold
region values. The structure is:
-\verbatim
+\code
struct Cell_head
{
- int format; /* number of bytes per cell */
+ int format; /* number of bytes per cell */
int compressed; /* compressed(1) or not compressed(0) */
int rows, cols; /* number of rows and columns */
- int proj; /* projection */
- int zone; /* zone */
- double ew_res; /* east-west resolution */
- double ns_res; /* north-south resolution */
- double north; /* northern edge */
- double south; /* southern edge */
- double east; /* eastern edge */
- double west; /* western edge */
+ int proj; /* projection */
+ int zone; /* zone */
+ double ew_res; /* east-west resolution */
+ double ns_res; /* north-south resolution */
+ double north; /* northern edge */
+ double south; /* southern edge */
+ double east; /* eastern edge */
+ double west; /* western edge */
};
-\endverbatim
+\endcode
-<P>
-The <I>format</I> and <I>compressed</I> fields apply only to raster
-headers. The <I>format</I> field describes the number of bytes per
-raster data value and the <I>compressed</I> field indicates if the
+The <i>format</i> and <i>compressed</i> fields apply only to raster
+headers. The <i>format</i> field describes the number of bytes per
+raster data value and the <i>compressed</i> field indicates if the
raster file is compressed or not. The other fields apply both to
raster headers and regions. The geographic boundaries are described by
-<I>north, south, east</I> and <I>west.</I> The grid resolution is
-described by <I>ew_res</I> and <I>ns_res.</I> The cartographic
-projection is described by <I>proj</I> and the related zone for the
-projection by <I>zone.</I> The <I>rows</I> and <I>cols</I> indicate
+<i>north, south, east</i> and <i>west</i>. The grid resolution is
+described by <i>ew_res</i> and <i>ns_res</i>. The cartographic
+projection is described by <i>proj</i> and the related zone for the
+projection by <i>zone</i>. The <i>rows</i> and <i>cols</i> indicate
the number of rows and columns in the raster file, or in the
-region. See \ref Raster_Header_Format for more information about raster
-headers, and \ref Region for more information about regions.
+region. See \ref Raster_Header_Format for more information about
+raster headers, and \ref Region for more information about regions.
-<P>
The routines described in \ref Raster_Header_File use this structure.
-<P>
-
\subsection struct_Categories struct Categories
-<P>
-The <I>Categories</I> structure contains a title for the map layer,
+
+The <i>Categories</i> structure contains a title for the map layer,
the largest category in the map layer, an automatic label generation
rule for missing labels, and a list of category labels.
-<P>
-The structure is declared: <I>struct Categories</I> .
-
-<P>
This structure should be accessed using the routines described in
-Raster_Category_File.
+\ref Raster_Category_File.
-<P>
-
\subsection struct_Colors struct Colors
-<P>
The color data structure holds red, green, and blue color intensities
for raster categories. The structure has become so complicated that it
will not be described in this manual.
-<P>
-The structure is declared: <I>struct Colors</I> .
-
-<P>
-The routines described in Raster_Color_Table must be used
+The routines described in \ref Raster_Color_Table must be used
to store and retrieve color information using this structure.
-<P>
-
\subsection struct_History struct History
-<P>
-The <I>History</I> structure is used to document raster files. The
+The <i>History</i> structure is used to document raster files. The
information contained here is for the user. It is not used in any
operational way by GRASS. The structure is:
-\verbatim
+\code
# define MAXEDLINES 50
# define RECORD_LEN 80
@@ -2370,62 +2186,47 @@
int edlinecnt;
char edhist[MAXEDLINES][RECORD_LEN];
};
-\endverbatim
+\endcode
-
-<P>
-The <I>mapid</I> and <I>mapset</I> are the raster file name and
-mapset, <I>title</I> is the raster file title, <I>creator</I> is the
-user who created the file, <I>maptype</I> is the map type (which
-should always be "raster"), <I>datasrc_1</I> and <I>datasrc_2</I>
-describe the original data source, <I>keywrd</I> is a one-line data
-description and <I>edhist</I> contains <I>edlinecnt</I> lines of user
+The <i>mapid</i> and <i>mapset</i> are the raster file name and
+mapset, <i>title</i> is the raster file title, <i>creator</i> is the
+user who created the file, <i>maptype</i> is the map type (which
+should always be "raster"), <i>datasrc_1</i> and <i>datasrc_2</i>
+describe the original data source, <i>keywrd</i> is a one-line data
+description and <i>edhist</i> contains <i>edlinecnt</i> lines of user
comments.
-<P>
-The routines described in Raster_History_File use this structure.
-However, there is very little support for manipulating the contents of this
-structure. The programmer must manipulate the contents directly.
+The routines described in \ref Raster_History_File use this structure.
+However, there is very little support for manipulating the contents of
+this structure. The programmer must manipulate the contents directly.
-<P>
-<B>Note.</B> Some of the information in this structure is not meaningful. For
-example, if the raster file is renamed, or copied into another mapset, the
-<I>mapid</I> and <I>mapset</I> will no longer be correct. Also the
-<I>title</I> does not reflect the true raster file title. The true title is
-maintained in the category file.
+<b>Note:</b> Some of the information in this structure is not
+meaningful. For example, if the raster file is renamed, or copied
+into another mapset, the <i>mapid</i> and <i>mapset</i> will no longer
+be correct. Also the <i>title</i> does not reflect the true raster
+file title. The true title is maintained in the category file.
-<P>
-<B>Warning.</B> This structure has remained unchanged since the inception of
+<b>Warning:</b> This structure has remained unchanged since the inception of
GRASS. There is a good possibility that it will be changed or eliminated in
future releases.
-<P>
-
\subsection struct_Range struct Range
-<P>
-The <I>Range</I> structure contains the minimum and maximum values which occur
+The <i>Range</i> structure contains the minimum and maximum values which occur
in a raster file.
-<P>
-The structure is declared: <I>struct Range</I> .
+The routines described in \ref Raster_Range_File should be used to access
+this structure.
-<P>
-The routines described in Raster_Range_File should be used
-to access this structure.
-
-<P>
-
\section Loading_the_GIS_Library Loading the GIS Library
-<P>
The library is loaded by specifying $(GISLIB) in the Makefile. The following
example is a complete Makefile which compiles code that uses this library:
-<br>
-<B>Makefile for $(GISLIB)}</B>
+<b>Makefile for $(GISLIB)</b>
+
\verbatim
MODULE_TOPDIR = ../..
@@ -2439,262 +2240,116 @@
default: cmd
\endverbatim
-<P>
-See \ref Compiling_and_Installing_GRASS_Modules for a complete discussion
-of Makefiles.
+See \ref Compiling_and_Installing_GRASS_Modules for a complete
+discussion of Makefiles.
-<P>
-
\section TimeStamp_functions Timestamp functions
-\verbatim
- #include <grass/gis.h>
-\endverbatim
-
-
-<P>
-This structure is defined in gis.h, but there should be no reason to access its
+This structure is defined in "gis.h", but there should be no reason to access its
elements directly:
-\verbatim
+\code
struct TimeStamp {
DateTime dt[2]; /* two datetimes */
int count;
};
-\endverbatim
+\endcode
-
-<P>
Using the G_*_timestamp() routines reads/writes a timestamp file in
-the cell_misc/rastername or dig_misc/vectorname mapset element.
+the cell_misc/rastername mapset element.
-<P>
A TimeStamp can be one DateTime, or two DateTimes representing a
-range. When preparing to write a TimeStamp, the programmer should
+range. When preparing to write a TimeStamp, the programmer should
use one of:
-<P>
-<B>G_set_timestamp()</B> to set a single DateTime
+ - G_set_timestamp() to set a single DateTime
-<P>
-<B>G_set_timestamp_range()</B> to set two DateTimes.
+ - G_set_timestamp_range() to set two DateTimes
-<P>
-int G_read_raster_timestamp(char *name, char *mapset, struct TimeStamp
- *ts) Read raster timestamp<br>
-Returns 1 on success. 0 or negative on error.
+ - G_read_raster_timestamp to read raster timestamp
-<P>
-int G_read_vector_timestamp(char *name, char *mapset, struct TimeStamp
- *ts) Read vector timestamp<br>
-Returns 1 on success. 0 or negative on error.
+ - G_read_vector_timestamp to read vector timestamp
-<P>
-int G_get_timestamps(struct TimeStamp *ts, DateTime *dt1, DateTime
- *dt2, int *count) copy TimeStamp into Datetimes
+ - G_get_timestamps() to copy TimeStamp into Datetimes
Use to copy the TimeStamp information into Datetimes, so the members
of struct TimeStamp shouldn't be accessed directly.
-<br>
-count=0 means no datetimes were copied
+ - count=0 means no datetimes were copied
+ - count=1 means 1 datetime was copied into dt1
+ - count=2 means 2 datetimes were copied
-<br>
-count=1 means 1 datetime was copied into dt1
+ - G_init_timestamp()
-<br>
-count=2 means 2 datetimes were copied
-
-
-<P>
-int G_init_timestamp()
Sets ts->count = 0, to indicate no valid DateTimes are in TimeStamp.
-<P>
-int G_set_timestamp() Copies a
- single DateTime to a TimeStamp in preparation for writing. (overwrites any
- existing information in TimeStamp)
+ - G_set_timestamp()
-<P>
-int G_set_timestamp_range()
-Copies two DateTimes (a range) to a TimeStamp in preparation for writing.
-(overwrites any existing information in TimeStamp)
+Copies a single DateTime to a TimeStamp in preparation for writing
+(overwrites any existing information in TimeStamp).
-<P>
-int G_write_raster_timestamp()
-Returns:
+ - G_set_timestamp_range()
-<br>
-1 on success.
+Copies two DateTimes (a range) to a TimeStamp in preparation for
+writing (overwrites any existing information in TimeStamp).
-<br>
--1 error - can't create timestamp file
+ - G_write_raster_timestamp()
-<br>
--2 error - invalid datetime in ts
+ - G_write_vector_timestamp()
+ - G_write_grid3_timestamp()
-<P>
-int G_write_vector_timestamp()
-Returns:
+ - G_format_timestamp()
-<br>
-1 on success.
+ - G_scan_timestamp()
-<br>
--1 error - can't create timestamp file
+ - G_remove_raster_timestamp()
-<br>
--2 error - invalid datetime in ts
+ - G_remove_vector_timestamp()
+ - G_remove_grid3_timestamp()
-<P>
-int G_format_timestamp()
-Returns:
+Only timestamp files in current mapset can be removed.
-<br>
-1 on success
+ - G_read_grid3_timestamp()
-<br>
--1 error
+See \ref DateTime_Library for a complete discussion of GRASS datetime
+routines.
+\section Memory_Allocation Memory Allocation
-<P>
-int G_scan_timestamp()
-Returns:
+The following routines provide memory allocation capability. They are
+simply calls to the UNIX suite of memory allocation routines malloc(),
+realloc() and calloc(), except that if there is not enough memory,
+they print a diagnostic message to that effect and then call exit().
-<br>
-1 on success
+ - G_malloc ()
-<br>
--1 error
+Allocates a block of memory at least <i>size</i> bytes which is
+aligned properly for all data types. A pointer to the aligned block is
+returned.
+ - G_realloc()
-<P>
-int G_remove_raster_timestamp()
-Only timestamp files in current mapset can be removed
+Changes the <i>size</i> of a previously allocated block of memory at
+<i>ptr</i> and returns a pointer to the new block of memory. The
+<i>size</i> may be larger or smaller than the original size. If the
+original block cannot be extended "in place", then a new block is
+allocated and the original block copied to the new block.
-<P>
-Returns:
+<b>Note:</b> If <i>ptr</i> is NULL, then this routine simply allocates
+a block of <i>size</i> bytes. This routine works around broken
+realloc() routines, which do not handle a NULL <i>ptr</i>.
-<br>
-0 if no file
+ - G_calloc()
-<br>
-1 if successful
+Allocates a properly aligned block of memory <i>n</i>*<i>size</i>
+bytes in length, initializes the allocated memory to zero, and returns
+a pointer to the allocated block of memory.
-<br>
--1 on fail
+ - G_free()
+Use the G_free() routine to release memory allocated by
+these routines.
-<P>
-int G_remove_vector_timestamp()
-Only timestamp files in current mapset can be removed
-
-<P>
-Returns:
-
-<br>
-0 if no file
-
-<br>
-1 if successful
-
-<br>
--1 on fail
-
-
-<P>
-int G_read_grid3_timestamp() read grid3 timestamp
-
-Returns 1 on success. 0 or negative on error.
-
-<P>
-int G_remove_grid3_timestamp() remove grid3
-timestamp
-
-Only timestamp files in current mapset can be removed
-
-<P>
-Returns:
-
-<br>
-0 if no file
-
-<br>
-1 if successful
-
-<br>
--1 on fail
-
-
-<P>
-int G_write_grid3_timestamp() write grid3 timestamp
-
-Returns:
-
-<br>
-1 on success.
-
-<br>
--1 error - can't create timestamp file
-
-<br>
--2 error - invalid datetime in ts
-
-
-<P>
-See \ref DateTime_Library for a complete discussion of GRASS datetime
-routines.
-
-<P>
-
-\section GRASS_GIS_Library_Overview GRASS GIS Library Overview
-
-
-<P>
-Contents of directory lib/:
-
-<P>
-<PRE>
-arraystats : statistical library
-bitmap : bitmap library for X Window Bitmaps
-btree : binary tree library
-cdhc : library for testing normality and exponentiality
-cairodriver: CAIRO graphics driver
-datetime : DateTime library
-db : database management interface database drivers + SQL parser
-display : library for CELL driver
-dspf : G3D display files library
-external : external libraries from other projects (shapelib)
-fonts : Hershey fonts
-g3d : G3D raster volume library
-gis : main GRASS library
-gmath : generic mathematical functions (matrix, fft etc.)
- (later to be extended, BLAS/LAPACK library wrapper)
-gpde : partial differential equations library
-htmldriver : HTML driver
-imagery : imagery library
-init : GRASS initialization code + scripts
-iostream : fast I/O library
-linkm : linked list memory manager
-manage : general database maintenance routines
-nviz : nviz visualization library
-ogsf : openGL library (required for NVIZ)
-pngdriver : PNG driver
-psdriver : Postscript driver
-proj : PROJ4 projection library wrapper
-python : Python wrapper
-raster : GRASS raster display library (raster map functions are in gis/)
-rowio : row in/out library
-rst : library for interpolation with regularized splines with tension
-segment : segment library
-sites : old sites library (deprecated), now interfaced to vect library
-stats : univariate statistics library
-symbol : drawing symbols for point vector data
-vask : Curses management library
-vect : GRASS vector and Direct Graph library
-</PRE>
-
-
*/
Modified: grass/trunk/lib/gis/gisrasterlib.dox
===================================================================
--- grass/trunk/lib/gis/gisrasterlib.dox 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/gisrasterlib.dox 2009-06-09 18:40:28 UTC (rev 37793)
@@ -3,206 +3,77 @@
by M. Neteler 2/2004, 8/2005, 2006
-->
-\section gisrastintro GRASS Raster File Processing
+by GRASS Development Team (http://grass.osgeo.org)
-<P>
-<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>
+<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>
-- \subpage gisrastintro
-- \subpage Opening_an_Existing_Raster_File
-- \subpage Creating_and_Opening_New_Raster_Files
-- \subpage Allocating_Raster_I_O_Buffers
-- \subpage Reading_Raster_Files
-- \subpage Raster_Map_Layer_Support_Routines
-- \subpage Raster_Header_File
-- \subpage Raster_Category_File
-- \subpage Reading_and_Writing_the_Raster_Category_File
-- \subpage Querying_and_Changing_the_Categories_Structure
-- \subpage Raster_Color_Table
-- \subpage Reading_and_Writing_the_Raster_Color_File
-- \subpage Lookup_Up_Raster_Colors
-- \subpage Creating_and_or_Modifying_the_Color_Table
-- \subpage Predefined_Color_Tables
-- \subpage Raster_History_File
-- \subpage Raster_Range_File
-- \subpage Raster_Histograms
-- \subpage GRASS_5_raster_API
-- \subpage Upgrades_to_Raster_Functions
-- \subpage Null_no_data
-- \subpage Color_Functions
-- \subpage New_functions_to_support_colors_for_floating_point
-- \subpage New_functions_to_support_a_colors_for_the_NULL_value
-- \subpage New_functions_to_support_a_default_color
-- \subpage New_functions_to_support_treating_a_raster_layer_as_a_color_image
-- \subpage Upgraded_color_functions
-- \subpage Changes_to_the_Colors_structure
-- \subpage Changes_to_the_colr_file
-- \subpage Range_functions
-- \subpage New_range_functions
-- \subpage New_and_Upgraded_Cell_stats_functions
-- \subpage New_Quantization_Functions
-- \subpage Categories_Labeling_Functions
-- \subpage Changes_to_the_cats_file
-- \subpage Range_functions
-- \subpage New_Functions_to_read_write_access_and_modify_Categories_structure
-- \subpage Library_Functions_that_are_Deprecated
-- \subpage Guidelines_for_upgrading_GRASS_4_x_Modules
-- \subpage Important_hints_for_upgrades_to_raster_modules
+\section gisrastintro GRASS Raster File Processing
-<P>
-Raster files are the heart and soul of GRASS (update 2005: meanwhile also
-vector data processing entered GRASS' heart). Because of this, a
-suite of routines which process raster file data has been
+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 (either by prompting the user
-or as 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 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.
-<P>
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.
-G3D (GRID3D) is treated as DCELL.
-<P>
+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.
-Prompting for Raster Files</A>
+- Finding_Raster_Files_in_the_Database
+- Opening_an_Existing_Raster_File
+\section Finding_Raster_Files_in_the_Database Finding Raster Files in
+the Database
-<P>
-The following routines interactively prompt the user for a raster 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 raster 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 char name.) These
-routines have a built-in 'list' capability which allows the user to
-get a list of existing raster files.
+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.
-<P> The user is required to enter a valid raster 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 raster file lives or is to be
-created is returned. Both the name and the mapset are used in other
-routines to refer to the raster file.
-
-<P>
-char * G_ask_cell_old(char *prompt, char *name) prompt for existing
-raster file
-
-Asks the user to enter the name of an existing raster file in any
-mapset in the database.
-
-<P> char * G_ask_cell_in_mapset(char *prompt, char *name) prompt for
-existing raster file
-
-Asks the user to enter the name of an existing raster file in the
-current mapset.
-
-<P> char * G_ask_cell_new(char *prompt, char *name) prompt for new
- raster file
-
-Asks the user to enter a name for a raster 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_cell_old("Enter raster file to be processed", name);
-
-if (mapset == NULL)
- return(0);
-\endverbatim
-
-
-\subsection Finding_Raster_Files_in_the_Database Finding Raster 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 raster file name as one of the command arguments. GRASS
-allows the user to specify raster file names (or any other database
-file) either as a simple unqualified name, such as "soils", or as a
-fully qualified name, such as "soils@<I>mapset</I>", 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.
-
-<P>
The following routines search the database for raster files:
-<P>
-char * G_find_cell(char *name, char *mapset) find a raster file
+ - G_find_cell()
-Looks for the raster 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, or it
-can be a specific mapset name, which means look for the raster file
-only in this one mapset (for example, in the current mapset) . If
-found, the mapset where the raster file lives is returned. If not
-found, the NULL pointer is returned.
+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>".
-<P>
-If the user specifies a fully qualified raster file which exists, then
-<I>G_find_cell() </I> modifies <B>name</B> by removing the
-"@<I>mapset</I>".
-
-<P>
For example, to find a raster file anywhere in the database:
-\verbatim
+\code
char name[GNAME_MAX];
char *mapset;
if ((mapset = G_find_cell(name,"")) == NULL)
/* not found */
-\endverbatim
+\endcode
-
-<P>
To check that the raster file exists in the current mapset:
-\verbatim
+\code
char name[GNAME_MAX];
-if (G_find_cell(name,G_mapset()) == NULL)
+if (G_find_cell(name, G_mapset()) == NULL)
/* not found */
-\endverbatim
+\endcode
-
-<P>
-
\section Opening_an_Existing_Raster_File Opening an Existing Raster File
+The following routine opens the raster file for <em>reading</em>.
-<P>
-The following routine opens the raster file <B>name</B> in <B>mapset</B> for
-reading.
+ - G_open_cell_old()
-<P>
-The raster file <B>name</B> and <B>mapset</B> can be obtained
-interactively using <I>G_ask_cell_old()</I> or <I>
-G_ask_cell_in_mapset()</I>, and noninteractively using <I>
-G_find_cell()</I>.
-
-<P>
-int G_open_cell_old(char *name, char *mapset) open an existing
- raster file
-
-This routine opens the raster file <B>name</B> in <B>mapset</B> for
-reading. A nonnegative file descriptor is returned if the open is
+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
@@ -211,1277 +82,976 @@
active module region. Preparation required for reading the various
raster file formats is also done.
-<P>
-
\section Creating_and_Opening_New_Raster_Files Creating and Opening New Raster Files
-####################
-<P>
-The following routines create the new raster file <B>name</B> in the
-current mapset [footnote] and open
-it for writing. The raster file <B>name</B> should be obtained
-interactively using <I>G_ask_cell_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.
+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.
-<P>
-<B>Note.</B> It is not an error for <B>name</B> 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. The interactive routine
-<I>G_ask_cell_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_cell</I> could be used to see if <B>name</B> exists.
+<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.
-<P>
-<B>Warning.</B> However, there is a subtle trap. The temporary file, which
-is created using <I>G_tempfile</I>, 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(), [footnote]
-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
-<I>G_tempfile()</I> for more details.)
+<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).
-<P>
-FILE * G_open_cell_new(char *name) open a new raster file
- (sequential) Creates and opens the raster file <B>name</B> for writing by
- <I>G_put_map_row</I> which writes the file row by row in sequential
- order. The raster file data will be compressed as it is written.
+ - G_open_cell_new()
-<P>
-A nonnegative file descriptor is returned if the open is successful.
- Otherwise a diagnostic message is printed and a negative value is returned.
+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.
-<P>
-FILE * G_open_cell_new_random(char *name) open a new raster file
- (random) Creates and opens the raster file <B>name</B> for writing by
- <I>G_put_map_row_random</I> which allows writing the raster file in a
- random fashion. The file will be created uncompressed. [footnote]
-<P>
-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()
-<P>
-FILE * G_open_cell_new_uncompressed(char *nameopen a new raster
- file (uncompressed) Creates and opens the raster file <B>name</B> for
- writing by <I>G_put_map_row</I> which writes the file row by row in
- sequential order. The raster file will be in uncompressed format when closed.
+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.
-<P>
-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.
+ - G_open_cell_new_uncompressed()
-<P>
-General use of this routine is not recommended. [footnote]
- This routine is provided so the
- <I>r.compress module</I> can create uncompressed raster files.
+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.
-<P>
+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
-
-<P>
Since there is no predefined limit for the number of columns in the
-region,[footnote]
- buffers which are used for reading and writing raster data must be
-dynamically allocated.
+region, buffers which are used for reading and writing raster data
+must be dynamically allocated.
-<P>
-CELL * G_allocate_cell_buf(void) allocate a raster buffer 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).
+ - G_allocate_cell_buf()
-
-\verbatim
+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) ;
-\endverbatim
+cell = G_allocate_cell_buf(void);
+\endcode
-<P>
-If larger buffers are required, the routine <I>G_malloc</I> can be used.
+If larger buffers are required, the routine G_malloc() can be
+used.
-<P>
-If sufficient memory is not available, an error message is printed and exit()
-is called.
+If sufficient memory is not available, an error message is printed and
+exit() is called.
-<P>
-int G_zero_cell_buf(CELL *buf) zero a raster buffer This
- routines assigns each member of the raster buffer array <B>buf</B> to zero.
- It assumes that <B>buf</B> has been allocated using
- <I>G_allocate_cell_buf.</I>
+ - G_zero_cell_buf()
-<P>
+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
-Needs updating for GRASS 5!! See later in this file.
-<BR>
-<P>
-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. [footnote]
-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.
-<P>
-<B>Note.</B> The rows and columns are specified "C style", i.e.,
+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.
-<P>
+<b>THIS FUNCTION IS DEPRECATED IN GRASS 5! SEE NEXT CHAPTER!</b>
-<P><P>
-<BR>
-THIS FUNCTION IS DEPRECATED IN GRASS 5! SEE NEXT CHAPTER!
+ - G_get_map_row()
-<P>
-int G_get_map_row (int fd, CELL *cell, int row) read a raster file
-This routine reads the specified <B>row</B> from the raster file open on
- file descriptor <B>fd</B> (as returned by <I>G_open_cell_old</I>) into
- the <B>cell</B> buffer. The <B>cell</B> buffer must be dynamically
- allocated large enough to hold one full row of raster data. It can be
- <I>allocated using G_allocate_cell_buf.</I>
+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.
-<P>
-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()
-<P>
-int G_get_map_row_nomask (int fd, CELL *cell, int row) read a
- raster file (without masking) This routine reads the specified <B>row</B>
- from the raster file open on file descriptor <B>fd</B> into the
- <B>cell</B> 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 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.
-<P>
-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.
-<P>
-<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 <I>r.describe</I>, which reads
-the raster file directly to report all data values in a raster file, and
-<I>r.slope.aspect</I>, 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 Mask for more information
-about the mask.
-<P>
-
\subsection Writing_Raster_Files Writing Raster Files
-Needs updating for GRASS 5!! See later in this file.
-<BR>
-<P>
-The routines described here write raster file data.
-<P>
-int G_put_map_row (int fd, CELL *buf) write a raster file
- (sequential) This routine writes one row of raster data from <B>buf</B> to
- the raster file open on file descriptor <B>fd.</B> The raster file must
- have been opened with <I>G_open_cell_new.</I>
+\todo <b>Needs updating for GRASS 5!! See later in this file.</b>
-<P>
-The cell <B>buf</B> must have been allocated large enough for the region,
- perhaps using <I>G_allocate_cell_buf.</I>
+ - G_put_map_row()
-<P>
-If there is an error writing the raster file, a warning message is printed
- and -1 is returned. Otherwise 1 is returned.
+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.
-<P>
-<B>Note.</B> The rows are written in sequential order. The first call
- writes row 0, the second writes row 1, etc. The following example assumes
- that the raster file <B>name</B> is to be created:
+<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:
-<P>
-\verbatim
+\code
int fd, row, nrows, ncols;
CELL *buf;
-fd = G_ope... /*...data for the row */
+fd = G_open_cell_old("map"); /*...data for the row */
-G_put_map_row(fd, buf) ;
-\endverbatim
+G_put_map_row(fd, buf);
+\endcode
-<P>
-int G_put_map_row_random (int fd, CELL *buf, int row, int col, int
- ncells) write a raster file (random) This routine allows random writes to
- the raster file open on file descriptor <B>fd.</B> The raster file must
- have been opened using <I>G_open_cell_new_random.</I> The raster buffer
- <B>buf</B> contains <B>ncells</B> columns of data and is to be written
- into the raster file at the specified <B>row</B>, starting at column
- <B>col.</B>
+ - G_put_map_row_random()
-<P>
+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.
-<P>
-All raster files are closed by one of the following routines, whether opened
-for reading or for writing.
+ - G_close_cell()
-<P>
-int G_close_cell (int fd) close a raster file The raster file
- opened on file descriptor <B>fd</B> 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.
+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.
-<P>
-<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.
+<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.
-<P>
-int G_unopen_cell (int fd) unopen a raster file The raster file
- opened on file descriptor <B>fd</B> 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
- Creating_and_Opening_New_Raster_Files) .
+ - G_unopen_cell()
-<P>
-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.
+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).
-<P>
+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.
-<P>
-GRASS map layers have a number of support files associated with them. These
-files are discussed in detail in Raster_Maps. The support files
-are the <I>raster header</I>, the <I>category</I> file, the
-<I>color</I> table, the <I>history</I> file, and the <I>range</I> file.
-Each support file has its own data structure and associated routines.
-
-<P>
-
\section Raster_Header_File Raster Header File
-<P>
-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
-Raster_Header_Format. The routines described below use the
-<I>Cell_head</I> structure which is shown in detail in
+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.
-<P>
-int G_get_cellhd(char *name, char *mapset, struct Cell_Head
- *cellhd) read the raster headerThe raster header for the raster file
- <B>name</B> in the specified <B>mapset</B> is read into the
- <B>cellhd</B> structure.
+ - G_get_cellhd()
-<P>
-If there is an error reading the raster header file, a diagnostic message is
-printed and -1 is returned. Otherwise, 0 is returned.
+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.
-<P>
-<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 <I>G_is_reclass</I> for
-distinguishing reclass files from regular raster files.
+<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.
-<P>
-<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. [footnote]
-If it is necessary to read the raster file directly
-without resampling into the active region, [footnote]
-then the raster header can be used to set the active region using
-<I>G_set_window.</I>
+<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().
-<P>
-char * G_adjust_Cell_head(struct Cell_Head *cellhd, int rflag, int
- cflag) adjust cell headerThis function fills in missing parts of the input
- cell header (or region) . It also makes projection-specific adjustments. The
- <B>cellhd</B> structure must have its <I>north, south, east, west</I>,
- and <I>proj</I> fields set. If <B>rflag</B> is true, then the north-south
- resolution is computed from the number of <I>rows</I> in the
- <B>cellhd</B> structure. Otherwise the number of <I>rows</I> is computed
- from the north-south resolution in the structure, similarly for
- <B>cflag</B> and the number of columns and the east-west resolution. This
- routine returns NULL if execution occurs without error, otherwise it returns
- an error message.
+ - G_adjust_Cell_head()
-<P>
-char * G_put_cellhd(char *name, struct Cell_Head *cellhd) write
- the raster header This routine writes the information from the
- <B>cellhd</B> structure to the raster header file for the map layer
- <B>name</B> in the current mapset.
+This function fills in missing parts of the input cell header (or
+region). It also makes projection-specific adjustments.
-<P>
-If there was an error creating the raster header, -1 is returned. No
+ - 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.
-<P>
-<B>Note.</B> Programmers should have no reason to use this routine. It is
-used by <I>G_close_cell</I> to giv e new raster files correct header
-files, and by the <I>r.support module</I> to give users a means of
-creating or modifying raster headers.
+<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.
-<P>
-int G_is_reclass(char *name, char *mapset, char r_name, char
-**r_mapset) reclass file?This function determines if the raster file
-*<B>name</B> in <B>mapset</B> is a reclass file.
-If it is, then the name and mapset of the referenced
-raster file are copied into the <B>r_name</B> and <B>r_mapset</B>
-buffers.
+ - G_is_reclass()
-<P>
-Returns 1 if <B>name</B> is a reclass file, 0 if it is not, and -1 if
-there was a problem reading the raster header for <B>name.</B>
+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.
-<P>
-int G_is_reclassed_to(char *name, char *mapset, int *nrmaps,
-char ***rmaps) get child reclass maps listThis 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()
-<P>
-G_is_reclassed_to() is used by g.rename, g.remove and r.reclass to
-prevent accidentally deleting the parent map of a reclassed raster map.
+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.
-<P>
-
\section Raster_Category_File Raster Category File
-<P>
-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
-Raster_Category_File_Format.
+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.
-<P>
-The routines described below manage the category file. Some of them use the
-<I>Categories</I> structure which is described in
+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.
-<P>
-
\section Reading_and_Writing_the_Raster_Category_File Reading and Writing the Raster Category File
-
-<P>
The following routines read or write the category file itself:
-<P>
-int G_read_cats(char *name, char *mapset, struct Categories
- *cats) read raster category fileThe category file for raster 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.
+ - G_read_cats()
-<P>
-int G_write_cats(char *name, struct Categories *cats) write raster
- category fileWrites the category file for the raster file <B>name</B> in
- the current mapset from the <B>cats</B> structure.
+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.
-<P>
-Returns 1 if successful. Otherwise, -1 is returned (no diagnostic is
- printed) .
+ - G_write_cats()
-<P>
-char * G_get_cell_title(char *name, char *mapset) get raster map
- titleIf 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
- <B>name</B> in <B>mapset</B> 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.
+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).
-<P>
-char * G_put_cell_title(char *name, char *title) change raster map
- titleIf 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 <B>title</B> for the
- raster file <B>name</B> in the current mapset directly in the category
- file. It returns a pointer to the title.
+ - G_get_cell_title()
-<P>
+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:
-<P>
-The following routines query or modify the information contained in the
-category structure:
+ - G_get_cat()
-<P>
-char * G_get_cat(CELL n, struct Categories *cats) get a category
- labelThis routine looks up category <B>n</B> in the <B>cats</B>
- 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 <B>cats,</B> then a pointer to the empty string "" is returned.
+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.
-<P>
-<B>Warning.</B> The pointer that is returned points to a hidden static
- buffer. Successive calls to G_get_cat() overwrite this buffer.
+<b>Warning:</b> The pointer that is returned points to a hidden static
+buffer. Successive calls to G_get_cat() overwrite this buffer.
-<P>
-char * G_get_cats_title (Categories *cats) get title from category
- structure structMap layers store a one-line title in the category structure
- as well. This routine returns a pointer to the title contained in the
- <B>cats</B> 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_get_cats_title()
-<P>
-int G_init_cats(CELL n, char *title, struct Categories
- *cats) initialize category structureTo construct a new category file, the
- structure must first be initialized. This routine initializes the
- <B>cats</B> structure, and copies the <B>title</B> into the structure.
- The number of categories is set initially to <B>n.</B>
+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.
-<P>
+ - 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:
-<P>
-\verbatim
+\code
struct Categories cats;
-G_init_cats ((CELL) 0, '''', &cats) ;
-\endverbatim
+G_init_cats ((CELL) 0, "", &cats);
+\endcode
-<P>
-int G_set_cat(CELL n, char *label, struct Categories *cats) set a
- category labelThe <B>label</B> is copied into the <B>cats</B> structure
- for category <B>n.</B>
+ - G_set_cat()
-<P>
-int G_set_cats_title(char *title, struct Categories *cats) set
- title in category structureThe <B>title</B> is copied into the
- <B>cats</B> structure.
+Copies the label into the cats structure for category.
-<P>
-int G_free_cats(struct Categories *cats) free category structure
- memoryFrees memory allocated by<I>G_read_cats, G_init_cats</I>
- and<I> G_set_cat.</I>
+ - G_set_cats_title()
-<P>
+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
-<P>
-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 Raster_Color_Table_Format.
-<P>
-The routines that manipulate the raster color file use the <I>Colors</I>
-structure which is described in detail in
+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.
-<P>
-
\section Reading_and_Writing_the_Raster_Color_File Reading and Writing the Raster Color File
-<P>
+
The following routines read, create, modify, and write color tables.
-<P>
-int G_read_colors(char *name, char *mapset, struct Colors
- *colors) read map layer color tableThe color table for the raster file
- <B>name</B> in the specified <B>mapset</B> is read into the
- <B>colors</B> structure.
+ - G_read_colors()
-<P>
-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.
+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.
-<P>
-int G_write_colors(char *name, char *mapset, struct Colors
- *colors) write map layer color tableThe color table is written for the
- raster file <B>name</B> in the specified <B>mapset</B> from the
- <B>colors</B> structure.
+ - G_write_colors()
-<P>
-If there is an error, -1 is returned. No diagnostic is printed. Otherwise, 1
- is returned.
+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.
-<P>
-The <B>colors</B> structure must be created properly, i.e.,
- <I>G_init_colors</I> to initialize the structure and
- <I>G_add_color_rule</I> to set the category colors. [footnote]
-<P>
-<B>Note.</B> The calling sequence for this function deserves special
- attention. The <B>mapset</B> 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
- <B>mapset</B> is the current mapset, then the color file for <B>name</B>
- will be overwritten by the new color table. But if <B>mapset</B> is not the
- current mapset, then the color table is actually written in the current
- mapset under the <B>colr2</B> element as: colr2/mapset/name.
+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.
-<P>
+<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
-
-<P>
These routines translates raster values to their respective colors.
-<P>
-int G_lookup_colors(CELL *raster, unsigned char *red, unsigned char
- *green, unsigned char *blue, set, int n, struct Colors *colors) lookup an
- array of colorsExtracts colors for an array of <B>raster</B> values. The
- colors for the <B>n</B> values in the <B>raster</B> array are stored in
- the <B>red, green</B>, and <B>blue</B> arrays. The values in the
- <B>set</B> array will indicate if the corresponding <B>raster</B> value
- has a color or not (1 means it does, 0 means it does not) . The programmer
- must allocate the <B>red, green, blue</B>, and <B>set</B> arrays to be at
- least dimension <B>n.</B>
+ - G_lookup_colors()
-<P>
-<B>Note.</B> The <B>red, green</B>, and <B>blue</B> intensities will be
- in the range 0 - 255.
+Extracts colors for an array of raster values. The colors from the
+raster array are stored in the red, green, and blue arrays.
-<P>
-int G_get_color(CELL cat, int *red, int *green, int *blue, struct
- Colors *colors) get a category colorThe <B>red, green</B>, and
- <B>blue</B> intensities for the color associated with category <B>cat</B>
- are extracted from the <B>colors</B> structure. The intensities will be in
- the range 0 - 255.
+<b>Note:</b> The red, green, and blue intensities will be in the range
+0 - 255.
-<P>
+ - 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
-
-<P>
These routines allow the creation of customized color tables as well as the
modification of existing tables.
-<P>
-int G_init_colors(struct Colors *colors) initialize color
- structureThe <B>colors</B> structure is initialized for subsequent calls
- to <I>G_add_color_rule</I> and<I>G_set_color.</I>
+ - G_init_colors()
-<P>
-int G_add_color_rule(CELL cat1, int r1, int g1, int b1, CELL cat2,
- int r2, int g2, int b2, struct Colors *colors) set colorsThis is the heart
- and soul of the new color logic. It adds a color rule to the <B>colors</B>
- structure. The colors defined by the red, green, and blue values
- <B>r1,g1,b1</B> and <B>r2,g2,b2</B> are assigned to <B>cat1</B> and
- <B>cat2</B> respectively. Colors for data values between <B>cat1</B> and
- <B>cat2</B> are not stored in the structure but are interpolated when
- queried by <I>G_lookup_colors</I> and<I> G_get_color.</I> The color
- components <B>r1,g1,b1</B> and <B>r2,g2,b2</B> must be in the range
- 0 - 255.
+Initialize <i>colors</i> structure for subsequent calls
+G_add_color_rule() and G_set_color().
-<P>
+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:
-<P>
-\verbatim
+\code
struct Colors colr;
G_init_colors (&colr) ;
G_add_color_rule ((CELL) 200, 0,0,0,(CELL) 1000, 255,255,255) ;
-\endverbatim
+\endcode
+The programmer is encouraged to review \ref Raster_Color_Table_Format
+how this routine fits into the 5.x raster color logic.
-<P>
-The programmer is encouraged to review Raster_Color_Table_Format how
-this routine fits into the 5.x raster color logic.
-
-<P>
-<B>Note.</B> The <B>colors</B> structure must have been initialized by
-<I>G_init_colors.</I> See \ref Predefined_Color_Tables for routines to
+<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.
-<P>
-int G_set_color(CELL cat, int red, int green, int blue, struct
- Colors *colors) set a category colorThe <B>red, green</B>, and
- <B>blue</B> intensities for the color associated with category <B>cat</B>
- are set in the <B>colors</B> structure. The intensities must be in the
- range 0 - 255. Values below zero are set as zero, values above 255 are set as
- 255.
+ - G_set_color()
-<P>
-<B>Use of this routine is discouraged because it defeats the new color
- logic.</B> It is provided only for backward compatibility. Overuse can create
- large color tables. <I>G_add_color_rule</I> should be used whenever
- possible.
+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.
-<P>
-<B>Note.</B> The <B>colors</B> structure must have been initialized by
- <I>G_init_color.</I>
+<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.
-<P>
-int G_get_color_range(CELL *min, CELL *max, struct Colors
-*colors) get color rangeGets the minimum and maximum raster values that
-have colors associated with them.
+<b>Note:</b> The <em>colors</em> structure must have been initialized
+by G_init_color().
-<P>
-int G_free_colors(struct Colors *colors) free color structure
- memoryThe dynamically allocated memory associated with the <B>colors</B>
- structure is freed.
+ - G_get_color_range()
+ - G_get_d_color_range()
-<P>
-<B>Note.</B> This routine may be used after <I>G_read_colors</I> as
- well as after <I>G_init_colors.</I>
+Get color range. Gets the minimum and maximum raster values that have
+colors associated with them.
-<P>
+ - 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
-<P>
-The following routines generate entire color tables. The tables are loaded into
-a <B>colors</B> structure based on a range of category values from
-<B>min</B> to <B>max.</B> The range of values for a raster map can be
-obtained, for example, using <I>G_read_range.</I> <B>Note.</B> The color
-tables are generated without information about any particular raster file.
+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().
-<P>
-These color tables may be created for a raster file, but they may also be
-generated for loading graphics colors.
+<b>Note:</b> The color tables are generated without information about
+any particular raster file.
-<P>
-These routines return -1 if <B>min</B> is greater than <B>max</B>, 1
-otherwise.
+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.
-<P>
-int G_make_aspect_colors(struct Colors *colors, CELL min, CELL
- max) make aspect colorsGenerates a color table for aspect data.
+ - G_make_aspect_colors()
-<P>
-int G_make_ramp_colors(struct Colors *colors, CELL min, CELL
- max) make color rampGenerates 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.
+Generates a color table for aspect data.
-<P>
-int G_make_wave_colors(struct Colors *colors, CELL min, CELL
- max) make color waveGenerates 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_ramp_colors()
-<P>
-int G_make_grey_scale_colors(struct Colors *colors, CELL min, CELL
- max) make linear grey scaleGenerates a grey scale color table. Each color
- is a level of grey, increasing from black to white.
+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.
-<P>
-int G_make_rainbow_colors(struct Colors *colors, CELL min, CELL
- max) make rainbow colorsGenerates 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_wave_colors()
-<P>
-int G_make_random_colors(struct Colors *colors, CELL min, CELL
- max) make random colorsGenerates random colors. Good as a first pass at a
- color table for nominal data.
+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.
-<P>
-int G_make_ryg_colors(struct Colors *colors, CELL min, CELL
- max) make red,yellow,green colorsGenerates a color table that goes from
- red to yellow to green.
+ - G_make_grey_scale_colors()
-<P>
-int G_make_gyr_colors(struct Colors *colors, CELL min, CELL
- max) make green,yellow,red colorsGenerates a color table that goes from
- green to yellow to red.
+Generates a grey scale color table. Each color is a level of grey,
+increasing from black to white.
-<P>
-int G_make_histogram_eq_colors(struct Colors *colors, struct
- Cell_stats *s) make histogram-stretched grey colorsGenerates a histogram
- contrast-stretched grey scale color table that goes from the ,histogram
- information in the Cell_stats structure <B>s.</B> (See
- Raster_Histograms) .
+ - G_make_rainbow_colors()
-<P>
+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
-<P>
-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
-Raster_History_File_Format
+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.
-<P>
-The following routines manage this file. They use the <I>History</I>
-structure which is described in GIS_Library_Data_Structures.
+The following routines manage this file. They use the <em>History</em>
+structure which is described in \ref GIS_Library_Data_Structures.
-<P>
-<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.
+<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.
-<P>
-int G_read_history(char *name, char *mapset, struct History
- *history) read raster history fileThis routine reads the history file for
- the raster file <B>name</B> in <B>mapset</B> into the <B>history</B>
- structure.
+ - G_read_history()
-<P>
-A diagnostic message is printed and -1 is returned if there is an error
- reading the history file. Otherwise, 0 is returned.
+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.
-<P>
-int G_write_history(char *name, struct History *history) write
- raster history fileThis routine writes the history file for the raster file
- <B>name</B> in the current mapset from the <B>history</B> structure.
+ - G_write_history()
-<P>
-A diagnostic message is printed and -1 is returned if there is an error
- writing the history file. Otherwise, 0 is returned.
+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.
-<P>
-<B>Note.</B> The <B>history</B> structure should first be initialized
- using <I>G_short_history.</I>
+<b>Note:</b> The <em>history</em> structure should first be
+initialized using G_short_history().
-<P>
-int G_short_history(char *name, char *type, struct History
- *history) initialize history structureThis routine initializes the
- <B>history</B> structure, recording the date, user, module name and the
- raster file <B>name</B> structure. The <B>type</B> is an anachronism from
- earlier versions of GRASS and should be specified as "raster".
+ - G_short_history()
-<P>
-<B>Note.</B> This routine only initializes the data structure. It does not
- write the history file.
+Initialize history structureThis routine initializes the
+<em>history</em> structure, recording the date, user, module name and
+the raster map.
-<P>
+<b>Note:</b> This routine only initializes the data structure. It does
+not write the history file.
\section Raster_Range_File Raster Range File
-<P>
-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 Raster_Range_File_Format.
-<P>
-The routines below use the <I>Range</I> data structure which is described in
-GIS_Library_Data_Structures.
+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.
-<P>
-int G_read_range(char *name, char *mapset, struct Range
- *range) read raster rangeThis routine reads the range information for the
- raster file <B>name</B> in <B>mapset</B> into the <B>range</B>
- structure.
+The routines below use the <i>Range</i> data structure which is
+described in \ref GIS_Library_Data_Structures.
-<P>
-A diagnostic message is printed and -1 is returned if there is an error
- reading the range file. Otherwise, 0 is returned.
+ - G_read_range()
-<P>
-int G_write_range(char *name, struct Range *range) write raster
- range fileThis routine writes the range information for the raster file
- <B>name</B> in the current mapset from the <B>range</B> structure.
+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.
-<P>
-A diagnostic message is printed and -1 is returned if there is an error
- writing the range file. Otherwise, 0 is returned.
+ - G_write_range()
-<P>
+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:
-<P>
-int G_init_range(struct Range *range) initialize range
- structureInitializes the <B>range</B> structure for updates by
- <I>G_update_range</I> and <I>G_row_update_range.</I>
+ - G_init_range()
-<P>
-int G_update_range(CELL cat, struct Range *range) update range
- structureCompares the <B>cat</B> value with the minimum and maximum
- values in the <B>range</B> structure, modifying the range if <B>cat</B>
- extends the range.
+Initializes the <i>range</i> structure for updates by G_update_range()
+and G_row_update_range().
-<P>
-int G_row_update_range(CELL *cell, int n, struct Range
- *range) update range structureThis routine updates the <B>range</B> data
- just like <I>G_update_range</I>, but for <B>n</B> values from the
- <B>cell</B> array.
+ - G_update_range()
-<P>
+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:
-<P>
-int G_get_range_min_max(struct Range *range, CELL *min, CELL
- *max) get range min and maxThe <B>min</B>inum and <B>max</B>imum CELL
- values are extracted from the <B>range</B> structure.
+ - G_get_range_min_max()
-<P>
+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.
-<P>
-The following routines provide a relatively efficient mechanism for computing
-and querying a histogram of raster data. They use the <I>Cell_stats</I>
-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.
-
-<P>
These next two routines are used to manage the Cell_stats structure:
-<P>
-int G_init_cell_stats(struct Cell_stats *s) initialize cell
- statsThis routine, which must be called first, initializes the Cell_stats
- structure <B>s.</B>
+ - G_init_cell_stats()
-<P>
-int G_free_cell_stats(struct Cell_stats *s) free cell statsThe
- memory associated with structure <B>s</B> is freed. This routine may be
- called any time after calling<I>G_init_cell_stats.</I>
+Initialize cell stats, This routine, which must be called first,
+initializes the Cell_stats structure.
-<P>
+ - 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:
-<P>
-int G_update_cell_stats(CELL *data, int n, struct Cell_stats
- *s) add data to cell statsThe <B>n</B> CELL values in the <B>data</B>
- array are inserted (and counted) in the Cell_stats structure <B>s.</B>
+ - G_update_cell_stats()
-<P>
-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) :
+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):
-<P>
-int G_find_cell_stat(CELL cat, long *count, struct Cell_stats
- *s) random query of cell statsThis routine allows a random query of the
- Cell_stats structure <B>s.</B> The <B>count</B> associated with the
- raster value <B>cat</B> is set. The routine returns 1 if <B>cat</B> was
- found in the structure, 0 otherwise.
+ - G_find_cell_stat()
-<P>
+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:
-<P>
-int G_rewind_cell_stats(struct Cell_stats *s) reset/rewind cell
- statsThe structure <B>s</B> is rewound (i.e., positioned at the first
- raster category) so that sorted sequential retrieval can begin.
+ - G_rewind_cell_stats()
-<P>
-int G_next_cell_stat(CELL *cat, long *count, struct Cell_stats
- *s) retrieve sorted cell stats Retrieves the next <B>cat,count</B>
- combination from the structure <B>s.</B> Returns 0 if there are no more
- items, non-zero if there are more.
+Reset/rewind cell stats. The structure is rewound (i.e., positioned at
+the first raster category) so that sorted sequential retrieval can
+begin.
-<P>
+ - 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:
-<P>
-\verbatim
+\code
struct Cell_stats s;
CELL cat;
long count;
-.
-. /* updating s occurs here */
-.
+/* updating s occurs here */
G_rewind_cell_stats(&s);
-while (G_next_cell_stat(&cat,&count,&s)
+while(G_next_cell_stat(&cat, &count, &s))
fprintf(stdout, "%ld %ld\n", (long) cat, count);
-\endverbatim
+\endcode
-<P>
-
\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., fprintf(stdout, ...), sscanf(),
-etc.) must use an intermediate variable of type long. To print a CELL
-value, it must be cast to long. For example:
+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:
-\verbatim
+\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 */
-\endverbatim
+\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):
-\verbatim
+\code
char userbuf[128];
-CELL c; long x;
+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 */
-\endverbatim
+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:
-<P>
-The <TT>"gis.h"</TT> contains 5 new items:
-
-<P>
-<PRE>
- typedef float FCELL
- typedef double DCELL
+\code
+ typedef float FCELL;
+ typedef double DCELL;
typedef int RASTER_MAP_TYPE;
- #define CELL_TYPE 0
+ #define CELL_TYPE 0
#define FCELL_TYPE 1
#define DCELL_TYPE 2
-</PRE>
+\endcode
-<P>
-Also <TT>"gis.h"</TT> contains the definitions for new structures:
+Also "gis.h" contains the definitions for new structures:
-<P>
-<PRE>
+\code
struct FPReclass;
struct FPRange;
struct Quant;
-</PRE>
+\endcode
-<P>
Some of the old structures such as
-<P>
-<PRE>
+\code
struct Categories
struct Cell_stats;
struct Range;
struct _Color_Rule_;
struct _Color_Info_;
struct Colors;
-</PRE>
+\endcode
-<P>
-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.
+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.
-<P>
-
\subsection NULL_value_functions NULL-value functions
+ - G_set_null_value()
-<P>
-int G_set_null_value(void *rast, int count, RASTER_MAP_TYPE
- data_type) Set NULL valueIf the <EM>data_type</EM> is CELL_TYPE, calls
- G_set_c_null_value((CELL *) rast, count) ;
+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().
-<P>
-If the <EM>data_type</EM> is FCELL_TYPE, calls G_set_f_null_value((FCELL
- *) rast, count) ;
+ - G_insert_null_values()
-<P>
-If the <EM>data_type</EM> is DCELL_TYPE, calls G_set_d_null_value((DCELL
- *) rast, count) ;
+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().
-<P>
-int G_set_c_null_value(CELL *cell, int count) Set CELL NULL
- valueSet the <EM>count</EM> elements in the <EM>cell</EM> array to the NULL value
- (the largest positive integer) .
+ - G_is_null_value()
-<P>
-int G_set_f_null_value(FCELL *fcell, int count) Set FCELL NULL
- valueSet the <EM>count</EM> elements in the <EM>fcell</EM> array to the NULL
- value (a bit pattern for a <TT>float</TT> NaN - 32 bits of 1's) .
+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().
-<P>
-int G_set_d_null_value(DCELL *dcell, int count) Set CELL NULL
- valueSet the <EM>count</EM> elements in the <EM>dcell</EM> array to the NULL
- value - which (a bit pattern for a <TT>double</TT> NaN - 64 bits of 1's) .
+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
-<P>
-int G_insert_null_values(void *rast, char *flags, int count,
- RASTER_MAP_TYPE data_type) Insert NULL valueIf the <EM>data_type</EM> is
- CELL_TYPE, calls G_insert_c_null_values ((CELL *) rast, flags, count) ;
-
-<P>
-If the <EM>data_type</EM> is FCELL_TYPE, calls G_insert_f_null_values
- ((FCELL *) rast, flags, count) ;
-
-<P>
-If the <EM>data_type</EM> is DCELL_TYPE, calls G_insert_d_null_values
- ((DCELL *) rast, flags, count) ;
-
-<P>
-int G_insert_c_null_values(CELL *cell, char *flags, int
- count) Insert CELL NULL value For each of the <EM>count</EM> <EM>flags</EM>
- which is true(!=0) , set the corresponding <EM>cell</EM> to the NULL value.
-
-<P>
-int G_insert_f_null_values(FCELL *fcell, char *flags, int
- count) Insert FCELL NULL value For each of the <EM>count</EM> <EM>flags</EM>
- which is true(!=0) , set the corresponding <EM>fcell</EM> to the NULL value.
-
-<P>
-int G_insert_d_null_values(DCELL *dcell, char *flags, int
- count) Insert DCELL NULL value For each for the <EM>count</EM> <EM>flag</EM>
- which is true(!=0) , set the corresponding <EM>dcell</EM> to the NULL value.
-
-<P>
-int G_is_null_value(void *rast, RASTER_MAP_TYPE data_type) If
- the <EM>data_type</EM> is CELL_TYPE, calls G_is_c_null_value ((CELL *)
- rast) ;
-
-<P>
-If the <EM>data_type</EM> is FCELL_TYPE, calls G_is_f_null_value ((FCELL
- *) rast) ;
-
-<P>
-If the <EM>data_type</EM> is DCELL_TYPE, calls G_is_d_null_value ((DCELL
- *) rast) ;
-
-<P>
-int G_is_c_null_value(CELL *cell) Returns 1 if <EM>cell</EM> is
- NULL, 0 otherwise. This will test if the value <EM>cell</EM> is the largest <TT>int</TT>.
-
-<P>
-int G_is_f_null_value(FCELL *fcell) Returns 1 if <EM>fcell</EM>
- is NULL, 0 otherwise. This will test if the value <EM>fcell</EM> is a NaN. 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
-
-<P>
-\verbatim
+\code
if(fcell == 0.0) return 0;
if(fcell > 0.0) return 0;
if(fcell < 0.0) return 0;
return 1;
-\endverbatim
-<BR>
+\endcode
-<P>
or (as suggested by Mark Line)
-<P>
-\verbatim
+\code
return(FCELL != fcell) ;
-\endverbatim
+\endcode
-<P>
-int G_is_d_null_value(DCELL *dcell) Returns 1 if <EM>dcell</EM> is
- NULL, 0 otherwise. This will test if the value <EM>dcell</EM> is a NaN. Same
- test as in <TT>G_is_f_null_value()</TT>.
+ - G_allocate_null_buf()
-<P>
-char * G_allocate_null_buf() Allocate an array of char based on
- the number of columns in the current region.
+Allocates an array of char based on the number of columns in the
+current region.
-<P>
-int G_get_null_value_row (int fd, char *flags, int row) Reads a
- row from NULL value bitmap file for the raster map open for read on <EM>fd</EM>.
- 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. <EM>
- flags</EM> is a resulting array of 0's and 1's where 1 corresponds to
- <TT>"no data"</TT> cell.
+ - G_get_null_value_row()
-<P>
+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()
-<P>
-int G_maskfd(void) test for current maskreturns file descriptor
- number if MASK is in use and -1 if no MASK is in use.
+Test for current maskreturns file descriptor number if MASK is in use
+and -1 if no MASK is in use.
-<P>
-int G_raster_map_is_fp(char *name, char *mapset) Returns true(1)
- if raster map <EM>name</EM> in <EM>mapset</EM> is a floating-point dataset;
- false(0) otherwise.
+ - G_raster_map_is_fp()
-<P>
-int G_raster_map_type(char *name, char *mapset) Returns the
- storage type for raster map <EM>name</EM> in <EM>mapset</EM>: <TT>CELL_TYPE</TT>
- (int) ; <TT>FCELL_TYPE</TT> (float) ; or <TT>DCELL_TYPE</TT> (double) .
+Returns true(1) if raster map is a floating-point dataset; false(0)
+otherwise.
-<P>
-int G_open_raster_new[_uncompressed](char *name,
- RASTER_MAP_TYPE map_type) If map_type == CELL_TYPE, calls
- G_open_map_new[_uncompressed](name) ;
+ - G_raster_map_type()
-<P>
-If map_type == FCELL_TYPE, calls G_set_fp_type(FCELL_TYPE) ;
- G_open_fp_map_new[_uncompressed](name) ;
+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)
-<P>
-If map_type == DCELL_TYPE, calls G_set_fp_type(DCELL_TYPE) ;
- G_open_fp_map_new[_uncompressed](name) ;
+ - G_open_raster_new()
-<P>
-The use of this routine by applications is discouraged since its use would override user
- preferences (what precision to use) .
+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).
-<P>
-int G_set_fp_type (RASTER_MAP_TYPE type) This controls the
- storage type for floating-point maps. It affects subsequent calls to
- <TT>G_open_fp_map_new()</TT>. 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_set_fp_type()
-<P>
-int G_open_fp_map_new(char *name) Opens a new floating-point
- raster map (in <TT>.tmp</TT>) and returns a file descriptor. The storage type
- (<TT>float</TT> or <TT>double</TT>) is determined by the last call to
- <TT>G_set_fp_type()</TT> or the default (<TT>float</TT> - unless the Unix env
- variable GRASS_FP_DOUBLE is set) .
+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.
-<P>
-void * G_allocate_raster_buf(RASTER_MAP_TYPE
- data_type) Allocate an array of CELL, FCELL, or DCELL (depending on <EM>
- data_type</EM>) based on the number of columns in the current region.
+ - G_open_fp_map_new()
-<P>
-CELL * G_allocate_c_raster_buf() Allocate an array of CELL
- based on the number of columns in the current region.
+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).
-<P>
-FCELL * G_allocate_f_raster_buf() Allocate an array of FCELL
- based on the number of columns in the current region.
+ - G_allocate_raster_buf()
+ - G_allocate_c_raster_buf()
+ - G_allocate_f_raster_buf()
+ - G_allocate_d_raster_buf()
-<P>
-DCELL * G_allocate_d_raster_buf() Allocate an array of DCELL
- based on the number of columns in the current region.
+Allocate an arrays of CELL, FCELL, or DCELL (depending on raster type)
+based on the number of columns in the current region.
-<P>
-void * G_incr_void_ptr(void *ptr, int size) Advances void
- pointer by n bytes. returns new pointer value. Usefull in raster row
- processing loops, substitutes
+ - G_incr_void_ptr()
-<P>
-\verbatim
+Advances void pointer by n bytes. Returns new pointer value. Usefull
+in raster row processing loops, substitutes
+
+\code
CELL *cell;
cell += n;
-\endverbatim
+\endcode
-<P>
Now
-\verbatim
-rast = G_incr_void_ptr(rast, G_raster_size(data_type) )
-\endverbatim
+\code
+rast = G_incr_void_ptr(rast, G_raster_size(data_type));
+\endcode
-<P>
-(where rast 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)
+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))
-<P>
-int G_raster_size (RASTER_MAP_TYPE data_type) If <EM>data_type</EM> is CELL_TYPE, returns sizeof(CELL)
+ - G_raster_size()
-<P>
-If <EM>data_type</EM> is FCELL_TYPE, returns sizeof(FCELL)
+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).
-<P>
-If <EM>data_type</EM> is DCELL_TYPE,q returns sizeof(DCELL)
+ - G_raster_cmp()
-<P>
-int G_raster_cmp(void *p, *q, RASTER_MAP_TYPE
- data_type) Compares raster vlues p and q. Returns 1 if p > q or only q is
- null value -1 if p < q or only p is null value 0 if p == q or
- p==q==null value
+Compares raster values.
-<P>
-int G_raster_cpy(void *p, void *q, int n, RASTER_MAP_TYPE
- data_type) Copies raster values q into p. If q is null value, sets q to
- null value.
+ - G_raster_cpy()
-<P>
-int G_set_raster_value_c(void *p, CELL val, RASTER_MAP_TYPE
- data_type) If G_is_c_null_value(val) is true, sets p to null value.
- Converts CELL val to data_type (type of p) and stores result in p. Used for
- assigning CELL values to raster cells of any type.
+Copies raster values.
-<P>
-int G_set_raster_value_f(void *p, FCELL val, RASTER_MAP_TYPE
- data_type) If G_is_f_null_value(val) is true, sets p to null value.
- Converts FCELL val to data_type (type of p) and stores result in p. Used for
- assigning FCELL values to raster cells of any type.
+ - G_set_raster_value_c()
-<P>
-int G_set_raster_value_d(void *p, DCELL val, RASTER_MAP_TYPE
- data_type) If G_is_d_null_value(val) is true, sets p to null value.
- Converts DCELL val to data_type (type of p) and stores result in p. Used for
- assigning DCELL values to raster cells of any type.
+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.
-<P>
-CELL G_get_raster_value_c(void *p, RASTER_MAP_TYPE
- data_type) Retrieves the value of type data_type from pointer p,
- converts it to CELL type and returns the result. If null value is stored in
- p, 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_set_raster_value_f()
-<P>
-FCELL G_get_raster_value_f(void *p, RASTER_MAP_TYPE
- data_type) Retrieves the value of type data_type from pointer p,
- converts it to FCELL type and returns the result. If null value is stored in
- p, returns FCELL null value. Used for retreiving FCELL values from raster
- cells of any type.
+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.
-<P>
-DCELL G_get_raster_value_d(void *p, RASTER_MAP_TYPE
- data_type) Retrieves the value of type data_type from pointer p,
- converts it to DCELL type and returns the result. If null value is stored in
- p, returns DCELL null value. Used for retreiving DCELL values from raster
- cells of any type.
+ - G_set_raster_value_d()
-<P>
+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.
+
int G_get_raster_row (int fd, void *rast, int row, RASTER_MAP_TYPE
data_type) If <EM>data_type</EM> is CELL_TYPE, calls
G_get_c_raster_row(fd,(CELL *) rast, row) ;
Modified: grass/trunk/lib/gis/history.c
===================================================================
--- grass/trunk/lib/gis/history.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/history.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,117 +1,95 @@
-
-/**********************************************************************
+/*!
+ * \file gis/history.c
*
- * G_read_history (name, mapset, phist)
- * char *name name of map
- * char *mapset mapset that map belongs to
- * struct History *phist structure to hold history info
+ * \brief GIS Library - History management
*
- * Reads the history information associated with map layer "map"
- * in mapset "mapset" into the structure "phist".
+ * (C) 2001-2009 GRASS Development Team
*
- * returns: 0 if successful
- * -1 on fail
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * note: a warning message is printed if the file is incorrect
- *
- **********************************************************************
- *
- * G_write_history (name, phist)
- * char *name name of map
- * struct History *phist structure holding history info
- *
- * Writes the history information associated with map layer "map"
- * into current from the structure "phist".
- *
- * returns: 0 if successful
- * -1 on fail
- ***********************************************************************
- *
- * G_short_history (name, type, hist)
- * char *name name of cell file
- * char *type type of cell file
- * struct History *hist History structure to be filled in
- *
- * Puts local information like time and date, user's name, map name,
- * and current mapset name into the hist structure
- *
- * NOTE: use G_write_history() to write the structure.
- **********************************************************************
- *
- * G_command_history (hist)
- * struct History *hist History structure to be filled in
- *
- * Appends (parsed) command line to history structure's comments
- *
- * Returns:
- * 0 success
- * 1 failure (history file full, no change)
- * 2 failure (history file full, added as much as we could)
- *
- * NOTE: initialize structure with G_short_history() first.
- * NOTE: use G_write_history() to write the structure.
- **********************************************************************/
+ * \author Original author CERL
+ */
#include <string.h>
#include <grass/gis.h>
#include <grass/glocale.h>
+static void print_history_error(const char *, const char *, FILE *);
/*!
- * \brief read raster history file
+ * \brief Read raster history file
*
- * This routine reads the history file for
- * the raster map <b>name</b> in <b>mapset</b> into the <b>history</b>
- * structure.
- * A diagnostic message is printed and -1 is returned if there is an error
- * reading the history file. Otherwise, 0 is returned.
+ * This routine reads the history file for the raster map <i>name</i>
+ * in <i>mapset</i> into the <i>hist</i> structure.
*
- * \param name
- * \param mapset
- * \param history
- * \return int
+ * A diagnostic message is printed and -1 is returned if there is an
+ * error reading the history file. Otherwise, 0 is returned.
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param hist pointer to History structure which holds history info
+ *
+ * \return -1 on error
+ * \return 0 on success
*/
-
int G_read_history(const char *name, const char *mapset, struct History *hist)
{
FILE *fd;
G_zero(hist, sizeof(struct History));
fd = G_fopen_old("hist", name, mapset);
- if (!fd)
- goto error;
+ if (!fd) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
-
- if (!G_getl(hist->mapid, sizeof(hist->mapid), fd))
- goto error;
+ if (!G_getl(hist->mapid, sizeof(hist->mapid), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->mapid);
- if (!G_getl(hist->title, sizeof(hist->title), fd))
- goto error;
+ if (!G_getl(hist->title, sizeof(hist->title), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->title);
- if (!G_getl(hist->mapset, sizeof(hist->mapset), fd))
- goto error;
+ if (!G_getl(hist->mapset, sizeof(hist->mapset), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->mapset);
- if (!G_getl(hist->creator, sizeof(hist->creator), fd))
- goto error;
+ if (!G_getl(hist->creator, sizeof(hist->creator), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->creator);
- if (!G_getl(hist->maptype, sizeof(hist->maptype), fd))
- goto error;
+ if (!G_getl(hist->maptype, sizeof(hist->maptype), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->maptype);
- if (!G_getl(hist->datsrc_1, sizeof(hist->datsrc_1), fd))
- goto error;
+ if (!G_getl(hist->datsrc_1, sizeof(hist->datsrc_1), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->datsrc_1);
- if (!G_getl(hist->datsrc_2, sizeof(hist->datsrc_2), fd))
- goto error;
+ if (!G_getl(hist->datsrc_2, sizeof(hist->datsrc_2), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->datsrc_2);
- if (!G_getl(hist->keywrd, sizeof(hist->keywrd), fd))
- goto error;
+ if (!G_getl(hist->keywrd, sizeof(hist->keywrd), fd)) {
+ print_history_error(name, mapset, fd);
+ return -1;
+ }
G_ascii_check(hist->keywrd);
hist->edlinecnt = 0;
@@ -122,43 +100,54 @@
hist->edlinecnt++;
}
-
fclose(fd);
+
return 0;
+}
- error:
+void print_history_error(const char *name, const char *mapset, FILE *fd)
+{
if (fd != NULL)
fclose(fd);
- G_warning(_("can't get history information for [%s] in mapset [%s]"),
- name, mapset);
- return -1;
+
+ if (mapset) {
+ G_warning(_("Unable to get history information for <%s@%s>"),
+ name, mapset);
+ }
+ else { /* write */
+ G_warning(_("Unable to write history information for <%s>"), name);
+ }
}
-
/*!
- * \brief write raster history file
+ * \brief Write raster history file
*
* This routine writes the history file for the raster map
- * <b>name</b> in the current mapset from the <b>history</b> 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 <b>history</b> structure should first be initialized
- * using <i>G_short_history.</i>
+ * <i>name</i> in the current mapset from the <i>hist</i> structure.
*
- * \param name
- * \param history
- * \return int
+ * 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 <i>hist</i> structure should first be initialized
+ * using G_short_history().
+ *
+ * \param name map name
+ * \param[out] hist pointer to History structure which holds history info
+ *
+ * \return -1 on error
+ * \return 0 on success
*/
-
int G_write_history(const char *name, struct History *hist)
{
FILE *fd;
int i;
fd = G_fopen_new("hist", name);
- if (!fd)
- goto error;
-
+ if (!fd) {
+ print_history_error(name, NULL, fd);
+ return -1;
+ }
+
fprintf(fd, "%s\n", hist->mapid);
fprintf(fd, "%s\n", hist->title);
fprintf(fd, "%s\n", hist->mapset);
@@ -172,33 +161,25 @@
fprintf(fd, "%s\n", hist->edhist[i]);
fclose(fd);
+
return 0;
-
- error:
- if (fd)
- fclose(fd);
- G_warning(_("can't write history information for [%s]"), name);
- return -1;
}
-
-
/*!
- * \brief initialize history structure
+ * \brief Initialize history structure
*
- * This routine initializes the
- * <b>history</b> structure, recording the date, user, module name and the
- * raster map <b>name</b> structure. The <b>type</b> is an anachronism from
- * earlier versions of GRASS and should be specified as "raster".
- * <b>Note.</b> This routine only initializes the data structure. It does not
- * write the history file.
+ * This routine initializes the <i>hist</i> structure, recording the
+ * date, user, module name and the raster map <i>name</i>
+ * structure. The <i>type</i> is an anachronism from earlier versions
+ * of GRASS and should be specified as "raster".
*
- * \param name
- * \param type
- * \param history
- * \return
+ * <b>Note:</b> This routine only initializes the data structure. It
+ * does not write the history file.
+ *
+ * \param name map name
+ * \param type map type
+ * \param hist pointer to History structure which holds history info
*/
-
void G_short_history(const char *name, const char *type, struct History *hist)
{
strncpy(hist->mapid, G_date(), RECORD_LEN);
@@ -207,7 +188,7 @@
strncpy(hist->creator, G_whoami(), RECORD_LEN);
strncpy(hist->maptype, type, RECORD_LEN);
- sprintf(hist->keywrd, "generated by %s", G_program_name());
+ sprintf(hist->keywrd, _("generated by %s"), G_program_name());
strcpy(hist->datsrc_1, "");
strcpy(hist->datsrc_2, "");
hist->edlinecnt = 0;
@@ -216,39 +197,36 @@
/*!
* \brief Save command line to raster history structure
*
- * This routine takes an existing (run <i>G_short_history first</i>) history
- * structure and adds the command line to the end of the comments array, as
- * cleaned & expanded by the parser.
+ * This routine takes an existing (run G_short_history first() history
+ * structure and adds the command line to the end of the comments
+ * array, as cleaned & expanded by the parser.
*
* History file is limited to [80]x[50], as defined in include/gis.h
*
- * * First version had for loops of [i][j] character assignments and ending
- * nulls, but using the string libraries is cleaner and less bug prone.
- * * Second version had white space detection, intelligent wrapping, and
- * indentation of continued lines, but this proved a pain in the neck for
- * things like r.patch which can have long strings without any
- * parser-acceptable breaks.
- * * This is MK-III, simplified, but that's good: it's cut & paste-able.
+ * - First version had for loops of [i][j] character assignments and ending
+ * nulls, but using the string libraries is cleaner and less bug prone.
+ * - Second version had white space detection, intelligent wrapping, and
+ * indentation of continued lines, but this proved a pain in the neck for
+ * things like r.patch which can have long strings without any
+ * parser-acceptable breaks.
+ * - This is MK-III, simplified, but that's good: it's cut & paste-able.
*
- * NOTE: use G_write_history() to write the structure.
+ * Note: use G_write_history() to write the structure.
*
* Sample Usage:
- *
+ * \code
* struct History history;
* G_short_history(rasterfile, "raster", &history);
* G_command_history(&history);
* G_write_history(rasterfile, &history);
+ * \endcode
*
- * Returns:
- * 0 success
- * 1 failure (history file full, no change)
- * 2 failure (history file full, added as much as we could)
+ * \param hist pointer to History structure which holds history info
*
- * \param history
- * \return int
- *
+ * \return 0 on success
+ * \return 1 on failure (history file full, no change)
+ * \return 2 on failure (history file full, added as much as we could)
*/
-
int G_command_history(struct History *hist)
{
int j, cmdlen;
@@ -258,7 +236,7 @@
cmdlen = strlen(cmdlin);
if (hist->edlinecnt > MAXEDLINES - 2) {
- G_warning(_("Not enough room in history file to record command line."));
+ G_warning(_("Not enough room in history file to record command line"));
return 1;
}
@@ -280,7 +258,7 @@
j += 68;
hist->edlinecnt++;
if (hist->edlinecnt > MAXEDLINES - 2) {
- G_warning(_("Not enough room in history file for command line (truncated)."));
+ G_warning(_("Not enough room in history file for command line (truncated)"));
return 2;
}
}
Modified: grass/trunk/lib/gis/maskfd.c
===================================================================
--- grass/trunk/lib/gis/maskfd.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/maskfd.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,24 +1,20 @@
-
-/**
- * \file maskfd.c
+/*!
+ * \file gis/maskfd.c
*
* \brief GIS Library - Mask functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <grass/gis.h>
#include "G.h"
-
-/**
+/*!
* \brief Test for MASK.
*
* \return -1 if no MASK
Modified: grass/trunk/lib/gis/null_val.c
===================================================================
--- grass/trunk/lib/gis/null_val.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/null_val.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,22 +1,20 @@
-/*
+/*!
+ * \file gis/null_value.c
*
- *****************************************************************************
+ * \brief GIS Library - NULL value management
*
- * MODULE: GRASS gis library
- * AUTHOR(S): Original author unknown - probably CERL
- * Justin Hickey - Thailand - jhickey at hpcc.nectec.or.th
- * PURPOSE: To provide functionality to handle NULL values for data types
- * CELL, FCELL, and DCELL. May need more...
- * COPYRIGHT: (C) 2000 by the GRASS Development Team
+ * To provide functionality to handle NULL values for data types CELL,
+ * FCELL, and DCELL. May need more...
*
- * This program is free software under the GNU General Public
- * License (>=v2). Read the file COPYING that comes with GRASS
- * for details.
+ * (C) 2001-2009 GRASS Development Team
*
- *****************************************************************************/
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author unknown - probably CERL
+ * \author Justin Hickey - Thailand - jhickey at hpcc.nectec.or.th
+ */
-/*============================= Include Files ==============================*/
-
/* System include files */
#include <string.h>
@@ -26,19 +24,16 @@
static void EmbedGivenNulls(void *, char *, RASTER_MAP_TYPE, int);
-/****************************************************************************
-* int EmbedGivenNulls (void *cell, char *nulls, RASTER_MAP_TYPE map_type,
-* int ncols)
-*
-* PURPOSE: To insert null values into a map. Needs more.....
-* INPUT VARS: cell => ??
-* nulls => ??
-* map_type => type of raster - CELL, FCELL, DCELL
-* ncols => ??
-* RETURN VAL: ??
-*****************************************************************************/
-static void EmbedGivenNulls(void *cell, char *nulls, RASTER_MAP_TYPE map_type,
- int ncols)
+/*!
+ \brief To insert null values into a map. Needs more.....
+
+ \param cell raster values
+ \param nulls raster null values
+ \param map_type type of raster - CELL, FCELL, DCELL
+ \param ncols number of columns
+*/
+void EmbedGivenNulls(void *cell, char *nulls, RASTER_MAP_TYPE map_type,
+ int ncols)
{
CELL *c;
FCELL *f;
@@ -65,26 +60,22 @@
break;
default:
- G_warning(_("EmbedGivenNulls: wrong data type!"));
+ G_warning(_("EmbedGivenNulls: wrong data type"));
}
}
}
}
-/*========================== Library Functions =============================*/
+/*!
+ \brief To set one or more raster values to null.
-/****************************************************************************
-* void G__set_null_value (void *rast, int numVals, int null_is_zero,
-* RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: To set one or more raster values to null. It also sets null
-* to zero if null_is_zero is TRUE.
-* INPUT VARS: rast => pointer to values to set to null
-* numVals => number of values to set to null
-* null_is_zero => flag to indicate if NULL = 0
-* data_type => type of raster - CELL, FCELL, DCELL
-* RETURN VAL: none
-*****************************************************************************/
+ It also sets null to zero if null_is_zero is TRUE.
+
+ \param rast pointer to values to set to null
+ \param numVals number of values to set to null
+ \param null_is_zero flag to indicate if NULL = 0
+ \param data_type type of raster - CELL, FCELL, DCELL
+*/
void G__set_null_value(void *rast, int numVals, int null_is_zero,
RASTER_MAP_TYPE data_type)
{
@@ -96,15 +87,13 @@
G_set_null_value(rast, numVals, data_type);
}
-/****************************************************************************
-* void G_set_null_value (void *buf, int numVals, RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: To set one or more raster values to null.
-* INPUT VARS: buf => pointer to values to set to null
-* numVals => number of values to set to null
-* data_type => type of raster - CELL, FCELL, DCELL
-* RETURN VAL: none
-*****************************************************************************/
+/*!
+ \brief To set one or more raster values to null.
+
+ \param buf pointer to values to set to null
+ \param numVals number of values to set to null
+ \param data_type type of raster - CELL, FCELL, DCELL
+*/
void G_set_null_value(void *buf, int numVals, RASTER_MAP_TYPE data_type)
{
switch (data_type) {
@@ -125,14 +114,12 @@
}
}
-/****************************************************************************
-* void G_set_c_null_value (CELL *cellVals, int numVals)
-*
-* PURPOSE: To set a number of CELL raster values to NULL.
-* INPUT VARS: cellVals => pointer to CELL values to set to null
-* numVals => number of values to set to null
-* RETURN VAL: none
-*****************************************************************************/
+/*!
+ \brief To set a number of CELL raster values to NULL.
+
+ \param cellVals pointer to CELL values to set to null
+ \param numVals number of values to set to null
+*/
void G_set_c_null_value(CELL *cellVals, int numVals)
{
int i; /* counter */
@@ -141,14 +128,12 @@
cellVals[i] = (int) 0x80000000;
}
-/****************************************************************************
-* void G_set_f_null_value (FCELL *fcellVals, int numVals)
-*
-* PURPOSE: To set a number of FCELL raster values to NULL.
-* INPUT VARS: fcellVals => pointer to FCELL values to set to null
-* numVals => number of values to set to null
-* RETURN VAL: none
-*****************************************************************************/
+/*!
+ \brief To set a number of FCELL raster values to NULL.
+
+ \param fcellVals pointer to FCELL values to set to null
+ \param numVals number of values to set to null
+*/
void G_set_f_null_value(FCELL *fcellVals, int numVals)
{
static const unsigned char null_bits[4] = {
@@ -159,14 +144,12 @@
memcpy(&fcellVals[i], null_bits, sizeof(null_bits));
}
-/****************************************************************************
-* void G_set_d_null_value (DCELL *dcellVals, int numVals)
-*
-* PURPOSE: To set a number of DCELL raster values to NULL.
-* INPUT VARS: dcellVals => pointer to DCELL values to set to null
-* numVals => number of values to set to null
-* RETURN VAL: none
-*****************************************************************************/
+/*!
+ \brief To set a number of DCELL raster values to NULL.
+
+ \param dcellVals pointer to DCELL values to set to null
+ \param numVals number of values to set to null
+*/
void G_set_d_null_value(DCELL *dcellVals, int numVals)
{
static const unsigned char null_bits[8] = {
@@ -177,27 +160,19 @@
memcpy(&dcellVals[i], null_bits, sizeof(null_bits));
}
-/****************************************************************************
-* int G_is_null_value (void *rast, RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: To check if a raster value is set to NULL
-* INPUT VARS: rast => raster value to check
-* data_type => type of raster - CELL, FCELL, DCELL
-* RETURN VAL: TRUE if raster value is NULL FALSE otherwise
-*****************************************************************************/
-
/*!
- * \brief
- *
- * If the <em>data_type</em> is CELL_TYPE, calls G_is_c_null_value ((CELL *) rast);
- * If the <em>data_type</em> is FCELL_TYPE, calls G_is_f_null_value ((FCELL *) rast);
- * If the <em>data_type</em> is DCELL_TYPE, calls G_is_d_null_value ((DCELL *) rast);
- *
- * \param rast
- * \param data_type
- * \return int
- */
+ \brief To check if a raster value is set to NULL
+ - If the <em>data_type</em> is CELL_TYPE, calls G_is_c_null_value()
+ - If the <em>data_type</em> is FCELL_TYPE, calls G_is_f_null_value()
+ - If the <em>data_type</em> is DCELL_TYPE, calls G_is_d_null_value()
+
+ \param rast raster value to check
+ \param data_type type of raster - CELL, FCELL, DCELL
+
+ \return TRUE if raster value is NULL
+ \return FALSE otherwise
+ */
int G_is_null_value(const void *rast, RASTER_MAP_TYPE data_type)
{
switch (data_type) {
@@ -216,221 +191,141 @@
}
}
-/****************************************************************************
-*
-* int G_is_c_null_value (CELL *cellVal)
-*
-* PURPOSE: To check if a CELL raster value is set to NULL
-* INPUT VARS: cellVal => CELL raster value to check
-* RETURN VAL: TRUE if CELL raster value is NULL FALSE otherwise
-*****************************************************************************/
-
/*!
- * \brief
- *
- * Returns 1 if <em>cell</em> is NULL, 0 otherwise. This will test if the
- * value <em>cell</em> is the largest <tt>int</tt>.
- *
- * \param cell
- * \return int
- */
+ \brief To check if a CELL raster value is set to NULL
+ Returns 1 if <em>cell</em> is NULL, 0 otherwise. This will test if the
+ value <em>cell</em> is the largest <tt>int</tt>.
+
+ \param cellVal CELL raster value to check
+
+ \return TRUE if CELL raster value is NULL
+ \return FALSE otherwise
+*/
int G_is_c_null_value(const CELL * cellVal)
{
/* Check if the CELL value matches the null pattern */
return *cellVal == (CELL) 0x80000000;
}
-/****************************************************************************
-*
-* int G_is_f_null_value (FCELL *fcellVal)
-*
-* PURPOSE: To check if a FCELL raster value is set to NULL
-* INPUT VARS: fcellVal => FCELL raster value to check
-* RETURN VAL: TRUE if FCELL raster value is NULL FALSE otherwise
-*****************************************************************************/
-
/*!
- * \brief
- *
- * Returns 1 if <em>fcell</em>
- * is NULL, 0 otherwise. This will test if the value <em>fcell</em> is a NaN. 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
- *
- * \param fcell
- * \return int
- */
+ \brief To check if a FCELL raster value is set to NULL
+ Returns 1 if <em>fcell</em> is NULL, 0 otherwise. This will test if
+ the value <em>fcell</em> is a NaN. 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
+
+ \param fcellVal FCELL raster value to check
+
+ \return TRUE if FCELL raster value is NULL
+ \return FALSE otherwise
+*/
int G_is_f_null_value(const FCELL * fcellVal)
{
return *fcellVal != *fcellVal;
}
-/****************************************************************************
-*
-* int G_is_d_null_value (DCELL *dcellVal)
-*
-* PURPOSE: To check if a DCELL raster value is set to NULL
-* INPUT VARS: dcellVal => DCELL raster value to check
-* RETURN VAL: TRUE if DCELL raster value is NULL FALSE otherwise
-*****************************************************************************/
-
/*!
- * \brief
- *
- * Returns 1 if <em>dcell</em> is
- * NULL, 0 otherwise. This will test if the value <em>dcell</em> is a NaN. Same
- * test as in <tt>G_is_f_null_value()</tt>.
- *
- * \param dcell
- * \return int
- */
+ \brief To check if a DCELL raster value is set to NULL
+ Returns 1 if <em>dcell</em> is NULL, 0 otherwise. This will test if
+ the value <em>dcell</em> is a NaN. Same test as in
+ G_is_f_null_value().
+
+ \param dcellVal DCELL raster value to check
+
+ \return TRUE if DCELL raster value is NULL
+ \return FALSE otherwise
+*/
int G_is_d_null_value(const DCELL * dcellVal)
{
return *dcellVal != *dcellVal;
}
-/****************************************************************************
-*
-* int G_insert_null_values (void *rast, char *null_row, int ncols,
-* RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: To insert null values into a map. Needs more.....
-* INPUT VARS: rast => ??
-* null_row => ??
-* ncols => ??
-* data_type => type of raster - CELL, FCELL, DCELL
-* RETURN VAL: ??
-*****************************************************************************/
-
/*!
- * \brief Insert NULL value
- *
- * If the <em>data_type</em> is
- * CELL_TYPE, calls G_insert_c_null_values ((CELL *) rast, flags, count);
- * If the <em>data_type</em> is FCELL_TYPE, calls G_insert_f_null_values
- * ((FCELL *) rast, flags, count);
- * If the <em>data_type</em> is DCELL_TYPE, calls G_insert_d_null_values
- * ((DCELL *) rast, flags, count);
- *
- * \param rast
- * \param flags
- * \param count
- * \param data_type
- * \return
- */
+ \brief To insert null values into a map.
+ - If the <em>data_type</em> is CELL_TYPE, calls G_insert_c_null_values()
+ - If the <em>data_type</em> is FCELL_TYPE, calls G_insert_f_null_values()
+ - If the <em>data_type</em> is DCELL_TYPE, calls G_insert_d_null_values()
+
+ \param rast pointer raster values
+ \param null_row null row
+ \param ncols number of columns
+ \param data_type type of raster - CELL, FCELL, DCELL
+ */
void G_insert_null_values(void *rast, char *null_row, int ncols,
RASTER_MAP_TYPE data_type)
{
EmbedGivenNulls(rast, null_row, data_type, ncols);
}
-/****************************************************************************
-*
-* int G_insert_c_null_values (CELL *cellVal, char *null_row, int ncols)
-*
-* PURPOSE: To insert null values into a CELL map. Needs more.....
-* INPUT VARS: cellVal => ??
-* null_row => ??
-* ncols => ??
-* RETURN VAL: ??
-*****************************************************************************/
-
/*!
- * \brief Insert CELL NULL value
- *
- * For each of the <em>count</em> <em>flags</em>
- * which is true(!=0), set the corresponding <em>cell</em> to the NULL value.
- *
- * \param cell
- * \param flags
- * \param count
- * \return
- */
+ \brief To insert null values into an integer raster map (CELL)
+ For each of the <em>count</em> <em>flags</em> which is true(!=0),
+ set the corresponding <em>cell</em> to the NULL value.
+
+ \param rast pointer raster values
+ \param null_row null row
+ \param ncols number of columns
+*/
void G_insert_c_null_values(CELL * cellVal, char *null_row, int ncols)
{
EmbedGivenNulls((void *)cellVal, null_row, CELL_TYPE, ncols);
}
-/****************************************************************************
-*
-* int G_insert_f_null_values (FCELL *fcellVal, char *null_row, int ncols)
-*
-* PURPOSE: To insert null values into a FCELL map. Needs more.....
-* INPUT VARS: fcellVal => ??
-* null_row => ??
-* ncols => ??
-* RETURN VAL: ??
-*****************************************************************************/
-
/*!
- * \brief Insert FCELL NULL value
- *
- * For each of the <em>count</em> <em>flags</em>
- * which is true(!=0), set the corresponding <em>fcell</em> to the NULL value.
- *
- * \param fcell
- * \param flags
- * \param count
- * \return
- */
+ \brief To insert null values into an floating-point raster map (FCELL)
+ \param fcellVal pointer raster values
+ \param null_row null row
+ \param ncols number of columns
+*/
void G_insert_f_null_values(FCELL * fcellVal, char *null_row, int ncols)
{
EmbedGivenNulls((void *)fcellVal, null_row, FCELL_TYPE, ncols);
}
-/****************************************************************************
-*
-* int G_insert_d_null_values (DCELL *dcellVal, char *null_row, int ncols)
-*
-* PURPOSE: To insert null values into a DCELL map. Needs more.....
-* INPUT VARS: dcellVal => ??
-* null_row => ??
-* ncols => ??
-* RETURN VAL: ??
-*****************************************************************************/
-
/*!
- * \brief Insert DCELL NULL value
- *
- * For each for the <em>count</em> <em>flag</em>
- * which is true(!=0), set the corresponding <em>dcell</em> to the NULL value.
- *
- * \param dcell
- * \param flags
- * \param count
- * \return
- */
+ \brief To insert null values into an floating-point raster map (FCELL)
+ For each for the <em>count</em> <em>flag</em> which is true(!=0), set
+ the corresponding <em>dcell</em> to the NULL value.
+
+ \param dcellVal pointer raster values
+ \param null_row null row
+ \param ncols number of columns
+*/
void G_insert_d_null_values(DCELL * dcellVal, char *null_row, int ncols)
{
EmbedGivenNulls((void *)dcellVal, null_row, DCELL_TYPE, ncols);
}
-/****************************************************************************
-* int G__check_null_bit (unsigned char *flags, int bit_num, int n)
-*
-* PURPOSE: To...
-* INPUT VARS: flags => ??
-* bit_num => ??
-* n => ??
-* RETURN VAL: ??
-*****************************************************************************/
+/*!
+ \brief Check NULL
+
+ Note: Only for internal use.
+
+ \param flags ?
+ \param bit_num ?
+ \param n ?
+
+ \return -1 on error
+*/
int G__check_null_bit(const unsigned char *flags, int bit_num, int n)
{
int ind;
@@ -442,9 +337,9 @@
/* find how many unsigned chars the buffer with bit_num+1 (counting from 0
has and subtract 1 to get unsigned char index */
if (ind > G__null_bitstream_size(n) - 1) {
- G_warning("G__check_null_bit: can't access index %d. "
+ G_warning("G__check_null_bit: Unable to access index %d. "
"Size of flags is %d (bit # is %d)",
- ind, G__null_bitstream_size(n) - 1, bit_num);
+ ind, G__null_bitstream_size(n) - 1, bit_num);
return -1;
}
@@ -453,20 +348,23 @@
return ((flags[ind] & ((unsigned char)1 << offset)) != 0);
}
-/****************************************************************************
-* int G__set_flags_from_01_random (char *zero_ones, unsigned char *flags,
-* int col, int n, int ncols)
-*
-* PURPOSE: given array of 0/1 of length n starting from column col
-* set the corresponding bits of flags; total number of bits
-* in flags is ncols
-* INPUT VARS: zero_ones => ??
-* flags => ??
-* col => ??
-* n => ??
-* ncols => ??
-* RETURN VAL: ??
-*****************************************************************************/
+/*!
+ \brief Given array of 0/1 of length n starting from column.
+
+ Note: Only for internal use.
+
+ Given array of 0/1 of length n starting from column set the
+ corresponding bits of flags; total number of bits in flags is ncols.
+
+ \param zero_ones
+ \param flags
+ \param col
+ \param n
+ \param ncols
+
+ \return 0
+ \return 1
+*/
int G__set_flags_from_01_random(const char *zero_ones, unsigned char *flags,
int col, int n, int ncols)
{
@@ -506,15 +404,15 @@
return 1;
}
-/****************************************************************************
-* int G__convert_01_flags (char *zero_ones, unsigned char *flags, int n)
-*
-* PURPOSE: To...
-* INPUT VARS: zero_ones => ??
-* flags => ??
-* n => ??
-* RETURN VAL: ??
-*****************************************************************************/
+/*!
+ \brief ?
+
+ Note: Only for internal use.
+
+ \param zero_ones
+ \param flags
+ \param n
+*/
void G__convert_01_flags(const char *zero_ones, unsigned char *flags, int n)
{
unsigned char *v;
@@ -543,15 +441,15 @@
}
}
-/****************************************************************************
-* int G__convert_flags_01 (char *zero_ones, unsigned char *flags, int n)
-*
-* PURPOSE: To...
-* INPUT VARS: zero_ones => ??
-* flags => ??
-* n => ??
-* RETURN VAL: ??
-*****************************************************************************/
+/*!
+ \brief ?
+
+ Note: Only for internal use.
+
+ \param zero_ones
+ \param flags
+ \param n
+ */
void G__convert_flags_01(char *zero_ones, const unsigned char *flags, int n)
{
const unsigned char *v;
@@ -577,14 +475,14 @@
}
}
-/****************************************************************************
-* int G__init_null_bits (unsigned char *flags, int cols)
-*
-* PURPOSE: To...
-* INPUT VARS: flags => ??
-* cols => ??
-* RETURN VAL: ??
-*****************************************************************************/
+/*!
+ \brief ?
+
+ Note: Only for internal use.
+
+ \param flags
+ \param cols
+ */
void G__init_null_bits(unsigned char *flags, int cols)
{
unsigned char *v;
Modified: grass/trunk/lib/gis/opencell.c
===================================================================
--- grass/trunk/lib/gis/opencell.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/opencell.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,9 +1,9 @@
/*!
* \file gis/opencell.c
*
- * \brief GIS Library - open raster (cell) file functions
+ * \brief GIS Library - Open raster file
*
- * (C) 1999-2008 by the GRASS Development Team
+ * (C) 1999-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public
* License (>=v2). Read the file COPYING that comes with GRASS
@@ -24,6 +24,8 @@
#include <grass/gis.h>
#include <grass/glocale.h>
+#define FORMAT_FILE "f_format"
+
static struct fileinfo *new_fileinfo(int fd)
{
int oldsize = G__.fileinfo_count;
@@ -52,19 +54,24 @@
/*!
- * \brief
+ * \brief Open raster file
*
- * 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
- * <tt>G_get_c_raster_row()</tt>, et. al., by reading the quantization rules for
- * the map using <tt>G_read_quant()</tt>.
- * 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().
+ * 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().
*
- * \return int
+ * \param name map name
+ * \param open_mode mode
+ * \param map_type map type (CELL, FCELL, DCELL)
+ *
+ * \return open file descriptor ( >= 0) if successful
+ * \return negative integer if error
*/
static int G__open_raster_new(const char *name, int open_mode,
@@ -83,10 +90,10 @@
GRASS users expect that all raster maps will be resampled into the
current region, the resampling index for the raster map is prepared
by this routine after the file is opened. The resampling is based on
- the active module region.\remarks{See also The_Region.} Preparation
- required for reading the various raster file formats\remarks{See
+ the active module region (see also \ref The_Region}. Preparation
+ required for reading the various raster file formats (see \ref
Raster_File_Format for an explanation of the various raster file
- formats.} is also done.
+ formats) is also done.
Diagnostics: warning message printed if open fails.
@@ -118,9 +125,8 @@
return fd;
}
-/*!
- \brief Lower level function, open cell files, supercell
- files, and the MASK file.
+/*! \brief Lower level function, open cell files, supercell files,
+ and the MASK file.
Actions:
- opens the named cell file, following reclass reference if
@@ -128,15 +134,13 @@
- creates the required mapping between the data and the window
for use by the get_map_row family of routines.
- Diagnostics:
- Errors other than actual open failure will cause a diagnostic to be
- delivered thru G_warning() open failure messages are left to the
- calling routine since the masking logic will want to issue a different
- warning.
+ Diagnostics: Errors other than actual open failure will cause a
+ diagnostic to be delivered thru G_warning() open failure messages
+ are left to the calling routine since the masking logic will want to
+ issue a different warning.
- Note:
- This routine does NOT open the MASK layer. If it did we would get
- infinite recursion. This routine is called to open the mask by
+ Note: This routine does NOT open the MASK layer. If it did we would
+ get infinite recursion. This routine is called to open the mask by
G__check_for_auto_masking() which is called by G_open_cell_old().
\param name map name
@@ -344,8 +348,6 @@
return fd;
}
-/*****************************************************************/
-
/*!
\brief Opens a new cell file in a database (compressed)
@@ -400,8 +402,6 @@
otherwise set flag=0. Applies to subsequent opens.
\param flag flag indicator
-
- \return 0
*/
void G_want_histogram(int flag)
{
@@ -412,15 +412,13 @@
\brief Sets the format for subsequent opens on new integer cell files
(uncompressed and random only).
- Warning: subsequent put_row calls will only write n+1 bytes
- per cell. If the data requires more, the cell file
- will be written incorrectly (but with n+1 bytes per cell)
+ Warning: subsequent put_row calls will only write n+1 bytes per
+ cell. If the data requires more, the cell file will be written
+ incorrectly (but with n+1 bytes per cell)
When writing float map: format is -1
\param n format
-
- \return 0
*/
void G_set_cell_format(int n)
/* sets the format for integer raster map */
@@ -716,10 +714,10 @@
\brief Set raster map floating-point data format.
This controls the storage type for floating-point maps. It affects
- subsequent calls to G_open_fp_map_new(). The <em>type</em>
- must be one of FCELL_TYPE (float) or DCELL_TYPE
- (double). The use of this routine by applications is discouraged
- since its use would override user preferences.
+ subsequent calls to G_open_fp_map_new(). The <i>type</i> must be
+ one of FCELL_TYPE (float) or DCELL_TYPE (double). The use of this
+ routine by applications is discouraged since its use would override
+ user preferences.
\param type raster data type
@@ -739,10 +737,6 @@
}
}
-
-#define FORMAT_FILE "f_format"
-
-
/*!
\brief Check if raster map is floating-point
@@ -762,7 +756,7 @@
xmapset = G_find_cell2(name, mapset);
if (!xmapset) {
- G_warning(_("Unable to find '%s' in '%s'"), name, mapset);
+ G_warning(_("Unable to find <%s@%s>"), name, mapset);
return -1;
}
G__file_name(path, "fcell", name, xmapset);
@@ -779,7 +773,7 @@
\brief Determine raster data type
Determines if the raster map is floating point or integer. Returns
- DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
+ DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
integer maps, -1 if error has occured
\param name map name
@@ -850,7 +844,7 @@
xmapset = G_find_cell2(name, mapset);
if (!xmapset) {
- G_warning(_("Unable to find '%s' in '%s'"), name, mapset);
+ G_warning(_("Unable to find <%s@%s>"), name, mapset);
return -1;
}
G__file_name_misc(path, "cell_misc", FORMAT_FILE, name, xmapset);
Modified: grass/trunk/lib/gis/progrm_nme.c
===================================================================
--- grass/trunk/lib/gis/progrm_nme.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/progrm_nme.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,40 +1,42 @@
-
-/**********************************************************************
+/*!
+ * \file gis/progrm_nme.c
*
- * char *
- * G_program_name()
+ * \brief GIS Library - Program name
*
- * returns the current program name
+ * (C) 2001-2009 by the GRASS Development Team
*
- **********************************************************************
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * G_set_program_name(name)
- * char *name
- *
- * program name set to name (name will be returned by G_program_name
- *
- **********************************************************************/
+ * \author Original author CERL
+ */
+
#include <string.h>
#include <grass/gis.h>
static const char *name = "?";
-
/*!
- * \brief return module name
+ * \brief Return module name
*
- * Routine returns the name
- * of the module as set by the call to <i>G_gisinit.</i>
+ * Routine returns the name of the module as set by the call to
+ * G_gisinit().
*
- * \param ~
- * \return char *
+ * \return pointer to string with program name
*/
-
const char *G_program_name(void)
{
return name;
}
+/*!
+ \brief Set program name
+
+ Program name set to name (name will be returned by
+ G_program_name*())
+
+ \param s program name
+*/
void G_set_program_name(const char *s)
{
int i;
Modified: grass/trunk/lib/gis/put_cellhd.c
===================================================================
--- grass/trunk/lib/gis/put_cellhd.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/put_cellhd.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,27 +1,37 @@
-
-/**********************************************************************
+/*!
+ * \file gis/put_cellhd.c
*
- * G_put_cellhd (name, cellhd)
- * char *name name of map
- * struct Cell_head *cellhd structure holding cell header info
+ * \brief GIS Library - Write raster header.
*
- * Writes the cell file header information associated with map layer "map"
- * into current mapset from the structure "cellhd".
+ * (C) 2001-2009 by the GRASS Development Team
*
- * returns: 0 if successful
- * -1 on fail
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- ***********************************************************************/
+ * \author Original author CERL
+ */
#include <grass/gis.h>
#include <grass/glocale.h>
+/*!
+ \brief Writes the raster file header.
+
+ Writes the cell file header information associated with map layer "map"
+ into current mapset from the structure "cellhd".
+
+ \param name name of map
+ \param cellhd structure holding cell header info
+
+ \return 0 on success
+ \return -1 on failure
+*/
int G_put_cellhd(const char *name, struct Cell_head *cellhd)
{
FILE *fd;
if (!(fd = G_fopen_new("cellhd", name))) {
- G_warning(_("Unable to create header file for [%s]"), name);
+ G_warning(_("Unable to create header file for <%s>"), name);
return -1;
}
Modified: grass/trunk/lib/gis/range.c
===================================================================
--- grass/trunk/lib/gis/range.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/range.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,137 +1,70 @@
-
-/**********************************************************************
+/*!
+ * \file gis/range.c
*
- * G_read_range (name, mapset, range)
- * const char *name name of map
- * const char *mapset mapset that map belongs to
- * struct Range *range struct to hold range info
+ * \brief GIS Library - Raster range file management
*
- * Reads the data range information associated with map layer "map"
- * in mapset "mapset"
+ * (C) 2001-2009 GRASS Development Team
*
- * returns: 1 if successful
- * 2 range is empty
- * 3 map is fp: get range from quant rules
- * -1 on fail
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * note: a warning message is printed if the file is missing or incorrect
- *
- **********************************************************************
- *
- * G_read_fp_range (name, mapset, range)
- * const char *name name of map
- * const char *mapset mapset that map belongs to
- * struct FPRange *range struct to hold range info
- *
- * Reads the fp data range information associated with map layer "map"
- * in mapset "mapset" . If map is integer, the integer range is read
- * and the max and min values are casted to doubles and copied to FPRange
- *
- * returns: 1 if successful
- * 2 range is empty
- * -1 on fail
- *
- * note: a warning message is printed if the file is missing or incorrect
- *
- **********************************************************************
- *
- * G_write_[fp_]range (name, range)
- * const char *name name of map
- * struct [FP]Range *range struct holding range info
- *
- * Writes the range information associated with map layer "map"
- *
- * returns: 0 if successful
- * -1 on fail (or if the map is fp )
- *
- **********************************************************************
- *
- * G_init_[fp_]range (range)
- * struct [FP]Range *range struct for range info
- *
- * initializes range structure for call to G_update_[fp_]range()
- *
- **********************************************************************
- *
- * G_construct_default_range (range)
- * struct Range *range struct for range info
- *
- * returns 1 and range is set to DEFAULT_CELL_MIN
- * and DEFAULT_SET_MAX, otherwise returns -1
- *
- **********************************************************************
- *
- * G_update_[fp_]range (cat, range)
- * DCELL cat cat to be factored into range
- * struct [FP]Range *range struct for range info
- **********************************************************************
- *
- * G_row_update_[fp_]range (rast, range, data_type)
- * void *rast raster row to be factored into range
- * struct [FP]Range *range struct for range info
- * RASTER_MAP_TYPE data_type;
- **********************************************************************
- *
- * G_get_[fp_]range_min_max (range, min, max)
- * struct [FP]Range *range;
- * [D]CELL *min, *max;
- **********************************************************************/
+ * \author Original author CERL
+ */
#include <unistd.h>
#include <rpc/types.h> /* need this for sgi */
#include <rpc/xdr.h>
#include "G.h"
#include <grass/glocale.h>
+
#define DEFAULT_CELL_MIN 1
#define DEFAULT_CELL_MAX 255
-/*-------------------------------------------------------------------------*/
+/*!
+ \brief Remove floating-point range
-/*-------------------------------------------------------------------------*/
+ Note: For internal use only.
-/* range functions for type "Range" */
-
-/*-------------------------------------------------------------------------*/
+ \param name map name
+*/
void G__remove_fp_range(const char *name)
{
G_remove_misc("cell_misc", "f_range", name);
}
-
/*!
- * \brief
+ * \brief Construct default range
*
- * Sets the integer range <em>r</em> to [1,255]
+ * Sets the integer range to [1,255]
*
- * \param r
- * \return
+ * \param[out] r pointer to Range structure which holds range info
*/
-
void G_construct_default_range(struct Range *range)
{
G_update_range(DEFAULT_CELL_MIN, range);
G_update_range(DEFAULT_CELL_MAX, range);
}
-
/*!
- * \brief
+ * \brief Read floating-point 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 <em>r</em>,
- * 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 <tt>G_construct_default_range()</tt>.
+ * Read the floating point range file <i>drange</i>. This file is
+ * written in binary using XDR format.
*
- * \param r
- * \param name
- * \param mapset
- * \return int
+ * 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().
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param drange pointer to FPRange structure which holds fp range
+ *
+ * \return 1 on success
+ * \return 2 range is empty
+ * \return -1 on error
*/
-
int G_read_fp_range(const char *name, const char *mapset,
struct FPRange *drange)
{
@@ -163,9 +96,12 @@
if (G_find_file2_misc("cell_misc", "f_range", name, mapset)) {
fd = G_open_old_misc("cell_misc", "f_range", name, mapset);
- if (fd < 0)
- goto error;
-
+ if (fd < 0) {
+ G_warning(_("Unable to read fp range file for <%s@%s>"),
+ name, mapset);
+ return -1;
+ }
+
if (read(fd, xdr_buf, 2 * XDR_DOUBLE_NBYTES) != 2 * XDR_DOUBLE_NBYTES)
return 2;
@@ -173,52 +109,49 @@
XDR_DECODE);
/* if the f_range file exists, but empty */
- if (!xdr_double(&xdr_str, &dcell1) || !xdr_double(&xdr_str, &dcell2))
- goto error;
+ if (!xdr_double(&xdr_str, &dcell1) || !xdr_double(&xdr_str, &dcell2)) {
+ if (fd)
+ close(fd);
+ G_warning(_("Unable to read fp range file for <%s@%s>"),
+ name, mapset);
+ return -1;
+ }
G_update_fp_range(dcell1, drange);
G_update_fp_range(dcell2, drange);
close(fd);
- return 1;
}
-
- error:
- if (fd > 0)
- close(fd);
- G_warning(_("can't read f_range file for [%s in %s]"),
- name, mapset);
- return -1;
+
+ return 1;
}
-/*-------------------------------------------------------------------------*/
-
-
/*!
- * \brief read raster range
+ * \brief Read raster range (CELL)
*
- * This routine reads the range information for the
- * raster map <b>name</b> in <b>mapset</b> into the <b>range</b>
- * structure.
+ * This routine reads the range information for the raster map
+ * <i>name</i> in <i>mapset</i> 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.
*
- * 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 <tt>G_construct_default_range()</tt>.
+ * 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().
*
- * \param name
- * \param mapset
- * \param range
+ * \param name map name
+ * \param mapset mapset name
+ * \param range pointer to Range structure which holds range info
*
- * \return int
+ * \return -1 on error
+ * \return 1 on success
+ * \return 2 if range is empty
+ * \return 3 if raster map is floating-point, get range from quant rules
*/
-
int G_read_range(const char *name, const char *mapset, struct Range *range)
{
FILE *fd;
@@ -236,8 +169,7 @@
DCELL dmin, dmax;
if (G_read_quant(name, mapset, &quant) < 0) {
- G_warning(_("G_read_range(): can't read quant rules"
- " for fp map %s@%s"),
+ G_warning(_("Unable to read quant rules for raster map <%s@%s>"),
name, mapset);
return -1;
}
@@ -273,9 +205,12 @@
if (G_find_file2_misc("cell_misc", "range", name, mapset)) {
fd = G_fopen_old_misc("cell_misc", "range", name, mapset);
- if (!fd)
- goto error;
-
+ if (!fd) {
+ G_warning(_("Unable to read range file for <%s@%s>"),
+ name, mapset);
+ return -1;
+ }
+
/* if range file exists but empty */
if (!fgets(buf, sizeof buf, fd))
return 2;
@@ -284,9 +219,15 @@
count = sscanf(buf, "%d%d%d%d", &x[0], &x[1], &x[2], &x[3]);
/* if wrong format */
- if (count <= 0)
- goto error;
-
+ if (count <= 0) {
+ if (fd)
+ fclose(fd);
+
+ G_warning(_("Unable to read range file for <%s@%s>"),
+ name, mapset);
+ return -1;
+ }
+
for (n = 0; n < count; n++) {
/* if count==4, the range file is old (4.1) and 0's in it
have to be ignored */
@@ -294,81 +235,73 @@
G_update_range((CELL) x[n], range);
}
fclose(fd);
- return 1;
}
- error:
- if (fd)
- fclose(fd);
- G_warning(_("can't read range file for [%s in %s]"),
- name, mapset);
- return -1;
+ return 1;
}
-/*-------------------------------------------------------------------------*/
-
-
/*!
- * \brief write raster range file
+ * \brief Write raster range file
*
* This routine writes the range information for the raster map
- * <b>name</b> in the current mapset from the <b>range</b> structure.
- * A diagnostic message is printed and -1 is returned if there is an error
- * writing the range file. Otherwise, 0 is returned.
+ * <i>name</i> 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.
*
* 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.
*
- * \param name
- * \param range
+ * \param name map name
+ * \param range pointer to Range structure which holds range info
*
- * \return int
+ * \return -1 on error (or raster map is floating-point)
+ * \return 0 on success
*/
-
int G_write_range(const char *name, const struct Range *range)
{
FILE *fd;
- if (G_raster_map_type(name, G_mapset()) != CELL_TYPE)
- goto error;
+ if (G_raster_map_type(name, G_mapset()) != CELL_TYPE) {
+ G_remove_misc("cell_misc", "range", name); /* remove the old file with this name */
+ G_warning(_("Unable to write range file for <%s>"),
+ name);
+ return -1;
+ }
fd = G_fopen_new_misc("cell_misc", "range", name);
- if (!fd)
- goto error;
+ if (!fd) {
+ G_remove_misc("cell_misc", "range", name); /* remove the old file with this name */
+ G_warning(_("Unable to write range file for <%s>"),
+ name);
+ return -1;
+ }
- if (range->first_time)
- /* if range hasn't been updated */
- {
+ /* if range hasn't been updated */
+ if (range->first_time) {
fclose(fd);
return 0;
}
+
fprintf(fd, "%ld %ld\n", (long)range->min, (long)range->max);
fclose(fd);
- return 0;
- error:
- G_remove_misc("cell_misc", "range", name); /* remove the old file with this name */
- G_warning(_("can't write range file for [%s in %s]"),
- name, G_mapset());
- return -1;
+ return 0;
}
-/*-------------------------------------------------------------------------*/
-
-
/*!
- * \brief
+ * \brief Write raster range file (floating-point)
*
- * 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.
+ * 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>range</em>, an empty <tt>f_range</tt> file is created.
*
- * \param r
- * \return
+ * \param name map name
+ * \param range pointer to FPRange which holds fp range info
+ *
+ * \return 0 on success
+ * \return -1 on error
*/
-
int G_write_fp_range(const char *name, const struct FPRange *range)
{
int fd;
@@ -376,12 +309,15 @@
XDR xdr_str;
fd = G_open_new_misc("cell_misc", "f_range", name);
- if (fd < 0)
- goto error;
-
- if (range->first_time)
- /* if range hasn't been updated, write empty file meaning Nulls */
- {
+ if (fd < 0) {
+ G_remove_misc("cell_misc", "f_range", name);
+ G_warning(_("Unable to write range file for <%s>"),
+ name);
+ return -1;
+ }
+
+ /* if range hasn't been updated, write empty file meaning Nulls */
+ if (range->first_time) {
close(fd);
return 0;
}
@@ -389,40 +325,38 @@
xdrmem_create(&xdr_str, xdr_buf, (u_int) XDR_DOUBLE_NBYTES * 2,
XDR_ENCODE);
- if (!xdr_double(&xdr_str, (double *)&(range->min)))
- goto error;
- if (!xdr_double(&xdr_str, (double *)&(range->max)))
- goto error;
-
+ if (!xdr_double(&xdr_str, (double *)&(range->min))) {
+ G_remove_misc("cell_misc", "f_range", name);
+ G_warning(_("Unable to write range file for <%s>"),
+ name);
+ return -1;
+ }
+
+ if (!xdr_double(&xdr_str, (double *)&(range->max))) {
+ G_remove_misc("cell_misc", "f_range", name);
+ G_warning(_("Unable to write range file for <%s>"),
+ name);
+ return -1;
+ }
+
write(fd, xdr_buf, XDR_DOUBLE_NBYTES * 2);
close(fd);
- return 0;
- error:
- G_remove_misc("cell_misc", "f_range", name); /* remove the old file with this name */
- G_warning(_("can't write range file for [%s in %s]"),
- name, G_mapset());
- return -1;
+ return 0;
}
-/*-------------------------------------------------------------------------*/
-
-
/*!
- * \brief update range structure
+ * \brief Update range structure (CELL)
*
- * Compares the <b>cat</b> value with the minimum and maximum
- * values in the <b>range</b> structure, modifying the range if <b>cat</b>
+ * Compares the <i>cat</i> value with the minimum and maximum values
+ * in the <i>range</i> structure, modifying the range if <i>cat</i>
* extends the range.
*
* NULL-values must be detected and ignored.
*
- * \param cat
- * \param range
- *
- * \return
+ * \param cat raster value
+ * \param range pointer to Range structure which holds range info
*/
-
void G_update_range(CELL cat, struct Range *range)
{
if (!G_is_c_null_value(&cat)) {
@@ -439,8 +373,18 @@
}
}
-/*-------------------------------------------------------------------------*/
-
+/*!
+ * \brief Update range structure (floating-point)
+ *
+ * Compares the <i>cat</i> value with the minimum and maximum values
+ * in the <i>range</i> structure, modifying the range if <i>cat</i>
+ * extends the range.
+ *
+ * NULL-values must be detected and ignored.
+ *
+ * \param val raster value
+ * \param range pointer to Range structure which holds range info
+ */
void G_update_fp_range(DCELL val, struct FPRange *range)
{
if (!G_is_d_null_value(&val)) {
@@ -457,29 +401,32 @@
}
}
-/*-------------------------------------------------------------------------*/
-
-
/*!
- * \brief update range structure
+ * \brief Update range structure based on raster row (CELL)
*
- * This routine updates the <b>range</b> data
- * just like <i>G_update_range</i>, but for <b>n</b> values from the
- * <b>cell</b> array.
+ * This routine updates the <i>range</i> data just like
+ * G_update_range(), but for <i>n</i> values from the <i>cell</i>
+ * array.
*
- * \param cell
- * \param n
- * \param range
- * \return
+ * \param cell raster values
+ * \param n number of values
+ * \param range pointer to Range structure which holds range info
*/
-
void G_row_update_range(const CELL *cell, int n, struct Range *range)
{
G__row_update_range(cell, n, range, 0);
}
-/*-------------------------------------------------------------------------*/
-
+/*!
+ * \brief Update range structure based on raster row
+ *
+ * Note: for internal use only.
+ *
+ * \param cell raster values
+ * \param n number of values
+ * \param range pointer to Range structure which holds range info
+ * \param ignore_zeros ignore zeros
+ */
void G__row_update_range(const CELL *cell, int n,
struct Range *range, int ignore_zeros)
{
@@ -502,8 +449,18 @@
}
}
-/*-------------------------------------------------------------------------*/
-
+/*!
+ * \brief Update range structure based on raster row (floating-point)
+ *
+ * This routine updates the <i>range</i> data just like
+ * G_update_range(), but for <i>n</i> values from the <i>cell</i>
+ * array.
+ *
+ * \param cell raster values
+ * \param n number of values
+ * \param range pointer to Range structure which holds range info
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ */
void G_row_update_fp_range(const void *rast, int n,
struct FPRange *range, RASTER_MAP_TYPE data_type)
{
@@ -542,21 +499,18 @@
}
}
-/*-------------------------------------------------------------------------*/
-
/*!
- * \brief initialize range structure
+ * \brief Initialize range structure
*
- * Initializes the <b>range</b> structure for updates by
- * <i>G_update_range</i> and <i>G_row_update_range.</i>
+ * Initializes the <i>range</i> structure for updates by
+ * G_update_range() and G_row_update_range().
*
- * Must set a flag in the range structure that indicates that
- * no min/max have been defined - probably a <tt>"first"</tt> boolean flag.
+ * Must set a flag in the range structure that indicates that no
+ * min/max have been defined - probably a <tt>"first"</tt> boolean
+ * flag.
*
- * \param range
- * \return
+ * \param range pointer to Range structure which holds range info
*/
-
void G_init_range(struct Range *range)
{
G_set_c_null_value(&(range->min), 1);
@@ -564,26 +518,20 @@
range->first_time = 1;
}
-/*-------------------------------------------------------------------------*/
-
-
/*!
- * \brief get range min and max
+ * \brief Get range min and max
*
- * The <b>min</b>inum and <b>max</b>imum CELL
- * values are extracted from the <b>range</b> structure.
+ * The mininum and maximum CELL values are extracted from the
+ * <i>range</i> 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.
+ * 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.
*
- * \param range
- * \param min
- * \param max
- * \return
+ * \param range pointer to Range structure which holds range info
+ * \param[out] min minimum value
+ * \param[out] max maximum value
*/
-
-
void G_get_range_min_max(const struct Range *range, CELL * min, CELL * max)
{
if (range->first_time) {
@@ -603,19 +551,15 @@
}
}
-/*-------------------------------------------------------------------------*/
-
/*!
- * \brief
+ * \brief Initialize fp range
*
- * Must set a flag in the range
- * structure that indicates that no min/max have been defined - probably a
- * <tt>"first"</tt> boolean flag.
+ * Must set a flag in the range structure that indicates that no
+ * min/max have been defined - probably a <tt>"first"</tt> boolean
+ * flag.
*
- * \param r
- * \return
+ * \param range pointer to FPRange which holds fp range info
*/
-
void G_init_fp_range(struct FPRange *range)
{
G_set_d_null_value(&(range->min), 1);
@@ -623,22 +567,18 @@
range->first_time = 1;
}
-/*-------------------------------------------------------------------------*/
-
-
/*!
- * \brief
+ * \brief Get minumum and maximum value from fp range
*
- * Extract the min/max from the range structure <em>r</em>.
- * 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.
+ * Extract the min/max from the range structure <i>range</i>. 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.
*
- * \param r
- * \param min
- * \param max
- * \return
+ * \param range pointer to FPRange which holds fp range info
+ * \param[out] min minimum value
+ * \param[out] max maximum value
*/
-
void G_get_fp_range_min_max(const struct FPRange *range,
DCELL *min, DCELL *max)
{
Modified: grass/trunk/lib/gis/raster.c
===================================================================
--- grass/trunk/lib/gis/raster.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/raster.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,14 +1,27 @@
+/*!
+ * \file gis/raster.c
+ *
+ * \brief GIS Library - Raster cell value routines.
+ *
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <stdlib.h>
#include <grass/gis.h>
-
/*!
- * \brief Advance void pointer
+ * \brief Advance void pointer
*
- * Advances void pointer by <em>size</em> bytes
- * Returns new pointer value.
+ * Advances void pointer by <i>size</i> bytes. Returns new pointer
+ * value.
*
* Useful in raster row processing loops, substitutes
+ *
\code
CELL *cell;
cell += n;
@@ -19,38 +32,35 @@
rast = G_incr_void_ptr(rast, G_raster_size(data_type))
\endcode
*
- * (where rast is void* and data_type is RASTER_MAP_TYPE can be used instead
- * of rast++.)
+ * (where rast is void* and <i>data_type</i> is RASTER_MAP_TYPE can be
+ * used instead of rast++.)
*
- * very useful to generalize the row processing - loop i.e.
+ * Very useful to generalize the row processing - loop i.e.
+ * \code
* void * buf_ptr += G_raster_size(data_type)
+ * \endcode
*
- * \param ptr
- * \param size
- * \return void *
+ * \param ptr pointer
+ * \param size buffer size
+ *
+ * \return pointer to the data
*/
-
void *G_incr_void_ptr(const void *ptr, const size_t size)
{
/* assuming that the size of unsigned char is 1 */
return (void *)((const unsigned char *)ptr + size);
}
-
/*!
- * \brief Compares raster values p and q
+ * \brief Compares raster values.
*
- * Returns:
- * 1 if p > q or only q is null value
- * -1 if p < q or only p is null value
- * 0 if p == q or p==q==null value
+ * \param v1,v2 values to be compared
+ * \param data_type raster type (CELL, FCELL, DCELL)
*
- * \param p
- * \param q
- * \param data_type
- * \return int
+ * \return 1 if p > q or only q is null value
+ * \return -1 if p < q or only p is null value
+ * \return 0 if p == q or p==q==null value
*/
-
int G_raster_cmp(const void *v1, const void *v2, RASTER_MAP_TYPE data_type)
{
if (G_is_null_value(v1, data_type)) {
@@ -89,38 +99,31 @@
return 0;
}
-
/*!
- * \brief Copies raster values q into p
+ * \brief Copies raster values.
*
- * If q is null value, sets q to null value.
+ * If v2 is null value, sets v2 to null value.
*
- * \param p
- * \param q
- * \param n
- * \param data_type
- * \return
+ * \param v1, v2 raster values
+ * \param n ?
+ * \param data_type raster type (CELL, FCELL, DCELL)
*/
-
void G_raster_cpy(void *v1, const void *v2, int n, RASTER_MAP_TYPE data_type)
{
G_copy(v1, v2, n * G_raster_size(data_type));
}
-
/*!
- * \brief Places a CELL raster value
+ * \brief Places a CELL raster value
*
- * If G_is_c_null_value(val) is true, sets p to null value.
- * Converts CELL val to data_type (type of p) and stores result in p.
- * Used for assigning CELL values to raster cells of any type.
+ * If G_is_c_null_value() is true, sets p to null value. Converts CELL
+ * val to data_type (type of p) and stores result in p. Used for
+ * assigning CELL values to raster cells of any type.
*
- * \param p
- * \param val
- * \param data_type
- * \return
+ * \param rast pointer to raster cell value
+ * \param cval value to set
+ * \param data_type raster type (CELL, FCELL, DCELL)
*/
-
void G_set_raster_value_c(void *rast, CELL cval, RASTER_MAP_TYPE data_type)
{
CELL c;
@@ -143,20 +146,17 @@
}
}
-
/*!
- * \brief Places a FCELL raster value
+ * \brief Places a FCELL raster value
*
- * If G_is_f_null_value(val) is true, sets p to null value.
- * Converts FCELL val to data_type (type of p) and stores result in p.
- * Used for assigning FCELL values to raster cells of any type.
+ * If G_is_f_null_value() is true, sets p to null value. Converts
+ * FCELL val to data_type (type of p) and stores result in p. Used for
+ * assigning FCELL values to raster cells of any type.
*
- * \param p
- * \param val
- * \param data_type
- * \return
+ * \param rast pointer to raster cell value
+ * \param fval value to set
+ * \param data_type raster type (CELL, FCELL, DCELL)
*/
-
void G_set_raster_value_f(void *rast, FCELL fval, RASTER_MAP_TYPE data_type)
{
FCELL f;
@@ -183,16 +183,14 @@
/*!
* \brief Places a DCELL raster value
*
- * If G_is_d_null_value(val) is true, sets p to null value.
- * Converts DCELL val to data_type (type of p) and stores result in p.
- * Used for assigning DCELL values to raster cells of any type.
+ * If G_is_d_null_value() is true, sets p to null value. Converts
+ * DCELL val to data_type (type of p) and stores result in p. Used for
+ * assigning DCELL values to raster cells of any type.
*
- * \param p
- * \param val
- * \param data_type
- * \return
+ * \param rast pointer to raster cell value
+ * \param fval value to set
+ * \param data_type raster type (CELL, FCELL, DCELL)
*/
-
void G_set_raster_value_d(void *rast, DCELL dval, RASTER_MAP_TYPE data_type)
{
DCELL d;
@@ -215,24 +213,23 @@
}
}
-
/*!
- * \brief Retrieves the value of type data_type from pointer p
+ * \brief Retrieves the value of give type from pointer p
*
- * Retrieves the value of type data_type from pointer p,
- * converts it to CELL type and returns the result.
- * If null value is stored in p, returns CELL null value.
+ * Retrieves the value of type data_type from pointer p, converts it
+ * to CELL type and returns the result. If null value is stored in p,
+ * returns CELL null value.
*
* Used for retrieving CELL values from raster cells of any type.
*
- * NOTE: when data_type != CELL_TYPE, no quantization is used, only
+ * Note: when data_type != CELL_TYPE, no quantization is used, only
* type conversion.
*
- * \param p
- * \param data_type
- * \return CELL
+ * \param rast pointer to raster cell value
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return raster value
*/
-
CELL G_get_raster_value_c(const void *rast, RASTER_MAP_TYPE data_type)
{
CELL c;
@@ -245,29 +242,28 @@
case CELL_TYPE:
return *((const CELL *)rast);
case FCELL_TYPE:
- return (CELL) * ((const FCELL *)rast);
+ return (CELL) *((const FCELL *)rast);
case DCELL_TYPE:
- return (CELL) * ((const DCELL *)rast);
+ return (CELL) *((const DCELL *)rast);
}
return 0;
}
-
/*!
- * \brief Retrieves the value of type data_type from pointer p
+ * \brief Retrieves the value of given raster type from pointer p (FCELL)
*
- * Retrieves the value of type data_type from pointer p,
- * converts it to FCELL type and returns the result.
- * If null value is stored in p, returns FCELL null value.
+ * Retrieves the value of type data_type from pointer p, converts it
+ * to FCELL type and returns the result. If null value is stored in p,
+ * returns FCELL null value.
*
* Used for retrieving FCELL values from raster cells of any type.
*
- * \param p
- * \param data_type
- * \return FCELL
+ * \param rast pointer to raster cell value
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return raster value
*/
-
FCELL G_get_raster_value_f(const void *rast, RASTER_MAP_TYPE data_type)
{
FCELL f;
@@ -290,19 +286,19 @@
/*!
- * \brief Retrieves the value of type data_type from pointer p,
+ * \brief Retrieves the value of given type from pointer p (DCELL)
*
- * Retrieves the value of type data_type from pointer p,
- * converts it to DCELL type and returns the result.
- * If null value is stored in p, returns DCELL null value.
+ * Retrieves the value of type data_type from pointer p, converts it
+ * to DCELL type and returns the result. If null value is stored in p,
+ * returns DCELL null value.
* Used for retrieving DCELL values from raster cells of any type.
*
- * \param p
- * \param data_type
- * \return DCELL
+ * \param rast pointer to raster cell value
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return raster value
*/
-
DCELL G_get_raster_value_d(const void *rast, RASTER_MAP_TYPE data_type)
{
DCELL d;
Modified: grass/trunk/lib/gis/reclass.c
===================================================================
--- grass/trunk/lib/gis/reclass.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/reclass.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,3 +1,16 @@
+/*!
+ * \file gis/reclass.c
+ *
+ * \brief GIS Library - Check if raster map is reclassified
+ *
+ * (C) 2001-2009 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
#include <string.h>
#include <grass/gis.h>
#include <grass/glocale.h>
@@ -8,25 +21,23 @@
static FILE *fopen_cellhd_new(const char *);
static int get_reclass_table(FILE *, struct Reclass *);
-
/*!
- * \brief reclass file?
+ * \brief Check if raster map is reclassified
*
- * This function determines if the raster map
- * <b>name</b> in <b>mapset</b> is a reclass file.
- * If it is, then the name and mapset of the referenced
- * raster map are copied into the <b>r_name</b> and <b>r_mapset</b>
- * buffers.
- * Returns 1 if <b>name</b> is a reclass file, 0 if it is not, and -1 if
- * there was a problem reading the raster header for <b>name.</b>
+ * This function determines if the raster map <i>name</i> in
+ * <i>mapset</i> is a reclass file. If it is, then the name and mapset
+ * of the referenced raster map are copied into the <i>r_name</i> and
+ * <i>r_mapset</i> buffers.
*
- * \param name
- * \param mapset
- * \param r_name
- * \param r_mapset
- * \return int
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] r_name name of reference map
+ * \param[out] r_mapset mapset where reference map lives
+ *
+ * \returns 1 if it is a reclass file
+ * \return 0 if it is not
+ * \return -1 if there was a problem reading the raster header
*/
-
int G_is_reclass(const char *name, const char *mapset, char *rname,
char *rmapset)
{
@@ -45,24 +56,24 @@
return type != 0;
}
-
/*!
- * \brief get child reclass maps list
+ * \brief Get child reclass maps list
*
- * 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 g.rename, g.remove and r.reclass to
- * prevent accidentally deleting the parent map of a reclassed raster map.
+ * 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.
*
- * \param name
- * \param mapset
- * \param nrmaps
- * \param rmaps
- * \return int
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] nrmaps number of reference maps
+ * \param[out] rmaps array of names of reference maps
+ *
+ * \return number of reference maps
+ * \return -1 on error
*/
-
int G_is_reclassed_to(const char *name, const char *mapset, int *nrmaps,
char ***rmaps)
{
@@ -112,6 +123,16 @@
return i;
}
+/*!
+ \brief Get reclass
+
+ \param name map name
+ \param mapset mapset name
+ \param[out] reclass pointer to Reclass structure
+
+ \return -1 on error
+ \return type code
+*/
int G_get_reclass(const char *name, const char *mapset,
struct Reclass *reclass)
{
@@ -140,16 +161,21 @@
fclose(fd);
if (stat < 0) {
if (stat == -2)
- G_warning(_("Too many reclass categories for [%s in %s]"),
+ G_warning(_("Too many reclass categories for <%s@%s>"),
name, mapset);
else
- G_warning(_("Illegal reclass format in header file for [%s in %s]"),
+ G_warning(_("Illegal reclass format in header file for <%s@%s>"),
name, mapset);
stat = -1;
}
return stat;
}
+/*!
+ \brief Free Reclass structure
+
+ \param reclass pointer to Reclass structure
+*/
void G_free_reclass(struct Reclass *reclass)
{
switch (reclass->type) {
@@ -220,6 +246,15 @@
return G_fopen_old("cellhd", name, mapset);
}
+/*!
+ \brief Put reclass
+
+ \param name map name
+ \param reclass pointer to Reclass structure
+
+ \return -1 on error
+ \return 1 on success
+*/
int G_put_reclass(const char *name, const struct Reclass *reclass)
{
FILE *fd;
@@ -241,7 +276,7 @@
fd = fopen_cellhd_new(name);
if (fd == NULL) {
- G_warning(_("Unable to create header file for [%s in %s]"),
+ G_warning(_("Unable to create header file for <%s@%s>"),
name, G_mapset());
return -1;
}
@@ -289,7 +324,7 @@
fd = fopen(buf1, "a+");
if (fd == NULL) {
#if 0
- G_warning(_("Unable to create dependency file in [%s in %s]"),
+ G_warning(_("Unable to create dependency file in <%s@%s>"),
buf2, reclass->mapset);
#endif
return 1;
Modified: grass/trunk/lib/gis/timestamp.c
===================================================================
--- grass/trunk/lib/gis/timestamp.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/timestamp.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,33 +1,10 @@
-/*
+/*!
+ * \file gis/timestamp.c
*
- * provides DateTime functions for timestamp management:
+ * \brief GIS Library - Timestamp management
*
- * Authors: Michael Shapiro & Bill Brown, CERL
- * grid3 functions by Michael Pelizzari, LMCO
+ * Provides DateTime functions for timestamp management.
*
- * G_init_timestamp()
- * G_set_timestamp()
- * G_set_timestamp_range()
- * G_format_timestamp()
- * G_scan_timestamp()
- * G_get_timestamps()
- * G_read_raster_timestamp()
- * G_remove_raster_timestamp()
- * G_read_vector_timestamp()
- * G_remove_vector_timestamp()
- * G_read_grid3_timestamp()
- * G_remove_grid3_timestamp()
- * G_write_raster_timestamp()
- * G_write_vector_timestamp()
- * G_write_grid3_timestamp()
- *
- * COPYRIGHT: (C) 2000 by the GRASS Development Team
- *
- * This program is free software under the GNU General Public
- * License (>=v2). Read the file COPYING that comes with GRASS
- * for details.
- *
- *
* The timestamp values must use the format as described in the GRASS
* datetime library. The source tree for this library should have a
* description of the format. For convience, the formats as of Feb, 1996
@@ -89,24 +66,51 @@
* 3 months 15 days
* 3 years 10 days
*
+ * (C) 2001-2009 by the GRASS Development Team
*
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Michael Shapiro & Bill Brown, CERL
+ * \author grid3 functions by Michael Pelizzari, LMCO
*/
#include <string.h>
#include <grass/gis.h>
#include <grass/glocale.h>
+#define RAST_MISC "cell_misc"
+#define VECT_MISC "dig_misc"
+#define GRID3 "grid3"
+
+/*!
+ \brief Initialize timestamp structure
+
+ \param ts pointer to TimeStamp structure
+*/
void G_init_timestamp(struct TimeStamp *ts)
{
ts->count = 0;
}
+/*!
+ \brief Set timestamp (single)
+
+ \param ts pointer to TimeStamp structure
+ \param dt pointer to DateTime structure (date/time to be set)
+*/
void G_set_timestamp(struct TimeStamp *ts, const DateTime * dt)
{
datetime_copy(&ts->dt[0], dt);
ts->count = 1;
}
+/*!
+ \brief Set timestamp (range)
+
+ \param ts pointer to TimeStamp structure
+ \param dt1,dt2 pointer to DateTime structures
+*/
void G_set_timestamp_range(struct TimeStamp *ts,
const DateTime * dt1, const DateTime * dt2)
{
@@ -115,6 +119,16 @@
ts->count = 2;
}
+/*!
+ \brief Read timestamp
+
+ \param fd file descriptor
+ \param[out] ts pointer to TimeStamp structure
+
+ \return -2 EOF
+ \return -1 on error
+ \return 0 on success
+*/
int G__read_timestamp(FILE * fd, struct TimeStamp *ts)
{
char buf[1024];
@@ -128,20 +142,17 @@
return -2; /* nothing in the file */
}
-
/*!
- * \brief output TimeStamp structure to a file as a formatted string
- *
- * A handy fd might be "stdout".
- *
- * Returns:
- * 0 on success
- * -1 error
- *
- * \param fd file descriptor
- * \param ts TimeStamp struct
- * \return int exit value
- */
+ \brief Output TimeStamp structure to a file as a formatted string
+
+ A handy fd might be "stdout".
+
+ \param[in,out] fd file descriptor
+ \param ts pointer to TimeStamp structure
+
+ \return 0 on success
+ \return -1 on error
+*/
int G__write_timestamp(FILE * fd, const struct TimeStamp *ts)
{
char buf[1024];
@@ -152,22 +163,19 @@
return 0;
}
-
/*!
- * \brief Create text string from TimeStamp structure
- *
- * Fills string *buf with info from TimeStamp structure *ts in a pretty
- * way. The TimeStamp struct is defined in gis.h and populated with e.g.
- * G_read_raster_timestamp().
- *
- * Returns:
- * 1 on success
- * -1 error
- *
- * \param ts TimeStamp structure containing time info
- * \param buf string to receive formatted timestamp
- * \return int exit value
- */
+ \brief Create text string from TimeStamp structure
+
+ Fills string *buf with info from TimeStamp structure *ts in a
+ pretty way. The TimeStamp struct is defined in gis.h and populated
+ with e.g. G_read_raster_timestamp().
+
+ \param ts TimeStamp structure containing time info
+ \param buf string to receive formatted timestamp
+
+ \return 1 on success
+ \return -1 error
+*/
int G_format_timestamp(const struct TimeStamp *ts, char *buf)
{
char temp1[128], temp2[128];
@@ -189,21 +197,19 @@
return 1;
}
-
/*!
- * \brief Fill a TimeStamp structure from a datetime string
- *
- * Populate a TimeStamp structure (defined in gis.h) from a text string.
- * Checks to make sure text string is in valid GRASS datetime format.
- *
- * Returns:
- * 1 on success
- * -1 error
- *
- * \param ts TimeStamp structure to be populated
- * \param buf String containing formatted time info
- * \return int exit code
- */
+ \brief Fill a TimeStamp structure from a datetime string
+
+ Populate a TimeStamp structure (defined in gis.h) from a text
+ string. Checks to make sure text string is in valid GRASS datetime
+ format.
+
+ \param ts TimeStamp structure to be populated
+ \param buf string containing formatted time info
+
+ \return 1 on success
+ \return -1 error
+*/
int G_scan_timestamp(struct TimeStamp *ts, const char *buf)
{
char temp[1024], *t;
@@ -232,23 +238,21 @@
return 1;
}
-
/*!
- * \brief copy TimeStamp into [two] Datetimes structs
- *
- * Use to copy the TimeStamp information into Datetimes, as the members of
- * struct TimeStamp shouldn't be accessed directly.
- *
- * count=0 means no datetimes were copied
- * count=1 means 1 datetime was copied into dt1
- * count=2 means 2 datetimes were copied
- *
- * \param ts source TimeStamp structure
- * \param dt1 first DateTime struct to be filled
- * \param dt2 second DateTime struct to be filled
- * \param count return code
- * \return
- */
+ \brief Copy TimeStamp into [two] Datetimes structs
+
+ Use to copy the TimeStamp information into Datetimes, as the members
+ of struct TimeStamp shouldn't be accessed directly.
+
+ - count=0 means no datetimes were copied
+ - count=1 means 1 datetime was copied into dt1
+ - count=2 means 2 datetimes were copied
+
+ \param ts source TimeStamp structure
+ \param[out] dt1 first DateTime struct to be filled
+ \param[out] dt2 second DateTime struct to be filled
+ \param[out] count return code
+*/
void G_get_timestamps(const struct TimeStamp *ts,
DateTime * dt1, DateTime * dt2, int *count)
{
@@ -264,11 +268,18 @@
}
-/* write timestamp file
- * 1 ok
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- */
+/*!
+ \brief Write timestamp file
+
+ \param maptype map type
+ \param dir directory
+ \param name map name
+ \param ts pointer to TimeStamp
+
+ \return 1 on success
+ \return -1 error - can't create timestamp file
+ \return -2 error - invalid datetime in ts
+*/
static int write_timestamp(const char *maptype, const char *dir,
const char *name, const struct TimeStamp *ts)
{
@@ -277,7 +288,7 @@
fd = G_fopen_new_misc(dir, "timestamp", name);
if (fd == NULL) {
- G_warning(_("Can't create timestamp file for %s map %s in mapset %s"),
+ G_warning(_("Unable to create timestamp file for %s map <%s@%s>"),
maptype, name, G_mapset());
return -1;
}
@@ -286,17 +297,25 @@
fclose(fd);
if (stat == 0)
return 1;
- G_warning(_("Invalid timestamp specified for %s map %s in mapset %s"),
+ G_warning(_("Invalid timestamp specified for %s map <%s@%s>"),
maptype, name, G_mapset());
return -2;
}
-/* read timestamp file
- * 0 no timestamp file
- * 1 ok
- * -1 error - can't open timestamp file
- * -2 error - invalid datetime values in timestamp file
- */
+/*!
+ \brief Read timestamp file
+
+ \param maptype map type
+ \param dir directory
+ \param name map name
+ \param mapset mapset name
+ \param ts pointer to TimeStamp
+
+ \return 0 no timestamp file
+ \return 1 on success
+ \return -1 error - can't open timestamp file
+ \return -2 error - invalid datetime values in timestamp file
+*/
static int read_timestamp(const char *maptype, const char *dir,
const char *name, const char *mapset,
struct TimeStamp *ts)
@@ -308,7 +327,7 @@
return 0;
fd = G_fopen_old_misc(dir, "timestamp", name, mapset);
if (fd == NULL) {
- G_warning(_("Can't open timestamp file for %s map %s in mapset %s"),
+ G_warning(_("Unable to open timestamp file for %s map <%s@%s>"),
maptype, name, mapset);
return -1;
}
@@ -317,179 +336,153 @@
fclose(fd);
if (stat == 0)
return 1;
- G_warning(_("Invalid timestamp file for %s map %s in mapset %s"),
+ G_warning(_("Invalid timestamp file for %s map <%s@%s>"),
maptype, name, mapset);
return -2;
}
-#define RAST_MISC "cell_misc"
-#define VECT_MISC "dig_misc"
-#define GRID3 "grid3"
-
-
/*!
- * \brief Read timestamp from raster map
- *
- * Returns:
- * 1 on success
- * 0 or negative on error.
- *
- * \param name map name
- * \param mapset mapset the map lives in
- * \param ts TimeStamp struct to populate
- * \return int
- */
+ \brief Read timestamp from raster map
+
+ \param name map name
+ \param mapset mapset the map lives in
+ \param[out] ts TimeStamp struct to populate
+
+ \return 1 on success
+ \return 0 or negative on error
+*/
int G_read_raster_timestamp(const char *name, const char *mapset,
struct TimeStamp *ts)
{
return read_timestamp("raster", RAST_MISC, name, mapset, ts);
}
-
/*!
- * \brief
- *
- * Only timestamp files in current mapset can be removed
- * Returns:
- * 0 if no file
- * 1 if successful
- * -1 on fail
- *
- * \param name
- * \return int
- */
+ \brief Remove timestamp from raster map
+
+ Only timestamp files in current mapset can be removed.
+
+ \param name map name
+
+ \return 0 if no file
+ \return 1 on success
+ \return -1 on error
+*/
int G_remove_raster_timestamp(const char *name)
{
return G_remove_misc(RAST_MISC, "timestamp", name);
}
-
-
/*!
- * \brief Read vector timestamp
- *
- * Is this used anymore with the new GRASS 6 vector engine???
- *
- * Returns 1 on success. 0 or negative on error.
- *
- * \param name
- * \param mapset
- * \param ts
- * \return int
- */
+ \brief Read timestamp from vector map
+
+ Is this used anymore with the new GRASS 6 vector engine???
+
+ \param name map name
+ \param mapset mapset name
+ \param[out] ts TimeStamp struct to populate
+
+ \return 1 on success
+ \return 0 or negative on error
+*/
int G_read_vector_timestamp(const char *name, const char *mapset,
struct TimeStamp *ts)
{
return read_timestamp("vector", VECT_MISC, name, mapset, ts);
}
+/*!
+ \brief Remove timestamp from vector map
+
+ Is this used anymore with the new GRASS 6 vector engine???
+
+ Only timestamp files in current mapset can be removed.
+ \param name map name
-/*!
- * \brief
- *
- * Is this used anymore with the new GRASS 6 vector engine???
- *
- * Only timestamp files in current mapset can be removed
- * Returns:
- * 0 if no file
- * 1 if successful
- * -1 on fail
- *
- * \param name
- * \return int
- */
+ \return 0 if no file
+ \return 1 on success
+ \return -1 on failure
+*/
int G_remove_vector_timestamp(const char *name)
{
return G_remove_misc(VECT_MISC, "timestamp", name);
}
-
/*!
- * \brief read grid3 timestamp
- *
- * Returns 1 on success. 0 or
- * negative on error.
- *
- * \param name
- * \param mapset
- * \param ts
- * \return int
- */
+ \brief Read timestamp from 3D raster map
+
+ \param name map name
+ \param mapset mapset name
+ \param[out] ts TimeStamp struct to populate
+
+ \return 1 on success
+ \return 0 or negative on error
+*/
int G_read_grid3_timestamp(const char *name, const char *mapset,
struct TimeStamp *ts)
{
return read_timestamp("grid3", GRID3, name, mapset, ts);
}
-
/*!
- * \brief remove grid3 timestamp
- *
- * Only timestamp files in current mapset can be removed
- * Returns:
- * 0 if no file
- * 1 if successful
- * -1 on fail
- *
- * \param name
- * \return int
- */
+ \brief Remove timestamp from 3D raster map
+
+ Only timestamp files in current mapset can be removed.
+
+ \param name map name
+
+ \return 0 if no file
+ \return 1 on success
+ \return -1 on failure
+*/
int G_remove_grid3_timestamp(const char *name)
{
return G_remove_misc(GRID3, "timestamp", name);
}
+/*!
+ \brief Write timestamp of raster map
+ \param name map name
+ \param[out] ts TimeStamp struct to populate
+
+ \return 1 on success
+ \return -1 error - can't create timestamp file
+ \return -2 error - invalid datetime in ts
-/*!
- * \brief
- *
- * Returns:
- * 1 on success.
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- *
- * \param name
- * \param ts
- * \return int
*/
int G_write_raster_timestamp(const char *name, const struct TimeStamp *ts)
{
return write_timestamp("raster", RAST_MISC, name, ts);
}
+/*!
+ \brief Write timestamp of vector map
+ \param name map name
+ \param[out] ts TimeStamp struct to populate
+
+ \return 1 on success
+ \return -1 error - can't create timestamp file
+ \return -2 error - invalid datetime in ts
-/*!
- * \brief
- *
- * Returns:
- * 1 on success.
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- *
- * \param name
- * \param ts
- * \return int
*/
int G_write_vector_timestamp(const char *name, const struct TimeStamp *ts)
{
return write_timestamp("vector", VECT_MISC, name, ts);
}
-
/*!
- * \brief write grid3 timestamp
- *
- * Returns:
- * 1 on success.
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- *
- * \param name
- * \param ts
- * \return int
+ \brief Write timestamp of 3D raster map
+
+ \param name map name
+ \param[out] ts TimeStamp struct to populate
+
+ \return 1 on success
+ \return -1 error - can't create timestamp file
+ \return -2 error - invalid datetime in ts
+
*/
int G_write_grid3_timestamp(const char *name, const struct TimeStamp *ts)
{
Modified: grass/trunk/lib/gis/whoami.c
===================================================================
--- grass/trunk/lib/gis/whoami.c 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/gis/whoami.c 2009-06-09 18:40:28 UTC (rev 37793)
@@ -1,17 +1,14 @@
-
-/**
- * \file whoami.c
+/*!
+ * \file gis/whoami.c
*
* \brief GIS Library - Login name functions.
*
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2009 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
*/
#include <unistd.h>
@@ -23,8 +20,7 @@
#include <grass/gis.h>
-
-/**
+/*!
* \brief Gets user's name.
*
* Returns a pointer to a string containing the user's login name.
@@ -34,9 +30,8 @@
* because the ttyname(0) rotuine fails in ucb universe.
* So we check for this, too.
*
- * \retval char * Pointer to string
+ * \return pointer to string ("anonymous" by default)
*/
-
const char *G_whoami(void)
{
static int initialized;
Modified: grass/trunk/lib/grasslib.dox
===================================================================
--- grass/trunk/lib/grasslib.dox 2009-06-09 18:21:38 UTC (rev 37792)
+++ grass/trunk/lib/grasslib.dox 2009-06-09 18:40:28 UTC (rev 37793)
@@ -33,13 +33,17 @@
Main web site: <a href="http://grass.osgeo.org">http://grass.osgeo.org</a>
-<h2>Table of contents</h2>
+<b>Table of contents</b>
- \subpage corelibs
- \subpage libs
- \subpage interfaces
- \subpage gui
- \subpage location
+- \subpage Compiling_and_Installing_GRASS_Modules
+ - \subpage Makefile_Variables
+ - \subpage Constructing_a_Makefile
+ - \subpage Multiple_Architecture_Conventions
<p>
<i>Missing entries below are either not yet uploaded to SVN (need to be migrated
@@ -164,4 +168,142 @@
-->
\image html "loc_struct.png" "Diagram of GRASS file structure"
+\section Compiling_and_Installing_GRASS_Modules Compiling and Installing GRASS Modules
+
+GRASS modules are compiled and installed using the UNIX <tt>make</tt>
+command, which reads a file named <tt>Makefile</tt> (see \ref
+Multiple_Architecture_Conventions for more information) and then runs
+the compiler. The GRASS compilation process allows for
+multiple-architecture compilation from a single copy of the source
+code (for instance, if the source code is NFS mounted to various
+machines with differing architectures). This chapter assumes that the
+programmer is familiar with <tt>make</tt> and its accompanying
+Makefile.
+
+\todo Explain ''auto-conf''
+
+\todo Include contents of SUBMITTING and INSTALL files from source code
+
+To compile enter following:
+
+\verbatim
+./configure
+make
+make install
+\endverbatim
+
+Then the code will be compiled into "/usr/local/grass-7.x.y" directory. The start
+script "grass7x" will be placed into "/usr/local/bin/".
+
+Optionally other target directories can be specified while "configuring":
+
+\verbatim
+./configure --prefix=/opt/grass-7.x.y --with-bindir=/usr/bin
+make
+make install
+\endverbatim
+
+This will store the GRASS binaries into the directory
+"/opt/grass-7.x.y" and the script mentioned above into "/usr/bin".
+
+The script "make" is required to compile single modules. The
+compilation process and requirements are discussed in more detail now.
+
+\subsection Makefile_Variables Makefile Variables
+
+\todo Update the list.
+
+<b>GRASS Libraries</b>. The following variables name the various GRASS
+libraries:
+
+ - <i>GISLIB</i> - This names the <b>GIS Library</b>, which is the
+principal GRASS library. See \ref GIS_Library for details about this
+library, and \ref Loading_the_GIS_Library for a sample Makefile which
+loads this library.
+
+ - <i>SEGMENTLIB</i> - This names the <b>Segment Library</b>, which
+manages large matrix data. See \ref Segment_Library for details about
+this library, and \ref Loading_the_Vask_Library for a sample
+<i>Makefile</i> which loads this library.
+
+ - <i>RASTERLIB</i> - This names the <b>Raster Graphics Library</b>,
+which communicates with GRASS graphics drivers. See \ref
+Raster_Graphics_Library for details about this library, and \ref
+Loading_the_Raster_Graphics_Library for a sample <i>Makefile</i> which
+loads this library.
+
+ - <i>DISPLAYLIB</i> - This names the <b>Display Graphics Library</b>,
+which provides a higher level graphics interface to
+<i>RASTERLIB</i>. See Display_Graphics_Library for details about this
+library, and Loading_the_Display_Graphics_Library for a sample
+<i>Makefile</i> which loads this library.
+
+<b>UNIX Libraries:</b> The following variables name some useful UNIX
+system libraries:
+
+ - <i>MATHLIB</i> This names the math library. It should be used
+instead of the -lm loader option.
+
+ - <i>CURSES</i> This names both the curses and termcap libraries. It
+should be used instead of the -lcurses/-lncurses and
+-ltermcap loader options. Do not use <tt>$CURSES</tt> if you use
+<tt>$VASK</tt>.
+
+ - <i>TERMLIB</i> This names the termcap library. It should be used
+-instead of the ltermcap or -ltermlib loader options. Do not use
+-<tt>$TERMLIB</tt> if you use <tt>$VASK</tt> or <tt>$CURSES</tt>.
+
+<b>Compiler and loader variables.</b> The following variables are
+related to compiling and loading C programs:
+
+ - <i>EXTRA\_CFLAGS</i> This variable can be used to add additional
+options to <tt>$CFLAGS</tt>. It has no predefined values. It is
+usually used to specify additional -I include directories, or -D
+preprocessor defines.
+
+\subsection Constructing_a_Makefile Constructing a Makefile
+
+
+The complete syntax for a <i>Makefile</i> is discussed in the UNIX
+documentation for <tt>make</tt> and will not be repeated here. The
+essential idea is that a target (e.g. a GRASS module) is to be built
+from a list of dependencies (e.g. object files, libraries, etc.). The
+relationship between the target, its dependencies, and the rules for
+constructing the target is expressed according to the following
+syntax:
+
+\code
+target: dependencies
+
+actions
+
+more actions
+\endcode
+
+If the target does not exist, or if any of the dependencies have a newer
+date than the target (i.e., have changed), the actions will be executed to
+build the target. The actions must be indented using a TAB. <tt>make</tt> is
+picky about this. It does not like spaces in place of the TAB.
+
+\section Multiple_Architecture_Conventions Multiple-Architecture Conventions
+
+
+The following conventions allow for multiple architecture compilation on a
+machine that uses a common or networked GRASS source code directory tree.
+
+Object files and library archives are compiled into subdirectories
+that represent the architecture that they were compiled on. These
+subdirectories are created in the $SRC directory as OBJ.<tt>arch</tt>
+and LIB.<tt>arch</tt>, where <tt>arch</tt> represents the architecture
+of the compiling machine. Thus, for example, $SRC/OBJ.sun4 would
+contain the object files for Sun/4 and SPARC architectures, and
+<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
+Linux architectures. Likewise, <tt>$SRC/OBJ.686-pc-linux-gnu</tt>
+would contain the object files for Linux architectures, and
+<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
+Linux architectures.
+
+Note that 'arch' is defined for a specific architecture during setup and
+compilation of GRASS, it is not limited to sun4 or any specific string.
+
*/
Modified: grass/trunk/lib/loc_struct.png
===================================================================
(Binary files differ)
More information about the grass-commit
mailing list