Opening and Closing G3D Files

 
void *

G3d_openCellOld (name, mapset, window, type, cache)


	char *name, *mapset;
	G3D_Region *window;
	int type, cache;
Opens existing g3d-file name in mapset. Tiles are stored in memory with type which must be any of G3D_FLOAT, G3D_DOUBLE, or G3D_TILE_SAME_AS_FILE. cache specifies the cache-mode used and must be either G3D_NO_CACHE, G3D_USE_CACHE_DEFAULT, G3D_USE_CACHE_X, G3D_USE_CACHE_Y, G3D_USE_CACHE_Z, G3D_USE_CACHE_XY, G3D_USE_CACHE_XZ, G3D_USE_CACHE_YZ, G3D_USE_CACHE_XYZ, the result of G3d_cacheSizeEncode (), or any positive integer which specifies the number of tiles buffered in the cache. window sets the window-region for the map. It is either a pointer to a window structure or G3D_DEFAULT_WINDOW, which uses the window stored at initialization time or set via G3d_setWindow (). To modify the window for the map after it has already been opened use G3d_setWindowMap (). 
Returns 
	a pointer to the cell structure ... if successful,
	NULL ... otherwise.

void *

G3d_openCellNew (name, type, cache, region)


	char *name;
	int type, cache;
 	G3D_Region *region;
Opens new g3d-file with name in the current mapset. Tiles are stored in memory with type which must be one of G3D_FLOAT, G3D_DOUBLE, or G3D_TILE_SAME_AS_FILE. cache specifies the cache-mode used and must be either G3D_NO_CACHE, G3D_USE_CACHE_DEFAULT, G3D_USE_CACHE_X, G3D_USE_CACHE_Y, G3D_USE_CACHE_Z, G3D_USE_CACHE_XY, G3D_USE_CACHE_XZ, G3D_USE_CACHE_YZ, G3D_USE_CACHE_XYZ, the result of G3d_cacheSizeEncode (), or any positive integer which specifies the number of tiles buffered in the cache. region specifies the 3d region. 
Returns 
	a pointer to the cell structure ... if successful,
	NULL ... otherwise.

void *

G3d_openCellNewParam (name, typeIntern, cache, region,
				     type, doLzw, doRle, precision, tileX, tileY, tileZ)


	char *name;
	int typeIntern, cache;
 	G3D_Region *region;
	int type, doLzw, doRle, precision, tileX, tileY, tileZ;
Opens new g3d-file with name in the current mapset. Tiles are stored in memory with typeIntern which must be one of G3D_FLOAT, G3D_DOUBLE, or G3D_TILE_SAME_AS_FILE. cache specifies the cache-mode used and must be either G3D_NO_CACHE, G3D_USE_CACHE_DEFAULT, G3D_USE_CACHE_X, G3D_USE_CACHE_Y, G3D_USE_CACHE_Z, G3D_USE_CACHE_XY, G3D_USE_CACHE_XZ, G3D_USE_CACHE_YZ, G3D_USE_CACHE_XYZ, the result of G3d_cacheSizeEncode (), or any positive integer which specifies the number of tiles buffered in the cache. region specifies the 3d region.

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 G3d_setStandart3dInputParams () and G3d_getStandart3dParams (). 

Returns 
	a pointer to the cell structure ... if successful,
	NULL ... otherwise.

int

G3d_closeCell (map)


	void *map;
Closes g3d-file. If map is new and cache-mode is used for map then every tile which is not flushed before closing is flushed. 
Returns 
	1 ... if successful,
	0 ... otherwise.

Reading and Writing Tiles

 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. 
int

G3d_readTile (map, tileIndex, tile, type)


	void *map;
	char *tile;
	int tileIndex, type;
Reads tile with index tileIndex into the tile buffer. The cells are stored with type type which must be one of G3D_FLOAT and G3D_DOUBLE. If the tile with tileIndex is not stored on the file corresponding to map, and tileIndex is a valid index tile is filled with NULL-values. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_readTileFloat (map, tileIndex, tile)
Is equivalent to G3d_readTile (map, tileIndex, tile, G3D_FLOAT). 
int

G3d_readTileDouble (map, tileIndex, tile)
Is equivalent to G3d_readTile (map, tileIndex, tile, G3D_DOUBLE). 
int

