GRASS GIS 8 Programmer's Manual  8.4.0dev(2024)-535c39c9fc
quant.c File Reference

Raster Library - Quantization rules. More...

#include <stdlib.h>
#include <grass/gis.h>
#include <grass/raster.h>
Include dependency graph for quant.c:

Go to the source code of this file.

Macros

#define USE_LOOKUP   1
 
#define MAX_LOOKUP_TABLE_SIZE   2048
 
#define NO_DATA   (Rast_set_c_null_value(&tmp, 1), (CELL)tmp)
 
#define NO_LEFT_INFINITE_RULE   (!q->infiniteLeftSet)
 
#define NO_RIGHT_INFINITE_RULE   (!q->infiniteRightSet)
 
#define NO_FINITE_RULE   (q->nofRules <= 0)
 
#define NO_EXPLICIT_RULE    (NO_FINITE_RULE && NO_LEFT_INFINITE_RULE && NO_RIGHT_INFINITE_RULE)
 

Functions

void Rast_quant_clear (struct Quant *q)
 Resets the number of defined rules and number of infinite rules to 0. More...
 
void Rast_quant_free (struct Quant *q)
 Resets and frees allocated memory. More...
 
int Rast__quant_organize_fp_lookup (struct Quant *q)
 Organized fp_lookup table. More...
 
void Rast_quant_init (struct Quant *quant)
 Initialize the structure. More...
 
int Rast_quant_is_truncate (const struct Quant *quant)
 Returns whether or not quant rules are set to truncate map. More...
 
int Rast_quant_is_round (const struct Quant *quant)
 Returns whether or not quant rules are set to round map. More...
 
void Rast_quant_truncate (struct Quant *quant)
 Sets the quant rules to perform simple truncation on floats. More...
 
void Rast_quant_round (struct Quant *quant)
 Sets the quant rules to perform simple rounding on floats. More...
 
int Rast_quant_get_limits (const struct Quant *q, DCELL *dMin, DCELL *dMax, CELL *cMin, CELL *cMax)
 Returns the minimum and maximum cell and dcell values of all the ranges defined. More...
 
int Rast_quant_nof_rules (const struct Quant *q)
 Returns the number of quantization rules defined. More...
 
void Rast_quant_get_ith_rule (const struct Quant *q, int i, DCELL *dLow, DCELL *dHigh, CELL *cLow, CELL *cHigh)
 Returns the i'th quantization rule. More...
 
void Rast_quant_set_neg_infinite_rule (struct Quant *q, DCELL dLeft, CELL c)
 Defines a rule for values "dLeft" and smaller. More...
 
int Rast_quant_get_neg_infinite_rule (const struct Quant *q, DCELL *dLeft, CELL *c)
 Returns in "dLeft" and "c" the rule values. More...
 
void Rast_quant_set_pos_infinite_rule (struct Quant *q, DCELL dRight, CELL c)
 Defines a rule for values "dRight" and larger. More...
 
int Rast_quant_get_pos_infinite_rule (const struct Quant *q, DCELL *dRight, CELL *c)
 Returns in "dRight" and "c" the rule values. More...
 
void Rast_quant_add_rule (struct Quant *q, DCELL dLow, DCELL dHigh, CELL cLow, CELL cHigh)
 Adds a new rule to the set of quantization rules. More...
 
void Rast_quant_reverse_rule_order (struct Quant *q)
 Rreverses the order in which the qunatization rules are stored. More...
 
CELL Rast_quant_get_cell_value (struct Quant *q, DCELL dcellVal)
 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. More...
 
void Rast_quant_perform_d (struct Quant *q, const DCELL *dcell, CELL *cell, int n)
 Returns in "cell" the quantized CELL values. More...
 
void Rast_quant_perform_f (struct Quant *q, const FCELL *fcell, CELL *cell, int n)
 Same as Rast_quant_perform_d(), except the type. More...
 
struct Quant_tableRast__quant_get_rule_for_d_raster_val (const struct Quant *q, DCELL val)
 Returns quant rule which will be applied. More...
 

Detailed Description

Raster Library - Quantization rules.

The quantization table is stored as a linear array. Rules are added starting from index 0. Redundant rules are not eliminated. Rules are tested from the highest index downto 0. There are two "infinite" rules. Support is provided to reverse the order of the rules.

