TODO: this sections needs to be cleaned up. The upper GRASS 4.x and the lower GRASS 5.x/6.x parts need to me merged.
Raster files are the heart and soul of GRASS (update 2005: meanwhile also vector data processing entered GRASS' heart). Because of this, a suite of routines which process raster file data has been provided. The processing of raster files consists of determining which raster file or files are to be processed (either by prompting the user or as specified on the module command line), locating the raster file in the database, opening the raster file, dynamically allocating i/o buffers, reading or writing the raster file, closing the raster file, and creating support files for newly created raster files.
Raster file data can be of type CELL, FCELL or DCELL, they are defined in "gis.h". CELL is a 32-bit signed integer, FCELL is an IEEE single-precision floating-point, and DCELL is an IEEE double-precision floating-point. G3D (GRID3D) is treated as DCELL.
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.
Here is an example of how to use these routines. Note that the programmer must handle the NULL return properly:
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.
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 [footnote] 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(), [footnote] the raster file may never get created since the temporary file would be associated with the parent process, not the child. GRASS management automatically removes temporary files associated with processes that are no longer running. If fork() must be used, the safest course of action is to create the child first, then open the raster file. (See the discussion under G_tempfile() for more details.)
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. [footnote]
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.
Since there is no predefined limit for the number of columns in the region,[footnote] buffers which are used for reading and writing raster data must be dynamically allocated.
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. [footnote] This allows the user to specify the coverage of the database during analyses. It also allows databases to consist of raster files which do not cover exactly the same area, or do not have the same grid cell resolution. When raster files are resampled into the region, they all "look" the same.
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.
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.
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:
All raster files are closed by one of the following routines, whether opened for reading or for writing.
int G_close_cell (int fd) close a raster file The raster file opened on file descriptor fd is closed. Memory allocated for raster processing is freed. If open for writing, skeletal support files for the new raster file are created as well.
Note. If a module wants to explicitly write support files (e.g., a specific color table) for a raster file it creates, it must do so after the raster file is closed. Otherwise the close will overwrite the support files. See Raster Map Layer Support Routines for routines which write raster support files.
int G_unopen_cell (int fd) unopen a raster file The raster file opened on file descriptor fd is closed. Memory allocated for raster processing is freed. If open for writing, the raster file is not created and the temporary file created when the raster file was opened is removed (see Creating_and_Opening_New_Raster_Files) .
This routine is useful when errors are detected and it is desired to not create the new raster file. While it is true that the raster file will not be created if the module exits without closing the file, the temporary file will not be removed at module exit. GRASS database management will eventually remove the temporary file, but the file can be quite large and will take up disk space until GRASS does remove it. Use this routine as a courtesy to the user.
GRASS map layers have a number of support files associated with them. These files are discussed in detail in Raster_Maps. The support files are the raster header, the category file, the color table, the history file, and the range file. Each support file has its own data structure and associated routines.
The raster header file contains information describing the geographic extent of the map layer, the grid cell resolution, and the format used to store the data in the raster file. The format of this file is described in Raster_Header_Format. The routines described below use the Cell_head structure which is shown in detail in GIS_Library_Data_Structures.
If there is an error reading the raster header file, a diagnostic message is printed and -1 is returned. Otherwise, 0 is returned.
char * G_adjust_Cell_head(struct Cell_Head *cellhd, int rflag, int cflag) adjust cell headerThis function fills in missing parts of the input cell header (or region) . It also makes projection-specific adjustments. The cellhd structure must have its north, south, east, west, and proj fields set. If rflag is true, then the north-south resolution is computed from the number of rows in the cellhd structure. Otherwise the number of rows is computed from the north-south resolution in the structure, similarly for cflag and the number of columns and the east-west resolution. This routine returns NULL if execution occurs without error, otherwise it returns an error message.
If there was an error creating the raster header, -1 is returned. No diagnostic is printed. Otherwise, 1 is returned to indicate success.
Note. Programmers should have no reason to use this routine. It is used by G_close_cell to giv e new raster files correct header files, and by the r.support module to give users a means of creating or modifying raster headers.
Returns 1 if name is a reclass file, 0 if it is not, and -1 if there was a problem reading the raster header for name.
GRASS map layers have category labels associated with them. The category file is structured so that each category in the raster file can have a one-line description. The format of this file is described in Raster_Category_File_Format.
The routines described below manage the category file. Some of them use the Categories structure which is described in GIS_Library_Data_Structures.
int G_read_cats(char *name, char *mapset, struct Categories cats) read raster category fileThe category file for raster file name in mapset is read into the cats structure. If there is an error reading the category file, a diagnostic message is printed and -1 is returned. Otherwise, 0 is returned.
char * G_get_cell_title(char *name, char *mapset) get raster map titleIf only the map layer title is needed, it is not necessary to read the entire category file into memory. This routine gets the title for raster file name in mapset directly from the category file, and returns a pointer to the title. A legal pointer is always returned. If the map layer does not have a title, then a pointer to the empty string "" is returned.
char * G_get_cat(CELL n, struct Categories *cats) get a category labelThis routine looks up category n in the cats structure and returns a pointer to a string which is the label for the category. A legal pointer is always returned. If the category does not exist in cats, then a pointer to the empty string "" is returned.
Warning. The pointer that is returned points to a hidden static buffer. Successive calls to G_get_cat() overwrite this buffer.
char * G_get_cats_title (Categories *cats) get title from category structure structMap layers store a one-line title in the category structure as well. This routine returns a pointer to the title contained in the cats structure. A legal pointer is always returned. If the map layer does not have a title, then a pointer to the empty string "" is returned.
GRASS map layers have colors associated with them. The color tables are structured so that each category in the raster file has its own color. The format of this file is described in Raster_Color_Table_Format.
The routines that manipulate the raster color file use the Colors structure which is described in detail in GIS_Library_Data_Structures.
If the data layer has no color table, a default color table is generated and 0 is returned. If there is an error reading the color table, a diagnostic message is printed and -1 is returned. If the color table is read ok, 1 is returned.
Note. The calling sequence for this function deserves special attention. The mapset parameter seems to imply that it is possible to overwrite the color table for a raster file which is in another mapset. However, this is not what actually happens. It is very useful for users to create their own color tables for raster files in other mapsets, but without overwriting other users' color tables for the same raster file. If mapset is the current mapset, then the color file for name will be overwritten by the new color table. But if mapset is not the current mapset, then the color table is actually written in the current mapset under the colr2 element as: colr2/mapset/name.
These routines allow the creation of customized color tables as well as the modification of existing tables.
The programmer is encouraged to review Raster_Color_Table_Format how this routine fits into the 5.x raster color logic.
Note. The colors structure must have been initialized by G_init_colors. See Predefined Color Tables for routines to build some predefined color tables.
Use of this routine is discouraged because it defeats the new color logic. It is provided only for backward compatibility. Overuse can create large color tables. G_add_color_rule should be used whenever possible.
These color tables may be created for a raster file, but they may also be generated for loading graphics colors.
int G_make_ramp_colors(struct Colors *colors, CELL min, CELL max) make color rampGenerates a color table with 3 sections: red only, green only, and blue only, each increasing from none to full intensity. This table is good for continuous data, such as elevation.
The history file contains documentary information about the raster file: who created it, when it was created, what was the original data source, what information is contained in the raster file, etc. This file is discussed in Raster_History_File_Format
The following routines manage this file. They use the History structure which is described in GIS_Library_Data_Structures.
Note. This structure has existed relatively unmodified since the inception of GRASS. It is in need of overhaul. Programmers should be aware that future versions of GRASS may no longer support either the routines or the data structure which support the history file.
A diagnostic message is printed and -1 is returned if there is an error reading the history file. Otherwise, 0 is returned.
A diagnostic message is printed and -1 is returned if there is an error writing the history file. Otherwise, 0 is returned.
The following routines manage the raster range file. This file contains the minimum and maximum values found in the raster file. The format of this file is described in Raster_Range_File_Format.
A diagnostic message is printed and -1 is returned if there is an error writing the range file. Otherwise, 0 is returned.
The following routines provide a relatively efficient mechanism for computing and querying a histogram of raster data. They use the Cell_stats structure to hold the histogram information. The histogram is a count associated with each unique raster value representing the number of times each value was inserted into the structure.
GRASS integer raster map data is defined to be of type CELL. This data type is defined in the "gis.h" header file. Programmers must declare all variables and buffers which will hold raster data or category codes as type CELL. Under GRASS the CELL data type is declared to be int, but the programmer should not assume this. What should be assumed is that CELL is a signed integer type. It may be changed sometime to short or long. This implies that use of CELL data with routines which do not know about this data type (e.g., fprintf(stdout, ...), sscanf(), etc.) must use an intermediate variable of type long. To print a CELL value, it must be cast to long. For example:
To read a CELL value, for example from user typed input, it is necessary to read into a long variable, and then assign it to the CELL variable. For example (this example does not check for valid inputs, EOF, etc., which good code must do):
Of course, with GRASS library routines that are designed to handle the CELL type, this problem does not arise. It is only when CELL data must be used in routines which do not know about the CELL type, that the values must be cast to or from long.
were modified, so it is very important to use functional interface to access and set elements of these structures instead of accessing elements of the structures directly. Because some former elements such as for example (struct Range range.pmin) do not exist anymore. It was made sure non of the former elements have different meaning, so that the programs which do access the old elements directly either do not compile or work exactly the same way as prior to change.
int G_is_f_null_value(FCELL *fcell) Returns 1 if fcell is NULL, 0 otherwise. This will test if the value fcell is a NaN. It isn't good enough to test for a particular NaN bit pattern since the machine code may change this bit pattern to a different NaN. The test will be
The use of this routine by applications is discouraged since its use would override user preferences (what precision to use) .
int G_set_fp_type (RASTER_MAP_TYPE type) This controls the storage type for floating-point maps. It affects subsequent calls to G_open_fp_map_new(). The type must be one of FCELL_TYPE (float) or DCELL_TYPE (double) . The use of this routine by applications is discouraged since its use would override user preferences.
int G_get_f_raster_row (int fd, FCELL fcell, int row) Read a row from the raster map open on fd into the float array fcell performing type conversions as necessary based on the actual storage type of the map. Masking, resampling into the current region. NULL-values are always embedded in fcell (never converted to a value) .
NOTE. When the raster map is old and null file doesn't exist, it is assumed that all 0-cells are no-data. When map is floating point, uses quant rules set explicitly by G_set_quant_rules or stored in map's quant file to convert floats to integers.
int G_put_c_raster_row (int fd, CELL buf) Writes a row of raster data and a row of the null-value bitmap, only treating NULL as NULL. (As opposed to the deprecated function G_put_map_row() which treats zero values also as NULL.)
int G_open_cell_old() Arrange for the NULL-value bitmap to be read as well as the raster map. If no NULL-value bitmap exists, arrange for the production of NULL-values based on zeros in the raster map.
int G_get_map_row() If the map is floating-point, quantize the floating-point values to integer using the quantization rules established for the map when the map was opened for reading (this quantization is read from cell_misc/name/f_quant file, but can be reset after opening raster map by G_set_quant_rules() ) .
The FP nulls are the all-ones bit patterns. These corresponds to NaN according to the IEEE-754 formats, although it isn't the "default" NaN pattern generated by most architectures (which is usually 7fc00000 or ffc00000 for float and 7ff8000000000000 or fff8000000000000 for double, i.e. an all-ones exponent, the top-bit of the mantissa set, and either sign).
So far as arithmetic is concerned, any value with an all-ones exponent and a non-zero mantissa is treated as NaN. But the GRASS G_is_[fd]_null_value() functions only consider the all-ones bit pattern to be null. I intend to change this in 7.x so that all FP NaN values are treated as null. This will mean that code which can generate NaNs doesn't have to explicitly convert them to the GRASS null value.
Presence or absence of null file: For an integer map, any cells which were null will become zero, but any zeroes (cells which were previously either null or zero) will be treated as nulls (this is for compatibility with GRASS 4.x, which didn't have a null file, but typically used zero to indicate a null value).
For a floating-point map, any cells which were null will become zero (when writing FP data, a null has a zero written to the fcell/<map> file, and the corresponding bit is set in the null file).
int D_f_raster(FCELL *fcell, int ncols, int nrows, struct Colors colors) Same functionality as D_raster() except that the fcell array is type FCELL. This implies that the floating-point interfaces to the colors are used by this routine.
int D_d_raster(DCELL *dcell, int ncols, int nrows, struct Colors colors) Same functionality as D_raster() except that the dcell array is type DCELL. This implies that the floating-point interfaces to the colors are used by this routine.
int D_f_color(FCELL *value, struct Colors *colors) Same functionality as D_color() except that the value is type FCELL. This implies that the floating-point interfaces to the colors are used by this routine.
int D_d_color(DCELL *value, struct Colors *colors) Same functionality as D_color() except that the value is type DCELL. This implies that the floating-point interfaces to the colors are used by this routine.
This provides a convenient way to treat a raster layer as a color image without having to explicitly cater for each of CELL, FCELL and DCELL types
int G_write_colors() The rules are written out using floating-point format, removing trailing zeros (possibly producing integers) . The flag marking the colors as floating-point is not written.
int G_get_colors_min_max() If the color table is marked as "float", then return the minimum as -(255&#94;3 * 128) and the maximum as (255&#94;3 * 128). This is to simulate a very large range so that GRASS doesn't attempt to use colormode float to allow interactive toggling of colors.
Modifications to the Colors structure to support colors for floating-point data and the NULL-value consist of
the Color_Rule struct was changed to have DCELL value (instead of CELL cat) to have the range be floating-point values instead of integer cats.
a flag was added to the Colors structure to indicate if either the map itself is floating-point (If the map is integer and the floating point functions are used to lookup colors, the values are checked to see if they are integer, and if they are, the integer mechanism is used)
fp_lookup - a lookup table for floating point numbers is added. It orders the end points of fp intervals into array with a pointer to a color rule for each inteval, and the binary search is then used when looking up colors instead of linearly searching through all color rules.
The rules are written out using floating-point format, removing trailing zeros (possibly producing integers) . For example, to ramp from red to green for the range [1.3,5.0]:
int G_read_range() Old range file (those with 4 numbers) should treat zeros in this file as NULL-values. New range files (those with just 2 numbers) should treat these numbers as real data (zeros are real data in this case) .
An empty range file indicates that the min, max are undefined. This is a valid case, and the result should be an initialized range struct with no defined min/max.
int G_set_quant_rules (int fd, struct Quant *q) Sets quant translation rules for raster map opened for reading. fd is a file descriptor returned by G_open_cell_old() . After calling this function, G_get_c_raster_row() and G_get_map_row() will use rules defined by q (instead of using rules defined in map's quant file) to convert floats to ints.
int G_quant_organize_fp_lookup(struct Quant *quant) Organizes fp_lookup table for faster (logarithmic) lookup time G_quant_organize_fp_lookup() creates a list of min and max for each quant rule, sorts this list, and stores the pointer to quant rule that should be used inbetween any 2 numbers in this list Also it stores extreme points for 2 infinite rules, if exist After the call to G_quant_organize_fp_lookup() instead of linearly searching through list of rules to find a rule to apply, quant lookup will perform a binary search to find an interval containing floating point value, and then use the rule associated with this interval. when the value doesn't fall within any interval, check for the infinite rules.
If any of of dmin, dmax cmin, or cmax is the NULL-value, this rule is not added and 0 is returned. Otherwise return 1. if the fp_lookup is organized, destroy it.
The order of the rules returned by increasing n is the order in which the rules are applied when quantizing a value - the first rule applicable is used.
CELL G_quant_get_cell_value(struct Quant *q, DCELL value) Returns a CELL category for the floating-point value based on the quantization rules in q. The first rule found that applies is used. The rules are searched in the reverse order they are added to q. If no rule is found, the value is first tested against the negative infinite rule, and finally against the positive infinite rule. if none of these rules apply, the NULL-value is returned.
NOTE. See G_quant_organize_fp_lookup() for details on how the values are looked up from fp_lookup table when it is active. (Right now fp_lookup is automatically organized during the first call to G_quant_get_cell_value()
These next two functions are convenience functions to allow applications to easily create quantization rules other than the defaults:
This routine differs from the one above in that the application controls the floating-point range. For example, r.slope.aspect will use this routine to quantize the slope map from [0.0, 90.0] to [0, 90] even if the range of slopes is not 0-90. The aspect map would be quantized from [0.0, 360.0] to [0, 360].
All the new programs which are using Categories structure directly have to be modified to use API functions to update and retrieve info from Categories structure. Both new and old API function can be used, since old functions still have exact same functionality (even though internally they are implemented very differently) . New function names end with raster_cats() ; old function names end with _cats() .
We made sure that all old fields in Categories structure are either missing in new Categories structure or have exactly the same meaning. We did it so that the modules using Categories structure directly either do not compile with new gis library or work exactly the same as bnefore. A programmer might want to read the data in a floating point map in a way that each cell value stores index of it's category label and data range. The way to do it is to call G_set_quant_rules(fd, &pcats->q) after openning the map.
This is helpful when trying to collect statistics (how many cells of each category are in the map. (although there is another new mechanism to collect such stats - see G_mark_raster_cats() ) . Another reason to get a category index instead of fp values is that this index will be the FID into GRASS-DBMS link. Also he can use G_get_ith_raster_cat() to get the category information for each cell using this index.
Internally the labels are stored for fp ranges of data. However when the cats file is written, all the decimal zeros are stripped so that integer values appear as integers in the file. Also if values are the same, only 1 value is written (i.e. first format) .
This way even though the old cats files will be processed differently internally, the user or application programmer will not notice this difference as long as the proper api is used and the elements of Categories structure are not accessed directly without API calls.
int G_unmark_raster_cats(struct Categories *pcats) Sets marks for all categories to 0. This initializes Categories structure for subsequest calls to G_mark_raster_cats (rast_row,...) for each row of data, where non-zero mark for i-th label means that some of the cells in rast_row are labeled with i-th label and fall into i-th data range.
NOTE: non-zero mark for i-th label stores the number of of raster cells read so far which are labeled with i-th label and fall into i-th data range.
int G_init_raster_cats(char *title, struct Categories pcats) Same as existing G_init_raster_cats() only ncats argument is missign. ncats has no meaning in new Categories structure and only stores (int) largets data value for backwards compatibility.
These functions are deprecated, since they imply that the application that uses them has not been upgraded to handle NULL-values and should be eliminated from GRASS code.
These functions are deprecated, since they can not be upgraded to support NULL-values, and should be eliminated from GRASS code.
Modules that process raster maps as continuous data should read raster maps as floating-point. Modules that process raster maps as nominal data should read raster maps as integer.
Exception: Modules that process raster colors or the modules which report on raster categories labels should either always read the maps as floating-point, or read the maps as integer if the map is integer and floating-point if the map is floating-point.
The quantization of floating-point to integer should NOT change the color table. The color lookup should have its own separate quantization.
The quantization of floating-point to integer should NOT change the Categories table. The Categories structure should have its own separate quantization.
Modues should process NULL values in a well defined (consistent) manner. Modules that processed zero as the pseudo NULL-value should be changed to use the true NULL-value for this and process zero as normal value.
AutomationCore was going to be attending InfusionCon and needed a flyer designed that would be similar to their AppointmentCore flyer we designed.
The flyer turned out great and helped AutomationCore sign up even more clients than they had hoped for.
select cuts of hand ground prime beef, seasoned, cured and gently dried into magical bites of intense beefy flavor
Has your property been damaged in an emergency? The technicians at Paul Davis can offer instant aid and cleanup services. Whether it is fire, flood, mold or storm, you can call Paul Davis of Lawrence KS 24/7. When you get in touch with us, we try to respond to your call within 30 minutes and reach the scene prepared to take care of damage in less than four hours. Our technicians are aware that fast action is imperative in the event of an emergency and that’s why we are here to grant you with direct emergency cleanup services.
Paul Davis Emergency Services of Lawrence KS technicians know specifically what is necessary to repair and renovate a property in order to restore to its pre-loss condition. This caliber of efficient expertise is all conceivable through hiring the correct teams and using high-quality tools and technology.
Whichever service is necessary, you can rely on our team to be enthusiastic, polite and considerate of your needs. Our objective is to guarantee that your home or business is practical and secure so you can return to ordinary life in your space. When disaster strikes and causes damage to your home, you can trust Paul Davis Emergency Services of Lawrence KS to take care of the situation.