G3d_writeTile (map, tileIndex, tile, type)


	void *map;
	char *tile;
	int tileIndex, type;
Writes tile with index tileIndex to the file corresponding to map. It is assumed that the cells in tile are of type which must be one of G3D_FLOAT and G3D_DOUBLE. The actual type used to write the tile depends on the type specified at the time when map is initialized. A tile can only be written once. Subsequent attempts to write the same tile are ignored. 
Returns 
	1 ... if successful,
	2 ... if write request was ignored,
	0 ... otherwise.

int

G3d_writeTileFloat (map, tileIndex, tile)
Is equivalent to G3d_writeTile (map, tileIndex, tile, G3D_FLOAT). 
int

G3d_writeTileDouble (map, tileIndex, tile)
Is equivalent to G3d_writeTile (map, tileIndex, tile, G3D_DOUBLE).

Reading and Writing Cells

 
void

G3d_getValue (map, x, y, z, value, type)


	void *map;
	int x, y, z;
	char *value;	
	int type;
Returns in *value the cell-value of the cell with window-coordinate (x, y, z). The value returned is of type.

This function invokes a fatal error if an error occurs. 

float

G3d_getFloat (map, x, y, z)


Is equivalent to 
	G3d_getValue (map, x, y, z, &value, G3D_FLOAT);
	return value.

double

G3d_getDouble (map, x, y, z)


Is equivalent to 
	G3d_getValue (map, x, y, z, &value, G3D_DOUBLE);
	return value.

void

G3d_getValueRegion (map, x, y, z, value, type)


	void *map;
	int x, y, z;
	char *value;	
	int type;
Returns in *value the cell-value of the cell with region-coordinate (x, y, z). The value returned is of type. Here region means the coordinate in the cube of data in the file, i.e. ignoring geographic coordinates.

This function invokes a fatal error if an error occurs. 

float

G3d_getFloatRegion (map, x, y, z)


Is equivalent to 
	G3d_getValueRegion (map, x, y, z, &value, G3D_FLOAT);
	return value.

double

G3d_getDoubleRegion (map, x, y, z)


Is equivalent to 
	G3d_getValueRegion (map, x, y, z, &value, G3D_DOUBLE);
	return value.

int

G3d_putValue (map, x, y, z, value, type)


	void *map;
	int x, y, z;
	char *value;	
	int type;
After converting *value of type into the type specified at the initialization time (i.e. typeIntern) this function writes the value into the tile buffer corresponding to cell-coordinate (x, y, z). 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_putFloat (map, x, y, z, value)


	void *map;
	int x, y, z;
	float value;
Is equivalent to G3d_putValue (map, x, y, z, &value, G3D_FLOAT). 
int

G3d_putDouble (map, x, y, z, value)


	void *map;
	int x, y, z;
	double value;
Is equivalent to G3d_putValue (map, x, y, z, &value, G3D_DOUBLE).

Loading and Removing Tiles

 
char *

G3d_getTilePtr (map, tileIndex)


	void *map;
	int tileIndex;
This function returns a pointer to a tile which contains the data for the tile with index tileIndex. The type of the data stored in the tile depends on the type specified at the initialization time of map. The functionality is different depending on whether map is old or new and depending on the cache-mode of map.

If map is old and the cache is not used the tile with tileIndex 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 tileIndex reading is skipped. Data which was stored in earlier calls to G3d_getTilePtr is destroyed. If the tile with tileIndex is not stored on the file corresponding to map, and tileIndex is a valid index the buffer is filled with NULL-values.

If map is old and the cache is used the tile with tileIndex 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 tileIndex is not stored on the file corresponding to map, and tileIndex is a valid index the buffer is filled with NULL-values. If one of the cache buffers already contains the tile with tileIndex reading is skipped and the pointer to this buffer is returned.

If map is new and the cache is not used the functionality is the same as if map is old and the cache is not used. If the tile with tileIndex 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 G3d_getTilePtr may destroy the values already stored in the buffer. Use G3d_flushTile to write the buffer to the file before reusing it for a different index. The use of this buffer as write buffer is discouraged.

If map is new and the cache is used the functionality is the same as if map is old and the cache is used with the following exception. If tileIndex 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 map, 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 map yet, the tile is copied into the file-cache.

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 G3d_getTilePtr are G3d_readTile () and G3d_writeTile () and their corresponding type-specific versions. 

