Geografic-Information-System/lib/raster3d/raster3dlib.dox

/*! \page raster3dlib GRASS 3D Raster Volume Library
<!-- doxygenized from "GRASS 5 Programmer's Manual" 
     by M. Neteler 5/2004, 8/2005
  -->

<i>TODO: Update for this page for GRASS 7, most of the function names have been changed from camel case to gnu underscore style.</i>

\tableofcontents

\section raster3dlib_Overview Overview

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 arbitrary 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.
<P>
Random reading and writing is supported until are tiles are flushed to the disk.
In case the tiles are written to the disk, random reading is still supported.
<P>
The size of the tile cache in memory can be set in bytes using the environmental variable  RASTER3D_MAX_CACHE_SIZE.
Default size is 16777216 bytes.The number of tiles hold in memory can be specified with the environmental variable
RASTER3D_DEFAULT_CACHE_SIZE. Default is 1000.

\image html "raster3d_layout.png" "The volume coordinate system and tile layout of the 3D Raster Library"

\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
        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 writing. <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

NOTE: RLE compression was removed because of error-prone implementation.
De-compression is still available for backward compatibility.

Default compression is now zip.

<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
        zlib
\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>
The default and suggested setting is to use precision and zlib.

<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_get_value()

<P>
and

<P>
int Rast3d_put_value()

<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_get_value()</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_get_value()</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
VerticalUnits: 1
\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 &gt;= 1, B == 1, C == 1, or
A &gt;= nofRows, B &gt;= 1, C == 1, or
A &gt;= nofRows, B &gt;= nofCols, C &gt;= 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>raster3d.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
NOTE: RLE compression is not used any longer, the RLE code is still present to assure backward compatibility.
G_zlib_write() and G_zlib_read() are used for compression now.


<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@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@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

The data untis of a map can be described using a string.
The vertical units are defined in gis.h and can be spatial or temporal.

<P>
No environment variable.

<P>
\verbatim
void Rast3d_set_unit (map, unit)
        RASTER3d_Map; // the map
        char *unit; // The data unit description

void Rast3d_set_vertical_unit (map, unit)
        RASTER3d_Map; // the map
        char *unit;  // Use the standard from units.c in lib/gis
void Rast3d_set_vertical_unit2 (map, unit)
        RASTER3d_Map; // the map
        int unit; // defined in gis.h
\endverbatim

\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>
void *Rast3d_open_new_opt_tile_size(const char *name, int cache, RASTER3D_Region * region, int type, int maxSize)

Opens new g3d-file with <em>name</em> in the current mapset. This method tries to compute
optimal tile size based on the number of rows, cols and depths and the maximum allowed tile size in KB.
Tiles are stored in memory using RASTER3D_TILE_SAME_AS_FILE method. <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_cache_size_encode ()</tt>
(cf.{g3d:G3d.cacheSizeEncode}), or any positive integer which
specifies the number of tiles buffered in the cache.  <em>region</em> specifies
the 3d region.
The map is created using the <em>type</em> which must be of FCELL_TYPE or DCELL_TYPE.
<P>
Returns a pointer to the cell structure ... if successful,
NULL ... 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, &amp;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, &amp;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, &amp;value, FCELL_TYPE);</TT>
  return value.

<P>

\code
Rast3d_getDoubleRegion(map, x, y, z)
\endcode
is equivalent to
\code
Rast3d_getValueRegion(map, x, y, z, &amp;value, DCELL_TYPE)
\endcode

<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, &amp;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, &amp;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 invocation 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_getAlignedVolume(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>
\code
Rast3d_allocTiles(map, nofTiles)
\endcode
is equivalent to
\code
Rast3d_allocTilesType(map, nofTiles, Rast3d_fileTypeMap(map)).
\endcode

<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

The map structure RASTER3D_Map 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
Rast3d_range_load() explicitly. Alternatively, an application can use
the Rast3d_read_range() function and FPRange structure to read the range.

Rast3d_range_min_max() is used to get the minimum and maximum values of the
map range into integer.

Rast3d_range_write() function stores the range in file and is invoked
automatically when a new map is closed.

In addition to these functions, the application can also use some of the
standard GRASS 2D raster functions to manipulate the floating point range. It
is preferred to use <tt>Rast3d_</tt> functions if possible and importantly it is
not possible to use functions for reading and writing.

\subsection RASTER3D_Color_Support RASTER3D Color Support

Applications can use the standard GRASS functions to work with colors,
e.g. Rast_get_d_color_range(). However, the file manipulations must be handled
using specialized raster 3D functions.

Rast3d_read_colors() function reads color file for a map into a Colors structure.
Rast3d_write_colors() function stores colors in color files for a map and
Rast3d_remove_color() function removes the color file.

\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>
Function Rast3d_read_cats() reads the categories file for map and
function Rast3d_write_cats() writes the
categories the Categories structure into the categories file for a map.
<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>
The default resampling function which uses nearest
neighbor resampling.
\code
Rast3d_nearestNeighbor(map, row, col, depth, value, type)
\endcode

<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&nbsp;<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@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
         
*/