(C) 1999-2009 by the GRASS Development Team

This program is free software under the GNU General Public License (>=v2). Read the file COPYING that comes with GRASS for details.

Author
USACERL and many others

Definition in file quant.c.

Macro Definition Documentation

◆ MAX_LOOKUP_TABLE_SIZE

#define MAX_LOOKUP_TABLE_SIZE   2048

Definition at line 27 of file quant.c.

◆ NO_DATA

#define NO_DATA   (Rast_set_c_null_value(&tmp, 1), (CELL)tmp)

Definition at line 28 of file quant.c.

◆ NO_EXPLICIT_RULE

#define NO_EXPLICIT_RULE    (NO_FINITE_RULE && NO_LEFT_INFINITE_RULE && NO_RIGHT_INFINITE_RULE)

Definition at line 33 of file quant.c.

◆ NO_FINITE_RULE

#define NO_FINITE_RULE   (q->nofRules <= 0)

Definition at line 32 of file quant.c.

◆ NO_LEFT_INFINITE_RULE

#define NO_LEFT_INFINITE_RULE   (!q->infiniteLeftSet)

Definition at line 30 of file quant.c.

◆ NO_RIGHT_INFINITE_RULE

#define NO_RIGHT_INFINITE_RULE   (!q->infiniteRightSet)

Definition at line 31 of file quant.c.

◆ USE_LOOKUP

#define USE_LOOKUP   1

Definition at line 26 of file quant.c.

Function Documentation

◆ Rast__quant_get_rule_for_d_raster_val()

struct Quant_table* Rast__quant_get_rule_for_d_raster_val ( const struct Quant q,
DCELL  val 
)

Returns quant rule which will be applied.

Returns quant rule which will be applied when looking up the integer quant value for val (used when organizing fp_lookup).

Parameters
qpointer to Quant structure which holds quant rules info
valfp cell value
Returns
pointer to the Quant_table (color rule)
NULL otherwise

Definition at line 774 of file quant.c.

References Quant_table::dHigh, Quant_table::dLow, Quant::nofRules, NULL, and Quant::table.

◆ Rast__quant_organize_fp_lookup()

int Rast__quant_organize_fp_lookup ( struct Quant q)

Organized fp_lookup table.

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 in between 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.

Parameters
qpointer to Quant structure which holds quant rules info
Returns
1 on success

Definition at line 90 of file quant.c.

◆ Rast_quant_add_rule()

void Rast_quant_add_rule ( struct Quant q,
DCELL  dLow,
DCELL  dHigh,
CELL  cLow,
CELL  cHigh 
)

Adds a new rule to the set of quantization rules.

If dLow < dHigh the rule will be stored with the low and high values interchanged.

Note: currently no cleanup of rules is performed, i.e. redundant rules are not removed. This can't be changed because Categories structure HEAVILY depends of quant rules stored in exactly the same order they are entered. So if the cleanup or rearrangement is done in the future make a flag for add_rule whether or not to do it, then quant will not set this flag.

Parameters
qpointer to Quant structure which holds quant rules info
dLowminimum fp value
dHighmaximum fp value
cLowminimum value
cHighmaximum value

Definition at line 469 of file quant.c.

Referenced by Rast_quantize_fp_map_range(), Rast_set_d_cat(), and Rast_set_quant_rules().

◆ Rast_quant_clear()

void Rast_quant_clear ( struct Quant q)

Resets the number of defined rules and number of infinite rules to 0.

Parameters
qpointer to Quant structure to be reset

Definition at line 41 of file quant.c.

References Quant::infiniteLeftSet, Quant::infiniteRightSet, and Quant::nofRules.

Referenced by Rast_quant_free(), and Rast_quant_init().

◆ Rast_quant_free()

void Rast_quant_free ( struct Quant q)

Resets and frees allocated memory.

Resets the number of defined rules to 0 and free's space allocated for rules. Calls Rast_quant_clear().

Parameters
qpointer to Quant structure to be reset

Definition at line 55 of file quant.c.

References Quant::active, Quant::fp_lookup, G_free(), Quant::maxNofRules, Quant::nalloc, Rast_quant_clear(), Quant::rules, Quant::table, and Quant::vals.