Returns 
	a pointer to a buffer ... if successful,
	NULL ... otherwise.

int

G3d_tileLoad (map, tileIndex)


	void *map;
	int tileIndex;
Same functionality as G3d_getTilePtr () but does not return the pointer. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_removeTile (map, tileIndex)


	void *map;
	int tileIndex;
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 G3d_tileLoad (). (Question: Is this a useful function?) 
Returns 
	1 ... if successful,
	0 ... otherwise.

Write Functions used in Cache Mode

 
int

G3d_flushTile (map, tileIndex)


	void *map;
	int tileIndex;
Writes the tile with tileIndex to the file corresponding to map and removes the tile from the cache (in non-cache mode the buffer provided by the map-structure is written). If this tile has already been written before the write request is ignored. If the tile was never referred to before the invokation of G3d_flushTile, a tile filled with NULL-values is written. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_flushTileCube (map, xMin, yMin, zMin, xMax, yMax, zMax)


	void *map;
	int xMin, yMin, zMin; /* Tile Coordinates */
	int xMax, yMax, zMax;
Writes the tiles with tile-coordinates contained in the axis-parallel cube with vertices (xMin, yMin, zMin) and (xMax, yMax, zMax). 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. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_flushTilesInCube (map, xMin, yMin, zMin, xMax, yMax, zMax)


	void *map;
	int xMin, yMin, zMin; /* Cell Coordinates */
	int  xMax, yMax, zMax;
Writes those tiles for which every cell has coordinate contained in the axis-parallel cube defined by the vertices with cell-coordinates (xMin, yMin, zMin) and (xMax, yMax, zMax). 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. 
Returns 
	1 ... if successful,
	0 ... otherwise.

Locking and Unlocking Tiles, and Cycles

 
int

G3d_lockTile (map, tileIndex)


	void *map;
	int tileIndex;
Locks tile with tileIndex in cache. If after locking fewer than the minimum number of unlocked tiles are unlocked, the lock request is ignored. 
Returns 
	 1 ... if successful,
	-1 ... if request is ignored,
	 0 ... otherwise.

int

G3d_unlockTile (map, tileIndex)


	void *map;
	int tileIndex;
Unlocks tile with tileIndex. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_unlockAll (map)


	void *map;
Unlocks every tile in cache of map. 
Returns 
	1 ... if successful,
	0 ... otherwise.

void

G3d_autolockOn (map)


	void *map;
Turns autolock mode on. 
void

G3d_autolockOff (map)


	void *map;
Turns autolock mode Off. 
void

G3d_minUnlocked (map, minUnlocked)


	void *map;
	int minUnlocked;
Sets the minimum number of unlocked tiles to minUnlocked. This function should be used in combination with G3d_unlockAll () in order to avoid situations where the new minimum is larger than the actual number of unlocked tiles.

minUnlocked must be one of G3D_USE_CACHE_X, G3D_USE_CACHE_Y, G3D_USE_CACHE_Z, G3D_USE_CACHE_XY, G3D_USE_CACHE_XZ, G3D_USE_CACHE_YZ, G3D_USE_CACHE_XYZ, the result of G3d_cacheSizeEncode (), or any positive integer which explicitly specifies the number of tiles. 

int

G3d_beginCycle (map)


	void *map;
Starts a new cycle. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_endCycle (map)


	void *map;
Ends a cycle. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_cacheSizeEncode (cacheCode, n)


	int cacheCode, n;
Returns a number which encodes multiplicity n of cacheCode. This value can be used to specify the size of the cache.

If cacheCode is the size (in tiles) of the cache the function returns cacheCode * n.

If cacheCode is G3D_USE_CACHE_DEFAULT the function returns G3D_USE_CACHE_DEFAULT.

If cacheCode is G3D_USE_CACHE_??? the function returns a value encoding G3D_USE_CACHE_??? and n. Here G3D_USE_CACHE_??? is one of G3D_USE_CACHE_X, G3D_USE_CACHE_Y, G3D_USE_CACHE_Z, G3D_USE_CACHE_XY, G3D_USE_CACHE_XZ, G3D_USE_CACHE_YZ, or G3D_USE_CACHE_XYZ, where e.g. G3D_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 G3D_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.

Reading Volumes

 
int

