CalcImg: Layers and fields Calculator/Reclassifyer: Mathematical and Logical Analysis

Access this help text as a web page: CalcImg

Presentation and options	Dialog box of the application
Examples	Syntax

Presentation and options

This program allows performing reclassifications and mathematical and logical operations, simultaneously, on layers of any type (rasters, structured vectors and unstructured vectors), in any number and in any directory. The logical operations return 1 in the true case and 0 in the false case.

The mathematical expression must contain at least one layer but can have no operator or function defined, in which case it can be utilized in order to saturate or scale the layer, change its flag value, transform the format of a raster layer, rasterize a vector layer..., even though MiraMon comes with specific applications to perform these transformations.(see IMGIMG, TiraVec).

All rasters contained in the expression must have the same geographical extent, resolution and reference units in the same reference system. However, they can be of different types (byte, real, etc) and degrees of compression. It does need not to be said that the geographical extent of vector layers is defined by the extent of the raster layers in the expression, if present. For expression with only vector layers it will be necessary to define the geographical extent through the Options button. Advanced. Singularities in the used operations or functions (e.g.: division by zero, negative square root...) will always result in the NODATA value at that particular geographical position. This value is established by the program as a function of the data type in the resulting layer (255 for data of byte type, 0 for bit type, and the most negative value for the rest of the data types), except when the value is explicitly indicated in the advanced options box. In this case, it is necessary to accurately choose the flag value so that it lies outside the possible range of values of the resulting raster file. In case of doubt, it is better to let the program decide it.

All calculations are made with double precision (15-16 significative digits, approx. range 1.7E-308 to 1.7E+308). There is no limit to the length and complexity of the expression (it will only depend on the user's hardware and operating system).

The logical-mathematical formula to be calculated is entered in the first entry field and is formed by numbers, layers (raster and vector), operators and functions. The names of the images that form part of the expression are aliases of the corresponding files and are indicator between claudators ('[' and ']'). Claudators are automatically inserted when using the "New..." button. For expression clarity the name of the file does not include its path (the program already knows the path since it has obtained it from the string returned by the file search box. When files have the same name but are located in different directories the program inserts a differentiating character that allows a correct evaluation of the expression). When the inserted layer in the expression is a vector layer it will be necessary to define some additional parameters:

External value for the vector: This is the value, that though within the defined geographical extent, it lies outside the outermost part of the graphical objects and that an emulating raster layer would have. For instance, if the layer is of polygon type this value will correspond to the value of the universal polygon. If it does not have one (e.g: empty field, missing record or non-labelled universal polygon). If the layer is of line or point type the value will be the value assigned to the matrix over which the lines or points lie.

Field: For topologically-structured vector layers, it is necessary to indicate the field in the layer's main table or associated table according to which the calculations will be done. Alphanumerical fields will be treated as numeric except in the case where there is a logical expression indicating equalness or non-equalness with respect a constant string of characters. Example: [Inv_for;Municipi;]="Olot".

Position in multiple records: For databases with multiple records for the same graphical identifier it is necessary to indicate which one of them is the one used for the calculation.
The program automatically inserts the field descriptor (or the name of the field in its absence) as a comment, along with the file alias. Comments are specified between ';' and may be included at any given position in the formula, provided they are correctly opened and closed.

Example of a commented expression so that it is easier to remember and use:

;difference in absolute value;ABS([model];theoretical model;-[dat0299];sample data for February 1999;)

The List button will inform us of the properties of the layers that form the expression and of the relation between real filenames (with path) and aliases.

The implemented operators and functions are described below. The function arguments must be enclosed within parenthesis. Parenthesis are automatically inserted when using the "Functions library..." button; e.g. SING(30). In functions with more than argument commas are used to separate them; e.g. MAX([IMG1]),[IMG2]).

All operators can be used both with images and numerical values.
As an example, when writing an expression such as:

 MAX([IMG1], SING(30))

the maximum value with respect to the cell value in the image and the sine of 30º will be obtained. The following expressions can also be written:

 MAX([IMG1], 100)
 100*SING([IMG1])
 MAX( MIN([IMG1],[IMG2]), 100)
 etc.

