Floating-Point / NULL Values in GRASS Raster Maps

3.3. Upgrades to Raster Functions

These routines are in the GISLIB.

3.4. Color Functions (new and upgraded)

3.4.0 Upgraded Colors structures

struct _Color_Rule_
{
    struct
    {
	DCELL value;
	unsigned char red,grn,blu;
    } low, high;
    struct _Color_Rule_ *next;
    struct _Color_Rule_ *prev;
};

struct _Color_Info_
{
    struct _Color_Rule_ *rules;
    int n_rules;
    struct
    {
	unsigned char *red;
	unsigned char *grn;
	unsigned char *blu;
	unsigned char *set;
	int nalloc;
	int active;
    } lookup;
    struct
    {
        DCELL *vals;
	/* pointers to color rules corresponding to the intervals btwn vals */
	struct _Color_Rule_ **rules;
	int nalloc;
	int active;
    } fp_lookup;
    DCELL min, max;
};

struct Colors
{
    int version;	/* set by read_colors: -1=old,1=new */
    DCELL shift;
    int invert;
    int is_float;             /* defined on floating point raster data? */
    int null_set; /* the colors for null are set? */
    unsigned char null_red, null_grn, null_blu;
    int undef_set; /* the colors for cells not in range are set? */
    unsigned char undef_red, undef_grn, undef_blu;
    struct _Color_Info_ fixed, modular;
    DCELL cmin, cmax;
};

3.4.1 New functions to support colors for floating-point.

These routines are in the GISLIB.

G_lookup_raster_colors (rast, r, g, b, set, n, colors, cell_type)

void *rast;

char *r, *g, *b, *set;

int n;

struct Colors *colors;

RASTER_MAP_TYPE cell_type;

If the cell_type is CELL_TYPE, calls G_lookup_colors((CELL *)cell, r, g, b, set, n, colors);

If the cell_type is FCELL_TYPE, calls G_lookup_f_raster_colors(FCELL *)cell, r, g, b, set, n, colors);

If the cell_type is DCELL_TYPE, calls G_lookup_d_raster_colors(DCELL *)cell, r, g, b, set, n, colors);

G_lookup_c_raster_colors (cell, r, g, b, set, n, colors)

CELL *cell;

char *r, *g, *b, *set;

int n;

struct Colors *colors;

The same as G_lookup_colors(cell, r, g, b, set, n, colors).

G_lookup_f_raster_colors (fcell, r, g, b, set, n, colors)

FCELL *fcell;

char *r, *g, *b, *set;

int n;

struct Colors *colors;

Converts the n floating-point values in the fcell array to their r,g,b color components. Embedded NULL-values are handled properly as well.

G_lookup_d_raster_colors (dcell, r, g, b, set, n, colors)

DCELL *dcell;

char *r, *g, *b, *set;

int n;

struct Colors *colors;

Converts the n floating-point values in the dcell array to their r,g,b color components. Embedded NULL-values are handled properly as well.

G_add_raster_color_rule (v1, r1, g1, b1, v2, r2, g2, b2, colors, map_type)

void *v1, *v2;

int r1, g1, b1;

int r2, g2, b2;

struct Colors *colors;

RASTER_MAP_TYPE map_type;

If map_type is CELL_TYPE, calls G_add_c_raster_color_rule ((CELL *) v1, r1, g1, b1, (CELL *) v2, r2, g2, b2, colors);

If map_type is FCELL_TYPE, calls G_add_f_raster_color_rule ((FCELL *) v1, r1, g1, b1, (FCELL *) v2, r2, g2, b2, colors);

If map_type is DCELL_TYPE, calls G_add_d_raster_color_rule ((DCELL *) v1, r1, g1, b1, (DCELL *) v2, r2, g2, b2, colors);

G_add_c_raster_color_rule (v1, r1, g1, b1, v2, r2, g2, b2, colors)

CELL *v1, *v2;

int r1, g1, b1;