G3d_getVolume (map, 
	       	   		   originNorth, originWest, originBottom,
	           		   vxNorth, vxWest, vxBottom,
	           		   vyNorth, vyWest, vyBottom,
	           		   vzNorth, vzWest, vzBottom,
		   		   nx, ny, nz,
		   		   volumeBuf, type)


	void *map;
	double originNorth, originWest, originBottom;
	double vxNorth, vxWest, vxBottom;
	double vyNorth, vyWest, vyBottom;
	double vzNorth, vzWest, vzBottom;
	double originNorth, originWest, originBottom;
	int nx, ny, nz;
	char *volumeBuf;
	int type;
Resamples the cube defined by origin and the 3 vertices vx, vy, and vz which are incident to the 3 edges adjacent to origin. The resampled cube is stored in volumeBuf which is a cube with dimensions (nx, ny, nz). The method of sampling is nearest neighbor sampling. The values stored are of type. 
Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_getAllignedVolume (map, 
						   originNorth, originWest, originBottom,
		           			   lengthNorth, lengthWest, lengthBottom, 
			   			   nx, ny, nz,
			   			   volumeBuf, type)


	void *map;
	double originNorth, originWest, originBottom;
	double lengthNorth, lengthWest, lengthBottom;
	int nx, ny, nz;
	char *volumeBuf;
	int type;
Resamples the axis-parallel cube defined by origin and the lengths of the 3 edges adjacent to origin. The resampled cube is stored in volumeBuf which is a cube with dimensions (nx, ny, nz). The method of sampling is nearest neighbor sampling. The values stored are of type. 
Returns 
	1 ... if successful,
	0 ... otherwise.

Allocating and Freeing Memory

 
void *

G3d_malloc (nBytes)


	int nBytes;
Same as malloc (nBytes), except that in case of error G3d_error () is invoked. 
Returns 
	a pointer ... if successful,
	NULL ... otherwise.

void *

G3d_realloc (ptr, nBytes)


	void *ptr;
	int nBytes;
Same as realloc (ptr, nBytes), except that in case of error G3d_error () is invoked. 
Returns 
	a pointer ... if successful,
	NULL ... otherwise.

void

G3d_free (ptr)


	void *ptr;
Same as free (ptr). 
char *

G3d_allocTilesType (map, nofTiles, type)


	void *mao;
	int nofTiles, type;
Allocates a vector of nofTiles tiles with the same dimensions as the tiles of map and large enough to store cell-values of type. 
Returns 
	a pointer to the vector ... if successful,
	NULL ... otherwise.

char *

G3d_allocTiles (map, nofTiles)


	void *mao;
	int nofTiles;
Is equivalent to G3d_allocTilesType (map, nofTiles, G3d_fileTypeMap (map)). 
void

G3d_freeTiles (tiles)


	char *tiles;
Is equivalent to G3d_free (tiles);

G3D Null Value Support

 
void

G3d_isNullValueNum (n, type)


	void *n;
	int type;
Returns 1 if the value of *n is a NULL-value. Returns 0 otherwise. 
void

G3d_setNullValue (c, nofElts, type)


	void *c;
	int nofElts, type;
Fills the vector pointed to by c with nofElts NULL-values of type. 
void

G3d_setNullTileType (map, tile, type)


	void *map;
	int tile, type;
Assumes that tile is a tile with the same dimensions as the tiles of map. Fills tile with NULL-values of type. 
void

G3d_setNullTile (map, tile)


	void *map;
	int tile;
Is equivalent to G3d_setNullTileType (map, tile, G3d_fileTypeMap (map)).

G3D Map Header Information

 
void

G3d_getCoordsMap (map, rows, cols, depths)


	void *map;
	int *rows, *cols, *depths;
Returns the size of the region of map in cells. 
void 

G3d_getRegionMap (map, north, south, east, west, top, bottom)


	void *map;
	int *north, *south, *east, *west, *top, *bottom;
Returns the size of the region. 
void

G3d_getRegionStructMap (map, region)


	void *map;
	G3D_Region *region;
Returns in region the region of map. 
void

G3d_getTileDimensionsMap (map, x, y, z)


	void *map;
	int *x, *y, *z;
Returns the tile dimensions used for map. 
void

G3d_getNofTilesMap (map, nx, ny, nz)


	void *map;
	int *nx, *ny, *nz;
Returns the dimensions of the tile-cube used to tile the region of map. These numbers include partial tiles. 
int