When dubious, it is recommended to use the syntax that is constructed by the program itself by pressing the corresponding buttons and menus of the Windows application without editing them afterwards. It is also advisable to always use parenthesis when doubting on the operator's precedence rules.

The resulting data type can be controlled with the corresponding listbox. It is recommended to use the "Automatic" option since the program adapts the resulting data type to the range and type (integer or real) of the resulting file. The program also compresses the resulting file when adequate (for instance, when the result is boolean (0,1), the file is compressed to the format byte-RLE, which results in very small files). "Automatic" will not compress any of the images if only one of the images is uncompressed (except for the case with boolean results (0,1), in which case the byte-RLE compression is used). Bit data type is only generated when explicitly expressed since the byte-RLE format usually results in smaller files. Although the automatic mode is easier, calculations are performed substantially faster if the resulting data type is defined. Besides, automatic needs to create a temporary file in with data as doubles, which normally consumes a lot of disk space. There is an information button which is associated with the data type and which allows to know the needs of the program in terms of disk space to generate the result. In the case of compressed files, when automatic is chosen or when "stretch" is activated, the program informs on the maximum disk space that would be necessary if the file(s) could not be compressed at all. For automatic and "stretch" it should be taken into account that the program generates an additional temporary file.

When the option "Saturation" is selected, all values above or below the range corresponding to the resulting data type are assigned the maximum and minimum values of the range, respectively. On the other hand, if the option "Stretching" is selected, the values are linearly distributed between the values indicated in the "Minimum" and "Maximum" entryfields of the stretching. Example: Suppose that a file with values comprised between 0 and 200 is multiplied by 2 and that the resulting data type chosen is byte. If "Saturation" is selected, all values between 256 and 400 will be assigned to 255. If "Stretching" is selected, the numerical range [0,400] will be stretched to the range [0,255].

When the resulting data is not of real type the program allows to either round (recommended) or truncate the results. This process is only applied in the final writing phase of the file, not during the calculations. If you need to truncate the data in an intermediate phase of the expression, you can use the function ENT() (integral part) which is available when pressing the button "Functions library".

The "Title" entrybox allows to introduce a title for the resulting image (when left blank the logical-mathematical expression will be used as a title).

The button "Reclassify" allows to define the function for reclassification: RECL([reclassification file],[file to be reclassified]). This function will change 'old' values of the layer to be reclassified into 'new' values as specified in the correspondences in the reclassification file (*.mrc). The format of this file is composed by lines of numbers where these changes are specified. A line with two numbers means that pixels with the first value will be assigned the second value (see line 2 in the example below, where a previousvalue, 10, will be converted into 20). A line with three numbers means that a previous value that isbetween the first and second number (equal or bigger than the first and strictly smaller than the second) will be assigned the value of the third number in the reclassificationchain (see line 2 in the example below). This format allows to leave blank lines and to put comments when the first character of the line is a ";" (see line 1 in the example below). Please note that the comment in the reclassification format does not necessarily have to be closed with a second ';'.
The reclassification format also has special formats that allow to change a value (as 1, example in line 5) or a numerical range (as [2,3), example in line 6) to the "flag value" or "NoData". The new value is assigned through the literal value "NoData". The flag value can also be reclassified as any other value (see example in line 4) and assign a new value to it, thus losing its condition as flag value.
The argument "layer to be reclassified" should be taken in its widest general sense, that is, it can effectively correspond to one of the selected layers, or to the result of any defined operation between layers and scalars. Also, the result of the reclassification can be saved as a final result or it can be simply one of the intermediate calculations in the logico-mathematical expression.
Examples of correct formats for reclassification:

;This line is a comment
10 20
1 5 8
NODATA 1
1 NODATA
2 3 NODATA

Examples of incorrect formats for reclassification

This line is an incorrect comment 
10 
1 5 8 9
NODATA 1 2
1 NODATA 2
NODATA NODATA

Example of an expression in which an intermediate format is reclassified:
RECL([altitudinal_levels], [MDE]*10)
In this example, a Digital Elevation Model (MDE), in decimeters, is transformed to meter units and then is reclassified in altitudinal levels according to the file "altitudinal_levels.MRC".