int r2, g2, b2;

struct Colors *colors;

Calls G_add_color_rule(*v1, r1, g1, b1, *v2, r2, g2, b2, colors).

G_add_f_raster_color_rule (v1, r1, g1, b1, v2, r2, g2, b2, colors)

FCELL *v1, *v2;

int r1, g1, b1;

int r2, g2, b2;

struct Colors *colors;

Adds the floating-point rule that the range [v1,v2] gets a linear ramp of colors from [r1,g1,b1] to [r2,g2,b2].

If either v1 or v2 is the NULL-value, this call is converted into G_set_null_value_color (r1, g1, b1, colors)

G_add_d_raster_color_rule (v1, r1, g1, b1, v2, r2, g2, b2, colors)

DCELL *v1, *v2;

int r1, g1, b1;

int r2, g2, b2;

struct Colors *colors;

Adds the floating-point rule that the range [v1,v2] gets a linear ramp of colors from [r1,g1,b1] to [r2,g2,b2].

If either v1 or v2 is the NULL-value, this call is converted into G_set_null_value_color (r1, g1, b1, colors)

G_get_raster_color (v, r, g, b, colors, data_type)

void *v;

int *r, *g, *b;

struct Colors *colors;

RASTER_MAP_TYPE data_type;

Looks up the rgb colors for v in the color table colors

G_get_c_raster_color (v, r, g, b, colors)

CELL *v;

int *r, *g, *b;

struct Colors *colors;

Calls G_get_color(*v, r, g, b, colors).

G_get_f_raster_color (v, r, g, b, colors)

FCELL *v;

int *r, *g, *b;

struct Colors *colors;

Looks up the rgb colors for v in the color table colors

G_get_d_raster_color (v, r, g, b, colors)

DCELL *v;

int *r, *g, *b;

struct Colors *colors;

Looks up the rgb colors for v in the color table colors

G_set_raster_color (v, r, g, b, colors, data_type)

void *v;

int r, g, b;

struct Colors *colors;

RASTER_MAP_TYPE data_type;

calls G_add_raster_color_rule (v, r, g, b, v, r, g, r, colors, data_type);

G_set_c_raster_color (v, r, g, b, colors)

CELL *v;

int r, g, b;

struct Colors *colors;

Calls G_set_color(*v, r, g, b, colors).

G_set_f_raster_color (v, r, g, b, colors)

FCELL *v;

int r, g, b;

struct Colors *colors;

Inserts a rule that assigns the color r,g,b to v. It is implemented as:

G_add_f_raster_color_rule (v, r, g, b, v, r, g, r, colors);

G_set_d_raster_color (v, r, g, b, colors)

DCELL *v;

int r, g, b;

struct Colors *colors;

Inserts a rule that assigns the color r,g,b to v. It is implemented as:

G_add_d_raster_color_rule (v, r, g, b, v, r, g, r, colors);

G_mark_colors_as_fp (struct Colors *colors)

Sets a flag in the colors structure that indicates that these colors should only be looked up using floating-point raster data (not integer data).

In particular if this flag is set, the routine G_get_colors_min_max() should return min=-255^3 and max=255^3.

These routines are in the DISPLAYLIB.

D_raster_of_type (rast, ncols, nrows, colors, data_type)

void *rast;

int ncols, nrows;

struct Colors *colors;

RASTER_MAP_TYPE data_type;

If map_type is CELL_TYPE, calls D_raster((CELL *) rast, ncols, nrows, colors);

If map_type is FCELL_TYPE, calls D_f_raster((FCELL *) rast, ncols, nrows, colors);

If map_type is DCELL_TYPE, calls D_d_raster((DCELL *) rast, ncols, nrows, colors);

D_f_raster (fcell, ncols, nrows, colors)

FCELL *fcell;

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

D_d_raster (dcell, ncols, nrows, colors)

DCELL *dcell;

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

D_color_of_type (value, colors, data_type)

void *value;

struct Colors *colors;