G3d_tileTypeMap (map)


	void *map;
Returns the type in which tiles of map are stored in memory. 
int

G3d_fileTypeMap (map)


	void *map;
Returns the type with which tiles of map are stored on file. 
int

G3d_tilePrecisionMap (map)


	void *map;
Returns the precision used to store map. 
int

G3d_tileUseCacheMap (map)


	void *map;
Returns 1 if map uses cache, returns 0 otherwise. 
void

G3d_printHeader (map)


	void *map;
Prints the header information of map.

G3D Tile Math

 
void

G3d_tileIndex2tile (map, tileIndex, xTile, yTile, zTile)


	void *map;
	int tileIndex;
	int *xTile, *yTile, *zTile;
Converts index tileIndex into tile-coordinates (xTile, yTile, zTile). 
int

G3d_tile2tileIndex (map, xTile, yTile, zTile)


	void *map;
	int xTile, yTile, zTile;
Returns tile-index corresponding to tile-coordinates (xTile, yTile, zTile). 
void

G3d_coord2tileCoord (map, x, y, z, xTile, yTile, zTile, xOffs, yOffs, zOffs)


	void *map;
	int x, y, z;
	int *xTile, *yTile, *zTile, *xOffs, *yOffs, *zOffs;
Converts cell-coordinates (x, y, z) into tile-coordinates (xTile, yTile, zTile) and the coordinate of the cell (xOffs, yOffs, zOffs) within the tile. 
void

G3d_tileCoordOrigin (map, xTile, yTile, zTile, x, y, z)


	void *map;
	int xTile, yTile, zTile;
	int *x, *y, *z;
Computes the cell-coordinates (x, y, z) which correspond to the origin of the tile with tile-coordinates (xTile, yTile, zTile). 
void

G3d_tileIndexOrigin (map, tileIndex, x, y, z)


	void *map;
	int tileIndex;
	int *x, *y, *z;
Computes the cell-coordinates (x, y, z) which correspond to the origin of the tile with tileIndex. 
void

G3d_coord2tileIndex (map, x, y, z, tileIndex, offset)


	void *map;
	int x, y, z;
	int *tileIndex, *offset;
Converts cell-coordinates (x, y, z) into tileIndex and the offset of the cell within the tile. 
int

G3d_coordInRange (map, x, y, z)


	void *map;
	int x, y, z; /* cell coordinates */
Returns 1 if cell-coordinate (x, y, z) is a coordinate inside the region. Returns 0 otherwise. 
int

G3d_tileInRange (map, x, y, z)


	void *map;
	int x, y, z; /* tile coordinates */
Returns 1 if tile-coordinate (x, y, z) is a coordinate inside tile cube. Returns 0 otherwise. 
int

G3d_tileIndexInRange (map, tileIndex)


	void *map;
	int tileIndex;
Returns 1 if tileIndex is a valid index for map. Returns 0 otherwise. 
int

G3d_isValidLocation (map, north, west, bottom)


	void *map;
	double north, west, bottom;
Returns 1 if region-coordinates (north, west, bottom) are inside the region of map. Returns 0 otherwise. 
void

G3d_location2coord (map, tileIndex)


	void *map;
	double north, west, bottom;
	int *x, *y, *z;
Converts region-coordinates (north, west, bottom) into cell-coordinates (x, y, z). 
int

G3d_computeClippedTileDimensions (map, tileIndex, 
						      rows, cols, depths, 
						      xRedundant, yRedundant, zRedundant)


	void *map;
	int tileIndex;
	int *rows, *cols, *depths;
	int *xRedundant, *yRedundant, *zRedundant;
Computes the dimensions of the tile when clipped to fit the region of map. The clipped dimensions are returned in rows, cols, depths. The complement is returned in xRedundant, yRedundant, and zRedundant. This function returns the number of cells in the clipped tile.

G3D Range Support

The map structure of g3d 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 G3d_range_load () explicitly. In addition to these function the application can also use the standard grass functions to manipulate the range. 
int

G3d_range_load (map)


	void *map;
Loads the range into the range structure of map. 
Returns
	1 ... if successful
	0 ... otherwise.

void

G3d_range_min_max (map, min, max)


	void *map;
	double *min, *max;
Returns in min and max the minimum and maximum values of the range. 
int