By pressing the button "Advanced" you can introduce a description of the values that will be obtained in the entryfield "Values description". This descriptor will be shown between parenthesis when querying by location the resulting image. You can leave it blank for categorical results (e.g. thematic maps) and specify the corresponding units in the case of images with continuous values (e.g. ºC for a map that is the result of a regression model which approximates the temperature in Celsius degrees). In the case of categorical results, the resulting file can import the categories associated with any layer, which are described in the DOC file or DBF associated table for raster cases, in particular, of any of the images that form part of the logical-mathematical expression. In this case, the IMG file must be indicated in the "Categories file" entryfield. This way, it is easy to get a resulting file of categorical type which automatically has its categories correctly described if we have a reference IMG.
The NoData value can also be defined in the resulting file. It is recommended to always use the parameter automatic, except in cases where the user needs to assign a specific value to the NoData value.
The advanced option "Preserve the NoData value from start" is useful when we want to anticipate the program, that is, when we know beforehand that a NoData value will be generated in the resulting file. In any case, if we leave this parameter not active, the program will perform the necessary modifications in order to add the parameter NoData if the program detects it must be added.
When there is no raster in the formula, the geographical extent of the resulting file must be specified. Its coordinates must be given along with pixel size, in the corresponding entryfields.

As in any of the MiraMon Support Applications that is launched from within the corresponding windows interface, the calculator saves the parameters that are used in each execution in a text file so that the parameters of the last execution can always be recovered. Also, if you need to save a specific expression for a later moment, independently of intermediate calculations you may have made, you can press the button "Save..." and the formula will be saved in the PAR file that you specify. To recover it you only need to press the button "Load". If a value NoData was explicitly defined in the last execution, a symbol "!" will appear by the button "Advanced...". This will warn us that it is very convenient to restore the automatic value if the new execution does not have the particularities that caused the change in the definition of the flag value.

More information can be consulted at the following reference:

Pesquer L, Masó J, Pons X (2000) Herramientas de análisis combinado ráster/vector en un entorno SIG. Aguado I, Gómez M (eds.) Tecnologías Geográficas para el Desarrollo Sostenible. Departamento de Geografía. Universidad de Alcalá, 2000: 53-73. IX congreso del Grupo de Métodos Cuantitativos, Teledetección y SIG de la Asociación de Geógrafos Españoles, Alcalá de Henares.

Dialog box of the application

CalcImg dialog box

Examples

Example 1: We want to create an image as if it had already been multiplied by a mask: Suppose we want to select from image 'A' all zones which have values bigger than 3000 in image 'B'.
The operation will be: [A]*([B]>3000)
In this case, the resulting image will have the value 0 in all zones with values that are equal or less than 3000 in image 'B', and will maintain the original values in 'A' in the rest of the image (zones with values greater than 3000).

Example 2: We want to reclassify the values of an image 'C' in two groups. All values that are less than 100 will become 50 and values equal or greater than 100 will become 150.
The operation will be: ([C]<100)*50+(NOT([C]<100))*150.
Alternatively, the following form can be used: ([C]<100)*50+([C]>=100)*150.
The resulting image will have two different values: 50 for those that where smaller than 100 and 150 for those that where greater than 100.
The function of reclassification can also be used: RECL([MMReclass],[C]) if we do know the range of values in the raster 'C'. If 'C' is a raster of type byte or byte-RLE the contents of the reclassification file MMReclass.MRC would be:

0 100 50
100 256 150

or, if we do not know the range of values for raster 'C', a reclassification based in a MRC file such as the following is also admitted:

-1.0E+40 100 50
100 1.0E+40 150

Example 3: Suppose we want to obtain a raster file with the following grouped categories:

category1 : Dense forest 
category2 : Sparse forest 
category3 : Riparian forests
category4 : Reforestations
category5 : Poplar plantations
category6 : Platanus plantations
category7 : Shrublands 
category8 : Wetlands
category9 : Meadows
category 10 : CORINE Fires
category 11 : Rock outcrops
category 12 : Scree
category 13 : Bare soil
category 14 : Beaches
category 15 : Continental waters 
category 16 : Glaciers and permanent snow
category 17 : Cultivation fields
category 18 : Urban zones
category 19 : Roads 
category 20 : Sport zones
category 21 : Quarrying zones

