[GRASS-SVN] r38422 - grass/trunk/lib/raster

[svn_grass at osgeo.org]

Author: neteler
Date: 2009-07-15 07:34:56 -0400 (Wed, 15 Jul 2009)
New Revision: 38422

Modified:
   grass/trunk/lib/raster/rasterlib.dox
Log:
cleanup continued

Modified: grass/trunk/lib/raster/rasterlib.dox
===================================================================
--- grass/trunk/lib/raster/rasterlib.dox	2009-07-15 09:57:19 UTC (rev 38421)
+++ grass/trunk/lib/raster/rasterlib.dox	2009-07-15 11:34:56 UTC (rev 38422)
@@ -34,7 +34,7 @@
 map is to be found. Often only the unqualified raster map name is
 provided on the command line and searched in all mapsets indicated in
 the mapset search path (SEARCH_PATH file in the actual mapset; managed
-with "g.mapsets" command).
+with <tt>g.mapsets</tt> command).
 
 The following routines search the database for raster map files:
 
@@ -137,8 +137,8 @@
 
  - Rast_allocate_buf()
  - Rast_allocate_c_buf()
+ - Rast_allocate_f_buf()
  - Rast_allocate_d_buf()
- - Rast_allocate_f_buf()
 
 This routine allocates a buffer of type CELL/FCELL/DCELL just large enough
 to hold one row of raster data (based on the number of columns in the active
@@ -170,22 +170,19 @@
 
 \section Reading_Raster_Files Reading Raster Files
 
-
 Raster data can be thought of as a two-dimensional matrix. The
 routines described below read one full row of the matrix. It should be
 understood, however, that the number of rows and columns in the matrix
 is determined by the region, not the raster file itself. Raster data
-is always read resampled into the region. This allows the user to
-specify the coverage of the database during analyses. It also allows
-databases to consist of raster files which do not cover exactly the
+is always read resampled (nearest neighbor) into the region. This allows 
+the user to specify the coverage of the database during analyses. It also 
+allows databases to consist of raster files which do not cover exactly the
 same area, or do not have the same grid cell resolution. When raster
 files are resampled into the region, they all "look" the same.
 
 <b>Note:</b> The rows and columns are specified "C style", i.e.,
 starting with 0.
 
-<b>THIS FUNCTION IS DEPRECATED IN GRASS 5! SEE NEXT CHAPTER!</b>
-
  - Rast_get_row()
 
 This routine reads the specified <i>row</i> from the raster file open
@@ -218,9 +215,6 @@
 
 \subsection Writing_Raster_Files Writing Raster Files
 
-
-\todo <b>Needs updating for GRASS 5!! See later in this file.</b>
-
  - Rast_put_row()
 
 This routine writes one row of raster data from buffer to the raster
@@ -236,22 +230,16 @@
 
 \code
 int fd, row, nrows, ncols;
-
 CELL *buf;
+RASTER_MAP_TYPE data_type;
 
-fd = Rast_open_old("map"); /*...data for the row */
+fd = Rast_open_old(inmap, ""); /*...data for the row */
+data_type = Rast_get_map_type(fd);
 
-Rast_put_row(fd, buf);
+Rast_put_row(fd, buf, data_type);
 \endcode
 
- - Rast_put_row_random()
 
-This routine allows random writes to the raster file open on file
-descriptor. The raster file must have been opened using
-Rast_open_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
@@ -266,9 +254,8 @@
 <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.
+overwrite the support files. See \ref Raster_Map_Layer_Support_Routines 
+for routines which write raster support files.
 
  - Rast_unopen()
 
@@ -294,9 +281,9 @@
 <em>range</em> file. Each support file has its own data structure and
 associated routines.
 
+
 \section Raster_Header_File Raster Header File
 
-
 The raster header file contains information describing the geographic
 extent of the map layer, the grid cell resolution, and the format used
 to store the data in the raster file. The format of this file is
@@ -304,7 +291,7 @@
 use the <i>Cell_head</i> structure which is shown in detail in \ref
 GIS_Library_Data_Structures.
 
- - G_get_cellhd()
+ - Rast_get_cellhd()
 
 The raster header for the raster file in the specified mapset is read
 into the <em>cellhd</em> structure. If there is an error reading the
@@ -312,8 +299,8 @@
 returned. Otherwise, 0 is returned.
 
 <b>Note:</b> If the raster file is a reclass file, the raster header
-for the referenced raster file is read instead. See \ref
-Reclass_Format for information about reclass files, and Rast_is_reclass()
+for the referenced raster file is read instead. See \ref Reclass_Format
+for information about reclass files, and Rast_is_reclass()
 for distinguishing reclass files from regular raster files.
 
 <b>Note:</b> It is not necessary to get the raster header for a map
@@ -329,7 +316,7 @@
 This function fills in missing parts of the input cell header (or
 region). It also makes projection-specific adjustments.
 
- - G_put_cellhd()
+ - Rast_put_cellhd()
 
 This routine writes the information from the Cell_head structure to
 the raster header file for the map layer in the current mapset. If
@@ -356,9 +343,9 @@
 <tt>g.remove</tt> and <tt>r.reclass</tt> to prevent accidentally
 deleting the parent map of a reclassed raster map.
 
+
 \section Raster_Category_File Raster Category File
 
-
 GRASS map layers have category labels associated with them. The
 category file is structured so that each category in the raster file
 can have a one-line description. The format of this file is described
@@ -368,6 +355,7 @@
 use the <i>Categories</i> structure which is described in \ref
 GIS_Library_Data_Structures.
 
+
 \section Reading_and_Writing_the_Raster_Category_File Reading and Writing the Raster Category File
 
 The following routines read or write the category file itself:
@@ -401,6 +389,7 @@
 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
@@ -451,21 +440,21 @@
 Frees memory allocated by Rast_read_cats(), Rast_init_cats() and
 Rast_set_cat().
 
+
 \section Raster_Color_Table Raster Color Table
 
-
 GRASS map layers have colors associated with them. The color tables
 are structured so that each category in the raster file has its own
-color. The format of this file is described in \ref
-Raster_Color_Table_Format.
+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.
+<i>Colors</i> structure which is described in detail in 
+\ref GIS_Library_Data_Structures.
 
+
 \section Reading_and_Writing_the_Raster_Color_File Reading and Writing the Raster Color File
 
-
 The following routines read, create, modify, and write color tables.
 
  - Rast_read_colors()
@@ -499,6 +488,7 @@
 color table is actually written in the current mapset under the
 <tt>colr2</tt> element as: <tt>colr2/mapset/name</tt>.
 
+
 \section Lookup_Up_Raster_Colors Lookup Up Raster Colors
 
 These routines translates raster values to their respective colors.
@@ -509,14 +499,15 @@
 raster array are stored in the red, green, and blue arrays.
 
 <b>Note:</b> The red, green, and blue intensities will be in the range
-0 -� 255.
+0-255.
 
  - Rast_get_color()
 
 Get a category color. The red, green, and blue intensities for the
 color associated with category are extracted from the colors
-structure. The intensities will be in the range 0 �- 255.
+structure. The intensities will be in the range 0-255.
 
+
 \section Creating_and_or_Modifying_the_Color_Table Creating and/or Modifying the Color Table
 
 These routines allow the creation of customized color tables as well as the
@@ -527,17 +518,17 @@
 Initialize <i>colors</i> structure for subsequent calls
 Rast_add_color_rule() and Rast_set_color().
 
-int Rast_add_color_rule()
+ - Rast_add_color_rule()
 
-This is the heart and soul of the new color logic. It adds a color
+This is the heart and soul of the color logic. It adds a color
 rule to the <em>colors</em> structure. The colors defined by the red,
 green, and blue values are assigned to the categories
 respectively. Colors for data values between two categories are not
 stored in the structure but are interpolated when queried by
-Rast_lookup_colors() Rast_get_color(). The color components must be in the
-range 0 - 255.
+Rast_lookup_colors() and Rast_get_color(). The color components must be in the
+range 0-255.
 
-For example, to create a linear grey scale for the range 200 - 1000:
+For example, to create a linear grey scale for the range 200-1000:
 
 \code
 struct Colors colr;
@@ -547,8 +538,7 @@
 Rast_add_color_rule ((CELL) 200, 0,0,0,(CELL) 1000, 255,255,255) ;
 \endcode
 
-The programmer is encouraged to review \ref Raster_Color_Table_Format
-how this routine fits into the 5.x raster color logic.
+The programmer is encouraged to review \ref Raster_Color_Table_Format.
 
 <b>Note:</b> The <em>colors</em> structure must have been initialized
 by Rast_init_colors(). See \ref Predefined_Color_Tables for routines to
@@ -557,8 +547,8 @@
  - Rast_set_color()
 
 Set a category color. The red, green, and blue intensities for the
-color associated with category The intensities must be in the range 0
--� 255. Values below zero are set as zero, values above 255 are set as
+color associated with category The intensities must be in the range 
+0-255. Values below zero are set as zero, values above 255 are set as
 255.
 
 <b>Warning:</b> Use of this routine is discouraged because it defeats
@@ -583,9 +573,9 @@
 <b>Note:</b> This routine may be used after Rast_read_colors() as well as
 after Rast_init_colors().
 
+
 \section Predefined_Color_Tables Predefined Color Tables
 
-
 The following routines generate entire color tables. The tables are
 loaded into a <i>colors</i> structure based on a range of category
 values from minimum to maximum value. The range of values for a raster
@@ -642,11 +632,12 @@
 
  - Rast_make_histogram_eq_colors()
 
-Generates a histogram contrast-stretched grey scale color table that goes from the, histogram information.
+Generates a histogram contrast-stretched grey scale color table that goes
+from the, histogram information.
 
+
 \section Raster_History_File Raster History File
 
-
 The history file contains documentary information about the raster
 file: who created it, when it was created, what was the original data
 source, what information is contained in the raster file, etc. This
@@ -686,9 +677,9 @@
 <b>Note:</b> This routine only initializes the data structure. It does
 not write the history file.
 
+
 \section Raster_Range_File Raster Range File
 
-
 The following routines manage the raster range file. This file
 contains the minimum and maximum values found in the raster file. The
 format of this file is described in \ref Raster_Range_File_Format.
@@ -734,6 +725,7 @@
 
 Get range minimum and maximum value.
 
+
 \section Raster_Histograms Raster Histograms
 
 The following routines provide a relatively efficient mechanism for
@@ -760,7 +752,7 @@
  - Rast_update_cell_stats()
 
 Adds data to cell stats. Once all values are stored, the structure may
-be queried either randomly (ie. search for a specific raster value) or
+be queried either randomly (i.e., search for a specific raster value) or
 sequentially (retrieve all raster values, in ascending order, and
 their related count):
 
@@ -1608,6 +1600,7 @@
 
 Writes the <tt>f_quant</TT> file for the raster map with one rule. 
 
+
 \section Categories_Labeling_Functions Categories Labeling Functions (new and upgraded)
 
 \subsection Upgraded_Categories_structure Upgraded Categories structure
@@ -1859,7 +1852,7 @@
 
 <b>TODO: Reorder functions</b>
 
- - Rast_cell_size()
+\subsection MemoryAllocation Memory allocation
  - Rast_allocate_c_buf()
  - Rast_allocate_f_buf()
  - Rast_allocate_d_buf()
@@ -1869,8 +1862,24 @@
  - Rast__allocate_null_bits()
  - Rast__null_bitstream_size()
 
+\subsection RasterMask Raster Mask
  - Rast_suppress_masking()
  - Rast_unsuppress_masking()
+
+\subsection RasterStatistics Raster statistics
+ - Rast_cell_size()
+ - Rast_init_cell_stats()
+ - Rast_update_cell_stats()
+ - Rast_find_cell_stat()
+ - Rast_rewind_cell_stats()
+ - Rast_next_cell_stat()
+ - Rast_get_stats_for_null_value()
+ - Rast_free_cell_stats()
+ - Rast_cell_stats_histo_eq()
+ - Rast_get_cell_title()
+ - Rast_cell_stats_histo_eq()
+
+\subsection RasterCategories Raster category management
  - Rast_read_cats()
  - Rast_get_max_cat()
  - Rast_get_cats_title()
@@ -1903,18 +1912,12 @@
  - Rast_copy_cats()
  - Rast_number_of_cats()
  - Rast_sort_cats()
- - Rast_init_cell_stats()
- - Rast_update_cell_stats()
- - Rast_find_cell_stat()
- - Rast_rewind_cell_stats()
- - Rast_next_cell_stat()
- - Rast_get_stats_for_null_value()
- - Rast_free_cell_stats()
- - Rast_cell_stats_histo_eq()
- - Rast_get_cell_title()
- - Rast_cell_stats_histo_eq()
+
+\subsection RasterFileManagement Raster file management
  - Rast_close()
  - Rast_unopen()
+
+\subsection ColorFunctions Color functions
  - Rast_make_ryg_colors()
  - Rast_make_ryg_fp_colors()
  - Rast_make_aspect_colors()
@@ -1983,6 +1986,8 @@
  - Rast_shift_c_colors()
  - Rast_shift_d_colors()
  - Rast_write_colors()
+
+\subsection RasterFloatingPointManagement Raster floating point management
  - Rast_fpreclass_clear()
  - Rast_fpreclass_reset()
  - Rast_fpreclass_init()
@@ -2007,6 +2012,8 @@
  - Rast_fpreclass_perform_ii()
  - Rast_fpreclass_perform_if()
  - Rast_fpreclass_perform_id()
+
+\subsection RasterMapReading Raster map reading
  - Rast_get_cellhd()
  - Rast_get_row_nomask()
  - Rast_get_c_row_nomask()
@@ -2018,6 +2025,8 @@
  - Rast_get_d_row()
  - Rast_get_null_value_row()
  - Rast_get_row_colors()
+
+\subsection RasterMapHistogram Raster map histogram
  - Rast_histogram_eq()
  - Rast_init_histogram()
  - Rast_read_histogram()
@@ -2035,14 +2044,46 @@
  - Rast_set_histogram()
  - Rast_extend_histogram()
  - Rast_zero_histogram()
+ - Rast_want_histogram()
+
+\subsection RasterMapHistory Raster map history
  - Rast_read_history()
  - Rast_write_history()
  - Rast_short_history()
  - Rast_command_history()
+
+\subsection RasterMapInterpolation Raster map interpolation
  - Rast_interp_linear()
  - Rast_interp_bilinear()
  - Rast_interp_cubic()
  - Rast_interp_bicubic()
+
+\subsection RasterMapQuantization Raster map quantization
+ - Rast_quant_clear()
+ - Rast_quant_free()
+ - Rast_quant_init()
+ - Rast_quant_is_truncate()
+ - Rast_quant_is_round()
+ - Rast_quant_truncate()
+ - Rast_quant_round()
+ - Rast_quant_get_limits()
+ - Rast_quant_nof_rules()
+ - Rast_quant_get_ith_rule()
+ - Rast_quant_set_neg_infinite_rule()
+ - Rast_quant_get_neg_infinite_rule()
+ - Rast_quant_set_pos_infinite_rule()
+ - Rast_quant_get_pos_infinite_rule()
+ - Rast_quant_add_rule()
+ - Rast_quant_reverse_rule_order()
+ - Rast_quant_get_cell_value()
+ - Rast_quant_perform_d()
+ - Rast_quant_perform_f()
+ - Rast_quantize_fp_map()
+ - Rast_quantize_fp_map_range()
+ - Rast_write_quant()
+ - Rast_read_quant()
+
+\subsection ToDo yet unsorted functions
  - Rast_maskfd()
  - Rast_mask_info()
  - Rast_set_null_value()
@@ -2060,7 +2101,6 @@
  - Rast_open_old()
  - Rast_open_c_new()
  - Rast_open_c_new_uncompressed()
- - Rast_want_histogram()
  - Rast_set_cell_format()
  - Rast_get_cell_format()
  - Rast_open_fp_new()
@@ -2078,31 +2118,8 @@
  - Rast_put_f_row()
  - Rast_put_d_row()
  - Rast_put_cell_title()
- - Rast_quant_clear()
- - Rast_quant_free()
- - Rast_quant_init()
- - Rast_quant_is_truncate()
- - Rast_quant_is_round()
- - Rast_quant_truncate()
- - Rast_quant_round()
- - Rast_quant_get_limits()
- - Rast_quant_nof_rules()
- - Rast_quant_get_ith_rule()
- - Rast_quant_set_neg_infinite_rule()
- - Rast_quant_get_neg_infinite_rule()
- - Rast_quant_set_pos_infinite_rule()
- - Rast_quant_get_pos_infinite_rule()
- - Rast_quant_add_rule()
- - Rast_quant_reverse_rule_order()
- - Rast_quant_get_cell_value()
- - Rast_quant_perform_d()
- - Rast_quant_perform_f()
  - Rast_truncate_fp_map()
  - Rast_round_fp_map()
- - Rast_quantize_fp_map()
- - Rast_quantize_fp_map_range()
- - Rast_write_quant()
- - Rast_read_quant()
  - Rast_construct_default_range()
  - Rast_read_fp_range()
  - Rast_read_range()