G3d_range_write (map)


	void *map;
Writes the range which is stored in the range structure of map. (This function is invoked automatically when a new file is closed). 
Returns
	1 ... if successful
	0 ... otherwise.

G3D Color Support

Applications can use the standard grass functions to work with colors, except for the file manipulations. 
int

G3d_removeColor (name)


	char *name;
Removes the primary and/or secondary color file. See G_remove_colr for details. 
Returns always 0.

int

G3d_readColors (name, mapset, colors)


	char *name;
	char *mapset;
	struct Colors *colors;
Reads color file for map name in mapset into the colors structure. See G_read_colors for details and return values. 
int

G3d_writeColors (name, mapset, colors)


	char *name;
	char *mapset;
	struct Colors *colors;
Writes colors stored in colors structure into the color file for map name in mapset. See G_write_colors for details and return values.

G3D Categories Support

Applications can use the standard grass functions to work with ccategories, except for the file manipulations. 
int

G3d_readCats (name, mapset, cats)


	char *name;
	char *mapset;
	struct Categories *pcats;
Reads the categories file for map name in mapset and stores the categories in the pcats structure. See G_read_cats for details and return values. 
int

G3d_writeCats (name, cats)


	char *name;
	struct Categories *cats;
Writes the categories stored in the cats structure into the categories file for map name in the current mapset. See G_write_cats for details and return values.

G3D Mask Support

 
void

G3d_maskOn (map)


	void *map;
Turns on the mask for map. Do not invoke this function after the first tile has been read since the result might be inconsistent cell-values. 
void

G3d_maskOff (map)


	void *map;
Turns off the mask for map. This is the default. Do not invoke this function after the first tile has been read since the result might be inconsistent cell-values. 
int

G3d_maskIsOn (map)


	void *map;
Returns 1 if the mask for map is turned on. Returns 0 otherwise. 
int

G3d_maskIsOff (map)


	void *map;
Returns 1 if the mask for map is turned off. Returns 0 otherwise.
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. 
int

G3d_maskReopen (cache)


	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 cache. 
Returns
	1 ... if successful
	0 ... otherwise.

int

G3d_maskFileExists ()
Returns 1 if the 3d mask file exists. 
int

G3d_maskMapExists ()
Returns 1 if the 3d mask is loaded. 
char *

G3d_maskFile ()
Returns the name of the 3d mask file. 
int

G3d_isMasked (x, y, z)


	int x, y, z;
Returns 1 if the cell with cell-coordinates (x, y, z) is masked out. Returns 0 otherwise. 
void

G3d_maskNum (x, y, z, value, type)


	int x, y, z;
	void *value;
	int type;
Replaces the value stored in value with the NULL-value if G3d_isMasked (x, y, z) returns 1. Does nothing otherwise. value is assumed to be oftype. 
void

G3d_maskFloat (x, y, z, value)


	int x, y, z;
	float *value;
Same as G3d_maskNum (x, y, z, value, G3D_FLOAT). 
void

G3d_maskDouble (x, y, z, value)


	int x, y, z;
	double *value;
Same as G3d_maskNum (x, y, z, value, G3D_DOUBLE). 
void

G3d_maskTile (map, tileIndex, tile, type)


     void *map; 
     int tileIndex;
     char *tile;
     int type;
Replaces the values stored in tile (with tileIndex) for which G3d_isMasked returns 1 with NULL-values. Does not change the remaining values. The values are assumed to be of type. 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 map (i.e. turned on or off).

G3D Window Support

 
void

G3d_setWindowMap (map, window)


	void *map;
	G3D_Region *window;
Sets the window for map to window. Can be used multiple times for the same map. 
void

G3d_setWindow (window)


	G3D_Region *window;
Sets the default window used for every map opened later in the program. Can be used multiple times in the same program. 
void

G3d_getWindow (window)


	G3D_Region *window;
Stores the current default window in window. 
G3D_Region *

G3d_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. 
int

G3d_readWindow (window, windowName)


	G3D_Region *window;
	char *windowName;
Reads window from the file specified by windowName. The name is converted by the rules defined in window defaults. A NULL pointer indicates the WIND3 file in the current mapset. 
Returns
	1 ... if successful
	0 ... otherwise.

int

G3d_writeWindow (window, windowName)


	G3D_Region *window;
	char *windowName;