according to the reclassification:

The resulting raster will have four categories which could be defined as:

category1 : Forests
category2 : Non-productive natural zones
category3 : Cultivation fields
category4 : Non-productive artificial zones

Example 4: Given an image, 256c, if you want to assign value 1 to all values that are equal to "3" or to "12" and "0" to the rest of the values, then you will write:

([256c]=3)OR([256c]=12)

This operation can also be done from within MiraMon through a query by attributes and saving the file as a IMG file.

Example 5: Given an image, 256c, in order to select both values 3 and 12, but preserving these values in the result and making the rest of the values as 0, we will write:

(([256c]=3)OR([256c]=12))*[256c]

Example 6: How to obtain the digital elevation model from three States out of the digital elevation model of a of USA '[USA_DEM]' and the vector layer of the counties '[States]'.

[USA_DEM]*([States;State;]="Connecticut" OR [States;State;]="Wisconsin" OR [States;State;]="Idaho")

It should be noted that the resulting file will have the same extent as [USA_DEM], the whole USA, and the Retalla application needs to be used in order to reduce the extent.

Example 7: The rasterization of an arc layer, '[Profiles]', converting rasterized lines to 0 value and the external zone to 1 is a less intuitive but interesting example that shows how dynamic rasterization is treated inside the calculator.

[Profiles;LONG_ARC;]=0
where we have defined 'Value external to the vector'=0

There is no arc with longitude equal to 0 in the cells affected by the vector (rasterized) and, thus, the logical operation returns FALSE, that is 0. On the other hand, as the external zone has been assigned the value 0, which compared to value 0, the result is TRUE, that is 1.

Example 8: We need to define a random value between -1 and 1. Raster1 is a raster file with the constant value 1, is necessary to define the extent and the pixel size of the output file.

(RND(2)-1)*[Raster1]

Syntax

Syntax:

CalcImg ParametersFile

Parameters:

ParametersFile (Parameters file - Input parameter): Calculations are made according to parameters specified in the _PARCLMM.MMC file in the MiraMon directory or in the operating system temporary directory when the MiraMon directory is read-only (the typical situation when MiraMon is installed in a server).

Description of the parameters file (*.MMC) and the mathematical and logical syntax:

(you need not to read it when using the windows interface)

[Formula]: Section which contains information on the mathematical formula which is to be calculated.
Expressio: String that represents the logical-mathematical operation to be executed. It is composed of numbers, images, operands and functions. Image names are aliases of the corresponding files and are given between claudators ('[' and ']'). Implemented operands and functions are described below. Function arguments need to be within parenthesis; e.g: SING(30). If the function contains more than argument these will be separated by commas; e.g: MAX([IMG1],[IMG2]). When not sure it is recommended to use the syntax that is constructed by clicking onto the corresponding buttons and menus of the Windows application without editing them, or at most, adding the needed parameters

[Result]: Characteristics of the resulting file of the mathematical expression.
Fitxer: Name of the resulting file. Its path is relative to the location of the parameters file.
Tipus: Data type of the resulting file (auto, byte, byte-RLE, etc.). Automatic means that the program has adjusted the final data type with respect to the range and integer or real data type of the values of the resulting file and of its degree of compression. Automatic will not compress when at least one of the images in the expression is compressed, except for the case of the resulting image being of 0 and 1 values. In this case, the resulting image will be byte-RLE. Bit data are generated only when specified because, usually, a byte-RLE format will result in files smaller in size.
Titol: Descriptive title of the resulting image. When left blank, by default, the title will be the mathematical formula.
Desc_valors: Descriptive string of the type of values that will result.
Fitxer_categories: In the case of categorical results, it is the IMG file from which categories are imported. Its address is relative to the parameters file.
Valor_Fons: Value given to the flag value or "NODATA" in the resulting file. The literal "NODATA" indicates that the program itself will decide which value will be chosen.
Stretch: 0 means that no stretching will be applied and that values beyond the range of the chosen domain will be saturated. 1 means that values are linearly scalated to the range in-between the minimum and maximum stretch. 0 is the default value, which corresponds to saturation.
Minim_Stretch: It is activated with Stretch=1. X is the default value according to the chosen data type.
Maxim_Stretch: It is activated with Stretch=1. X is the default value according to the chosen data type.
Truncar:If real values are not chosen, any resulting image will be rounded when Truncar=0 or will be truncated when Truncar=1. 0 is the default value.
Reservar_V_Fons: 0 implies that no value for NoData is reserved from start. 1 implies that a value is reserved for possible NoData values in the result. Its default value is 0. X_minima, X_maxima, Y_minima, Y_maxima: Definition of the geographical extent of the resulting raster when there is no raster in the mathematical expression.
Costat_pixel: Pixel size of the resulting raster when there is no raster in the mathematical expression.