RASTER_MAP_TYPE data_type;

If the data_type is CELL_TYPE, calls D_color((CELL *value, colors);

If the data_type is FCELL_TYPE, calls D_f_color((FCELL *value, colors);

If the data_type is DCELL_TYPE, calls D_d_color((DCELL *value, colors);

D_f_color (value, colors)

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.

D_d_color (value, colors)

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.

D_lookup_raster_colors (rast, colornum, n, colors, data_type)

void *rast;

int *colornum;

int n;

struct Colors *colors;

RASTER_MAP_TYPE data_type;

If the data_type is CELL_TYPE, calls D_lookup_c_raster_colors((CELL *) rast, colornum, n, colors);

If the data_type is FCELL_TYPE, calls D_lookup_f_raster_colors((FCELL *) rast, colornum, n, colors);

If the data_type is DCELL_TYPE, calls D_lookup_d_raster_colors((DCELL *) rast, colornum, n, colors);

D_lookup_c_raster_colors (dcell, colornum, n, colors)

CELL *cell;

int *colornum;

int n;

struct Colors *colors;

Same functionality as D_lookup_colors() except that the resultant color numbers are placed into a separate colornum array (which the caller must allocate).

D_lookup_f_raster_colors (fcell, colornum, n, colors)

FCELL *fcell;

int *colornum;

int n;

struct Colors *colors;

Same functionality as D_lookup_colors() except that the fcell array is type FCELL and that the resultant color numbers are placed into a separate colornum array (which the caller must allocate).

D_lookup_d_raster_colors (dcell, colornum, n, colors)

DCELL *dcell;

int *colornum;

int n;

struct Colors *colors;

Same functionality as D_lookup_colors() except that the dcell array is type DCELL and that the resultant color numbers are placed into a separate colornum array (which the caller must allocate).

D_draw_cell_of_type(A_row, xarray, colors, map_type)

int A_row;

DCELL *xarray;

struct Colors *colors;

RASTER_MAP_TYPE map_type;

If map_type is CELL_TYPE, calls D_draw_cell (A_row, (CELL *) xarray, colors);

If map_type is FCELL_TYPE, calls D_draw_f_cell (A_row, (FCELL *) xarray, colors);

If map_type is DCELL_TYPE, calls D_draw_d_cell (A_row, (DCELL *) xarray, colors);

D_draw_f_cell (A_row, xarray, colors)

int A_row;

FCELL *xarray;

struct Colors *colors;

Same functionality as D_draw_cell() except that the xarray array is type FCELL which implies a call to D_f_raster() instead of a call to D_raster().

D_draw_d_cell (A_row, xarray, colors)

int A_row;

DCELL *xarray;

struct Colors *colors;

Same functionality as D_draw_cell() except that the xarray array is type DCELL which implies a call to D_d_raster() instead of a call to D_raster().

3.4.2. New functions to support a color for the NULL-value.

G_set_null_value_color (r, g, b, colors)

int r, g, b;

struct Colors *colors;

Sets the color (in colors) for the NULL-value to r,g,b.

G_get_null_value_color (r, g, b, colors)

int *r, *g, *b;

struct Colors *colors;

Puts the red, green, and blue components of the color for the NULL-value into r,g,b.

3.4.3. New functions to support a default color.

G_set_default_color (r, g, b, colors)

int r, g, b;

struct Colors *colors;

Sets the default color (in colors) to r,g,b. This is the color for values which do not have an explicit rule.

G_get_default_color (r, g, b, colors)

int *r, *g, *b;

struct Colors *colors;

Puts the red, green, and blue components of the "default" color into r,g,b.

3.4.4. Upgraded color functions

G_read_colors()

This routine reads the rules from the color file. If the input raster map is is a floating-point map it calls G_mark_colors_as_fp().

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.

G_get_colors_min_max()

If the color table is marked as "float", then return the minimum as -(255^3 * 128) and the maximum as (255^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.

G_lookup_colors()

Modified to return a color for NULL-values.

G_get_color()

Modified to return a color for the NULL-value.

3.4.5. Changes to the Colors structure

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 color for NULL was added
• the special color for zero was eliminated
• a default color for values which have no assigned color was added
• 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.

3.4.6. Changes to the colr file

• 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]:

             1.3:255:0:0  5:0:255:0
  

• The NULL-value color is written as:

             nv:red:grn:blu
  

• The default color (for values that don't have an explicit rule) is written as:

             *:red:grn:blu
  

3.5. Range functions (new and upgraded)

3.5.1. Modified range functions

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.

If the range file is missing and the map is a floating-point map, this function will create a default range by calling G_construct_default_range().

G_init_range()

Must set a flag in the range structure that indicates that no min/max have been defined - probably a "first" boolean flag.

G_update_range()

NULL-values must be detected and ignored.

G_get_range_min_max()

If the range structure has no defined min/max (first!=0) there will not be a valid range. In this case the min and max returned must be the NULL-value.

G_write_range()

This routine only writes 2 numbers (min,max) to the range file, instead of the 4 (pmin,pmax,nmin,nmax) previously written. If there is no defined min,max, an empty file is written.

3.5.2. New range functions

G_construct_default_range (struct Range *r)

Sets the integer range r to [1,255]

G_read_raster_range (void *r, char *name, char *mapset, RASTER_MAP_TYPE map_type)

If map_type is CELL_TYPE, calls G_read_range((struct Range *) r, name, mapset); otherwise calls G_read_fp_range((struct FPRange *) r, name, mapset);

G_read_fp_range (struct FPRange *r, char *name, char *mapset)

Read the floating point range file f_range. This file is written in binary using XDR format. If there is no defined min/max in r, an empty f_rangefile is created.

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.

If the range file is missing and the map is a floating-point map, this function will create a default range by calling G_construct_default_range().

G_init_raster_range (FPRange *r, RASTER_MAP_TYPE map_type)

If map_type is CELL_TYPE, calls G_init_range(struct Range *) r); otherwise calls G_init_fp_range((struct FPRange *) r);

G_init_fp_range (FPRange *r)

Must set a flag in the range structure that indicates that no min/max have been defined - probably a "first" boolean flag.

G_update_f_range (FPRange *r, FCELL *fcell, int n)

Updates the floating-point range r from the n FCELL values in fcell NULL-values must be detected and ignored.

G_update_d_range (FPRange *r, DCELL *dcell, int n)

Updates the floating-point range r from the n DCELL values in dcell NULL-values must be detected and ignored.

G_get_fp_range_min_max (FPRange *r, DCELL *min, DCELL *max)

Extract the min/max from the range structure r.

If the range structure has no defined min/max (first!=0) there will not be a valid range. In this case the min and max returned must be the NULL-value.

G_write_fp_range (FPRange *r)

Write the floating point range file f_range. This file is written in binary using XDR format. If there is no defined min/max in r, an empty f_rangefile is created.

3.6. New and Upgraded Cell_stats functions

G_init_cell_stats()

Set the count for NULL-values to zero.

G_update_cell_stats()

Look for NULLs and update the NULL-value count.

G_next_cell_stat()

Do not return a record for the NULL-value

G_find_cell_stat()

Allow finding the count for the NULL-value

G_get_stats_for_null_value(int *count, struct Cell_stats *s)

Get a number of null values from stats structure. Note: when reporting values which appear in a map using G_next_cell_stats(), to get stats for null, call G_get_stats_for_null_value() first, since G_next_cell_stats() does not report stats for null.

3.7. New Quantization Functions

G_write_quant (char *name, char *mapset, struct Quant *q)

Writes the f_quant file for the raster map name from q.

if mapset==G_mapset() i.e. the map is in current mapset, then the original quant file in cell_misc/map/f_quant is written. Otherwise q is written into quant2/mapset/name (much like colr2 element). This results in map@mapset being read using quant rules stored in q from G_mapset(). Seee G_read_quant() for detailes.

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.

G_read_quant (char *name, char *mapset, struct Quant *q)

reads quantization rules for "name" in "mapset" and stores them in the quantization structure "quant". If the map is in another mapset, first checks for quant2 table for this map in current mapset.

Return codes:

-2 if raster map is of type integer

-1 if (! G__name_is_fully_qualified ())

0 if quantization file does not exist, or the file is empty or has wrong format.

1 if non-empty quantization file exists.

G_quant_init (struct Quant *q)

Initializes the q struct.

G_quant_free (struct Quant *q)

Frees any memory allocated in q and re-initializes q by calling G_quant_init().

G_quant_truncate (struct Quant *q)

sets the quant for q rules to perform simple truncation on floats.

G_quant_truncate (struct Quant *q)

sets the quant for q rules to perform simple rounding on floats.

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.

G_quant_add_rule (q, dmin, dmax, cmin, cmax)

struct Quant *q;

DCELL dmin, dmax;

CELL cmin, cmax;

Add the rule that the floating-point range [dmin,dmin] produces an integer in the range [cmin,cmax] by linear interpolation.

Rules that are added later have higher precedence when searching.

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.

G_quant_set_positive_infinite_rule (q, dmax, c)

struct Quant *q;

DCELL dmax;

CELL c;

Set the rule that values greater than or equal to dmax produce the integer c. If dmax or c is the NULL-value, return 0 and don't set the rule. Otherwise return 1.

This rule has lower precedence than rules added with G_quant_add_rule().

G_quant_get_positive_infinite_rule (q, dmax, c)

struct Quant *q;

DCELL *dmax;

CELL *c;

Sets dmax and c to the positive "infinite" rule in q if there is one and returns 1. If there is no such rule, it just returns 0. if the fp_lookup is organized, updates infinite limits.

G_quant_set_negative_infinite_rule (q, dmin, c)

struct Quant *q;

DCELL dmin;

CELL c;

Set the rule that values less than or equal to dmin produce the integer c. If dmin or c is the NULL-value, return 0 and don't set the rule. Otherwise return 1. if the fp_lookup is organized, updates infinite limits.

This rule has lower precedence than rules added with G_quant_add_rule().

G_quant_get_negative_infinite_rule (q, dmin, c)

struct Quant *q;

DCELL *dmax;

CELL *c;

Sets dmin and c to the negative "infinite" rule in q if there is one and returns 1. If there is no such rule, it just returns 0.

G_quant_get_limits (q, dmin, dmax, cmin, cmax)

struct Quant *q;

DCELL *dmin, *dmax;

CELL *cmin, *cmax;

Extracts the minimum and maximum floating-point and integer values from all the rules (except the "infinite" rules) in q into dmin, dmax, cmin, and cmax. Returns 1 if there are any explicit rules. If there are no explicit rules, (this includes cases when q is set to truncate or round map), it returns 0 and sets dmin, dmax, cmin, and cmax to NULL.

G_quant_nrules (struct Quant *q)

Returns the number of rules in q, excluding the negative and positive "infinite" rules.

G_quant_get_rule (q, n, dmin, dmax, cmin, cmax)

struct Quant *q;

int n;

DCELL *dmin, *dmax;

CELL *cmin, *cmax;

Get the nth rule from q. If 0 <= n < nrules(q), extract the rule and return 1. Otherwise return 0. This function can't be used to get the "infinite" rules.

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

G_quant_perform_d (q, dcell, cell, n)

struct Quant *q;

DCELL *dcell;

CELL *cell;

int n;

Performs a quantization of the n DCELL values in the dcell array and puts the results into the cell array.

G_quant_perform_f (q, fcell, cell, n)

struct Quant *q;

FCELL *fcell;

CELL *cell;

int n;

Performs a quantization of the n FCELL values in the fcell array and puts the results into the cell array.