Writes window to the file specified by windowName. The name is converted by the rules defined in window defaults. A NULL pointer indicates the WIND3 file in the current mapset. 
Returns
	1 ... if successful
	0 ... otherwise.

void

G3d_useWindowParams ()
Allows the window to be set at run-time via the region3 command line argument. This function has to be called before G_parser (). See also window defaults. 
void

G3d_setResamplingFun (map, resampleFun)


	void *map;
	void (*resampleFun) ();
Sets the resampling function to be used by G3d_getValue (). This function is defined as follows: 
	void 
	G3d_customResampleFun (map, row, col, depth, value, type)
		void *map;
		int row, col, depth;
		char *value;
		int type;
row, col, and depth are in region coordinates. The result is returned in value as type which is one of G3D_FLOAT or G3D_DOUBLE. Possible choices include G3d_nearestNeighbor () and G3d_getValueRegion (). 
void

G3d_nearestNeighbor (map, row, col, depth, value, type)

	void *map;
	int row, col, depth;
	char *value;
	int type;
The default resampling function which uses nearest neighbor resampling. 
void

G3d_getResamplingFun (map, resampleFun)


	void *map;
	void (**resampleFun) ();
Returns in resampleFun a pointer to the resampling function used by map. 
void

G3d_getNearestNeighborFunPtr (nnFunPtr)


	void (**nnFunPtr) ();
Returns in nnFunPtr a pointer to G3d_nearestNeighbor ().

Region

 
void

G3d_extract2dRegion (region3d, region2d)


	G3D_Region *region3d;
	struct Cell_head *region2d;
Returns in region2d the 2d portion of region3d. 
void

G3d_incorporate2dRegion (region2d, region3d)


	struct Cell_head *region2d;
	G3D_Region *region3d;
Replaces the 2d portion of region3d with the values stored in region2d. 
void

G3d_adjustRegion (region)


	G3D_Region *region;
Computes an adjusts the resolutions in the region structure from the region boundaries and number of cells per dimension. 
void

G3d_adjustRegionRes (region)


	G3D_Region *region;
Computes an adjusts the number of cells per dimension in the region structure from the region boundaries and resolutions. 
void

G3d_regionCopy (regionDest, regionSrc)


	G3D_Region *regionDest, *regionSrc;
Copies the values of regionSrc into regionDst. (The unfortunate order of parameters was chosen in order to conform to the order used in G_copy ()). 
void

G3d_getRegionValue (map, north, east, top, value, type)


	void *map;
	double north, east, top;
	char *value;
	int type;
Returns in value the value of the map which corresponds to region coordinates (north, east, top). The value is resampled using the resampling function specified for map. The value is of type. 
void

G3d_readRegionMap (name, mapset, region)


	char *name, *mapset;
	G3D_Region *region;
Returns in region the region information for 3d cell name@mapset.

Miscellaneous Functions

 
void

G3d_g3dType2cellType (g3dType)


	int g3dType;
Returns the GRASS floating point type which is equivalent to the G3D type of g3dType. 
void

G3d_initDefaults ()
Initializes the default values described in G3D 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. 
void

G3d_setStandart3dInputParams ()
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 type of the cell values, the precision, the properties of the compression, and the dimension of the tiles (tiledimension). Every of these values defaults to the value described in G3D Defaults.

This function has to be used in conjunction with G3d_getStandart3dInputParams (). 

int

G3d_getStandart3dInputParams (useTypeDefault, type, 
			 			useLzwDefault, doLzw, 
			 			useRleDefault, doRle, 
			 			usePrecisionDefault, precision,
			 			useDimensionDefault, tileX, tileY, tileZ)


	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 useXxxxDefault is 1, it is 0 otherwise. In addition, the corresponding parameters contain the default value if useXxxxDefault is 1, or the value specified by the user if useXxxxDefault is 0.

Function G3d_setStandart3dInputParams () has to be used to initialize the internal parameter structure. 

Returns 
	1 ... if successful,
	0 ... otherwise.

int

G3d_makeMapsetMapDirectory (mapName)


	char *mapName;
Creates the 3d mapset element for map mapName. 
int

G3d_filename (path, elementName, mapName, mapset)


	char *path, *elementName, *mapName, *mapset;
Returns in path the path for element elementName for map mapName in mapset. Note, an error occurs if mapName is fully qualified.