Referenced by Rast__quant_import(), and Rast_free_cats().

◆ Rast_quant_get_cell_value()

CELL Rast_quant_get_cell_value ( struct Quant q,
DCELL  dcellVal 
)

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

Parameters
qpointer to Quant structure which holds quant rules info
dcellValuefp cell value
Returns
cell value (integer)

Definition at line 592 of file quant.c.

Referenced by Rast_quant_perform_d(), and Rast_quant_perform_f().

◆ Rast_quant_get_ith_rule()

void Rast_quant_get_ith_rule ( const struct Quant q,
int  i,
DCELL dLow,
DCELL dHigh,
CELL cLow,
CELL cHigh 
)

Returns the i'th quantization rule.

For 0 <= i < Rast_quant_nof_rules(). A larger value for i means that the rule has been added later.

Parameters
qpointer to Quant structure which holds quant rules info
iindex
[out]dLowminimum fp value
[out]dHighmaximum fp value
[out]cLowminimum value
[out]cHighmaximum value

Definition at line 327 of file quant.c.

References Quant_table::cHigh, Quant_table::cLow, Quant_table::dHigh, Quant_table::dLow, and Quant::table.

Referenced by Rast_get_ith_d_cat().

◆ Rast_quant_get_limits()

int Rast_quant_get_limits ( const struct Quant q,
DCELL dMin,
DCELL dMax,
CELL cMin,
CELL cMax 
)

Returns the minimum and maximum cell and dcell values of all the ranges defined.

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.

Parameters
quantpointer to Quant structure which holds quant rules info
[out]dminminimum fp value
[out]dmaxmaximum fp value
[out]cminminimum value
[out]cmaxmaximum value
Returns
-1 if q->truncate or q->round are true or after Rast_quant_init (), or any call to Rast_quant_clear () or Rast_quant_free() no explicit rules have been added. In this case the returned minimum and maximum CELL and DCELL values are null.
1 if there are any explicit rules
0 if there are no explicit rules (this includes cases when q is set to truncate or round map), and sets dmin, dmax, cmin, and cmax to NULL.

Definition at line 281 of file quant.c.

References Quant::cMax, Quant::cMin, Quant::dMax, Quant::dMin, NO_EXPLICIT_RULE, Rast_set_c_null_value(), and Rast_set_d_null_value().

Referenced by Rast_read_range(), and Rast_write_quant().

◆ Rast_quant_get_neg_infinite_rule()

int Rast_quant_get_neg_infinite_rule ( const struct Quant q,
DCELL dLeft,
CELL c 
)

Returns in "dLeft" and "c" the rule values.

For the negative infinite interval (see Rast_quant_set_neg_infinite_rule()).

Parameters
qpointer to Quant structure which holds quant rules info
[out]dLeftfp value
[out]cvalue
Returns
0 if this rule is not defined
1 otherwise

Definition at line 390 of file quant.c.

Referenced by Rast_set_quant_rules().

◆ Rast_quant_get_pos_infinite_rule()

int Rast_quant_get_pos_infinite_rule ( const struct Quant q,
DCELL dRight,
CELL c 
)

Returns in "dRight" and "c" the rule values.

For the positive infinite interval (see Rast_quant_set_pos_infinite_rule()).

Parameters
qpointer to Quant structure which holds quant rules info
[out]dRightfp value
[out]cvalue
Returns
0 if this rule is not defined
1 otherwise

Definition at line 438 of file quant.c.

Referenced by Rast_set_quant_rules().

◆ Rast_quant_init()

void Rast_quant_init ( struct Quant quant)

Initialize the structure.

Initializes the q struct.

Parameters
quantpointer to Quant structure to be initialized

Definition at line 175 of file quant.c.

References Quant::active, Quant::fp_lookup, Quant::maxNofRules, Rast_quant_clear(), Quant::round_only, and Quant::truncate_only.

Referenced by Rast_init_cats(), Rast_quantize_fp_map_range(), Rast_read_quant(), Rast_round_fp_map(), Rast_set_quant_rules(), and Rast_truncate_fp_map().

◆ Rast_quant_is_round()

int Rast_quant_is_round ( const struct Quant quant)

Returns whether or not quant rules are set to round map.

