[GRASS-SVN] r47538 - in grass/trunk: . lib/raster3d
svn_grass at osgeo.org
svn_grass at osgeo.org
Wed Aug 10 13:49:39 EDT 2011
Author: martinl
Date: 2011-08-10 10:49:39 -0700 (Wed, 10 Aug 2011)
New Revision: 47538
Added:
grass/trunk/lib/raster3d/raster3dlib.dox
Removed:
grass/trunk/lib/raster3d/lib.dox
Modified:
grass/trunk/grasslib.dox
grass/trunk/lib/raster3d/Makefile
Log:
doxygen: g3d renamed to raster3d
Modified: grass/trunk/grasslib.dox
===================================================================
--- grass/trunk/grasslib.dox 2011-08-10 17:27:10 UTC (rev 47537)
+++ grass/trunk/grasslib.dox 2011-08-10 17:49:39 UTC (rev 47538)
@@ -93,7 +93,7 @@
\subsection rasteribs Raster Libraries
- edit: Raster edit library (cellhd, history, cats) - \ref edit
- - g3d: \ref g3dlib
+ - raster3d: \ref raster3dlib
- raster: \ref rasterlib
- rowio: \ref rowiolib
- rst: \ref rst - Library for interpolation with regularized splines with tension
Modified: grass/trunk/lib/raster3d/Makefile
===================================================================
--- grass/trunk/lib/raster3d/Makefile 2011-08-10 17:27:10 UTC (rev 47537)
+++ grass/trunk/lib/raster3d/Makefile 2011-08-10 17:49:39 UTC (rev 47538)
@@ -2,11 +2,10 @@
LIB = RASTER3D
-
include $(MODULE_TOPDIR)/include/Make/Lib.make
include $(MODULE_TOPDIR)/include/Make/Doxygen.make
default: lib
#doxygen:
-DOXNAME=g3d
+DOXNAME=raster3d
Deleted: grass/trunk/lib/raster3d/lib.dox
===================================================================
--- grass/trunk/lib/raster3d/lib.dox 2011-08-10 17:27:10 UTC (rev 47537)
+++ grass/trunk/lib/raster3d/lib.dox 2011-08-10 17:49:39 UTC (rev 47538)
@@ -1,1758 +0,0 @@
-/*! \page g3dlib GRASS Grid3D raster volume Library
-<!-- doxygenized from "GRASS 5 Programmer's Manual"
- by M. Neteler 5/2004, 8/2005
- -->
-
-\section g3dintro Grid3D raster volume Library
-
-
-<P>
-Authors: Roman Waupotitsch and Michael Shapiro, Helena Mitasova,
- Bill Brown, Lubos Mitas, Jaro Hofierka,
- Minor modification, code cleanup and test suite by Soeren Gebbert
-
-
-
-<b>Overview</b>
-
-The Grid3D raster volume Library is used for the r3.* and vector
-volume tools. The RASTER3D library uses a tile cache based approach to store floating point
- values in abritrary order in a volume. The coordinate system of a volume is
-column and row compatible to the raster library and counts from the bottom to the top
-of the cube.
-
-<center>
-<img src=g3d_volume_layout.png border=0><BR>
-<table border=0 width=700>
-<tr><td><center>
-<i>The volume coordinate system and tile layout of the RASTER3D library</i>
-</center></td></tr>
-</table>
-</center>
-
-
-\section Directory_Structure Directory Structure
-
-<P>
-The file format consists of a mapset element <EM>grid3</EM> which contains a
-directory for every map. The elements for each map are
-
-<P>
-\verbatim
- 3d region file
- color file (color)
- categories file (cats)
- range file (range)
- timestamp file /* not yet implemented */
- cell file (cell)
- header file (cellhd)
- a directory containing display files (dsp)
-\endverbatim
-
-<P>
-There is also a <EM>colr2</EM> mechanism provided. <EM>colr2</EM> color tables
-are stored in <EM>grid3/colr2/MAPSET/MAP</EM>.
-
-<P>
-Note: color, categories, and the range can be used in the same way as in <EM>2d</EM>
-GRASS with the exception of reading and writng. <EM>3d</EM> read and write
-functions have to be used for this purpose.
-
-
-\section Data_File_Format Data File Format
-
-
-<UL>
-<LI>Cell-values can be either double or float.
-</LI>
-<LI>Values are written in XDR-format.
-</LI>
-<LI>NULL-values are stored in an embedded fashion.
-</LI>
-<LI>The cell-values are organized in <EM>3d</EM>-tiles.
-</LI>
-<LI>The tile dimensions can be chosen when a new map is opened.
-</LI>
-<LI>Every tile of a map has the same dimension except those which overlap the
- region boundaries.
-</LI>
-<LI>Compression is used to store tiles.
-</LI>
-</UL>
-
-<P>
-The data file has the following format:
-
-<P>
-\verbatim
- xdr_int nofBytesLong;
- xdr_int nofBytesUsed;
- encoded_long indexOffset;
- compressed_tile[] tiles;
- compressed_encoded_long[] index;
-\endverbatim
-
-<P>
-
-\section Transportability_of_data_file Transportability of data file
-
-<P>
-All numbers stored in the data file are either XDR-encoded or encoded by some
-other method (for variables of type long only).
-
-<P>
-
-\section Tile_Data_NULL_values Tile Data NULL-values
-
-<P>
-RASTER3D uses the same functions as <EM>2d</EM> GRASS to set and test NULL-values. The
-storage in the file is different though. NULL-values are stored with a special
-bit-pattern if maximum precision is chosen. They are stored by adding an
-additional bit if the precision is smaller.
-
-<P>
-
-\section Tile_Data_Compression Tile Data Compression
-
-<P>
-There are three methods of compression provided. The compression
-methods can either be those defined by default, set by environment
-variables or explicitly set at run-time.
-
-\verbatim
- Precision
- RLE
-\endverbatim
-
-<P>
-Precision indicates how many of the mantissa bits should be stored on
-file. This number can be any value between 0 and 23 for floats and
-between 0 and 52 for doubles. Choosing a small precision is the most
-effective way to achieve good compression.
-
-<P>
-RLE takes advantage of possible repetitions of the
-exponents and the NULL-bit structure. Using RLE does not significantly
-increase the running time. If for some tile the non-RLEed version is
-smaller in size, RLE is not used for this tile.
-
-<P>
-The default and suggested setting is to use precision and RLE.
-
-<P>
-Additional compression is achieved by storing the extra NULL-bit in a
-separate bit-array. Using this scheme NULL-values need not actually be
-represented in the array of cell values. This array is stored together
-with the cell-values of the tile.
-
-
-\section Tile_Cache Tile Cache
-
-<P>
-Tiles can either be read and written directly or use an intermediate
-cache instead.
-
-<P>
-In non-cache mode the application should only use the functions
-
-<P>
-int Rast3d_readTile()
-
-<P>
-and
-
-<P>
-int Rast3d_writeTile()
-
-<P>
-to read and write tiles. The application can use one tile provided by the map
-structure as buffer. See <TT>Rast3d_getTilePtr()</TT>.
-
-<P>
-In cache mode the application can access cell-values directly by their
-coordinates. The corresponding functions are
-
-<P>
-int Rast3d_getValue()
-
-<P>
-and
-
-<P>
-int Rast3d_putValue()
-
-<P>
-and their corresponding typed versions.
-<BR>
-<P>
-If the map is new then in addition to the memory-cache a file-cache is provided.
-This allows the application to write the cell-values in any arbitrary order.
-Tiles are written (flushed) to the data-file either at closing time or if
-explicitly requested.
-<BR>
-<P>
-If the map is new <TT>Rast3d_getValue()</TT> can be used even if the tile which
-contains the cell has already been flushed to the data file. In this case the
-tile is simply read back into the memory-cache from the data file.
-<BR>
-<P>
-Explicitly flushing tiles can have the advantage that less disk space is
-occupied since tiles are stored in a uncompressed fashion in the file-cache.
-Flushing tiles explicitly can cause problems with accuracy though if precision
-is less than the maximum precision and an already flushed value is used for
-computations later in the program.
-<BR>
-<P>
-The type of the cell-values of the tiles in memory can be chosen independently
-of the type of the tiles in the file. Here, once again one has to consider
-possible problems arising from mixing different precisions.
-<BR>
-<P>
-As an example consider the case where the data is stored in the file with double
-precision and the tiles are stored in memory in single precision. Then using
-<TT>Rast3d_getValue()</TT> will actually return a double precision number whose precision
-is only 23 bits. It is therefore a good idea to use the types in the memory
-consistently.
-<BR>
-<P>
-
-\section Header_File Header File
-
-<P>
-The header file has the following format:
-
-<P>
-\verbatim
-Proj: 1
-Zone: 1
-North: 2.0000000000000
-South: 0.5000000000000
-East: 4.0000000000000
-West: 3.0000000000000
-Top: 6.0000000000000
-Bottom: 5.0000000000000
-nofRows: 30
-nofCols: 20
-nofDepths: 14
-e-w resol: 0.05
-n-s resol: 0.05
-t-b resol: 0.071428571
-TileDimensionX: 8
-TileDimensionY: 8
-TileDimensionZ: 8
-CellType: double
-useCompression: 1
-useRle: 1
-Precision: -1
-nofHeaderBytes: 12
-useXdr: 1
-hasIndex: 1
-Units: none
-\endverbatim
-
-<P>
-Except for the first 14 fields the entries of the header file should
-not be modified. The precision value -1 indicates that maximum
-precision is used.
-<BR>
-<P>
-Binary files not in RASTER3D format can be read by the library. The
-following actions have to be taken:
-
-<P>
-Make a new map directory in the <EM>grid3</EM> element of the mapset (say <EM>mymap</EM>).
- Copy the file into <EM>mymap/cell</EM> and generate a header file <EM>mymap/cellhd</EM>.
-
-<P>
-In the following example the relevant values of <EM>mymap/cellhd</EM> are shown:
-
-<P>
-\verbatim
-TileDimensionX: A
-TileDimensionY: B
-TileDimensionZ: C
-useCompression: 0
-useRle: 0
-Precision: -1
-nofHeaderBytes: X
-useXdr: 0
-hasIndex: 0
-\endverbatim
-
-<P>
-The values of <EM>A</EM>, <EM>B</EM>, and <EM>C</EM> have to be chosen
-according to one of the following patterns:
-
-<P>
-\verbatim
-A >= 1, B == 1, C == 1, or
-A >= nofRows, B >= 1, C == 1, or
-A >= nofRows, B >= nofCols, C >= 1.
-\endverbatim
-
-<P>
-A larger tile size reduces the number of tile-reads. If in the third pattern
-<EM>C</EM> is chosen larger than or equal to <EM>nofDepths</EM>, the entire region is
-considered one large tile.
-
-<P>
-The value <EM>nofHeaderBytes</EM> indicates the offset in the file to the first
-data entry.
-
-<P>
-For performance reasons it is a good idea to use function
-<TT>Rast3d_retile()</TT> before using the file in other applications.
-
-<P>
-
-\section Region_Structure Region Structure
-
-<P>
-\verbatim
-typedef struct{
-
- double north, south;
- double east, west;
- double top, bottom;
-
- int rows, cols, depths;/* data dimensions in cells */
-
- double ns_res, ew_res, tb_res;
-
- int proj; /* Projection (see gis.h) */
- int zone; /* Projection zone (see gis.h) */
-
-} RASTER3D\_Region;
-\endverbatim
-
-<P>
-
-\section Windows Windows
-
-<P>
-Window capability similar to that of <EM>2d</EM> GRASS is provided (compare
-Region). Additional features are the window for the third dimension
-as well as the possibility to choose a different window for every map. The
-window can be specified at the time of opening an old map. It can be modified
-at any time later in the program. The resampling method can be the default
-nearest neighbor method as well as an application provided method.
-<BR>
-<P>
-The default <EM>3d</EM> window file is <EM>WIND3</EM> located in the mapset.
-Application programs should use <TT>Rast3d_useWindowParams()</TT> to allow the
-user to overwrite this default.
-
-<P>
-The window file has the following format:
-
-<P>
-\verbatim
-Proj: 1
-Zone: 1
-North: 2.0
-South: 0.5
-East: 4.0
-West: 3.0
-Top: 5.0
-Bottom: 6.0
-nofRows: 30
-nofCols: 20
-nofDepths: 14
-e-w resol: 0.05000000000000000
-n-s resol: 0.05000000000000000
-t-b resol: 0.07142857142857142
-\endverbatim
-
-<P>
-Note: after reading the window file the fields <EM>e-w</EM>, <EM>n-s</EM>, and <EM>t-b</EM>
- are recomputed internally.
-
-<P>
-A note about windows and caching. Caching is performed on the level of tiles
-read from the file. There is no caching performed on resampled data. This is
-different from <EM>2d</EM> GRASS since resampling for a specific value is
-performed every time it is being accessed.
-
-<P>
-
-\section Masks Masks
-
-<P>
-RASTER3D provides a mask for the <EM>3d</EM> region. The mask structure is
-automatically initialized at the time the first file is opened. The same
-structure is used for all the files. The default for every file is that the
-mask is turned off. If masking should be performed, the application program has
-to turn on masking explicitly. If masking is turned on for a file, the
-cell-values of a tile are automatically checked against the mask. Values which
-are masked out, are set to NULL.
-
-<P>
-Note: changing the status of masking after one or more tiles have already
-been read does not affect the tiles which are already stored in the cache.
-
-<P>
-Any arbitrary 3d raster map can be used as mask file: NULL-values are interpreted as
- <TT>"mask-out"</TT>, all other values are interpreted as <TT>"don't mask
- out"</TT>. Using <EM>r3.mask</EM> to convert a 3d raster map into a mask file instead of
-simply copying (or renaming) the directory will significantly reduce to amount
-of disk space and the access time for the mask.
-
-<P>
-
-\section Include_File Include File
-
-<P>
-Exported RASTER3D constants and structures can be found in <EM>G3d.h</EM>.
-
-<P>
-
-\section RASTER3D_Defaults RASTER3D Defaults
-
-<P>
-There are three methods to set default variables. First, the default can be set
-at compile time in <EM>g3ddefault.c</EM>. This value has lowest priority.
-
-<P>
-Second, the default can be set via an environment variable. Third, the value
-can be set explicitly set at run time. This value has highest priority.
-
-<P>
-There are also functions provided to query the value.
-
-<P>
-
-\section Cache_Mode Cache Mode
-
-<P>
-
-\subsection Limiting_the_maximum_cache_size Limiting the maximum cache size
-
-<P>
-The limit is specified in bytes. It is a limit on the size of cell-data stored
-in the cache and does not include the support structure.
-
-<P>
-Default RASTER3D_CACHE_SIZE_MAX_DEFAULT. This is currently set to 16meg and can
-be changed at compilation time of the library.
-
-<P>
-Environment variable RASTER3D_MAX_CACHE_SIZE.
-
-<P>
-void Rast3d_setCacheLimit(int nBytes)Set cache limit
-
-<P>
-int Rast3d_getCacheLimit(int nBytes)Get cache limit
-
-<P>
-
-\subsection Setting_the_cache_size Setting the cache size
-
-<P>
-This value specifies the number of tiles stored in the cache. It is the value
-used if at opening time of a map RASTER3D_USE_CACHE_DEFAULT is used for the cache
-mode. Any other value used at opening time will supersede the default value. A
-default value of 0 indicates that non-cache mode should be used by default.
-
-<P>
-Default RASTER3D_CACHE_SIZE_DEFAULT. This is currently set to 1000 and can be
-changed at compilation time of the library.
-
-<P>
-Environment variable RASTER3D_DEFAULT_CACHE_SIZE.
-
-<P>
-void Rast3d_setCacheSize(int nTiles)
-
-<P>
-int Rast3d_getCacheSize()
-
-<P>
-
-\section Compression Compression
-
-\subsection Toggling_compression_mode Toggling compression mode
-
-<P>
-This value specifies whether compression should be used while writing a new
-map. It does not have any effect on old maps.
-
-<P>
-Default RASTER3D_COMPRESSION_DEFAULT. This is set to RASTER3D_COMPRESSION. This
-default should not be changed.
-
-<P>
-Environment variables RASTER3D_USE_COMPRESSION and RASTER3D_NO_COMPRESSION.
-
-<P>
-See functions Rast3d_setCompressionMode() (cf.
-Section 22.3.2.3 ) and Rast3d_getCompressionMode() (cf. Section 22.3.2.3 ).
-
-<P>
-
-\subsection Toggling_RLE_compression Toggling RLE compression
-
-<P>
-This value specifies whether RLE compression should be used (in addition to
-precision).
-
-<P>
-Default RASTER3D_USE_RLE_DEFAULT. This is currently set to RASTER3D_USE_RLE and can
-be changed at compilation time of the library.
-
-<P>
-Environment variables RASTER3D_USE_RLE and RASTER3D_NO_RLE.
-
-<P>
-See functions Rast3d_setCompressionMode() (cf.
-Section 22.3.2.3) and Rast3d_getCompressionMode() (cf. Section 22.3.2.3).
-
-\section Setting_the_precision Setting the precision
-
-<P>
-This number specifies how many mantissa bits should be used when writing a cell
-value. The minimum value is 0. The maximum value is 23 or RASTER3D_MAX_PRECISION
-for type FCELL_TYPE, it is 52 or RASTER3D_MAX_PRECISION for type DCELL_TYPE.
-
-<P>
-Default RASTER3D_PRECISION_DEFAULT. This is set to RASTER3D_MAX_PRECISION. This
-default should not be changed.
-
-<P>
-Environment variables RASTER3D_PRECISION and RASTER3D_MAX_PRECISION.
-
-<P>
-void Rast3d_setCompressionMode(int doCompress, int doLzw, int doRle, int
- precision) <EM>doCompress</EM> should be one of RASTER3D_NO_COMPRESSION and
- RASTER3D_COMPRESSION, <EM>doRle</EM> should be either RASTER3D_NO_RLE or
- RASTER3D_USE_RLE, and <EM>precision</EM> should be either RASTER3D_MAX_PRECISION or
- a positive integer.
-
-<P>
-void Rast3d_getCompressionMode(int *doCompress, int *doLzw, int *doRle,
- int *precision)
-
-<P>
-
-\section Tiles Tiles
-
-\subsection Setting_the_tile_dimensions Setting the tile dimensions
-
-<P>
-The dimensions are specified in number of cell.
-
-<P>
-Defaults RASTER3D_TILE_X_DEFAULT, RASTER3D_TILE_Y_DEFAULT, and
-RASTER3D_TILE_Z_DEFAULT. These are currently set to 8 and can be changed at
-compilation time of the library.
-
-<P>
-Environment variables RASTER3D_TILE_DIMENSION_X, RASTER3D_TILE_DIMENSION_Y, and
-RASTER3D_TILE_DIMENSION_Z.
-
-<P>
-void Rast3d_setTileDimension(int tileX, int tileY, int tileZ)
-
-<P>
-void Rast3d_getTileDimension(int *tileX, int *tileY, int *tileZ)
-
-<P>
-
-\section Setting_the_tile_cell_value_type Setting the tile cell-value type
-
-<P>
-Specifies which type is used to write cell-values on file. This type can be
-chosen independently of the type used to store cell-values in memory.
-
-<P>
-Default RASTER3D_FILE_TYPE_DEFAULT. This is set to DCELL_TYPE. This default
-should not be changed.
-
-<P>
-Environment variables RASTER3D_WRITE_FLOAT and RASTER3D_WRITE_DOUBLE.
-
-<P>
-void Rast3d_setFileType(int type)
-
-<P>
-int Rast3d_getFileType(int type)
-
-<P>
-
-\section Setting_the_window Setting the window
-
-<P>
-The window is set from a <EM>3d</EM> window file.
-
-<P>
-The default <EM>3d</EM> window file is <EM>WIND3</EM> located in the current mapset.
-
-<P>
-Possible choices for <EM>3d</EM> window files are <EM>name</EM> which refers to a
-window file in the <EM>3d</EM> window database located at <EM>windows3d</EM> of the
-current mapset; or file names which are identified by a leading <EM><TT>"/"</TT></EM>
-or <EM><TT>"."</TT></EM>; or fully qualified
-names, i.e. <EM>file at mapset</EM> which refer to window files in the <EM>3d</EM> window
-database of mapset. Note, that names <EM>WIND3</EM> and <EM>WIND3 at mapset</EM> do not
-specify the default window name in the (current)
-mapset but rather a window file in the window database of the (current) mapset.
-
-<P>
-Environment variable RASTER3D_DEFAULT_WINDOW3D.
-
-<P>
-See functions
-
-<P>
-<TT>Rast3d_useWindowParams()</TT>,
-
-<P>
-<TT>Rast3d_setWindow()</TT>, and
-
-<P>
-<TT>Rast3d_setWindowMap()</TT>.
-
-<P>
-
-\section Setting_the_Units Setting the Units
-
-<P>
-Default <TT>"none"</TT>.
-
-<P>
-No environment variable.
-
-<P>
-void Rast3d_setUnit (unit)
- char *unit;
-
-<P>
-
-\section Error_Handling Error Handling: Setting the error function
-
-<P>
-This variable specifies the function which is invoked when an error
-(not a fatal error) occurs. For example setting the error function to
-<TT>Rast3d_fatalError</TT> simplifies debugging with dbx and also might show
-errors which are missed because the application does not check the
-return value.
-
-<P>
-Default <TT>Rast3d_skipError</TT>.
-
-<P>
-Environment variables RASTER3D_USE_FATAL_ERROR and RASTER3D_USE_PRINT_ERROR.
-
-<P>
-void Rast3d_setErrorFun(void (*fun)(char *))
-
-<P>
-The following 3 functions are possible choices for error functions.
-
-<P>
-void Rast3d_skipError(char (*msg)(char *)) This function ignores the
- error.
-
-<P>
-void Rast3d_printError(char (*msg)(char *)) This function prints the
- error message <EM>msg</EM> to <EM>stderr</EM> and returns.
-
-<P>
-void Rast3d_fatalError(char (*msg)(char *)) This function prints the
- error message <EM>msg</EM> to <EM>stderr</EM>, flushes <EM>stdout</EM>
- and <EM>stderr</EM>, and terminates the program with a segementation fault.
-
-<P>
-
-\section RASTER3D_Function_Index RASTER3D Function Index
-
-\subsection Opening_and_Closing_RASTER3D_Files Opening and Closing RASTER3D Files
-
-<P>
-void *Rast3d_openCellOld(char *name, char *mapset, RASTER3D_Region *window,
- int type, int cache)Opens existing g3d-file <EM>name</EM> in <EM>mapset</EM>.
-
-<P>
-Tiles are stored in memory with <EM>type</EM> which must be any of FCELL_TYPE,
- DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies the
- cache-mode used and must be either RASTER3D_NO_CACHE, RASTER3D_USE_CACHE_DEFAULT,
- RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
- RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ,
- RASTER3D_USE_CACHE_XYZ, the result of <TT>Rast3d_cacheSizeEncode()</TT> (cf.
- Section 22.4.6), or any positive integer which
- specifies the number of tiles buffered in the cache. <EM>window</EM> sets the
- window-region for the map. It is either a pointer to a window structure or
- RASTER3D_DEFAULT_WINDOW, which uses the window stored at initialization time or
- set via <TT>Rast3d_setWindow()</TT> (cf. Section 22.4.16).
- To modify the window for the map after it has already been opened use
- <TT>Rast3d_setWindowMap()</TT> (cf. Section 22.4.16).
-
-<P>
-Returns a pointer to the cell structure ... if successful, NULL ...
- otherwise.
-
-<P>
-void *Rast3d_openCellNew(char *name, int type, int cache, RASTER3D_Region
- *region)Opens new g3d-file with <EM>name</EM> in the current mapset. Tiles
- are stored in memory with <EM>type</EM> which must be one of FCELL_TYPE,
- DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies the
- cache-mode used and must be either RASTER3D_NO_CACHE, RASTER3D_USE_CACHE_DEFAULT,
- RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
- RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ,
- RASTER3D_USE_CACHE_XYZ, the result of <TT>Rast3d_cacheSizeEncode()</TT> (cf.
- Section 22.4.6), or any positive integer which
- specifies the number of tiles buffered in the cache. <EM>region</EM> specifies
- the 3d region.
-
-<P>
-Returns a pointer to the cell structure ... if successful,
- NULL ... otherwise.
-
-<P>
-void *Rast3d_openCellNewParam(char *name, int typeIntern, int cache,
- RASTER3D_Region *region, int type, int doLzw, int doRle, int precision, int tileX,
- int tileY, int tileZ)Opens new g3d-file with <EM>name</EM> in the current
- mapset. Tiles are stored in memory with <EM>typeIntern</EM> which must be one of
- FCELL_TYPE, DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies
- the cache-mode used and must be either RASTER3D_NO_CACHE,
- RASTER3D_USE_CACHE_DEFAULT, RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y,
- RASTER3D_USE_CACHE_Z, RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ,
- RASTER3D_USE_CACHE_YZ, RASTER3D_USE_CACHE_XYZ, the result of
- <TT>Rast3d_cacheSizeEncode()</TT> (cf.
- Section 22.4.6), or any positive integer which
- specifies the number of tiles buffered in the cache. <EM>region</EM> specifies
- the 3d region.
-
-<P>
-In addition the properties of the new file have to be specified. It is
- assumed by default that compression is used. This function first sets the
- global default values to the specified values, and then restores the original
- global defaults. This function can be used in conjunction with
- <TT>Rast3d_setStandard3dInputParams()</TT> (cf.
- Section 22.4.18) and
- <TT>Rast3d_getStandard3dParams()</TT>.
-
-<P>
-Returns a pointer to the cell structure ... if successful, NULL ...
- otherwise.
-
-<P>
-int Rast3d_closeCell(void *map)Closes g3d-file. If <EM>map</EM> is new
- and cache-mode is used for <EM>map</EM> then every tile which is not flushed
- before closing is flushed.
-
-<P>
-Returns 1 ... if successful, 0 ... otherwise.
-
-<P>
-
-\subsection Reading_and_Writing_Tiles Reading and Writing Tiles
-
-<P>
-These functions read or write data directly to the file (after performing the
-appropriate compression) without going through the cache. In order to avoid
-unexpected side-effects the use of these functions in cache mode is
-discouraged.
-
-<P>
-int Rast3d_readTile(void *map, char *tileIndex, int tile, int type)
- Reads tile with index <EM>tileIndex</EM> into the <EM>tile</EM> buffer. The cells
- are stored with type <EM>type</EM> which must be one of FCELL_TYPE and
- DCELL_TYPE. If the tile with <EM>tileIndex</EM> is not stored on the file
- corresponding to <EM>map</EM>, and <EM>tileIndex</EM> is a valid index <EM>tile</EM>
- is filled with NULL-values.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_readTileFloat(void *map, char *tileIndex, int tile)
-Is equivalent to Rast3d_readTile (map, tileIndex, tile, FCELL_TYPE).
-
-<P>
-int Rast3d_readTileDouble(void *map, char *tileIndex, int tile)
-Is equivalent to Rast3d_readTile (map, tileIndex, tile, DCELL_TYPE).
-
-<P>
-int Rast3d_writeTile(void *map, char *tileIndex, int tile, int type)
- Writes tile with index <EM>tileIndex</EM> to the file corresponding to <EM>map</EM>. It is assumed that the cells in <EM>tile</EM> are of <EM>type</EM> which
- must be one of FCELL_TYPE and DCELL_TYPE. The actual type used to write the
- tile depends on the type specified at the time when <EM>map</EM> is initialized.
-
-<P>
-A tile can only be written once. Subsequent attempts to write the same tile
- are ignored.
-
-<P>
-Returns
- 1 ... if successful,
- 2 ... if write request was ignored,
- 0 ... otherwise.
-
-<P>
-int Rast3d_writeTileFloat(void *map, char *tileIndex, int tile)
-Is equivalent to <TT>Rast3d_writeTile (map, tileIndex, tile, FCELL_TYPE).</TT>
-
-<P>
-int Rast3d_writeTileDouble(void *map, char *tileIndex, int tile)
-Is equivalent to <TT>Rast3d_writeTile (map, tileIndex, tile, DCELL_TYPE).</TT>
-
-<P>
-
-\subsection Reading_and_Writing_Cells Reading and Writing Cells
-
-<P>
-void Rast3d_getValue(void *map, int x, int y, int z, char *value, int
- type) Returns in <EM>*value</EM> the cell-value of the cell with
- window-coordinate <EM>(x, y, z)</EM>. The value returned is of <EM>type</EM>.
-
-<P>
-This function invokes a fatal error if an error occurs.
-
-<P>
-float Rast3d_getFloat(void *map, int x, int y, int z)Is equivalent to
- <TT>Rast3d_getValue (map, x, y, z, &value, FCELL_TYPE);</TT> return value.
-
-<P>
-double Rast3d_getDouble(void *map, int x, int y, int z)Is equivalent
- to <TT>Rast3d_getValue (map, x, y, z, &value, DCELL_TYPE);</TT> return value.
-
-<P>
-void Rast3d_getValueRegion(void *map, int x, int y, int z, char*value,
- int type) Returns in <EM>*value</EM> the cell-value of the cell with
- region-coordinate <EM>(x, y, z)</EM>. The value returned is of <EM>type</EM>.
- Here <EM>region</EM> means the coordinate in the cube of data in the file, i.e.
- ignoring geographic coordinates.
-
-<P>
-This function invokes a fatal error if an error occurs.
-
-<P>
-float Rast3d_getFloatRegion(void *map, int x, int y, int z)Is
- equivalent to <TT>Rast3d_getValueRegion (map, x, y, z, &value, FCELL_TYPE);</TT>
- return value.
-
-<P>
-double Rast3d_getDoubleRegion(void *map, int x, int y, int z)Is
- equivalent to <TT>Rast3d_getValueRegion (map, x, y, z, &value,
- DCELL_TYPE);</TT> return value.
-
-<P>
-int Rast3d_putValue(void *map, int x, int y, int z, char *value, int
- type)After converting <EM>*value</EM> of <EM>type</EM> into the type specified
- at the initialization time (i.e. <EM>typeIntern</EM>) this function writes the
- value into the tile buffer corresponding to cell-coordinate <EM>(x, y, z)</EM>.
-
-<P>
-Returns
-
-<P>
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_putFloat(void *map, int x, int y, int z, char *value)Is
- equivalent to Rast3d_putValue (map, x, y, z, &value, FCELL_TYPE).
-
-<P>
-int Rast3d_putDouble(void *map, int x, int y, int z, char *value) Is
- equivalent to Rast3d_putValue (map, x, y, z, &value, DCELL_TYPE).
-
-<P>
-
-\subsection Loading_and_Removing_TilesLoading and Removing Tiles
-
-<P>
-char *Rast3d_getTilePtr(void *map, int tileIndex) This function
- returns a pointer to a tile which contains the data for the tile with index
- <EM>tileIndex</EM>. The type of the data stored in the tile depends on the type
- specified at the initialization time of <EM>map</EM>. The functionality is
- different depending on whether <EM>map</EM> is old or new and depending on the
- cache-mode of <EM>map</EM>.
-<BR>
-<P>
-If <EM>map</EM> is old and the cache is not used the tile with <EM>tileIndex</EM>
- is read from file and stored in the buffer provided by the map structure.
- The pointer to this buffer is returned. If the buffer already contains the
- tile with <EM>tileIndex</EM> reading is skipped. Data which was stored in
- earlier calls to <TT>Rast3d_getTilePtr</TT> is destroyed. If the tile with
- <EM>tileIndex</EM> is not stored on the file corresponding to <EM>map</EM>, and
- <EM>tileIndex</EM> is a valid index the buffer is filled with NULL-values.
-<BR>
-<P>
-If <EM>map</EM> is old and the cache is used the tile with <EM>tileIndex</EM> is
- read from file and stored in one of the cache buffers. The pointer to buffer
- is returned. If no free cache buffer is available an unlocked cache-buffer
- is freed up and the new tile is stored in its place. If the tile with
- <EM>tileIndex</EM> is not stored on the file corresponding to <EM>map</EM>, and
- <EM>tileIndex</EM> is a valid index the buffer is filled with NULL-values. If one
- of the cache buffers already contains the tile with <EM>tileIndex</EM> reading
- is skipped and the pointer to this buffer is returned.
-<BR>
-<P>
-If <EM>map</EM> is new and the cache is not used the functionality is the same
- as if <EM>map</EM> is old and the cache is not used. If the tile with
- <EM>tileIndex</EM> is already stored on file, it is read into the buffer, if not,
- the cells are set to null-values. If the buffer corresponding to the pointer
- is used for writing, subsequent calls to <TT>Rast3d_getTilePtr</TT> may destroy the
- values already stored in the buffer. Use <TT>Rast3d_flushTile</TT> to write the buffer
- to the file before reusing it for a different index. The use of this buffer
- as write buffer is discouraged.
-<BR>
-<P>
-If <EM>map</EM> is new and the cache is used the functionality is the same as if
- <EM>map</EM> is old and the cache is used with the following exception. If
- <EM>tileIndex</EM> is a valid index and the tile with this index is not found in
- the cache and is not stored on the file corresponding to <EM>map</EM>, then the
- file cache is queried next. If the file-cache contains the tile it is loaded
- into the cache (memory-cache). Only if the file-cache does not contain the
- tile it is filled with NULL-values. Tile contents of buffers are never
- destroyed. If a cache buffer needs to be freed up, and the tile stored in the
- buffer has not been written to the file corresponding to <EM>map</EM> yet, the
- tile is copied into the file-cache.
-<BR>
-<P>
-Care has to be taken if this function is used in non-cache mode since it is
- implicitly invoked every time a read or write request is issued. The only
- I/O-functions for which it is safe to assume that they do not invoke
- <TT>Rast3d_getTilePtr</TT> are <TT>Rast3d_readTile()</TT> and
- <TT>Rast3d_writeTile()</TT> and their corresponding type-specific versions.
-
-<P>
-Returns
- a pointer to a buffer ... if successful,
- NULL ... otherwise.
-
-<P>
-int Rast3d_tileLoad(void *map, int tileIndex)
-Same functionality as <TT>Rast3d_getTilePtr()</TT> but does not return the
-pointer.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_removeTile(void *map, inttileIndex) Removes a tile
- from memory-cache if tile is in memory-cache. For new maps the
- application does not know whether the tile is in the memory-cache or in
- the file-cache. Therefore, for new maps this function should be
- preceded by <TT>Rast3d_tileLoad()</TT>.
-
-<P>
-<EM>(Question: Is this a useful function?)</EM>
-
-<P>
-Returns 1 ... if successful, 0 ... otherwise.
-
-<P>
-
-\subsection Write_Functions_used_in_Cache_Mode Write Functions used in Cache Mode
-
-<P>
-int Rast3d_flushTile(void *map, int tileIndex) Writes the tile with
- <EM>tileIndex</EM> to the file corresponding to <EM>map</EM> and removes the tile
- from the cache (in non-cache mode the buffer provided by the map-structure is
- written).
-
-<P>
-If this tile has already been written before the write request is ignored.
- If the tile was never referred to before the invokation of Rast3d_flushTile, a
- tile filled with NULL-values is written.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_flushTileCube(void *map, int xMin, int yMin, int zMin, int
- xMax, int yMax, int zMax) Writes the tiles with tile-coordinates
- contained in the axis-parallel cube with vertices <EM>(xMin, yMin, zMin)</EM>
- and <EM>(xMax, yMax, zMax</EM>). Tiles which are not stored in the cache are
- written as NULL-tiles. Write attempts for tiles which have already been
- written earlier are ignored.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_flushTilesInCube(void *map, int xMin, int yMin, int
- zMin, int xMax, int yMax, int zMax) Writes those tiles for which
- <EM>every</EM> cell has coordinate contained in the axis-parallel cube
- defined by the vertices with cell-coordinates <EM>(xMin, yMin, zMin)</EM>
- and <EM>(xMax, yMax, zMax)</EM>.
-
-<P>
-Tiles which are not stored in the cache are written as NULL-tiles.
- Write attempts for tiles which have already been written earlier are
- ignored.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-
-\subsection Locking_and_Unlocking_Tiles_and_CyclesLocking and Unlocking Tiles, and Cycles
-
-<P>
-int Rast3d_lockTile(void *map, int tileIndex) Locks tile with <EM>tileIndex</EM> in cache.
-If after locking fewer than the minimum number of
- unlocked tiles are unlocked, the lock request is ignored.
-
-<P>
-Returns
- 1 ... if successful,
- -1 ... if request is ignored,
- 0 ... otherwise.
-
-<P>
-int Rast3d_unlockTile(void *map, int tileIndex)
-Unlocks tile with <EM>tileIndex</EM>.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_unlockAll(void *map)
-Unlocks every tile in cache of <EM>map</EM>.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-void Rast3d_autolockOn(void *map)
-Turns autolock mode on.
-
-<P>
-void Rast3d_autolockOff(void *map)
-Turns autolock mode Off.
-
-<P>
-void Rast3d_minUnlocked(void *map, int minUnlocked) Sets the minimum
- number of unlocked tiles to <EM>minUnlocked</EM>. This function should be used
- in combination with <TT>Rast3d_unlockAll()</TT> in order to avoid situations where the
- new minimum is larger than the actual number of unlocked tiles.
-
-<P>
-<EM>minUnlocked</EM> must be one of RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y,
- RASTER3D_USE_CACHE_Z, RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ,
- RASTER3D_USE_CACHE_YZ, RASTER3D_USE_CACHE_XYZ, the result of Rast3d_cacheSizeEncode()
- (cf. Section 22.4.6), or any positive integer
- which explicitly specifies the number of tiles.
-
-<P>
-int Rast3d_beginCycle(void *map)
-Starts a new cycle.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_endCycle(void *map)
-Ends a cycle.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_cacheSizeEncode(int cacheCode, int n) Returns a number
- which encodes multiplicity <EM>n</EM> of <EM>cacheCode</EM>. This value can be used
- to specify the size of the cache.
-
-<P>
-If <EM>cacheCode</EM> is the size (in tiles) of the cache the function returns
- <EM>cacheCode * n</EM>.
-
-<P>
-If <EM>cacheCode</EM> is RASTER3D_USE_CACHE_DEFAULT the function returns
- RASTER3D_USE_CACHE_DEFAULT.
-
-<P>
-If <EM>cacheCode</EM> is RASTER3D_USE_CACHE_??? the function returns a value
- encoding RASTER3D_USE_CACHE_??? and <EM>n</EM>. Here RASTER3D_USE_CACHE_??? is one
- of RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
- RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ, or
- RASTER3D_USE_CACHE_XYZ, where e.g. RASTER3D_USE_CACHE_X specifies that the cache
- should store as many tiles as there exist in one row along the x-axis of the
- tile cube, and RASTER3D_USE_CACHE_XY specifies that the cache should store as
- many tiles as there exist in one slice of the tile cube with constant Z
- coordinate.
-
-<P>
-
-\subsection Reading_Volumes Reading Volumes
-
-<P>
-int Rast3d_getVolume(void *map, double originNorth, double originWest,
- double originBottom, double vxNorth, double vxWest, double vxBottom, double
- vyNorth, double vyWest, double vyBottom, double vzNorth, double vzWest,
- double vzBottom, int nx, int ny, int nz, char *volumeBuf, int type)
- Resamples the cube defined by <EM>origin</EM> and the 3 vertices <EM>vx</EM>,
- <EM>vy</EM>, and <EM>vz</EM> which are incident to the 3 edges adjacent to
- <EM>origin</EM>. The resampled cube is stored in <EM>volumeBuf</EM> which is a cube
- with dimensions <EM>(nx, ny, nz)</EM>.
-
-<P>
-The method of sampling is nearest neighbor sampling.
-
-<P>
-The values stored are of <EM>type</EM>.
-
-<P>
-Returns 1 ... if successful, 0 ... otherwise.
-
-<P>
-int Rast3d_getAllignedVolume(void *map, double originNorth, double
- originWest, double originBottom, double lengthNorth, double lengthWest,
- double lengthBottom, int nx, int ny, int nz, char *volumeBuf, int type)
- Resamples the axis-parallel cube defined by <EM>origin</EM> and the lengths of
- the 3 edges adjacent to <EM>origin</EM>. The resampled cube is stored in
- <EM>volumeBuf</EM> which is a cube with dimensions <EM>(nx, ny, nz)</EM>. The method
- of sampling is nearest neighbor sampling. The values stored are of <EM>type</EM>.
-
-<P>
-Returns 1 ... if successful, 0 ... otherwise.
-
-<P>
-
-\subsection Allocating_and_Freeing_Memory Allocating and Freeing Memory
-
-<P>
-void *Rast3d_malloc(int nBytes)
-Same as <EM>malloc (nBytes)</EM>, except that in case of error
-<TT>Rast3d_error()</TT> is invoked.
-
-<P>
-Returns
- a pointer ... if successful,
- NULL ... otherwise.
-
-<P>
-void *Rast3d_realloc(void *ptr, int nBytes)
-Same as <EM>realloc (ptr, nBytes)</EM>, except that in case of error
-<TT>Rast3d_error()</TT> is invoked.
-
-<P>
-Returns
- a pointer ... if successful,
- NULL ... otherwise.
-
-<P>
-void Rast3d_free(void *ptr) Same as <EM>free (ptr)</EM>.
-
-<P>
-char *Rast3d_allocTilesType(void *map, int nofTiles, int type)
-Allocates a vector of <EM>nofTiles</EM> tiles with the same dimensions
-as the tiles of <EM>map</EM> and large enough to store cell-values of
-<EM>type</EM>.
-
-<P>
-Returns
- a pointer to the vector ... if successful,
- NULL ... otherwise.
-
-<P>
-char *Rast3d_allocTiles(void *map, int nofTiles)
-Is equivalent to Rast3d_allocTilesType (map, nofTiles, Rast3d_fileTypeMap (map)).
-
-<P>
-void Rast3d_freeTiles(char *tiles)
-Is equivalent to <TT>Rast3d_free (tiles);</TT>
-
-<P>
-
-\subsection RASTER3D_Null_Value_Support RASTER3D Null Value Support
-
-<P>
-void Rast3d_isNullValueNum(void *n, int type)
-Returns 1 if the value of <EM>*n</EM> is a NULL-value. Returns 0
-otherwise.
-
-<P>
-void Rast3d_setNullValue(void *c, int nofElts, int type)
-Fills the vector pointed to by <EM>c</EM> with <EM>nofElts</EM> NULL-values
-of <EM>type</EM>.
-
-<P>
-void Rast3d_setNullTileType(void *map, int tile, int type)
-Assumes that <EM>tile</EM> is a tile with the same dimensions as the
-tiles of <EM>map</EM>. Fills <EM>tile</EM> with NULL-values of
-<EM>type</EM>.
-
-<P>
-void Rast3d_setNullTile(void *map, int tile)
-Is equivalent to Rast3d_setNullTileType (map, tile, Rast3d_fileTypeMap (map)).
-
-<P>
-
-\subsection RASTER3D_Map_Header_Information RASTER3D Map Header Information
-
-<P>
-void Rast3d_getCoordsMap(void *map, int *rows, int *cols, int *depths)
-Returns the size of the region of <EM>map</EM> in cells.
-
-<P>
-void Rast3d_getRegionMap(void *map, int *north, int *south, int *east,
- int *west, int *top, int *bottom)Returns the size of the region.
-
-<P>
-void Rast3d_getRegionStructMap(void *map, RASTER3D_Region *region)
-Returns in <EM>region</EM> the region of <EM>map</EM>.
-
-<P>
-void Rast3d_getTileDimensionsMap(void *map, int *x, int *y, int *z)
-Returns the tile dimensions used for <EM>map</EM>.
-
-<P>
-void Rast3d_getNofTilesMap(void *map, int *nx, int *ny, int *nz)
- Returns the dimensions of the tile-cube used to tile the region of <EM>map</EM>.
- These numbers include partial tiles.
-
-<P>
-int Rast3d_tileTypeMap(void *map)
-Returns the type in which tiles of <EM>map</EM> are stored in memory.
-
-<P>
-int Rast3d_fileTypeMap(void *map)
-Returns the type with which tiles of <EM>map</EM> are stored on file.
-
-<P>
-int Rast3d_tilePrecisionMap(void *map)
-Returns the precision used to store <EM>map</EM>.
-
-<P>
-int Rast3d_tileUseCacheMap(void *map)
-Returns 1 if <EM>map</EM> uses cache, returns 0 otherwise.
-
-<P>
-void Rast3d_printHeader(void *map)
-Prints the header information of <EM>map</EM>.
-
-<P>
-
-\subsection RASTER3D_Tile_Math RASTER3D Tile Math
-
-<P>
-void Rast3d_tileIndex2tile(void *map, int tileIndex, int *xTile, int
- *yTile, int *zTile) Converts index <EM>tileIndex</EM> into tile-coordinates
- <EM>(xTile, yTile, zTile)</EM>.
-
-<P>
-int Rast3d_tile2tileIndex(void *map, int xTile, int yTile, int
- zTile) Returns tile-index corresponding to tile-coordinates <EM>(xTile,
- yTile, zTile)</EM>.
-
-<P>
-void Rast3d_coord2tileCoord(void *map, int x, int y, int z, int *xTile,
- int *yTile, int *zTile, int *xOffs, int *yOffs, int *zOffs) Converts
- cell-coordinates <EM>(x, y, z)</EM> into tile-coordinates <EM>(xTile, yTile,
- zTile)</EM> and the coordinate of the cell <EM>(xOffs, yOffs, zOffs)</EM> within
- the tile.
-
-<P>
-void Rast3d_tileCoordOrigin(void *map, int xTile, int yTile, int zTile,
- int *x, int *y, int *z) Computes the cell-coordinates <EM>(x, y, z)</EM>
- which correspond to the origin of the tile with tile-coordinates <EM>(xTile,
- yTile, zTile)</EM>.
-
-<P>
-void Rast3d_tileIndexOrigin(void *map, int tileIndex, int *x, int *y,
- int *z) Computes the cell-coordinates <EM>(x, y, z)</EM> which correspond to
- the origin of the tile with <EM>tileIndex</EM>.
-
-<P>
-void Rast3d_coord2tileIndex(void *map, int x, int y, int z, int
- *tileIndex, int *offset) Converts cell-coordinates <EM>(x, y, z)</EM> into
- <EM>tileIndex</EM> and the <EM>offset</EM> of the cell within the tile.
-
-<P>
-int Rast3d_coordInRange(void *map, int x, int y, int z) Returns 1 if
- cell-coordinate <EM>(x, y, z)</EM> is a coordinate inside the region. Returns 0
- otherwise.
-
-<P>
-int Rast3d_tileInRange(void *map, int x, int y, int z) Returns 1 if
- tile-coordinate <EM>(x, y, z)</EM> is a coordinate inside tile cube. Returns 0
- otherwise.
-
-<P>
-int Rast3d_tileIndexInRange(void *map, int tileIndex)
-Returns 1 if <EM>tileIndex</EM> is a valid index for <EM>map</EM>.
-Returns 0 otherwise.
-
-<P>
-int Rast3d_isValidLocation(void *map, double north, double west, double
- bottom) Returns 1 if region-coordinates <EM>(north, west, bottom)</EM> are
- inside the region of <EM>map</EM>. Returns 0 otherwise.
-
-<P>
-void Rast3d_location2coord(void *map, double north, double west, double
- bottom, int *x, *y, *z) Converts region-coordinates <EM>(north, west,
- bottom)</EM> into cell-coordinates <EM>(x, y, z)</EM>.
-
-<P>
-int Rast3d_computeClippedTileDimensions(void *map, int tileIndex, int
- *rows, int *cols, int *depths, int *xRedundant, int *yRedundant, int
- *zRedundant) Computes the dimensions of the tile when clipped to fit the
- region of <EM>map</EM>. The clipped dimensions are returned in <EM>rows</EM>,
- <EM>cols</EM>, <EM>depths</EM>. The complement is returned in <EM>xRedundant</EM>,
- <EM>yRedundant</EM>, and <EM>zRedundant</EM>. This function returns the number of
- cells in the clipped tile.
-
-<P>
-
-\subsection RASTER3D_Range_Support RASTER3D Range Support
-
-<P>
-The map structure of RASTER3D provides storage for the range. The range of a map is
-updated every time a cell is written to the file. When an old map is opened the
-range is not automatically loaded. The application has to invoke
-<TT>Rast3d_range_load()</TT> (cf. Section 22.4.12)
- explicitly. In
-addition to these function the application can also use the standard grass
-functions to manipulate the range.
-
-<P>
-int Rast3d_range_load(void *map)
-Loads the range into the range structure of <EM>map</EM>.
-
-<P>
-Returns
- 1 ... if successful
- 0 ... otherwise.
-
-<P>
-void Rast3d_range_min_max(void *map, double *min, double *max)
- Returns in <EM>min</EM> and <EM>max</EM> the minimum and maximum values of
- the range.
-
-<P>
-int Rast3d_range_write(void *map)
-Writes the range which is stored in the range structure of <EM>map</EM>.
-(This function is invoked automatically when a new file is closed).
-
-<P>
-Returns
- 1 ... if successful
- 0 ... otherwise.
-
-<P>
-
-\subsection RASTER3D_Color_Support RASTER3D Color Support
-
-<P>
-Applications can use the standard grass functions to work with colors, except
-for the file manipulations.
-
-<P>
-int Rast3d_removeColor(char *name)
-Removes the primary and/or secondary color file. See <EM>G_remove_colr</EM> for
-details.
-
-<P>
-Returns always 0.
-
-<P>
-int Rast3d_readColors(char *name, char *mapset, struct Colors
- *colors) Reads color file for map <EM>name</EM> in <EM>mapset</EM> into the
- <EM>colors</EM> structure. See <EM>G_read_colors</EM>
- (Raster_Color_Table) for details and return values.
-
-<P>
-int Rast3d_writeColors(char *name, char *mapset, struct Colors
- *colors)Writes colors stored in <EM>colors</EM> structure into the color
- file for map <EM>name</EM> in <EM>mapset</EM>. See <EM>G_write_colors</EM>
- (Raster_Color_Table) for
- details and return values.
-
-<P>
-
-\subsection RASTER3D_Categories_Support RASTER3D Categories Support
-
-<P>
-Applications can use the standard grass functions to work with categories,
-except for the file manipulations.
-
-<P>
-int Rast3d_readCats(char *name, char *mapset, struct Categories *cats)
-Reads the categories file for map <EM>name</EM> in <EM>mapset</EM> and
-stores the categories in the <EM>cats</EM> structure. See <EM>G_read_cats</EM>
-(Raster_Category_File) for details and return values.
-
-<P>
-int Rast3d_writeCats(char *name, struct Categories *cats) Writes the
- categories stored in the <EM>cats</EM> structure into the categories file for
- map <EM>name</EM> in the current mapset. See <EM>G_write_cats</EM>
- (Raster_Category_File) for details and return values.
-
-<P>
-
-
-\subsection RASTER3D_History_Support RASTER3D History Support
-
-<P>
-Applications can use the standard grass functions to work with histories,
-except for the file manipulations.
-
-<P>
-int Rast3d_readHistory(char *name, char *mapset, struct History *hist)
- Reads the history file for map <EM>name</EM> in <EM>mapset</EM> and
- stores the history in the <EM>hist</EM> structure. See <EM>G_read_history</EM>
- (Raster_History_File) for details and return values.
-
-<P>
-int Rast3d_writeHistory(char *name, struct History *hist)
- Writes the
- history stored in the <EM>hist</EM> structure into the categories file for
- map <EM>name</EM> in the current mapset. See <EM>G_write_history</EM>
- (Raster_History_File) for details and return values.
-
-<P>
-
-\subsection RASTER3D_Mask_Support RASTER3D Mask Support
-
-<P>
-void Rast3d_maskOn(void *map) Turns on the mask for <EM>map</EM>. Do
- not invoke this function after the first tile has been read since the result
- might be inconsistent cell-values.
-
-<P>
-void Rast3d_maskOff(void *map) Turns off the mask for <EM>map</EM>.
- This is the default. Do not invoke this function after the first tile has
- been read since the result might be inconsistent cell-values.
-
-<P>
-int Rast3d_maskIsOn(void *map) Returns 1 if the mask for <EM>map</EM>
- is turned on. Returns 0 otherwise.
-
-<P>
-int Rast3d_maskIsOff(void *map)
-Returns 1 if the mask for <EM>map</EM> is turned off. Returns 0 otherwise.
-
-<P>
-The remaining functions in this section are for the explicit query of the mask
-and the masking of individual cells or tiles. These functions are used in the
-library and might have applications in situations where both the masked and
-non-masked value of a cell has to be known.
-
-<P>
-int Rast3d_maskReopen(int cache)
-This function should be used to adjust the cache size used for the
-3d-mask. First the open 3d-mask is closed and then opened again with
-a cache size as specified with <EM>cache</EM>.
-
-<P>
-Returns
- 1 ... if successful
- 0 ... otherwise.
-
-<P>
-int Rast3d_maskFileExists() Returns 1 if the 3d mask file
- exists.
-
-<P>
-int Rast3d_maskMapExists()
-Returns 1 if the 3d mask is loaded.
-
-<P>
-char *Rast3d_maskFile()
-Returns the name of the 3d mask file.
-
-<P>
-int Rast3d_isMasked(int x, int y, int z)
-Returns 1 if the cell with cell-coordinates <EM>(x, y, z)</EM> is masked
-out. Returns 0 otherwise.
-
-<P>
-void Rast3d_maskNum(int x, int y, int z, void *value, int type)
-Replaces the value stored in <EM>value</EM> with the NULL-value if
-<EM>Rast3d_isMasked (x, y, z)</EM> returns 1. Does nothing otherwise.
-<EM>value</EM> is assumed to be of<EM>type</EM>.
-
-<P>
-void Rast3d_maskFloat(int x, int y, int z, float *value)
-Same as <EM>Rast3d_maskNum (x, y, z, value, FCELL_TYPE)</EM>.
-
-<P>
-void Rast3d_maskDouble(int x, int y, int z, double *value)
-Same as <EM>Rast3d_maskNum (x, y, z, value, DCELL_TYPE)</EM>.
-
-<P>
-void Rast3d_maskTile(void *map, int tileIndex, char *tile, int type)
-Replaces the values stored in <EM>tile</EM> (with <EM>tileIndex</EM>) for
-which <EM>Rast3d_isMasked</EM> returns 1 with NULL-values. Does not change
-the remaining values. The values are assumed to be of <EM>type</EM>.
-Whether replacement is performed or not only depends on location of the
-cells of the tile and not on the status of the mask for <EM>map</EM>
-(i.e. turned on or off).
-
-<P>
-
-\subsection RASTER3D_Window_Support RASTER3D Window Support
-
-<P>
-void Rast3d_setWindowMap(void *map, RASTER3D_Region *window)
-Sets the window for <EM>map</EM> to <EM>window</EM>.
-Can be used multiple times for the same map.
-
-<P>
-void Rast3d_setWindow(RASTER3D_Region *window)
-Sets the default window used for every map opened later in the program.
-Can be used multiple times in the same program.
-
-<P>
-void Rast3d_getWindow(RASTER3D_Region *window)
-Stores the current default window in <EM>window</EM>.
-
-<P>
-void *Rast3d_windowPtr()
-Returns a pointer to the current default window. This pointer should not be
-(ab)used to modify the current window structure directly. It is
-provided to pass a window pointer when opening a map.
-
-<P>
-int Rast3d_readWindow(RASTER3D_Region *window, char *windowName) Reads
- <EM>window</EM> from the file specified by <EM>windowName</EM>. The name is
- converted by the rules defined in window defaults. A NULL pointer indicates
- the <EM>WIND3</EM> file in the current mapset.
-
-<P>
-Returns
- 1 ... if successful
- 0 ... otherwise.
-
-<P>
-int Rast3d_writeWindow(RASTER3D_Region *window, char *windowName)
- Writes <EM>window</EM> to the file specified by <EM>windowName</EM>. The name
- is converted by the rules defined in window defaults. A NULL pointer
- indicates the <EM>WIND3</EM> file in the current mapset.
-
-<P>
-Returns
- 1 ... if successful
- 0 ... otherwise.
-
-<P>
-void Rast3d_useWindowParams()
-Allows the window to be set at run-time via the <EM>region3</EM>
-command line argument. This function has to be called before
-<EM>G_parser()</EM>. See also
- window defaults.
-
-<P>
-void Rast3d_setResamplingFun(void *map, void (*resampleFun)())
-Sets the resampling function to be used by
-Rast3d_getValue() (cf. Section 22.4.3). This function is defined
-as follows:
-
-<P>
-void Rast3d_customResampleFun(void *map, int row, int col, int depth,
- char *value, int type) <EM>row</EM>, <EM>col</EM>, and <EM>depth</EM> are in
- region coordinates. The result is returned in <EM>value</EM> as <EM>type</EM> which
- is one of FCELL_TYPE or DCELL_TYPE. Possible choices include
- Rast3d_nearestNeighbor() (cf. Section22.4.16) and
- Rast3d_getValueRegion() (cf. Section 22.4.3).
-
-<P>
-void Rast3d_nearestNeighbor(void *map, int row, int col, int depth, char
- *value, int type) The default resampling function which uses nearest
- neighbor resampling.
-
-<P>
-void Rast3d_getResamplingFun(void *map, void (**resampleFun)())
- Returns in <EM>resampleFun</EM> a pointer to the resampling function used by
- <EM>map</EM>.
-
-<P>
-void Rast3d_getNearestNeighborFunPtr(void (**nnFunPtr)()) Returns
- in <EM>nnFunPtr</EM> a pointer to Rast3d_nearestNeighbor() (cf.
- Section <A HREF="#g3d:G3d.nearestNeighbor">22.4.16</A>).
-
-<P>
-
-\subsection RASTER3D_Region RASTER3D Region
-
-<P>
-void Rast3d_extract2dRegion(RASTER3D_Region *region3d, struct Cell_head
- *region2d) Returns in <EM>region2d</EM> the <EM>2d</EM> portion of <EM>region3d</EM>.
-
-<P>
-void Rast3d_incorporate2dRegion(struct Cell_head *region2d, RASTER3D_Region
- *region3d) Replaces the <EM>2d</EM> portion of <EM>region3d</EM> with the
- values stored in <EM>region2d</EM>.
-
-<P>
-void Rast3d_adjustRegion(RASTER3D_Region *region)
-Computes an adjusts the resolutions in the region structure from the region
-boundaries and number of cells per dimension.
-
-<P>
-void Rast3d_adjustRegionRes(RASTER3D_Region *region)
-Computes an adjusts the number of cells per dimension in the region
-structure from the region boundaries and resolutions.
-
-<P>
-void Rast3d_regionCopy(RASTER3D_Region *regionDest, RASTER3D_Region *regionSrc)
-Copies the values of <EM>regionSrc</EM> into <EM>regionDst</EM>.
-(The unfortunate order of parameters was chosen in order to conform to the
-order used in <EM>G_copy()</EM>).
-
-<P>
-void Rast3d_getRegionValue(void *map, double north, double east, double
- top, char *value, int type) Returns in <EM>value</EM> the value of the <EM>map</EM>
- which corresponds to region coordinates <EM>(north, east, top)</EM>. The
- value is resampled using the resampling function specified for <EM>map</EM>. The
- <EM>value</EM> is of <EM>type</EM>.
-
-<P>
-void Rast3d_readRegionMap(char *name, char *mapset, RASTER3D_Region *region)
-Returns in <EM>region</EM> the region information for 3d cell <EM>name at mapset</EM>.
-
-<P>
-
-\subsection Miscellaneous_Functions Miscellaneous Functions
-
-<P>
-void Rast3d_g3dType2cellType(int g3dType) Returns the GRASS floating
- point type which is equivalent to the RASTER3D type of <EM>g3dType</EM>.
-
-<P>
-void Rast3d_initDefaults() Initializes the default values described
- in RASTER3D Defaults. Applications have to use this function only if they need to
- query the default values before the first file (either old or new) has been
- opened.
-
-<P>
-void Rast3d_setStandard3dInputParams()
- Initializes a parameter
- structure for the subset of command line arguments which lets the user
- overwrite the default properties of the new file. Applications are
- encouraged to use this function in order to provide a uniform style. The
- command line arguments provided are the <EM>type</EM> of the cell values, the
- <EM>precision</EM>, the properties of the <EM>compression</EM>, and the dimension
- of the tiles (<EM>tiledimension</EM>). Every of these values defaults to the
- value described in RASTER3D Defaults.
-
-<P>
-This function has to be used in conjunction with
- Rast3d_getStandard3dInputParams() (cf.
- Section 22.4.18).
-
-<P>
-int Rast3d_getStandard3dInputParams(int *useTypeDefault, *type, *useLzwDefault, *doLzw,
- int *useRleDefault, *doRle, *usePrecisionDefault, *precision,
- int *useDimensionDefault, *tileX, *tileY, *tileZ
-Returns the properties of the new file as chosen by the user via command
-line arguments. If the default is chosen the values of
-<EM>useXxxxDefault</EM> is 1, it is 0 otherwise. In addition, the
-corresponding parameters contain the default value if
-<EM>useXxxxDefault</EM> is 1, or the value specified by the user if
-<EM>useXxxxDefault</EM> is 0.
-
-<P>
-Function
-Rast3d_setStandard3dInputParams() (cf. Section 22.4.18)
-has to be used to initialize the internal parameter structure.
-
-<P>
-Returns
- 1 ... if successful,
- 0 ... otherwise.
-
-<P>
-int Rast3d_makeMapsetMapDirectory(char *mapName)
-Creates the 3d mapset element for map <EM>mapName</EM>.
-
-<P>
-int Rast3d_filename(char *path, *elementName, *mapName, *mapset)
-Returns in <EM>path</EM> the path for element <EM>elementName</EM> for map
-<EM>mapName</EM> in <EM>mapset</EM>. Note, an error occurs if <EM>mapName</EM>
-is fully qualified.
-
-<P>
-See TimeStamp_functions for a complete discussion of GRASS datetime
-routines (reading, writing grid3d timestamps).
-
-<P>
-
-\section Sample_RASTER3D_Applications Sample RASTER3D Applications
-
-<P>
-These functions were implemented to test the library. They are not very
-efficient but can be used as starting point for other
-applications. Some of them might actually be useful. They are available from
-GRASS 7 source code in lib/g3d/.
-
-<P>
-void Rast3d_retile(void *map, char *nameOut, int tileX, int tileY, int tileZ)
-Makes a copy of <EM>map</EM> with name <EM>nameOut</EM> which has
-tile dimensions <EM>tileX</EM>, <EM>tileY</EM>, <EM>tileZ</EM>.
-
-<P>
-The source code can be found in <EM>retile.c</EM>.
-
-<P>
-void Rast3d_changePrecision(void *map, int precision, char *nameOut)
-Makes a copy of <EM>map</EM> with name <EM>nameOut</EM> which is
-written with <EM>precision</EM>.
-
-<P>
-The source code can be found in <EM>changeprecision.c</EM>.
-
-<P>
-void Rast3d_changeType(void *map, char *nameOut)
-Makes a copy of <EM>map</EM> with name <EM>nameOut</EM> in which the
-cells are of type FCELL_TYPE if they are DCELL_TYPE in <EM>map</EM>,
-and in DCELL_TYPE otherwise.
-
-<P>
-The source code can be found in <EM>changetype.c</EM>.
-
-<P>
-void Rast3d_compareFiles(char *f1, char *mapset1, char *f2, char *mapset2)
-Compares the cell-values of file <EM>f1</EM> in mapset
-<EM>mapset1</EM> and file <EM>f2</EM> in mapset <EM>mapset2</EM>.
-The values are compared up to precision.
-Terminates in error if the files don't match.
-This function uses the more advanced features of the cache.
-
-<P>
-The source code can be found in <EM>filecompare.c</EM>.
-
-<P>
-void Rast3d_getBlock(void *map, int x0, int y0, int z0, int nx, int ny,
-int nz, char *block, int type)
-Copies the cells contained in the block (cube) with vertices
-<EM>(x0, y0, z0)</EM> and <EM>(x0 + nx - 1, y0 + ny - 1, z0 + nz - 1)</EM>
-into <EM>block</EM>. The cell-values in <EM>block</EM> are of <EM>type</EM>.
-
-<P>
-The source code can be found in <EM>getblock.c</EM>.
-
-<P>
-void Rast3d_writeAscii(void *map, char *fname)
-Writes the cell-values of <EM>map</EM> in ascii format to file
-<EM>fname</EM>. The values are organized by horizontal slices.
-
-
-<P>
-See \ref Compiling_and_Installing_GRASS_Modules for a complete
-discussion of Makefiles.
-
-*/
Copied: grass/trunk/lib/raster3d/raster3dlib.dox (from rev 47537, grass/trunk/lib/raster3d/lib.dox)
===================================================================
--- grass/trunk/lib/raster3d/raster3dlib.dox (rev 0)
+++ grass/trunk/lib/raster3d/raster3dlib.dox 2011-08-10 17:49:39 UTC (rev 47538)
@@ -0,0 +1,1746 @@
+/*! \page raster3dlib GRASS 3D Raster Volume Library
+<!-- doxygenized from "GRASS 5 Programmer's Manual"
+ by M. Neteler 5/2004, 8/2005
+ -->
+
+<b>Overview</b>
+
+The 3D Raster Volume Library is used for the <tt>r3.*</tt> and vector
+volume tools. The library uses a tile cache based approach to store
+floating point values in abritrary order in a volume. The coordinate
+system of a volume is column and row compatible to the raster library
+and counts from the bottom to the top of the cube.
+
+\image html "volume_layout.png" "The volume coordinate system and tile layout of the 3D Raster Library"
+
+<b>TODO: update for GRASS7</b>
+
+\section Directory_Structure Directory Structure
+
+<P>
+The file format consists of a mapset element <EM>grid3</EM> which contains a
+directory for every map. The elements for each map are
+
+<P>
+\verbatim
+ 3d region file
+ color file (color)
+ categories file (cats)
+ range file (range)
+ timestamp file /* not yet implemented */
+ cell file (cell)
+ header file (cellhd)
+ a directory containing display files (dsp)
+\endverbatim
+
+<P>
+There is also a <EM>colr2</EM> mechanism provided. <EM>colr2</EM> color tables
+are stored in <EM>grid3/colr2/MAPSET/MAP</EM>.
+
+<P>
+Note: color, categories, and the range can be used in the same way as in <EM>2d</EM>
+GRASS with the exception of reading and writng. <EM>3d</EM> read and write
+functions have to be used for this purpose.
+
+
+\section Data_File_Format Data File Format
+
+
+<UL>
+<LI>Cell-values can be either double or float.
+</LI>
+<LI>Values are written in XDR-format.
+</LI>
+<LI>NULL-values are stored in an embedded fashion.
+</LI>
+<LI>The cell-values are organized in <EM>3d</EM>-tiles.
+</LI>
+<LI>The tile dimensions can be chosen when a new map is opened.
+</LI>
+<LI>Every tile of a map has the same dimension except those which overlap the
+ region boundaries.
+</LI>
+<LI>Compression is used to store tiles.
+</LI>
+</UL>
+
+<P>
+The data file has the following format:
+
+<P>
+\verbatim
+ xdr_int nofBytesLong;
+ xdr_int nofBytesUsed;
+ encoded_long indexOffset;
+ compressed_tile[] tiles;
+ compressed_encoded_long[] index;
+\endverbatim
+
+<P>
+
+\section Transportability_of_data_file Transportability of data file
+
+<P>
+All numbers stored in the data file are either XDR-encoded or encoded by some
+other method (for variables of type long only).
+
+<P>
+
+\section Tile_Data_NULL_values Tile Data NULL-values
+
+<P>
+RASTER3D uses the same functions as <EM>2d</EM> GRASS to set and test NULL-values. The
+storage in the file is different though. NULL-values are stored with a special
+bit-pattern if maximum precision is chosen. They are stored by adding an
+additional bit if the precision is smaller.
+
+<P>
+
+\section Tile_Data_Compression Tile Data Compression
+
+<P>
+There are three methods of compression provided. The compression
+methods can either be those defined by default, set by environment
+variables or explicitly set at run-time.
+
+\verbatim
+ Precision
+ RLE
+\endverbatim
+
+<P>
+Precision indicates how many of the mantissa bits should be stored on
+file. This number can be any value between 0 and 23 for floats and
+between 0 and 52 for doubles. Choosing a small precision is the most
+effective way to achieve good compression.
+
+<P>
+RLE takes advantage of possible repetitions of the
+exponents and the NULL-bit structure. Using RLE does not significantly
+increase the running time. If for some tile the non-RLEed version is
+smaller in size, RLE is not used for this tile.
+
+<P>
+The default and suggested setting is to use precision and RLE.
+
+<P>
+Additional compression is achieved by storing the extra NULL-bit in a
+separate bit-array. Using this scheme NULL-values need not actually be
+represented in the array of cell values. This array is stored together
+with the cell-values of the tile.
+
+
+\section Tile_Cache Tile Cache
+
+<P>
+Tiles can either be read and written directly or use an intermediate
+cache instead.
+
+<P>
+In non-cache mode the application should only use the functions
+
+<P>
+int Rast3d_readTile()
+
+<P>
+and
+
+<P>
+int Rast3d_writeTile()
+
+<P>
+to read and write tiles. The application can use one tile provided by the map
+structure as buffer. See <TT>Rast3d_getTilePtr()</TT>.
+
+<P>
+In cache mode the application can access cell-values directly by their
+coordinates. The corresponding functions are
+
+<P>
+int Rast3d_getValue()
+
+<P>
+and
+
+<P>
+int Rast3d_putValue()
+
+<P>
+and their corresponding typed versions.
+<BR>
+<P>
+If the map is new then in addition to the memory-cache a file-cache is provided.
+This allows the application to write the cell-values in any arbitrary order.
+Tiles are written (flushed) to the data-file either at closing time or if
+explicitly requested.
+<BR>
+<P>
+If the map is new <TT>Rast3d_getValue()</TT> can be used even if the tile which
+contains the cell has already been flushed to the data file. In this case the
+tile is simply read back into the memory-cache from the data file.
+<BR>
+<P>
+Explicitly flushing tiles can have the advantage that less disk space is
+occupied since tiles are stored in a uncompressed fashion in the file-cache.
+Flushing tiles explicitly can cause problems with accuracy though if precision
+is less than the maximum precision and an already flushed value is used for
+computations later in the program.
+<BR>
+<P>
+The type of the cell-values of the tiles in memory can be chosen independently
+of the type of the tiles in the file. Here, once again one has to consider
+possible problems arising from mixing different precisions.
+<BR>
+<P>
+As an example consider the case where the data is stored in the file with double
+precision and the tiles are stored in memory in single precision. Then using
+<TT>Rast3d_getValue()</TT> will actually return a double precision number whose precision
+is only 23 bits. It is therefore a good idea to use the types in the memory
+consistently.
+<BR>
+<P>
+
+\section Header_File Header File
+
+<P>
+The header file has the following format:
+
+<P>
+\verbatim
+Proj: 1
+Zone: 1
+North: 2.0000000000000
+South: 0.5000000000000
+East: 4.0000000000000
+West: 3.0000000000000
+Top: 6.0000000000000
+Bottom: 5.0000000000000
+nofRows: 30
+nofCols: 20
+nofDepths: 14
+e-w resol: 0.05
+n-s resol: 0.05
+t-b resol: 0.071428571
+TileDimensionX: 8
+TileDimensionY: 8
+TileDimensionZ: 8
+CellType: double
+useCompression: 1
+useRle: 1
+Precision: -1
+nofHeaderBytes: 12
+useXdr: 1
+hasIndex: 1
+Units: none
+\endverbatim
+
+<P>
+Except for the first 14 fields the entries of the header file should
+not be modified. The precision value -1 indicates that maximum
+precision is used.
+<BR>
+<P>
+Binary files not in RASTER3D format can be read by the library. The
+following actions have to be taken:
+
+<P>
+Make a new map directory in the <EM>grid3</EM> element of the mapset (say <EM>mymap</EM>).
+ Copy the file into <EM>mymap/cell</EM> and generate a header file <EM>mymap/cellhd</EM>.
+
+<P>
+In the following example the relevant values of <EM>mymap/cellhd</EM> are shown:
+
+<P>
+\verbatim
+TileDimensionX: A
+TileDimensionY: B
+TileDimensionZ: C
+useCompression: 0
+useRle: 0
+Precision: -1
+nofHeaderBytes: X
+useXdr: 0
+hasIndex: 0
+\endverbatim
+
+<P>
+The values of <EM>A</EM>, <EM>B</EM>, and <EM>C</EM> have to be chosen
+according to one of the following patterns:
+
+<P>
+\verbatim
+A >= 1, B == 1, C == 1, or
+A >= nofRows, B >= 1, C == 1, or
+A >= nofRows, B >= nofCols, C >= 1.
+\endverbatim
+
+<P>
+A larger tile size reduces the number of tile-reads. If in the third pattern
+<EM>C</EM> is chosen larger than or equal to <EM>nofDepths</EM>, the entire region is
+considered one large tile.
+
+<P>
+The value <EM>nofHeaderBytes</EM> indicates the offset in the file to the first
+data entry.
+
+<P>
+For performance reasons it is a good idea to use function
+<TT>Rast3d_retile()</TT> before using the file in other applications.
+
+<P>
+
+\section Region_Structure Region Structure
+
+<P>
+\verbatim
+typedef struct{
+
+ double north, south;
+ double east, west;
+ double top, bottom;
+
+ int rows, cols, depths;/* data dimensions in cells */
+
+ double ns_res, ew_res, tb_res;
+
+ int proj; /* Projection (see gis.h) */
+ int zone; /* Projection zone (see gis.h) */
+
+} RASTER3D\_Region;
+\endverbatim
+
+<P>
+
+\section Windows Windows
+
+<P>
+Window capability similar to that of <EM>2d</EM> GRASS is provided (compare
+Region). Additional features are the window for the third dimension
+as well as the possibility to choose a different window for every map. The
+window can be specified at the time of opening an old map. It can be modified
+at any time later in the program. The resampling method can be the default
+nearest neighbor method as well as an application provided method.
+<BR>
+<P>
+The default <EM>3d</EM> window file is <EM>WIND3</EM> located in the mapset.
+Application programs should use <TT>Rast3d_useWindowParams()</TT> to allow the
+user to overwrite this default.
+
+<P>
+The window file has the following format:
+
+<P>
+\verbatim
+Proj: 1
+Zone: 1
+North: 2.0
+South: 0.5
+East: 4.0
+West: 3.0
+Top: 5.0
+Bottom: 6.0
+nofRows: 30
+nofCols: 20
+nofDepths: 14
+e-w resol: 0.05000000000000000
+n-s resol: 0.05000000000000000
+t-b resol: 0.07142857142857142
+\endverbatim
+
+<P>
+Note: after reading the window file the fields <EM>e-w</EM>, <EM>n-s</EM>, and <EM>t-b</EM>
+ are recomputed internally.
+
+<P>
+A note about windows and caching. Caching is performed on the level of tiles
+read from the file. There is no caching performed on resampled data. This is
+different from <EM>2d</EM> GRASS since resampling for a specific value is
+performed every time it is being accessed.
+
+<P>
+
+\section Masks Masks
+
+<P>
+RASTER3D provides a mask for the <EM>3d</EM> region. The mask structure is
+automatically initialized at the time the first file is opened. The same
+structure is used for all the files. The default for every file is that the
+mask is turned off. If masking should be performed, the application program has
+to turn on masking explicitly. If masking is turned on for a file, the
+cell-values of a tile are automatically checked against the mask. Values which
+are masked out, are set to NULL.
+
+<P>
+Note: changing the status of masking after one or more tiles have already
+been read does not affect the tiles which are already stored in the cache.
+
+<P>
+Any arbitrary 3d raster map can be used as mask file: NULL-values are interpreted as
+ <TT>"mask-out"</TT>, all other values are interpreted as <TT>"don't mask
+ out"</TT>. Using <EM>r3.mask</EM> to convert a 3d raster map into a mask file instead of
+simply copying (or renaming) the directory will significantly reduce to amount
+of disk space and the access time for the mask.
+
+<P>
+
+\section Include_File Include File
+
+<P>
+Exported RASTER3D constants and structures can be found in <EM>G3d.h</EM>.
+
+<P>
+
+\section RASTER3D_Defaults RASTER3D Defaults
+
+<P>
+There are three methods to set default variables. First, the default can be set
+at compile time in <EM>g3ddefault.c</EM>. This value has lowest priority.
+
+<P>
+Second, the default can be set via an environment variable. Third, the value
+can be set explicitly set at run time. This value has highest priority.
+
+<P>
+There are also functions provided to query the value.
+
+<P>
+
+\section Cache_Mode Cache Mode
+
+<P>
+
+\subsection Limiting_the_maximum_cache_size Limiting the maximum cache size
+
+<P>
+The limit is specified in bytes. It is a limit on the size of cell-data stored
+in the cache and does not include the support structure.
+
+<P>
+Default RASTER3D_CACHE_SIZE_MAX_DEFAULT. This is currently set to 16meg and can
+be changed at compilation time of the library.
+
+<P>
+Environment variable RASTER3D_MAX_CACHE_SIZE.
+
+<P>
+void Rast3d_setCacheLimit(int nBytes)Set cache limit
+
+<P>
+int Rast3d_getCacheLimit(int nBytes)Get cache limit
+
+<P>
+
+\subsection Setting_the_cache_size Setting the cache size
+
+<P>
+This value specifies the number of tiles stored in the cache. It is the value
+used if at opening time of a map RASTER3D_USE_CACHE_DEFAULT is used for the cache
+mode. Any other value used at opening time will supersede the default value. A
+default value of 0 indicates that non-cache mode should be used by default.
+
+<P>
+Default RASTER3D_CACHE_SIZE_DEFAULT. This is currently set to 1000 and can be
+changed at compilation time of the library.
+
+<P>
+Environment variable RASTER3D_DEFAULT_CACHE_SIZE.
+
+<P>
+void Rast3d_setCacheSize(int nTiles)
+
+<P>
+int Rast3d_getCacheSize()
+
+<P>
+
+\section Compression Compression
+
+\subsection Toggling_compression_mode Toggling compression mode
+
+<P>
+This value specifies whether compression should be used while writing a new
+map. It does not have any effect on old maps.
+
+<P>
+Default RASTER3D_COMPRESSION_DEFAULT. This is set to RASTER3D_COMPRESSION. This
+default should not be changed.
+
+<P>
+Environment variables RASTER3D_USE_COMPRESSION and RASTER3D_NO_COMPRESSION.
+
+<P>
+See functions Rast3d_setCompressionMode() (cf.
+Section 22.3.2.3 ) and Rast3d_getCompressionMode() (cf. Section 22.3.2.3 ).
+
+<P>
+
+\subsection Toggling_RLE_compression Toggling RLE compression
+
+<P>
+This value specifies whether RLE compression should be used (in addition to
+precision).
+
+<P>
+Default RASTER3D_USE_RLE_DEFAULT. This is currently set to RASTER3D_USE_RLE and can
+be changed at compilation time of the library.
+
+<P>
+Environment variables RASTER3D_USE_RLE and RASTER3D_NO_RLE.
+
+<P>
+See functions Rast3d_setCompressionMode() (cf.
+Section 22.3.2.3) and Rast3d_getCompressionMode() (cf. Section 22.3.2.3).
+
+\section Setting_the_precision Setting the precision
+
+<P>
+This number specifies how many mantissa bits should be used when writing a cell
+value. The minimum value is 0. The maximum value is 23 or RASTER3D_MAX_PRECISION
+for type FCELL_TYPE, it is 52 or RASTER3D_MAX_PRECISION for type DCELL_TYPE.
+
+<P>
+Default RASTER3D_PRECISION_DEFAULT. This is set to RASTER3D_MAX_PRECISION. This
+default should not be changed.
+
+<P>
+Environment variables RASTER3D_PRECISION and RASTER3D_MAX_PRECISION.
+
+<P>
+void Rast3d_setCompressionMode(int doCompress, int doLzw, int doRle, int
+ precision) <EM>doCompress</EM> should be one of RASTER3D_NO_COMPRESSION and
+ RASTER3D_COMPRESSION, <EM>doRle</EM> should be either RASTER3D_NO_RLE or
+ RASTER3D_USE_RLE, and <EM>precision</EM> should be either RASTER3D_MAX_PRECISION or
+ a positive integer.
+
+<P>
+void Rast3d_getCompressionMode(int *doCompress, int *doLzw, int *doRle,
+ int *precision)
+
+<P>
+
+\section Tiles Tiles
+
+\subsection Setting_the_tile_dimensions Setting the tile dimensions
+
+<P>
+The dimensions are specified in number of cell.
+
+<P>
+Defaults RASTER3D_TILE_X_DEFAULT, RASTER3D_TILE_Y_DEFAULT, and
+RASTER3D_TILE_Z_DEFAULT. These are currently set to 8 and can be changed at
+compilation time of the library.
+
+<P>
+Environment variables RASTER3D_TILE_DIMENSION_X, RASTER3D_TILE_DIMENSION_Y, and
+RASTER3D_TILE_DIMENSION_Z.
+
+<P>
+void Rast3d_setTileDimension(int tileX, int tileY, int tileZ)
+
+<P>
+void Rast3d_getTileDimension(int *tileX, int *tileY, int *tileZ)
+
+<P>
+
+\section Setting_the_tile_cell_value_type Setting the tile cell-value type
+
+<P>
+Specifies which type is used to write cell-values on file. This type can be
+chosen independently of the type used to store cell-values in memory.
+
+<P>
+Default RASTER3D_FILE_TYPE_DEFAULT. This is set to DCELL_TYPE. This default
+should not be changed.
+
+<P>
+Environment variables RASTER3D_WRITE_FLOAT and RASTER3D_WRITE_DOUBLE.
+
+<P>
+void Rast3d_setFileType(int type)
+
+<P>
+int Rast3d_getFileType(int type)
+
+<P>
+
+\section Setting_the_window Setting the window
+
+<P>
+The window is set from a <EM>3d</EM> window file.
+
+<P>
+The default <EM>3d</EM> window file is <EM>WIND3</EM> located in the current mapset.
+
+<P>
+Possible choices for <EM>3d</EM> window files are <EM>name</EM> which refers to a
+window file in the <EM>3d</EM> window database located at <EM>windows3d</EM> of the
+current mapset; or file names which are identified by a leading <EM><TT>"/"</TT></EM>
+or <EM><TT>"."</TT></EM>; or fully qualified
+names, i.e. <EM>file at mapset</EM> which refer to window files in the <EM>3d</EM> window
+database of mapset. Note, that names <EM>WIND3</EM> and <EM>WIND3 at mapset</EM> do not
+specify the default window name in the (current)
+mapset but rather a window file in the window database of the (current) mapset.
+
+<P>
+Environment variable RASTER3D_DEFAULT_WINDOW3D.
+
+<P>
+See functions
+
+<P>
+<TT>Rast3d_useWindowParams()</TT>,
+
+<P>
+<TT>Rast3d_setWindow()</TT>, and
+
+<P>
+<TT>Rast3d_setWindowMap()</TT>.
+
+<P>
+
+\section Setting_the_Units Setting the Units
+
+<P>
+Default <TT>"none"</TT>.
+
+<P>
+No environment variable.
+
+<P>
+void Rast3d_setUnit (unit)
+ char *unit;
+
+<P>
+
+\section Error_Handling Error Handling: Setting the error function
+
+<P>
+This variable specifies the function which is invoked when an error
+(not a fatal error) occurs. For example setting the error function to
+<TT>Rast3d_fatalError</TT> simplifies debugging with dbx and also might show
+errors which are missed because the application does not check the
+return value.
+
+<P>
+Default <TT>Rast3d_skipError</TT>.
+
+<P>
+Environment variables RASTER3D_USE_FATAL_ERROR and RASTER3D_USE_PRINT_ERROR.
+
+<P>
+void Rast3d_setErrorFun(void (*fun)(char *))
+
+<P>
+The following 3 functions are possible choices for error functions.
+
+<P>
+void Rast3d_skipError(char (*msg)(char *)) This function ignores the
+ error.
+
+<P>
+void Rast3d_printError(char (*msg)(char *)) This function prints the
+ error message <EM>msg</EM> to <EM>stderr</EM> and returns.
+
+<P>
+void Rast3d_fatalError(char (*msg)(char *)) This function prints the
+ error message <EM>msg</EM> to <EM>stderr</EM>, flushes <EM>stdout</EM>
+ and <EM>stderr</EM>, and terminates the program with a segementation fault.
+
+<P>
+
+\section RASTER3D_Function_Index RASTER3D Function Index
+
+\subsection Opening_and_Closing_RASTER3D_Files Opening and Closing RASTER3D Files
+
+<P>
+void *Rast3d_openCellOld(char *name, char *mapset, RASTER3D_Region *window,
+ int type, int cache)Opens existing g3d-file <EM>name</EM> in <EM>mapset</EM>.
+
+<P>
+Tiles are stored in memory with <EM>type</EM> which must be any of FCELL_TYPE,
+ DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies the
+ cache-mode used and must be either RASTER3D_NO_CACHE, RASTER3D_USE_CACHE_DEFAULT,
+ RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
+ RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ,
+ RASTER3D_USE_CACHE_XYZ, the result of <TT>Rast3d_cacheSizeEncode()</TT> (cf.
+ Section 22.4.6), or any positive integer which
+ specifies the number of tiles buffered in the cache. <EM>window</EM> sets the
+ window-region for the map. It is either a pointer to a window structure or
+ RASTER3D_DEFAULT_WINDOW, which uses the window stored at initialization time or
+ set via <TT>Rast3d_setWindow()</TT> (cf. Section 22.4.16).
+ To modify the window for the map after it has already been opened use
+ <TT>Rast3d_setWindowMap()</TT> (cf. Section 22.4.16).
+
+<P>
+Returns a pointer to the cell structure ... if successful, NULL ...
+ otherwise.
+
+<P>
+void *Rast3d_openCellNew(char *name, int type, int cache, RASTER3D_Region
+ *region)Opens new g3d-file with <EM>name</EM> in the current mapset. Tiles
+ are stored in memory with <EM>type</EM> which must be one of FCELL_TYPE,
+ DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies the
+ cache-mode used and must be either RASTER3D_NO_CACHE, RASTER3D_USE_CACHE_DEFAULT,
+ RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
+ RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ,
+ RASTER3D_USE_CACHE_XYZ, the result of <TT>Rast3d_cacheSizeEncode()</TT> (cf.
+ Section 22.4.6), or any positive integer which
+ specifies the number of tiles buffered in the cache. <EM>region</EM> specifies
+ the 3d region.
+
+<P>
+Returns a pointer to the cell structure ... if successful,
+ NULL ... otherwise.
+
+<P>
+void *Rast3d_openCellNewParam(char *name, int typeIntern, int cache,
+ RASTER3D_Region *region, int type, int doLzw, int doRle, int precision, int tileX,
+ int tileY, int tileZ)Opens new g3d-file with <EM>name</EM> in the current
+ mapset. Tiles are stored in memory with <EM>typeIntern</EM> which must be one of
+ FCELL_TYPE, DCELL_TYPE, or RASTER3D_TILE_SAME_AS_FILE. <EM>cache</EM> specifies
+ the cache-mode used and must be either RASTER3D_NO_CACHE,
+ RASTER3D_USE_CACHE_DEFAULT, RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y,
+ RASTER3D_USE_CACHE_Z, RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ,
+ RASTER3D_USE_CACHE_YZ, RASTER3D_USE_CACHE_XYZ, the result of
+ <TT>Rast3d_cacheSizeEncode()</TT> (cf.
+ Section 22.4.6), or any positive integer which
+ specifies the number of tiles buffered in the cache. <EM>region</EM> specifies
+ the 3d region.
+
+<P>
+In addition the properties of the new file have to be specified. It is
+ assumed by default that compression is used. This function first sets the
+ global default values to the specified values, and then restores the original
+ global defaults. This function can be used in conjunction with
+ <TT>Rast3d_setStandard3dInputParams()</TT> (cf.
+ Section 22.4.18) and
+ <TT>Rast3d_getStandard3dParams()</TT>.
+
+<P>
+Returns a pointer to the cell structure ... if successful, NULL ...
+ otherwise.
+
+<P>
+int Rast3d_closeCell(void *map)Closes g3d-file. If <EM>map</EM> is new
+ and cache-mode is used for <EM>map</EM> then every tile which is not flushed
+ before closing is flushed.
+
+<P>
+Returns 1 ... if successful, 0 ... otherwise.
+
+<P>
+
+\subsection Reading_and_Writing_Tiles Reading and Writing Tiles
+
+<P>
+These functions read or write data directly to the file (after performing the
+appropriate compression) without going through the cache. In order to avoid
+unexpected side-effects the use of these functions in cache mode is
+discouraged.
+
+<P>
+int Rast3d_readTile(void *map, char *tileIndex, int tile, int type)
+ Reads tile with index <EM>tileIndex</EM> into the <EM>tile</EM> buffer. The cells
+ are stored with type <EM>type</EM> which must be one of FCELL_TYPE and
+ DCELL_TYPE. If the tile with <EM>tileIndex</EM> is not stored on the file
+ corresponding to <EM>map</EM>, and <EM>tileIndex</EM> is a valid index <EM>tile</EM>
+ is filled with NULL-values.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_readTileFloat(void *map, char *tileIndex, int tile)
+Is equivalent to Rast3d_readTile (map, tileIndex, tile, FCELL_TYPE).
+
+<P>
+int Rast3d_readTileDouble(void *map, char *tileIndex, int tile)
+Is equivalent to Rast3d_readTile (map, tileIndex, tile, DCELL_TYPE).
+
+<P>
+int Rast3d_writeTile(void *map, char *tileIndex, int tile, int type)
+ Writes tile with index <EM>tileIndex</EM> to the file corresponding to <EM>map</EM>. It is assumed that the cells in <EM>tile</EM> are of <EM>type</EM> which
+ must be one of FCELL_TYPE and DCELL_TYPE. The actual type used to write the
+ tile depends on the type specified at the time when <EM>map</EM> is initialized.
+
+<P>
+A tile can only be written once. Subsequent attempts to write the same tile
+ are ignored.
+
+<P>
+Returns
+ 1 ... if successful,
+ 2 ... if write request was ignored,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_writeTileFloat(void *map, char *tileIndex, int tile)
+Is equivalent to <TT>Rast3d_writeTile (map, tileIndex, tile, FCELL_TYPE).</TT>
+
+<P>
+int Rast3d_writeTileDouble(void *map, char *tileIndex, int tile)
+Is equivalent to <TT>Rast3d_writeTile (map, tileIndex, tile, DCELL_TYPE).</TT>
+
+<P>
+
+\subsection Reading_and_Writing_Cells Reading and Writing Cells
+
+<P>
+void Rast3d_getValue(void *map, int x, int y, int z, char *value, int
+ type) Returns in <EM>*value</EM> the cell-value of the cell with
+ window-coordinate <EM>(x, y, z)</EM>. The value returned is of <EM>type</EM>.
+
+<P>
+This function invokes a fatal error if an error occurs.
+
+<P>
+float Rast3d_getFloat(void *map, int x, int y, int z)Is equivalent to
+ <TT>Rast3d_getValue (map, x, y, z, &value, FCELL_TYPE);</TT> return value.
+
+<P>
+double Rast3d_getDouble(void *map, int x, int y, int z)Is equivalent
+ to <TT>Rast3d_getValue (map, x, y, z, &value, DCELL_TYPE);</TT> return value.
+
+<P>
+void Rast3d_getValueRegion(void *map, int x, int y, int z, char*value,
+ int type) Returns in <EM>*value</EM> the cell-value of the cell with
+ region-coordinate <EM>(x, y, z)</EM>. The value returned is of <EM>type</EM>.
+ Here <EM>region</EM> means the coordinate in the cube of data in the file, i.e.
+ ignoring geographic coordinates.
+
+<P>
+This function invokes a fatal error if an error occurs.
+
+<P>
+float Rast3d_getFloatRegion(void *map, int x, int y, int z)Is
+ equivalent to <TT>Rast3d_getValueRegion (map, x, y, z, &value, FCELL_TYPE);</TT>
+ return value.
+
+<P>
+double Rast3d_getDoubleRegion(void *map, int x, int y, int z)Is
+ equivalent to <TT>Rast3d_getValueRegion (map, x, y, z, &value,
+ DCELL_TYPE);</TT> return value.
+
+<P>
+int Rast3d_putValue(void *map, int x, int y, int z, char *value, int
+ type)After converting <EM>*value</EM> of <EM>type</EM> into the type specified
+ at the initialization time (i.e. <EM>typeIntern</EM>) this function writes the
+ value into the tile buffer corresponding to cell-coordinate <EM>(x, y, z)</EM>.
+
+<P>
+Returns
+
+<P>
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_putFloat(void *map, int x, int y, int z, char *value)Is
+ equivalent to Rast3d_putValue (map, x, y, z, &value, FCELL_TYPE).
+
+<P>
+int Rast3d_putDouble(void *map, int x, int y, int z, char *value) Is
+ equivalent to Rast3d_putValue (map, x, y, z, &value, DCELL_TYPE).
+
+<P>
+
+\subsection Loading_and_Removing_TilesLoading and Removing Tiles
+
+<P>
+char *Rast3d_getTilePtr(void *map, int tileIndex) This function
+ returns a pointer to a tile which contains the data for the tile with index
+ <EM>tileIndex</EM>. The type of the data stored in the tile depends on the type
+ specified at the initialization time of <EM>map</EM>. The functionality is
+ different depending on whether <EM>map</EM> is old or new and depending on the
+ cache-mode of <EM>map</EM>.
+<BR>
+<P>
+If <EM>map</EM> is old and the cache is not used the tile with <EM>tileIndex</EM>
+ is read from file and stored in the buffer provided by the map structure.
+ The pointer to this buffer is returned. If the buffer already contains the
+ tile with <EM>tileIndex</EM> reading is skipped. Data which was stored in
+ earlier calls to <TT>Rast3d_getTilePtr</TT> is destroyed. If the tile with
+ <EM>tileIndex</EM> is not stored on the file corresponding to <EM>map</EM>, and
+ <EM>tileIndex</EM> is a valid index the buffer is filled with NULL-values.
+<BR>
+<P>
+If <EM>map</EM> is old and the cache is used the tile with <EM>tileIndex</EM> is
+ read from file and stored in one of the cache buffers. The pointer to buffer
+ is returned. If no free cache buffer is available an unlocked cache-buffer
+ is freed up and the new tile is stored in its place. If the tile with
+ <EM>tileIndex</EM> is not stored on the file corresponding to <EM>map</EM>, and
+ <EM>tileIndex</EM> is a valid index the buffer is filled with NULL-values. If one
+ of the cache buffers already contains the tile with <EM>tileIndex</EM> reading
+ is skipped and the pointer to this buffer is returned.
+<BR>
+<P>
+If <EM>map</EM> is new and the cache is not used the functionality is the same
+ as if <EM>map</EM> is old and the cache is not used. If the tile with
+ <EM>tileIndex</EM> is already stored on file, it is read into the buffer, if not,
+ the cells are set to null-values. If the buffer corresponding to the pointer
+ is used for writing, subsequent calls to <TT>Rast3d_getTilePtr</TT> may destroy the
+ values already stored in the buffer. Use <TT>Rast3d_flushTile</TT> to write the buffer
+ to the file before reusing it for a different index. The use of this buffer
+ as write buffer is discouraged.
+<BR>
+<P>
+If <EM>map</EM> is new and the cache is used the functionality is the same as if
+ <EM>map</EM> is old and the cache is used with the following exception. If
+ <EM>tileIndex</EM> is a valid index and the tile with this index is not found in
+ the cache and is not stored on the file corresponding to <EM>map</EM>, then the
+ file cache is queried next. If the file-cache contains the tile it is loaded
+ into the cache (memory-cache). Only if the file-cache does not contain the
+ tile it is filled with NULL-values. Tile contents of buffers are never
+ destroyed. If a cache buffer needs to be freed up, and the tile stored in the
+ buffer has not been written to the file corresponding to <EM>map</EM> yet, the
+ tile is copied into the file-cache.
+<BR>
+<P>
+Care has to be taken if this function is used in non-cache mode since it is
+ implicitly invoked every time a read or write request is issued. The only
+ I/O-functions for which it is safe to assume that they do not invoke
+ <TT>Rast3d_getTilePtr</TT> are <TT>Rast3d_readTile()</TT> and
+ <TT>Rast3d_writeTile()</TT> and their corresponding type-specific versions.
+
+<P>
+Returns
+ a pointer to a buffer ... if successful,
+ NULL ... otherwise.
+
+<P>
+int Rast3d_tileLoad(void *map, int tileIndex)
+Same functionality as <TT>Rast3d_getTilePtr()</TT> but does not return the
+pointer.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_removeTile(void *map, inttileIndex) Removes a tile
+ from memory-cache if tile is in memory-cache. For new maps the
+ application does not know whether the tile is in the memory-cache or in
+ the file-cache. Therefore, for new maps this function should be
+ preceded by <TT>Rast3d_tileLoad()</TT>.
+
+<P>
+<EM>(Question: Is this a useful function?)</EM>
+
+<P>
+Returns 1 ... if successful, 0 ... otherwise.
+
+<P>
+
+\subsection Write_Functions_used_in_Cache_Mode Write Functions used in Cache Mode
+
+<P>
+int Rast3d_flushTile(void *map, int tileIndex) Writes the tile with
+ <EM>tileIndex</EM> to the file corresponding to <EM>map</EM> and removes the tile
+ from the cache (in non-cache mode the buffer provided by the map-structure is
+ written).
+
+<P>
+If this tile has already been written before the write request is ignored.
+ If the tile was never referred to before the invokation of Rast3d_flushTile, a
+ tile filled with NULL-values is written.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_flushTileCube(void *map, int xMin, int yMin, int zMin, int
+ xMax, int yMax, int zMax) Writes the tiles with tile-coordinates
+ contained in the axis-parallel cube with vertices <EM>(xMin, yMin, zMin)</EM>
+ and <EM>(xMax, yMax, zMax</EM>). Tiles which are not stored in the cache are
+ written as NULL-tiles. Write attempts for tiles which have already been
+ written earlier are ignored.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_flushTilesInCube(void *map, int xMin, int yMin, int
+ zMin, int xMax, int yMax, int zMax) Writes those tiles for which
+ <EM>every</EM> cell has coordinate contained in the axis-parallel cube
+ defined by the vertices with cell-coordinates <EM>(xMin, yMin, zMin)</EM>
+ and <EM>(xMax, yMax, zMax)</EM>.
+
+<P>
+Tiles which are not stored in the cache are written as NULL-tiles.
+ Write attempts for tiles which have already been written earlier are
+ ignored.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+
+\subsection Locking_and_Unlocking_Tiles_and_CyclesLocking and Unlocking Tiles, and Cycles
+
+<P>
+int Rast3d_lockTile(void *map, int tileIndex) Locks tile with <EM>tileIndex</EM> in cache.
+If after locking fewer than the minimum number of
+ unlocked tiles are unlocked, the lock request is ignored.
+
+<P>
+Returns
+ 1 ... if successful,
+ -1 ... if request is ignored,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_unlockTile(void *map, int tileIndex)
+Unlocks tile with <EM>tileIndex</EM>.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_unlockAll(void *map)
+Unlocks every tile in cache of <EM>map</EM>.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+void Rast3d_autolockOn(void *map)
+Turns autolock mode on.
+
+<P>
+void Rast3d_autolockOff(void *map)
+Turns autolock mode Off.
+
+<P>
+void Rast3d_minUnlocked(void *map, int minUnlocked) Sets the minimum
+ number of unlocked tiles to <EM>minUnlocked</EM>. This function should be used
+ in combination with <TT>Rast3d_unlockAll()</TT> in order to avoid situations where the
+ new minimum is larger than the actual number of unlocked tiles.
+
+<P>
+<EM>minUnlocked</EM> must be one of RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y,
+ RASTER3D_USE_CACHE_Z, RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ,
+ RASTER3D_USE_CACHE_YZ, RASTER3D_USE_CACHE_XYZ, the result of Rast3d_cacheSizeEncode()
+ (cf. Section 22.4.6), or any positive integer
+ which explicitly specifies the number of tiles.
+
+<P>
+int Rast3d_beginCycle(void *map)
+Starts a new cycle.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_endCycle(void *map)
+Ends a cycle.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_cacheSizeEncode(int cacheCode, int n) Returns a number
+ which encodes multiplicity <EM>n</EM> of <EM>cacheCode</EM>. This value can be used
+ to specify the size of the cache.
+
+<P>
+If <EM>cacheCode</EM> is the size (in tiles) of the cache the function returns
+ <EM>cacheCode * n</EM>.
+
+<P>
+If <EM>cacheCode</EM> is RASTER3D_USE_CACHE_DEFAULT the function returns
+ RASTER3D_USE_CACHE_DEFAULT.
+
+<P>
+If <EM>cacheCode</EM> is RASTER3D_USE_CACHE_??? the function returns a value
+ encoding RASTER3D_USE_CACHE_??? and <EM>n</EM>. Here RASTER3D_USE_CACHE_??? is one
+ of RASTER3D_USE_CACHE_X, RASTER3D_USE_CACHE_Y, RASTER3D_USE_CACHE_Z,
+ RASTER3D_USE_CACHE_XY, RASTER3D_USE_CACHE_XZ, RASTER3D_USE_CACHE_YZ, or
+ RASTER3D_USE_CACHE_XYZ, where e.g. RASTER3D_USE_CACHE_X specifies that the cache
+ should store as many tiles as there exist in one row along the x-axis of the
+ tile cube, and RASTER3D_USE_CACHE_XY specifies that the cache should store as
+ many tiles as there exist in one slice of the tile cube with constant Z
+ coordinate.
+
+<P>
+
+\subsection Reading_Volumes Reading Volumes
+
+<P>
+int Rast3d_getVolume(void *map, double originNorth, double originWest,
+ double originBottom, double vxNorth, double vxWest, double vxBottom, double
+ vyNorth, double vyWest, double vyBottom, double vzNorth, double vzWest,
+ double vzBottom, int nx, int ny, int nz, char *volumeBuf, int type)
+ Resamples the cube defined by <EM>origin</EM> and the 3 vertices <EM>vx</EM>,
+ <EM>vy</EM>, and <EM>vz</EM> which are incident to the 3 edges adjacent to
+ <EM>origin</EM>. The resampled cube is stored in <EM>volumeBuf</EM> which is a cube
+ with dimensions <EM>(nx, ny, nz)</EM>.
+
+<P>
+The method of sampling is nearest neighbor sampling.
+
+<P>
+The values stored are of <EM>type</EM>.
+
+<P>
+Returns 1 ... if successful, 0 ... otherwise.
+
+<P>
+int Rast3d_getAllignedVolume(void *map, double originNorth, double
+ originWest, double originBottom, double lengthNorth, double lengthWest,
+ double lengthBottom, int nx, int ny, int nz, char *volumeBuf, int type)
+ Resamples the axis-parallel cube defined by <EM>origin</EM> and the lengths of
+ the 3 edges adjacent to <EM>origin</EM>. The resampled cube is stored in
+ <EM>volumeBuf</EM> which is a cube with dimensions <EM>(nx, ny, nz)</EM>. The method
+ of sampling is nearest neighbor sampling. The values stored are of <EM>type</EM>.
+
+<P>
+Returns 1 ... if successful, 0 ... otherwise.
+
+<P>
+
+\subsection Allocating_and_Freeing_Memory Allocating and Freeing Memory
+
+<P>
+void *Rast3d_malloc(int nBytes)
+Same as <EM>malloc (nBytes)</EM>, except that in case of error
+<TT>Rast3d_error()</TT> is invoked.
+
+<P>
+Returns
+ a pointer ... if successful,
+ NULL ... otherwise.
+
+<P>
+void *Rast3d_realloc(void *ptr, int nBytes)
+Same as <EM>realloc (ptr, nBytes)</EM>, except that in case of error
+<TT>Rast3d_error()</TT> is invoked.
+
+<P>
+Returns
+ a pointer ... if successful,
+ NULL ... otherwise.
+
+<P>
+void Rast3d_free(void *ptr) Same as <EM>free (ptr)</EM>.
+
+<P>
+char *Rast3d_allocTilesType(void *map, int nofTiles, int type)
+Allocates a vector of <EM>nofTiles</EM> tiles with the same dimensions
+as the tiles of <EM>map</EM> and large enough to store cell-values of
+<EM>type</EM>.
+
+<P>
+Returns
+ a pointer to the vector ... if successful,
+ NULL ... otherwise.
+
+<P>
+char *Rast3d_allocTiles(void *map, int nofTiles)
+Is equivalent to Rast3d_allocTilesType (map, nofTiles, Rast3d_fileTypeMap (map)).
+
+<P>
+void Rast3d_freeTiles(char *tiles)
+Is equivalent to <TT>Rast3d_free (tiles);</TT>
+
+<P>
+
+\subsection RASTER3D_Null_Value_Support RASTER3D Null Value Support
+
+<P>
+void Rast3d_isNullValueNum(void *n, int type)
+Returns 1 if the value of <EM>*n</EM> is a NULL-value. Returns 0
+otherwise.
+
+<P>
+void Rast3d_setNullValue(void *c, int nofElts, int type)
+Fills the vector pointed to by <EM>c</EM> with <EM>nofElts</EM> NULL-values
+of <EM>type</EM>.
+
+<P>
+void Rast3d_setNullTileType(void *map, int tile, int type)
+Assumes that <EM>tile</EM> is a tile with the same dimensions as the
+tiles of <EM>map</EM>. Fills <EM>tile</EM> with NULL-values of
+<EM>type</EM>.
+
+<P>
+void Rast3d_setNullTile(void *map, int tile)
+Is equivalent to Rast3d_setNullTileType (map, tile, Rast3d_fileTypeMap (map)).
+
+<P>
+
+\subsection RASTER3D_Map_Header_Information RASTER3D Map Header Information
+
+<P>
+void Rast3d_getCoordsMap(void *map, int *rows, int *cols, int *depths)
+Returns the size of the region of <EM>map</EM> in cells.
+
+<P>
+void Rast3d_getRegionMap(void *map, int *north, int *south, int *east,
+ int *west, int *top, int *bottom)Returns the size of the region.
+
+<P>
+void Rast3d_getRegionStructMap(void *map, RASTER3D_Region *region)
+Returns in <EM>region</EM> the region of <EM>map</EM>.
+
+<P>
+void Rast3d_getTileDimensionsMap(void *map, int *x, int *y, int *z)
+Returns the tile dimensions used for <EM>map</EM>.
+
+<P>
+void Rast3d_getNofTilesMap(void *map, int *nx, int *ny, int *nz)
+ Returns the dimensions of the tile-cube used to tile the region of <EM>map</EM>.
+ These numbers include partial tiles.
+
+<P>
+int Rast3d_tileTypeMap(void *map)
+Returns the type in which tiles of <EM>map</EM> are stored in memory.
+
+<P>
+int Rast3d_fileTypeMap(void *map)
+Returns the type with which tiles of <EM>map</EM> are stored on file.
+
+<P>
+int Rast3d_tilePrecisionMap(void *map)
+Returns the precision used to store <EM>map</EM>.
+
+<P>
+int Rast3d_tileUseCacheMap(void *map)
+Returns 1 if <EM>map</EM> uses cache, returns 0 otherwise.
+
+<P>
+void Rast3d_printHeader(void *map)
+Prints the header information of <EM>map</EM>.
+
+<P>
+
+\subsection RASTER3D_Tile_Math RASTER3D Tile Math
+
+<P>
+void Rast3d_tileIndex2tile(void *map, int tileIndex, int *xTile, int
+ *yTile, int *zTile) Converts index <EM>tileIndex</EM> into tile-coordinates
+ <EM>(xTile, yTile, zTile)</EM>.
+
+<P>
+int Rast3d_tile2tileIndex(void *map, int xTile, int yTile, int
+ zTile) Returns tile-index corresponding to tile-coordinates <EM>(xTile,
+ yTile, zTile)</EM>.
+
+<P>
+void Rast3d_coord2tileCoord(void *map, int x, int y, int z, int *xTile,
+ int *yTile, int *zTile, int *xOffs, int *yOffs, int *zOffs) Converts
+ cell-coordinates <EM>(x, y, z)</EM> into tile-coordinates <EM>(xTile, yTile,
+ zTile)</EM> and the coordinate of the cell <EM>(xOffs, yOffs, zOffs)</EM> within
+ the tile.
+
+<P>
+void Rast3d_tileCoordOrigin(void *map, int xTile, int yTile, int zTile,
+ int *x, int *y, int *z) Computes the cell-coordinates <EM>(x, y, z)</EM>
+ which correspond to the origin of the tile with tile-coordinates <EM>(xTile,
+ yTile, zTile)</EM>.
+
+<P>
+void Rast3d_tileIndexOrigin(void *map, int tileIndex, int *x, int *y,
+ int *z) Computes the cell-coordinates <EM>(x, y, z)</EM> which correspond to
+ the origin of the tile with <EM>tileIndex</EM>.
+
+<P>
+void Rast3d_coord2tileIndex(void *map, int x, int y, int z, int
+ *tileIndex, int *offset) Converts cell-coordinates <EM>(x, y, z)</EM> into
+ <EM>tileIndex</EM> and the <EM>offset</EM> of the cell within the tile.
+
+<P>
+int Rast3d_coordInRange(void *map, int x, int y, int z) Returns 1 if
+ cell-coordinate <EM>(x, y, z)</EM> is a coordinate inside the region. Returns 0
+ otherwise.
+
+<P>
+int Rast3d_tileInRange(void *map, int x, int y, int z) Returns 1 if
+ tile-coordinate <EM>(x, y, z)</EM> is a coordinate inside tile cube. Returns 0
+ otherwise.
+
+<P>
+int Rast3d_tileIndexInRange(void *map, int tileIndex)
+Returns 1 if <EM>tileIndex</EM> is a valid index for <EM>map</EM>.
+Returns 0 otherwise.
+
+<P>
+int Rast3d_isValidLocation(void *map, double north, double west, double
+ bottom) Returns 1 if region-coordinates <EM>(north, west, bottom)</EM> are
+ inside the region of <EM>map</EM>. Returns 0 otherwise.
+
+<P>
+void Rast3d_location2coord(void *map, double north, double west, double
+ bottom, int *x, *y, *z) Converts region-coordinates <EM>(north, west,
+ bottom)</EM> into cell-coordinates <EM>(x, y, z)</EM>.
+
+<P>
+int Rast3d_computeClippedTileDimensions(void *map, int tileIndex, int
+ *rows, int *cols, int *depths, int *xRedundant, int *yRedundant, int
+ *zRedundant) Computes the dimensions of the tile when clipped to fit the
+ region of <EM>map</EM>. The clipped dimensions are returned in <EM>rows</EM>,
+ <EM>cols</EM>, <EM>depths</EM>. The complement is returned in <EM>xRedundant</EM>,
+ <EM>yRedundant</EM>, and <EM>zRedundant</EM>. This function returns the number of
+ cells in the clipped tile.
+
+<P>
+
+\subsection RASTER3D_Range_Support RASTER3D Range Support
+
+<P>
+The map structure of RASTER3D provides storage for the range. The range of a map is
+updated every time a cell is written to the file. When an old map is opened the
+range is not automatically loaded. The application has to invoke
+<TT>Rast3d_range_load()</TT> (cf. Section 22.4.12)
+ explicitly. In
+addition to these function the application can also use the standard grass
+functions to manipulate the range.
+
+<P>
+int Rast3d_range_load(void *map)
+Loads the range into the range structure of <EM>map</EM>.
+
+<P>
+Returns
+ 1 ... if successful
+ 0 ... otherwise.
+
+<P>
+void Rast3d_range_min_max(void *map, double *min, double *max)
+ Returns in <EM>min</EM> and <EM>max</EM> the minimum and maximum values of
+ the range.
+
+<P>
+int Rast3d_range_write(void *map)
+Writes the range which is stored in the range structure of <EM>map</EM>.
+(This function is invoked automatically when a new file is closed).
+
+<P>
+Returns
+ 1 ... if successful
+ 0 ... otherwise.
+
+<P>
+
+\subsection RASTER3D_Color_Support RASTER3D Color Support
+
+<P>
+Applications can use the standard grass functions to work with colors, except
+for the file manipulations.
+
+<P>
+int Rast3d_removeColor(char *name)
+Removes the primary and/or secondary color file. See <EM>G_remove_colr</EM> for
+details.
+
+<P>
+Returns always 0.
+
+<P>
+int Rast3d_readColors(char *name, char *mapset, struct Colors
+ *colors) Reads color file for map <EM>name</EM> in <EM>mapset</EM> into the
+ <EM>colors</EM> structure. See <EM>G_read_colors</EM>
+ (Raster_Color_Table) for details and return values.
+
+<P>
+int Rast3d_writeColors(char *name, char *mapset, struct Colors
+ *colors)Writes colors stored in <EM>colors</EM> structure into the color
+ file for map <EM>name</EM> in <EM>mapset</EM>. See <EM>G_write_colors</EM>
+ (Raster_Color_Table) for
+ details and return values.
+
+<P>
+
+\subsection RASTER3D_Categories_Support RASTER3D Categories Support
+
+<P>
+Applications can use the standard grass functions to work with categories,
+except for the file manipulations.
+
+<P>
+int Rast3d_readCats(char *name, char *mapset, struct Categories *cats)
+Reads the categories file for map <EM>name</EM> in <EM>mapset</EM> and
+stores the categories in the <EM>cats</EM> structure. See <EM>G_read_cats</EM>
+(Raster_Category_File) for details and return values.
+
+<P>
+int Rast3d_writeCats(char *name, struct Categories *cats) Writes the
+ categories stored in the <EM>cats</EM> structure into the categories file for
+ map <EM>name</EM> in the current mapset. See <EM>G_write_cats</EM>
+ (Raster_Category_File) for details and return values.
+
+<P>
+
+
+\subsection RASTER3D_History_Support RASTER3D History Support
+
+<P>
+Applications can use the standard grass functions to work with histories,
+except for the file manipulations.
+
+<P>
+int Rast3d_readHistory(char *name, char *mapset, struct History *hist)
+ Reads the history file for map <EM>name</EM> in <EM>mapset</EM> and
+ stores the history in the <EM>hist</EM> structure. See <EM>G_read_history</EM>
+ (Raster_History_File) for details and return values.
+
+<P>
+int Rast3d_writeHistory(char *name, struct History *hist)
+ Writes the
+ history stored in the <EM>hist</EM> structure into the categories file for
+ map <EM>name</EM> in the current mapset. See <EM>G_write_history</EM>
+ (Raster_History_File) for details and return values.
+
+<P>
+
+\subsection RASTER3D_Mask_Support RASTER3D Mask Support
+
+<P>
+void Rast3d_maskOn(void *map) Turns on the mask for <EM>map</EM>. Do
+ not invoke this function after the first tile has been read since the result
+ might be inconsistent cell-values.
+
+<P>
+void Rast3d_maskOff(void *map) Turns off the mask for <EM>map</EM>.
+ This is the default. Do not invoke this function after the first tile has
+ been read since the result might be inconsistent cell-values.
+
+<P>
+int Rast3d_maskIsOn(void *map) Returns 1 if the mask for <EM>map</EM>
+ is turned on. Returns 0 otherwise.
+
+<P>
+int Rast3d_maskIsOff(void *map)
+Returns 1 if the mask for <EM>map</EM> is turned off. Returns 0 otherwise.
+
+<P>
+The remaining functions in this section are for the explicit query of the mask
+and the masking of individual cells or tiles. These functions are used in the
+library and might have applications in situations where both the masked and
+non-masked value of a cell has to be known.
+
+<P>
+int Rast3d_maskReopen(int cache)
+This function should be used to adjust the cache size used for the
+3d-mask. First the open 3d-mask is closed and then opened again with
+a cache size as specified with <EM>cache</EM>.
+
+<P>
+Returns
+ 1 ... if successful
+ 0 ... otherwise.
+
+<P>
+int Rast3d_maskFileExists() Returns 1 if the 3d mask file
+ exists.
+
+<P>
+int Rast3d_maskMapExists()
+Returns 1 if the 3d mask is loaded.
+
+<P>
+char *Rast3d_maskFile()
+Returns the name of the 3d mask file.
+
+<P>
+int Rast3d_isMasked(int x, int y, int z)
+Returns 1 if the cell with cell-coordinates <EM>(x, y, z)</EM> is masked
+out. Returns 0 otherwise.
+
+<P>
+void Rast3d_maskNum(int x, int y, int z, void *value, int type)
+Replaces the value stored in <EM>value</EM> with the NULL-value if
+<EM>Rast3d_isMasked (x, y, z)</EM> returns 1. Does nothing otherwise.
+<EM>value</EM> is assumed to be of<EM>type</EM>.
+
+<P>
+void Rast3d_maskFloat(int x, int y, int z, float *value)
+Same as <EM>Rast3d_maskNum (x, y, z, value, FCELL_TYPE)</EM>.
+
+<P>
+void Rast3d_maskDouble(int x, int y, int z, double *value)
+Same as <EM>Rast3d_maskNum (x, y, z, value, DCELL_TYPE)</EM>.
+
+<P>
+void Rast3d_maskTile(void *map, int tileIndex, char *tile, int type)
+Replaces the values stored in <EM>tile</EM> (with <EM>tileIndex</EM>) for
+which <EM>Rast3d_isMasked</EM> returns 1 with NULL-values. Does not change
+the remaining values. The values are assumed to be of <EM>type</EM>.
+Whether replacement is performed or not only depends on location of the
+cells of the tile and not on the status of the mask for <EM>map</EM>
+(i.e. turned on or off).
+
+<P>
+
+\subsection RASTER3D_Window_Support RASTER3D Window Support
+
+<P>
+void Rast3d_setWindowMap(void *map, RASTER3D_Region *window)
+Sets the window for <EM>map</EM> to <EM>window</EM>.
+Can be used multiple times for the same map.
+
+<P>
+void Rast3d_setWindow(RASTER3D_Region *window)
+Sets the default window used for every map opened later in the program.
+Can be used multiple times in the same program.
+
+<P>
+void Rast3d_getWindow(RASTER3D_Region *window)
+Stores the current default window in <EM>window</EM>.
+
+<P>
+void *Rast3d_windowPtr()
+Returns a pointer to the current default window. This pointer should not be
+(ab)used to modify the current window structure directly. It is
+provided to pass a window pointer when opening a map.
+
+<P>
+int Rast3d_readWindow(RASTER3D_Region *window, char *windowName) Reads
+ <EM>window</EM> from the file specified by <EM>windowName</EM>. The name is
+ converted by the rules defined in window defaults. A NULL pointer indicates
+ the <EM>WIND3</EM> file in the current mapset.
+
+<P>
+Returns
+ 1 ... if successful
+ 0 ... otherwise.
+
+<P>
+int Rast3d_writeWindow(RASTER3D_Region *window, char *windowName)
+ Writes <EM>window</EM> to the file specified by <EM>windowName</EM>. The name
+ is converted by the rules defined in window defaults. A NULL pointer
+ indicates the <EM>WIND3</EM> file in the current mapset.
+
+<P>
+Returns
+ 1 ... if successful
+ 0 ... otherwise.
+
+<P>
+void Rast3d_useWindowParams()
+Allows the window to be set at run-time via the <EM>region3</EM>
+command line argument. This function has to be called before
+<EM>G_parser()</EM>. See also
+ window defaults.
+
+<P>
+void Rast3d_setResamplingFun(void *map, void (*resampleFun)())
+Sets the resampling function to be used by
+Rast3d_getValue() (cf. Section 22.4.3). This function is defined
+as follows:
+
+<P>
+void Rast3d_customResampleFun(void *map, int row, int col, int depth,
+ char *value, int type) <EM>row</EM>, <EM>col</EM>, and <EM>depth</EM> are in
+ region coordinates. The result is returned in <EM>value</EM> as <EM>type</EM> which
+ is one of FCELL_TYPE or DCELL_TYPE. Possible choices include
+ Rast3d_nearestNeighbor() (cf. Section22.4.16) and
+ Rast3d_getValueRegion() (cf. Section 22.4.3).
+
+<P>
+void Rast3d_nearestNeighbor(void *map, int row, int col, int depth, char
+ *value, int type) The default resampling function which uses nearest
+ neighbor resampling.
+
+<P>
+void Rast3d_getResamplingFun(void *map, void (**resampleFun)())
+ Returns in <EM>resampleFun</EM> a pointer to the resampling function used by
+ <EM>map</EM>.
+
+<P>
+void Rast3d_getNearestNeighborFunPtr(void (**nnFunPtr)()) Returns
+ in <EM>nnFunPtr</EM> a pointer to Rast3d_nearestNeighbor() (cf.
+ Section <A HREF="#g3d:G3d.nearestNeighbor">22.4.16</A>).
+
+<P>
+
+\subsection RASTER3D_Region RASTER3D Region
+
+<P>
+void Rast3d_extract2dRegion(RASTER3D_Region *region3d, struct Cell_head
+ *region2d) Returns in <EM>region2d</EM> the <EM>2d</EM> portion of <EM>region3d</EM>.
+
+<P>
+void Rast3d_incorporate2dRegion(struct Cell_head *region2d, RASTER3D_Region
+ *region3d) Replaces the <EM>2d</EM> portion of <EM>region3d</EM> with the
+ values stored in <EM>region2d</EM>.
+
+<P>
+void Rast3d_adjustRegion(RASTER3D_Region *region)
+Computes an adjusts the resolutions in the region structure from the region
+boundaries and number of cells per dimension.
+
+<P>
+void Rast3d_adjustRegionRes(RASTER3D_Region *region)
+Computes an adjusts the number of cells per dimension in the region
+structure from the region boundaries and resolutions.
+
+<P>
+void Rast3d_regionCopy(RASTER3D_Region *regionDest, RASTER3D_Region *regionSrc)
+Copies the values of <EM>regionSrc</EM> into <EM>regionDst</EM>.
+(The unfortunate order of parameters was chosen in order to conform to the
+order used in <EM>G_copy()</EM>).
+
+<P>
+void Rast3d_getRegionValue(void *map, double north, double east, double
+ top, char *value, int type) Returns in <EM>value</EM> the value of the <EM>map</EM>
+ which corresponds to region coordinates <EM>(north, east, top)</EM>. The
+ value is resampled using the resampling function specified for <EM>map</EM>. The
+ <EM>value</EM> is of <EM>type</EM>.
+
+<P>
+void Rast3d_readRegionMap(char *name, char *mapset, RASTER3D_Region *region)
+Returns in <EM>region</EM> the region information for 3d cell <EM>name at mapset</EM>.
+
+<P>
+
+\subsection Miscellaneous_Functions Miscellaneous Functions
+
+<P>
+void Rast3d_g3dType2cellType(int g3dType) Returns the GRASS floating
+ point type which is equivalent to the RASTER3D type of <EM>g3dType</EM>.
+
+<P>
+void Rast3d_initDefaults() Initializes the default values described
+ in RASTER3D Defaults. Applications have to use this function only if they need to
+ query the default values before the first file (either old or new) has been
+ opened.
+
+<P>
+void Rast3d_setStandard3dInputParams()
+ Initializes a parameter
+ structure for the subset of command line arguments which lets the user
+ overwrite the default properties of the new file. Applications are
+ encouraged to use this function in order to provide a uniform style. The
+ command line arguments provided are the <EM>type</EM> of the cell values, the
+ <EM>precision</EM>, the properties of the <EM>compression</EM>, and the dimension
+ of the tiles (<EM>tiledimension</EM>). Every of these values defaults to the
+ value described in RASTER3D Defaults.
+
+<P>
+This function has to be used in conjunction with
+ Rast3d_getStandard3dInputParams() (cf.
+ Section 22.4.18).
+
+<P>
+int Rast3d_getStandard3dInputParams(int *useTypeDefault, *type, *useLzwDefault, *doLzw,
+ int *useRleDefault, *doRle, *usePrecisionDefault, *precision,
+ int *useDimensionDefault, *tileX, *tileY, *tileZ
+Returns the properties of the new file as chosen by the user via command
+line arguments. If the default is chosen the values of
+<EM>useXxxxDefault</EM> is 1, it is 0 otherwise. In addition, the
+corresponding parameters contain the default value if
+<EM>useXxxxDefault</EM> is 1, or the value specified by the user if
+<EM>useXxxxDefault</EM> is 0.
+
+<P>
+Function
+Rast3d_setStandard3dInputParams() (cf. Section 22.4.18)
+has to be used to initialize the internal parameter structure.
+
+<P>
+Returns
+ 1 ... if successful,
+ 0 ... otherwise.
+
+<P>
+int Rast3d_makeMapsetMapDirectory(char *mapName)
+Creates the 3d mapset element for map <EM>mapName</EM>.
+
+<P>
+int Rast3d_filename(char *path, *elementName, *mapName, *mapset)
+Returns in <EM>path</EM> the path for element <EM>elementName</EM> for map
+<EM>mapName</EM> in <EM>mapset</EM>. Note, an error occurs if <EM>mapName</EM>
+is fully qualified.
+
+<P>
+See TimeStamp_functions for a complete discussion of GRASS datetime
+routines (reading, writing grid3d timestamps).
+
+<P>
+
+\section Sample_RASTER3D_Applications Sample RASTER3D Applications
+
+<P>
+These functions were implemented to test the library. They are not very
+efficient but can be used as starting point for other
+applications. Some of them might actually be useful. They are available from
+GRASS 7 source code in lib/g3d/.
+
+<P>
+void Rast3d_retile(void *map, char *nameOut, int tileX, int tileY, int tileZ)
+Makes a copy of <EM>map</EM> with name <EM>nameOut</EM> which has
+tile dimensions <EM>tileX</EM>, <EM>tileY</EM>, <EM>tileZ</EM>.
+
+<P>
+The source code can be found in <EM>retile.c</EM>.
+
+<P>
+void Rast3d_changePrecision(void *map, int precision, char *nameOut)
+Makes a copy of <EM>map</EM> with name <EM>nameOut</EM> which is
+written with <EM>precision</EM>.
+
+<P>
+The source code can be found in <EM>changeprecision.c</EM>.
+
+<P>
+void Rast3d_changeType(void *map, char *nameOut)
+Makes a copy of <EM>map</EM> with name <EM>nameOut</EM> in which the
+cells are of type FCELL_TYPE if they are DCELL_TYPE in <EM>map</EM>,
+and in DCELL_TYPE otherwise.
+
+<P>
+The source code can be found in <EM>changetype.c</EM>.
+
+<P>
+void Rast3d_compareFiles(char *f1, char *mapset1, char *f2, char *mapset2)
+Compares the cell-values of file <EM>f1</EM> in mapset
+<EM>mapset1</EM> and file <EM>f2</EM> in mapset <EM>mapset2</EM>.
+The values are compared up to precision.
+Terminates in error if the files don't match.
+This function uses the more advanced features of the cache.
+
+<P>
+The source code can be found in <EM>filecompare.c</EM>.
+
+<P>
+void Rast3d_getBlock(void *map, int x0, int y0, int z0, int nx, int ny,
+int nz, char *block, int type)
+Copies the cells contained in the block (cube) with vertices
+<EM>(x0, y0, z0)</EM> and <EM>(x0 + nx - 1, y0 + ny - 1, z0 + nz - 1)</EM>
+into <EM>block</EM>. The cell-values in <EM>block</EM> are of <EM>type</EM>.
+
+<P>
+The source code can be found in <EM>getblock.c</EM>.
+
+<P>
+void Rast3d_writeAscii(void *map, char *fname)
+Writes the cell-values of <EM>map</EM> in ascii format to file
+<EM>fname</EM>. The values are organized by horizontal slices.
+
+
+<P>
+See \ref Compiling_and_Installing_GRASS_Modules for a complete
+discussion of Makefiles.
+
+Authors: Roman Waupotitsch and Michael Shapiro, Helena Mitasova,
+ Bill Brown, Lubos Mitas, Jaro Hofierka,
+ Minor modification, code cleanup and test suite by Soeren Gebbert
+
+*/
More information about the grass-commit
mailing list