[Variables]: In this section the correspondences between the aliases of the images that appear in the formula and the actual files are specified. Paths are relative to the location of the parameters file.

[Reclassificadors]: This is the section where the aliases that appear in the formula for the reclassification files are related to their full real names. The paths of these files are relative to the parameters file.

[Alias_vector]: Each vector in the [Variables] section will have its own section named after its alias and with the following contents:
base: For topologically-structured vectors, -1 when referred to the main table or the index of the field with which the relation with the associated table is established (starting from 0).
camp: For topologically-structured vectors, the index on which calculations are performed (indexed from 0).
repeticio: For topologically-structured vectors with multiple records, it is the index of the record to be taken into account: 1,2.. (starting from the first record), -1,-2... (starting from the last record).
valor_exterior: Value that will take the emulated raster, external to the vector and inside the defined geographical extent.

Implemented operands and functions

Arithmetical operators:

+ Sum or positive sign.
-Substraction or negative sign.
*Multiplication.
/Division.

Logical and Comparison operators (when true the result is 1, when false the result is 0):

ANDI. 
OR Or.
NOTNegation
XORExclusive Or.
>Strictly bigger.
>= Equal or bigger.
<Strictly smaller.
<= Equal or smaller. 
=Equal.
=/=Different.

Mathematical functions of only one argument:

SQRT Square root.
LOGBase 10 logarithm.
LN Natural logarithm.
EXPExponential.
INVInverse.
ENTTruncation.
ABSAbsolute value.
RNDRandom value between 0 and the argument.

Logical functions of only one argument:

BOLBoolean.

Mathematical functions of two arguments:

POWPower. 
NR Normalized ratio.
MODDivision remainder.

Comparison functions of two arguments:

MAXthe Bigger of two values.
MINthe Smaller of two values.

Reclassification functions and category grouping:

RECL Reclassification.

Layer overlay functions:

CVRTransparent (*).

(*) Transparent function (also named Cover) returns the value of the second argument when the first argument is equal to the flag value (value defined by NoData in the documentation of the first file in case of rasters) and returns the first argument when it is different to this value. This way, values of the second file can be seen through NoData zones of the first layer. As in the other cases, any of the arguments of Transparent can be the partial results of other operations between layers and scalars.

Trigonometric functions with the angle expressed in radiants:

SINSine.
COSCosine.
TANTangent.
ASIN Arc sine.
ACOS Arc cosine.
ATAN Arc tangent.
COSECCosecant.
SECSecant.
CTGCotangent.

Trigonometric functions with the angle expressed in degrees:

SING Sine.
COSG Cosine.
TANG Tangent.
ASINGArc sine.
ACOSGArc cosine.
ATANGArc tangent.
COSECG Cosecant.
SECG Secant.
CTGG Cotangent.

The order of precedence is governed by the six categories of operands and functions ordered from bigger to smaller precedence. Within the same category the operations are carried out from left to right. The different categories are:

1: ()
2: + , - [as positive and negative signs] and functions of only one argument [e.g.: SIN, LOG...]
3: Functions of two arguments [e.g.: POW, CVR, MAX, ...]
4: * , /
5: + , - [as sum and substraction operations]
6: logical [p. ex.: AND, >=...]

The conditional function has not been implemented
? (condition, function_TRUE, function_FALSE) since it can be simulated with a combination of logical operations in the form:

(condition)*(function_TRUE)+(NOT condition)*(function_FALSE)