Raster file data can be of type CELL, FCELL or DCELL, they are defined in "gis.h".
Prompting for Raster Files
The following routines interactively prompt the user for a raster file name. In each, the prompt string will be printed as the first line of the full prompt which asks the user to enter a raster file name. If prompt is the empty string "" then an appropriate prompt will be substituted. The name that the user enters is copied into the name buffer (The size of name should be large enough to hold any GRASS file name. Most systems allow file names to be quite long. It is recommended that name be declared char name.) These routines have a built-in 'list' capability which allows the user to get a list of existing raster files.
The user is required to enter a valid raster file name, or else hit the RETURN key to cancel the request. If the user enters an invalid response, a message is printed, and the user is prompted again. If the user cancels the request, the NULL pointer is returned. Otherwise the mapset where the raster file lives or is to be created is returned. Both the name and the mapset are used in other routines to refer to the raster file.
char *G_ask_cell_old(char *prompt, char *name) prompt for existing raster file
Asks the user to enter the name of an existing raster file in any mapset in the database.
char *G_ask_cell_in_mapset(char *prompt, char *name) prompt for existing raster file
Asks the user to enter the name of an existing raster file in the current mapset.
char *G_ask_cell_new(char *prompt, char *name) prompt for new raster file
Asks the user to enter a name for a raster file which does not exist in the current mapset.
Here is an example of how to use these routines. Note that the programmer must handle the NULL return properly:
char *mapset; char name[50]; mapset = G_ask_cell_old("Enter raster file to be processed", name); if (mapset = = NULL) return(0);
Noninteractive modules cannot make use of the interactive prompting routines described above. For example, a command line driven module may require a raster file name as one of the command arguments. GRASS allows the user to specify raster file names (or any other database file) either as a simple unqualified name, such as "soils", or as a fully qualified name, such as "soils@<I>mapset</I>", where mapset is the mapset where the raster file is to be found. Often only the unqualified raster file name is provided on the command line.
The following routines search the database for raster files:
char *G_find_cell(char *name, char *mapset) find a raster file
Looks for the raster file name in the database. The mapset parameter can either be the empty string "", which means search all the mapsets in the user's current mapset search path, or it can be a specific mapset name, which means look for the raster file only in this one mapset (for example, in the current mapset) . If found, the mapset where the raster file lives is returned. If not found, the NULL pointer is returned.
If the user specifies a fully qualified raster file which exists, then G_find_cell() modifies name by removing the "@<I>mapset</I>".
For example, to find a raster file anywhere in the database:
char name[50]; char *mapset; if ((mapset = G_find_cell(name,"")) == NULL) /* not found */
To check that the raster file exists in the current mapset:
char name[50]; if (G_find_cell(name,G_mapset()) == NULL) /* not found */
Opening an Existing Raster File
The following routine opens the raster file name in mapset for reading.
The raster file name and mapset can be obtained interactively using G_ask_cell_old() or G_ask_cell_in_mapset(), and noninteractively using G_find_cell().
int G_open_cell_old(char *name, char *mapset) open an existing raster file
This routine opens the raster file name in mapset for reading. A nonnegative file descriptor is returned if the open is successful. Otherwise a diagnostic message is printed and a negative value is returned. This routine does quite a bit of work. Since GRASS users expect that all raster files will be resampled into the current region, the resampling index for the raster file is prepared by this routine after the file is opened. The resampling is based on the active module region. Preparation required for reading the various raster file formats is also done.
####################
The following routines create the new raster file name in the current mapset and open it for writing. The raster file name should be obtained interactively using G_ask_cell_new. If obtained noninteractively (e.g., from the command line) , G_legal_filename should be called first to make sure that name is a valid GRASS file name.
Note. It is not an error for name to already exist. New raster files are actually created as temporary files and moved into the cell directory when closed. This allows an existing raster file to be read at the same time that it is being rewritten. The interactive routine G_ask_cell_new guarantees that name will not exist, but if name is obtained from the command line, name may exist. In this case G_find_cell could be used to see if name exists.
Warning. However, there is a subtle trap. The temporary file, which is created using G_tempfile, is named using the current process id. If the new raster file is opened by a parent process which exits after creating a child process using fork() ,
FILE *G_open_cell_new(char *name) open a new raster file (sequential) Creates and opens the raster file name for writing by G_put_map_row which writes the file row by row in sequential order. The raster file data will be compressed as it is written.
A nonnegative file descriptor is returned if the open is successful. Otherwise a diagnostic message is printed and a negative value is returned.
FILE *G_open_cell_new_random(char *name) open a new raster file (random) Creates and opens the raster file name for writing by G_put_map_row_random which allows writing the raster file in a random fashion. The file will be created uncompressed.
A nonnegative file descriptor is returned if the open is successful. Otherwise a diagnostic message is printed and a negative value is returned.
FILE *G_open_cell_new_uncompressed(char *nameopen a new raster file (uncompressed) Creates and opens the raster file name for writing by G_put_map_row which writes the file row by row in sequential order. The raster file will be in uncompressed format when closed.
A nonnegative file descriptor is returned if the open is successful. Otherwise a warning message is printed on stderr and a negative value is returned.
General use of this routine is not recommended.
Since there is no predefined limit for the number of columns in the region,
CELL *G_allocate_cell_buf(void) allocate a raster buffer This routine allocates a buffer of type CELL just large enough to hold one row of raster data (based on the number of columns in the active region) .
If larger buffers are required, the routine G_malloc can be used.
If sufficient memory is not available, an error message is printed and exit() is called.
int G_zero_cell_buf(CELL *buf) zero a raster buffer This routines assigns each member of the raster buffer array buf to zero. It assumes that buf has been allocated using G_allocate_cell_buf.
Reading Raster Files Needs updating for GRASS 5!! See later in this file.
Raster data can be thought of as a two-dimensional matrix. The routines described below read one full row of the matrix. It should be understood, however, that the number of rows and columns in the matrix is determined by the region, not the raster file itself. Raster data is always read resampled into the region.
Note. The rows and columns are specified "C style", i.e., starting with 0.
THIS FUNCTION IS DEPRECATED IN GRASS 5! SEE NEXT CHAPTER!
int G_get_map_row (int fd, CELL *cell, int row) read a raster file This routine reads the specified row from the raster file open on file descriptor fd (as returned by G_open_cell_old) into the cell buffer. The cell buffer must be dynamically allocated large enough to hold one full row of raster data. It can be allocated using G_allocate_cell_buf.
This routine prints a diagnostic message and returns -1 if there is an error reading the raster file. Otherwise a nonnegative value is returned.
int G_get_map_row_nomask (int fd, CELL *cell, int row) read a raster file (without masking) This routine reads the specified row from the raster file open on file descriptor fd into the cell buffer like G_get_map_row() does. The difference is that masking is suppressed. If the user has a mask set, G_get_map_row() will apply the mask but G_get_map_row_nomask() will ignore it.
This routine prints a diagnostic message and returns -1 if there is an error reading the raster file. Otherwise a nonnegative value is returned.
Note. Ignoring the mask is not generally acceptable. Users expect the mask to be applied. However, in some cases ignoring the mask is justified. For example, the GRASS modules r.describe, which reads the raster file directly to report all data values in a raster file, and r.slope.aspect, which produces slope and aspect from elevation, ignore both the mask and the region. However, the number of GRASS modules which do this should be minimal. See Mask for more information about the mask.
Writing Raster Files Needs updating for GRASS 5!! See later in this file.
The routines described here write raster file data.
int G_put_map_row (int fd, CELL *buf) write a raster file (sequential) This routine writes one row of raster data from buf to the raster file open on file descriptor fd. The raster file must have been opened with G_open_cell_new.
The cell buf must have been allocated large enough for the region, perhaps using G_allocate_cell_buf.
If there is an error writing the raster file, a warning message is printed and -1 is returned. Otherwise 1 is returned.
Note. The rows are written in sequential order. The first call writes row 0, the second writes row 1, etc. The following example assumes that the raster file name is to be created:
<IMG WIDTH="380" HEIGHT="241" ALIGN="BOTTOM" BORDER="0" SRC="img47.png" ALT="{Gprog} int fd, row, nrows, ncols;