/* **************************************************** Grid IO API --------------- Function Naming Conventions --------------------------- Function names are multi-word with no underscores, and the first letter of each word capitalized. For example : CellLyrOpen, GetWindowRectangle. **************************************************** */ /* Constants Defining String Handling */ #ifndef STRLEN #define STRLEN 129 /* Max string Length */ #endif /* Defined C constants */ #ifndef TRUE #define TRUE 1 #endif #ifndef FALSE #define FALSE 0 #endif #ifndef NULL #define NULL 0 #endif /* Constants Defining CellLayer ReadWrite Flag */ #ifndef READONLY #define READONLY 1 #endif #ifndef READWRITE #define READWRITE 2 #endif #ifndef WRITEONLY #define WRITEONLY 3 #endif /* Constants Defining CellLayer I/O Mode Buffer Cache Allocation is dependent on IO mode. */ #define ROWIO 1 #define CELLIO 2 #define BLOCKIO 3 #define ROWRUNIO 4 #define BLOCKRUNIO 5 #define REGIONIO 6 #define REGIONRUNIO 7 typedef int CELLTYPE; /* cell values are 32 bit quantities */ #define CELLINT 1 /* 32 bit signed integers */ #define CELLFLOAT 2 /* 32 bit floating point numbers*/ #define CELLMAX 2147483646 /* maximum integer value (2**31 - 2) */ #define CELLMIN -2147483646 /* minimum integer value -(2**31 - 2) */ #define MISSINGINT -2147483647 /* CELLMIN - 1 */ void GetMissingFloat(float *); /* * ------------------------------------------------------------------ */ /* * Grid Management Functions * ------------------------- * * GridExists - check for existence of a grid * GridCopy - copy a grid given from and to pathnames * GridRename - rename a grid given old and new pathnames * GridDelete - delete a grid removing all * component files including info files * GridKill - delete a grid with options for component removal * DescribeGridDbl - Describe spatial, statistical and attribute * characteristics of a grid * BndCellRead - read the bounding box for a grid */ int GridExists(char *grid_name); int GridCopy(char *from_grid, char *to_grid); int GridRename(char *from_grid, char *to_grid); int GridDelete(char *grid_name); int GridKill(char *grid_name, int option); int DescribeGridDbl(char *grdnam, double *cellsz, int *gridsz, double *box, double *sta, int *datatyp, int *nclass, int *reclen); int BndCellRead (char *grdnam, double *box); /* * CLYRIO : Access operations on Grids * ----------------------------------- */ /* * PURPOSE * * CLYRIO performs I/O operations on grids. * It consists of a library of C functions that allow the user * to read and write raster data by row, rectangle or cell * to or from a specified area of a grid at a specified resolution. * It handles windowing, resampling, * attribute access and data compression * in a manner transparent to the application program. */ /* * IMPLEMENTATION * * Grids are based on a locational data model in which space is partitioned * into square cells. Each cell in a grid stores a numeric value. * Integer Grids are also accompanied by Value Attribute Tables that * can store attributes defined on the set of values for a grid. * * A grid exists in a cartesian coordinate system, and the rows and columns in the * grid are parallel to the axes of the coordinate system. * Grids in a database that are used for joint analysis * need not be at the same resolution * or cover exactly the same spatial area * but they must be in the same map projection. * * Grids are implemented using a tiled raster data structure * in which the basic unit of data storage is * a rectangular block of cells. * * A Cell Layer is a raster layer defined * by a grid name and optionally an item name in the VAT. * The CLYRIO module allows an aplication program to * create, open and close cell layers and * to read and write data from and * to cell layers. * All access to the data in a cell layer is * made through a rectangular window in cartesian (map) coordinate space. * The extent and resolution of * this window must be set by the application program by calling * the WindowSet routine, prior to performing any * I/O operations. * Once a window has been set, an application program can access the cells * in a cell layer by row, rectangle, or cell - all specified * relative to the virtual raster represented by the window. * * The I/O units used by the application program are * the Window-Row spanning the width of the window, the Window-Band consisting * of a set of contiguos rows, the Window-Rectangle consisting of a 2D rectangle * contained in the window and, the Window-Cell consisting of a single cell * specified by its window row and column coordinates. * All cell data is automatically resampled to the window cell size on retrieval * during row and cell access. * * An application program can either set a global window * that is applied to all cell layers accessed or set a separate * window for each layer accessed. The latter mode is suitable * when transforming a grid from one coordinate system to another * such as during warping or projection. * * Grids may be integer or floating point. * Integer grids are accompanied by a Value Attribute Table. * The CLYRIO module supports spatial access to the numeric value * attributes associated with a grid by supporting * a grid.item naming convention for cell layers that correspond * to grid value attributes. * If an item name is specified when a Cell Layer is opened * for read access then the values returned for the cells retrieved * will be the values for the specified item. * */ /* * Initialization and Termination * -------------------------------- * * GridIOSetup - Initialize the Grid IO library * GridIOExit - Call when done using the Grid IO library */ int GridIOSetup(void); int GridIOExit(void); /* * Creating, Opening and Closing Grids : * ----------------------------------- * * CellLyrExists - Check if a cell layer exists. * CellLayerCreate - Create a new Cell Layer using the default blocksize. * CellLayerCreateTiled - Create a new Cell Layer using the specified blocksize. * CellLayerOpen - Open an existing Cell Layer. * CellLyrClose - Close an opened or created Cell Layer, * automatically builds VAT and STA. * CellLyrCloseNoVat - Close an opened or created Cell Layer, * does not build VAT. * CellLyrDelete - Delete a cell layer. * * IO mode * ------- * * The client is responsible for selecting an IO mode * when opening or creating a cell layer and for using * the access method appropriate for the current IO mode. * The IO mode can be reset while the layer is opened. * The permissible values for IO mode are * ROWIO, ROWRUNIO, CELLIO, REGIONIO, REGIONRUNIO, BLOCKIO and BLOCKRUNIO * For a more detailed description of these modes see the * section on IO mode below. * * ReadWriteFlag * ------------- * A celllayer is opened READONLY or READWRITE * * Compression * ----------- * * Integer grids are stored in a run length compressed format. * Floating point grids are stored in uncompressed format. * */ #define ROWIO 1 #define CELLIO 2 #define BLOCKIO 3 #define ROWRUNIO 4 #define BLOCKRUNIO 5 #define REGIONIO 6 #define REGIONRUNIO 7 #define READONLY 1 #define READWRITE 2 #define ADAPTIVE -1 #define COMPRESSED 0 #define UNCOMPRESSED 1 int CellLyrExists (char *clyr_name); int CellLayerCreate (char *clyr_name, int rdwrflag, int iomode, int celltype, double cellsize, double box[4]); int CellLayerCreateTiled (char *clyr_name, int rdwrflag, int iomode, int celltype, double cellsize, double box[4], int blockxcells, int blockycells); int CellLayerOpen (char *clyr_name, int rdwrflag, int iomode, int *celltype, double *cellsize); int CellLyrClose (int channel); int CellLyrCloseNoVat (int channel); int CellLyrDelete (char *clyr_name); /* * AcessDepth * * CLYRIO mantains an internal cache of block buffers for each opened grid. * * The process of performing IO on a cell layer involves * mapping data between client buffers and cache buffers * for the layer and between the cache buffers and records on disk. * Data compression is applied in the process of mapping data between the * cache buffers and records on disk and is hidden from the client. * * When a layer is opened in 32 bit mode the client is responsible * for ensuring that all client (input and output) buffers used in the * CLYRIO API functions are 32 bits per cell. * In 32 bit access mode all the block buffers in the cache for the layer * are also 32 bits per cell. * The Client is responsible for using the 32 bit API functions. * By default a layer is opened in 32 bit mode. * * */ /* * IO mode * * The client is responsible for using * the access method appropriate for the current IO mode. * The IO modes supported are : * * ROWIO - To Get and Put Rows of Cells * CELLIO - To Get and Put individual cells * REGIONIO - To Get and Put Rectangles of cells * * The IO mode for an opened layer can be queried and changed * with the following API calls * */ int CellLyrGetIO(int channel); int CellLyrSetIO(int channel, int mode); /* * Getting information about an opened cell layer given its handle * * CellLyrName - query the grid name for the cell layer * CellLyrItem - query the item name for the cell layer * CellLyrEvalType - query the cell type for the cell layer, * the cell type is based on the type of the item * CellLyrBlockSize - query the block size for the cell layer * CellLyrSta - query the statistics for the cell layer */ int CellLyrName (int channel, char *name); int CellLyrItem (int channel, char *name); int CellLyrEvalType (int channel); int CellLyrBlockSize (int channel, int *bxcells, int *bycells); int CellLyrSta (int channel, double *dmin, double *dmax, double *dmean, double *dstdv); /* * Setting and Querying the Overlay Window for Multi-Layer registered I/O * * AccessWindowSet - Set the Overlay Window * WindowRows - Return number of rows in the overlay window. * WindowCols - Return number of columns in the overlay window. * WindowBox - Return the box for the overlay window. * XY2WindowColRow - translate from map to window cell coordinates * AccessWindowClear - Clear the Overlay Window */ int AccessWindowSet(double box[4], double cellsize, double newbox[4]); int WindowRows(void); int WindowCols(void); int WindowBox(double box[4]); int XY2WindowColRow(double x, double y, int *col, int *row); int AccessWindowClear(void); /* * * Routines for Setting Separate Windows for each layer * * PrivateAccessWindowSet - Set the Window for the specified layer. * PrivateWindowRows - Return number of rows in window for specified layer. * PrivateWindowColumns - Return number of columns in window for specified layer. * PrivateWindowBox - Return the box for the window for specified layer. * XY2PrivateWindowColRow - translate from map to window cell coordinates * PrivateAccessWindowClear - Clear the window for the specified layer */ int PrivateAccessWindowSet(int channel, double box[4], double cellsize, double newbox[4]); int PrivateWindowCols(int i); int PrivateWindowRows(int i); int PrivateWindowBox(int i, double box[4]); int XY2PrivateWindowColRow(int i, double x, double y, int *col, int *row); int PrivateAccessWindowClear(int channel); /* * Memory Allocation for Rows, Bands and Rectangles * * CAllocate1 - allocate a 1 dimensional array (Row) * that can be accessed as pointer[i] * CAllocate2 - allocate a 2 dimensional "array" (Rectangle, Band) * that can be accessed as pointer[i][j] * CAllocate3 - allocate a 3 dimensional "array" * that can be accessed as pointer[i][j][k] * CFree1 - free a 1 dimensional array * CFree2 - free a 2 dimensional array * CFree3 - free a 3 dimensional array * */ char *CAllocate1(int number, int size); char **CAllocate2(int nrows, int ncols, int size); char ***CAllocate3(int nlyrs, int nrows, int ncols, int size); void CFree1(char *ptr); void CFree2(char **ptr, int nrows); void CFree3(char ***ptr, int nlyrs, int nrows); /* * ACCESS FUNCTIONS : * The following functions access the data within the window for a given layer. * The window may be the overlay window, or the private window set for the layer. */ /* * Routines for 32 bit ROW based access : * * GetWindowRow - Get a row spanning the window for a layer * as a buffer of 32 bit values. * Client must interpret the type of the output buffer * to be the type of the layer being read from (32 bit int or float). * * GetWindowRowFloat - Get a row as a buffer of 32 bit floating points * GetWindowRowInt - Get a row as a buffer of 32 bit integers * * PutWindowRow - Put a row spanning the window for a layer * as a buffer of 32 bit values. * Client must ensure that the type of the input buffer * (32 bit int or float) is the type of the layer being written to. * * The following band access functions retrieve contiguos sets of * rows into a two dimensional buffer. * * GetWindowBand - Get a band of rows spanning the window for a layer. * Client must interpret the type of the output buffer * to be the type of the layer being read from (32 bit int or float). * GetWindowBandFloat - Get a band of rows as a buffer of 32 bit floating points * GetWindowBandInt - Get a band of rows as a buffer of 32 bit ints * * PutWindowBand - Put a band of rows spanning the window for a layer. * Client must ensure that the type of the input buffer * (32 bit int or float) is the type of the layer being written to. * */ int GetWindowRow(int channel, int nreswinrow, CELLTYPE *rowbuf); int GetWindowRowFloat(int channel, int nreswinrow, float *rowbuf); int GetWindowRowInt(int channel, int nreswinrow, int *rowbuf); int PutWindowRow(int channel, int nwinrow, CELLTYPE *rowbuf); int GetWindowBand(int channel, int startrow, int nrows, CELLTYPE **bandbuf); int GetWindowBandFloat(int channel, int startrow, int nrows, float **bandbuf); int GetWindowBandInt(int channel, int startrow, int nrows, int **bandbuf); int PutWindowBand(int channel, int startrow, int nrows, CELLTYPE **bandbuf); /* * Routines for 32 bit REGION (rectangle) based access : * * GetWindowRectangle - Get a rectangle of cells within the window for a layer * as a 2D buffer of 32 bit values. * Client must interpret the type of the output buffer * to be the type of the layer being read from * (32 bit int or float). * * GetWindowRectangleInt - Get a rectangle of cells within the window for a layer * as a 2D buffer of 32 bit integers. * * GetWindowRectangleFloat - Get a rectangle of cells within the window for a layer * as a 2D buffer of 32 bit floats. * * PutWindowRectangle - Put a rectangle of cells within the window for a layer * as a 2D buffer of 32 bit values. * Client must ensure that the type of the input buffer * (32 bit int or float) is the type of the * layer being written to. */ int GetWindowRectangle(int channel, int rxul, int ryul, int rxcells, int rycells, CELLTYPE **rbuf); int GetWindowRectangleInt(int channel, int rxul, int ryul, int rxcells, int rycells, int **rbuf); int GetWindowRectangleFloat(int channel, int rxul, int ryul, int rxcells, int rycells, float **rbuf); int PutWindowRectangle(int channel, int rxul, int ryul, int rxcells, int rycells, CELLTYPE **rbuf); /* * Routines for 32 bit CELL based access : * * GetWindowCell - Get a cell within the window for a layer, * Client must interpret the type of the output 32 Bit Ptr * to be the type of the layer being read from. * * GetWindowCellFloat - Get a cell within the window for a layer as a 32 Bit Float * * GetWindowCellInt - Get a cell within the window for a layer as a 32 Bit Integer * * PutWindowCell - Put a cell within the window for a layer. * Client must ensure that the type of the input 32 Bit Ptr * is the type of the layer being read from. * * * PutWindowCellFloat - Put a cell within the window for a layer as a 32 Bit Float * * PutWindowCellInt - Put a cell within the window for a layer as a 32 Bit Integer * */ int GetWindowCell(int channel, int rescol, int resrow, CELLTYPE *cell); int GetWindowCellFloat(int channel, int rescol, int resrow, float *cell); int GetWindowCellInt(int channel, int rescol, int resrow, int *cell); int PutWindowCellFloat(int channel, int col, int row, double fcell); int PutWindowCellInt(int channel, int col, int row, int icell); int PutWindowCell(int channel, int col, int row, CELLTYPE cell); /* * STAIO : Read Statistics for a cell layer * * StaGetDbl - get min, max, mean and stdv for a cell layer * StaGetMinMaxDbl - get min and max for a cell layer * */ int StaGetDbl(char *clyr_name, double *dmin, double *dmax, double *dmean, double *dstdv); int StaGetMinmaxDbl(char *clyr_name, double *dmin, double *dmax);