Parameters
quantpointer to Quant structure which holds quant rules info
Returns
1 is round
0 not round

Definition at line 204 of file quant.c.

References Quant::round_only.

Referenced by Rast_read_range().

◆ Rast_quant_is_truncate()

int Rast_quant_is_truncate ( const struct Quant quant)

Returns whether or not quant rules are set to truncate map.

Parameters
quantpointer to Quant structure which holds quant rules info
Returns
1 if truncate is enable
0 if not truncated

Definition at line 192 of file quant.c.

References Quant::truncate_only.

Referenced by Rast_read_range().

◆ Rast_quant_nof_rules()

int Rast_quant_nof_rules ( const struct Quant q)

Returns the number of quantization rules defined.

This number does not include the 2 infinite intervals.

Parameters
qpointer to Quant structure which holds quant rules info
Returns
number of quantization rules

Definition at line 309 of file quant.c.

References Quant::nofRules.

Referenced by Rast3d_write_cats(), and Rast_get_next_marked_d_cat().

◆ Rast_quant_perform_d()

void Rast_quant_perform_d ( struct Quant q,
const DCELL dcell,
CELL cell,
int  n 
)

Returns in "cell" the quantized CELL values.

Returns in "cell" the quantized CELL values corresponding to the DCELL values stored in "dcell". the number of elements quantized is n. quantization is performed by repeated application of Rast_quant_get_cell_value().

Parameters
qpointer to Quant structure which holds quant rules info
dcellpointer to fp cell values array
[out]cellpointer cell values array
nnumber of cells

Definition at line 715 of file quant.c.

References Rast_is_d_null_value, Rast_quant_get_cell_value(), and Rast_set_c_null_value().

◆ Rast_quant_perform_f()

void Rast_quant_perform_f ( struct Quant q,
const FCELL fcell,
CELL cell,
int  n 
)

Same as Rast_quant_perform_d(), except the type.

Parameters
qpointer to Quant structure which holds quant rules info
fcellpointer to fp cell values array
[out]cellpointer cell values array
nnumber of cells

Definition at line 735 of file quant.c.

References Rast_is_f_null_value, Rast_quant_get_cell_value(), and Rast_set_c_null_value().

◆ Rast_quant_reverse_rule_order()

void Rast_quant_reverse_rule_order ( struct Quant q)

Rreverses the order in which the qunatization rules are stored.

See also Rast_quant_get_ith_rule() and Rast_quant_perform_d()).

Parameters
qpointer to Quant rules which holds quant rules info

Definition at line 513 of file quant.c.

◆ Rast_quant_round()

void Rast_quant_round ( struct Quant quant)

Sets the quant rules to perform simple rounding on floats.

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

Parameters
quantpointer to Quant structure which holds quant rules info

Definition at line 230 of file quant.c.

References Quant::round_only.

Referenced by Rast_round_fp_map().

◆ Rast_quant_set_neg_infinite_rule()

void Rast_quant_set_neg_infinite_rule ( struct Quant q,
DCELL  dLeft,
CELL  c 
)

Defines a rule for values "dLeft" and smaller.

Values in this range are mapped to "c" if none of the "finite" quantization rules applies.

Parameters
qpointer to Quant structure which holds quant rules info
dLeftfp value
cvalue

Definition at line 364 of file quant.c.

Referenced by Rast_set_quant_rules().

◆ Rast_quant_set_pos_infinite_rule()

void Rast_quant_set_pos_infinite_rule ( struct Quant q,
DCELL  dRight,
CELL  c 
)

Defines a rule for values "dRight" and larger.

Values in this range are mapped to "c" if none of the "finite" quantization rules or the negative infinite rule applies.

Parameters
qpointer to Quant structure which holds quant rules info
dRightfp value
cvalue

Definition at line 412 of file quant.c.

Referenced by Rast_set_quant_rules().

◆ Rast_quant_truncate()

void Rast_quant_truncate ( struct Quant quant)

Sets the quant rules to perform simple truncation on floats.

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

Parameters
quantpointer to Quant structure which holds quant rules info

Definition at line 217 of file quant.c.

References Quant::truncate_only.

Referenced by Rast_set_quant_rules(), and Rast_truncate_fp_map().