MODEL

Name	Type	Length
Input *	Raster	1 - 1
InputBit	Bitmap	0 - 48
InputText *	Text	1 - 48
Output	Raster	0 - 1
OutputBitmap	Bitmap	0 - 48
ModelFile	Text	0 - 64
ModelT	Text	0 - 48
Undefined	Float	0 - 1

Details

MODEL is a generalized image processing and raster GIS tool. Using a special programming language, the user enters a set of equations (model) describing how channels of imagery data and attribute data should be combined. The results appear in new data channels.

In imaging applications, input typically consists of image channels that contain raw imagery. In GIS applications, input usually consists of attribute data and image channels containing data 'layers'. Layers may include raw imagery, elevation, classification themes, digitized maps, and proximity maps.

All raster channels/layers are assumed to be contained in a single PCIDSK file. Attribute data may be held in text files or as segments in the PCIDSK file.

The text describing the model is read in and the equations are applied to each pixel in the raster data. Because imagery is often of unpredictable quality, it is possible to specify the results of undefined operations rather than have MODEL terminate immediately upon the detection of such an operation.

Image/Layer Data

MODEL works with the pixels in image channels on the PCIDSK database. This data can be 8-bit integer, 16-bit signed or unsigned integer, or 32-bit real. Although channels on the database are called 'image channels', this is only a convention. In fact, it is often more useful to think of a database as a series of registered data layers. The following chart lists some of the types of possible data layers that can be held in an image channel.

 Layer Type             Common Sources

 Raw Imagery          Satellite/Aircraft distributed on magnetic tape
 Elevation                  USGS DEM from tape, gridded from contours
 Theme/Overlays      USGS LULC from tape, digitized from maps
 Processed Imagery  Classified images, slopes calculated from elevation, etc.

Attribute Data

Attribute data is a set of numeric and/or character values which are associated with a range of values.

For example:

        23 : 27   ;  1.3  19  river  Mississippi

means that values on the range 23 to 27 are associated with the two numeric attributes 1.3 and 19 and the two character attributes 'river' and 'Mississippi'.

MODEL can access attribute data held in a text segment on PCIDSK files or in text files on disk. This is accomplished by tying the attribute data to a specific image channel (layer) and then using the gray level values for individual pixels to match against the ranges in the attribute data.

A special feature of MODEL is the ability to use lookup table (LUT) and pseudocolor table (PCT) segments held on a PCIDSK file as attribute data. LUT data is equivalent to attribute data having 256 entries, each entry having one numeric attribute. PCT data is equivalent to attribute data having 256 entries, each entry having three numeric attributes (red, green, blue).

Vector Data

Vector data cannot be directly handled. The GRDVEC function can be used to embed vector data into an image channel (layer) after which it can be used by model.

Errors

There are two general types of errors:

Language errors: occur when the model is improperly written. This includes misspelling keywords, incorrectly ordering statements, not matching brackets. MODEL attempts to locate as many of these errors as possible before the model starts execution; however, some can only be detected during execution. In all cases, MODEL prints a meaningful error message, indicates the location of the error, and terminates execution. The user will then have to correct this error before running the model again.
Computation errors: occur when illegal mathematical operations occur, such as division by zero. These can be corrected in one of three ways:
- altering the input data
- altering the model to check for these conditions
- using the UNDEFVAL (Undefined) parameter to override these operations

Complex models may require debugging. The following hints may help in this process:

While developing/debugging a model, use small data sets; use the CIM and III functions to make smaller data sets.
Get hardcopy printouts of small image data areas and of any attribute data used; use the NUM and TEXWRIT functions.
Add extra channels to the file and use them to output 'intermediate' results. This can be useful in 'tracing' model execution. Use PCIMOD to add extra 8-bit channels.

Note: One of the most common debugging methods is to use strategically placed print statements. Due to the structure of MODEL, the use of parallelism (where available) cannot perform I/O while processing a pixel. This means that the print statement cannot be used within the processing section of the model, because parallelism is not used. The print statement can, however, be used in the INPUT/SET section.

Accuracy

All computations are made in double precision. On most systems, this will be 64-bit floating point. The results are truncated to the data type of the output image channel (8-bit integer, 16-bit signed/unsigned integer or 32-bit real). The user should take care that results generated by the model are appropriate for the channels selected for output.

Speed Hints

Modeling is a computationally intensive process. The modeling equations are re-executed for each pixel in the database. For example, a database file with 1000 by 1000 resolution would require that the modeling equations be evaluated 1,000,000 times.

To improve execution speed, MODEL "half compiles" the modeling equations; MODEL basically works as an interpreter. The following hints can help improve speed even further.

Make equations as simple as possible. For example:

replace:  #e = 7 * (%1/2 + 3^2);         
with:     #e = 3.5 * %1 + 63;

Accessing attribute data is slow. If this data will be used a number of times in the model, assign it to a numeric/string variable and use the variable instead. For example:
```
replace:   if (%3.2>27) then #e = %3.2 + ln(%3.2); endif;
with:      #a = %3.2; if (#a>27) then #e = #a + ln(#a); endif;
```
Avoid the use of character data where possible; this type of data is much slower than numeric data.

Note that comments, blank lines, and white space do not affect execution speed; these may be used liberally.

Limitations

Modeling is not only CPU-intensive, it is also memory-intensive. The following table lists approximate limitations for various computer systems. If these limits are exceeded, the MODEL program will terminate with an error message.

Feature      

Model Size (char)               32768            
Layers/Variables                128           
Attribute Data (Kbytes)       1000          
Array Data (Kbytes)            32

Language

The modeling language is similar to other procedural languages such as BASIC, FORTRAN, or C, but is specifically designed for raster imaging and GIS applications.

The modeling language is not case-sensitive, although character data is.

Constants

The following types of constants are available:

n           123.4                numerical constant
"text"     "abc"                string constant
'text'      'B12'                 string constant

Variables

Variables give access to image (layer) pixel values, attribute data, and other values. Variables are identified by a special leading character (#,%,@,$), followed by 1 to 7 characters.

Layer Variables

Layer variables are identified by the leading character '%'. Layer variables take on the gray level value of the pixel being processed for a particular layer (image channel); for example, %3 would take on the gray level value of the third image channel at the current pixel position. If a name is used (for example, %tree), the association between the name and an explicit layer is made when the model is first run using a SET or INPUT statement.

Syntax:    %x, %n

Examples:  %soil,%z,%1,%23

Attribute Variables

Attribute variables are identified by the leading character '%' and a '.'. Attribute variables take on the value of an attribute associated with the layer through the gray level value. For example, %2.3 would be evaluated as follows: at the current pixel location, the gray level value for the second image channel would be used as a key to a single line of attribute data associated with the layer; within this line, the list of attributes would be scanned and the third attribute value extracted; %2.3 would take on this value. Note that this value could be numeric or character, depending on the actual nature of the attribute.

Syntax:    %x.i, %n.i

Examples:  %slope.2, %5.3

Subscripts

It is possible to access the gray-level values and attribute data for adjacent pixels by subscripting layer or attribute variables. The following diagram shows the subscript syntax and relationship to the pixel being currently processed (which is [ 0, 0]).

                [-1,-1]  [ 0,-1]  [ 1,-1]
                [-1, 0]  [ 0, 0]  [ 1, 0]
                [-1, 1]  [ 0, 1]  [ 1, 1]

%x is equivalent to %x[0,0]. Subscripted pixels which are outside the bounds of the image are automatically assigned the value of the nearest pixel which is inside the image.

Note: It is NOT possible to assign a value to a subscripted pixel.

Numeric Variables

Numeric variables are identified by the leading character '#'. Numeric variables are used for temporary storage of numeric values. They have no relation to any layers or attributes and provide a convenient way of holding results of calculations or user-entered constants.

Syntax:    #x

Examples:  #tree, #t37

Character Variables

Character variables are identified by the leading character '$'. Character variables are used for temporary storage of character data. They have no relation to any layers or attributes and provide a convenient way of holding user-entered character data.

Syntax:    $x

Examples:  $name,$a

Numeric Array Variables

Numeric array variables are identified by the leading character '#' followed by 1 to 7 characters and an array subscript. Subscripts can range from 1 to the number of elements in the numeric array.

Syntax:  #x[n]

Examples: #array[7], #colval[127]

Numeric array variables allow access to one-dimensional array information held in PCIDSK array segments [type ARR:181].

Special

Special variables allow access to information about the file and location information about the pixel being processed. They can be used within numerical expressions like constants.

Variable Description

@x             current x (pixel) processing location
@y             current y (line ) processing location
@dbx           size of database in x (pixel) direction
@dby           size of database in y (line ) direction
@metrex        size of a pixel in x direction in metres
@metrey        size of a pixel in y direction in metres
@geox          x georeferenced center of current pixel
@geoy          y georeferenced center of current pixel
@sizex         x size of a pixel in georeferenced units
@sizey         y size of a pixel in georeferenced units

Character Expressions

Character expressions are limited to a single character constant character variable, or character attribute variable.

Examples of these are:

'abcdef'
"ab   123"
$answer
%3.2   (if the attribute is character)

It is not possible to access part of a character string, concatenate two strings, or process a string.

Character strings are case-sensitive. For example, 'abc' is not the same as 'ABC'.

Arithmetic Expressions

Arithmetic expressions are made up of arithmetic elements and arithmetic operators. The evaluation of an arithmetic expression yields a single numeric value. Arithmetic elements consist of: numeric constants, numeric variables, layer variables, numeric attribute variables, numeric array variables and special variables. Available operators are listed in the following sections.

Examples of arithmetic expressions are:

10.3
sin(%3) * 27.05 - (2+ln(#temp))
min(%1,%2,%3) * and(%6,15)

Operators

The following arithmetic operators are available, with standard algebraic precedence being observed:

'-x'            negation
'^'             exponentiation
'/'             division
'*'             multiplication
'+'             addition
'-'             subtraction
'()'            parenthesis

Single-value functions

The following single-value arithmetic functions are available:

sin   (e)               sine
cos   (e)               cosine
tan   (e)               tangent
asin  (e)               arc sine
acos  (e)               arc cosine
atan  (e)               arc tangent
deg   (e)               radians to degrees
rad   (e)               degrees to radians
ln    (e)               natural logarithm
exp   (e)               natural exponent
log10 (e)               base 10 logarithm
exp10 (e)               base 10 exponent
int   (e)               integer  part of real
frac  (e)               fraction part of real
abs   (e)               absolute value

where:

e can be any arithmetic expression
arguments for trigonometric functions MUST be expressed in radians

int(tan(2.3 * ln(%6)))

Multi-value functions

The following multi-value arithmetic functions are available:

atan2 (v1,v2)           arc tan (v1/v2) using signs of v1,v2
mod   (v1,v2)           remainder of v1/v2
min   (v1,v2,...,vn)    minimum value of v1,v2,...,vn
max   (v1,v2,...,vn)    maximum value of v1,v2,...,vn

where:

v1,v2,...,vn are arithmetic elements, excluding attribute variables.

min (%1, %2, #temp, 25.5, @dbx)

Bit manipulation functions

The following bit manipulation functions are available. They are accomplished by converting passed values to integers, performing the logical operation on all the bits, and converting back. 'not' operations should be followed by an 'and' to remove high bits.

not (v1)                logical not
and (v1,v2,...,vn)      logical and
or  (v1,v2,...,vn)      logical inclusive or
xor (v1,v2,...,vn)      logical exclusive or

where:

v1,v2,...,vn are arithmetic elements, excluding attribute variables.

#t = not(%1); #t= and(#t,255);   | to ensure only 8 bits

Sections

The statements and comments which make up a model are divided up into the following sections:

Setup
Equation

The Setup section sets up the processing environment. This includes: prompting the user for any required data; associating attribute data with image channels (layers); and printing messages to the user's screen. This section is executed once before any processing is done.

The following types of statements can be included in the 'Setup' section:

COMMENTS
INPUT
INPUTA
SET
SETA
PRINT

The Equations section defines the processing that should be done. This section is applied to each pixel in the database. For example, if the database has dimensions of 512 by 512, the equations section would be executed 262144 times.

The following types of statements can be included in the Equations section:

COMMENTS
ASSIGNMENT
IF
GOTO
LABEL
STOP

Each time this section is applied, numeric variables are reset to the value entered from an INPUT statement or to zero. Character variables are also reset to values entered or to the empty (null) string.

When MODEL is run, the following steps are followed:

The model is read in and internal data structures are set up.
The Setup section is executed and, if necessary, the user is prompted for required data.
The image database is read in and the modeling equations in the Equations section are applied to each pixel. If any output channels (layers) are generated, these are written back to the file.

Note: This step takes almost all the processing time.
All data files are closed and the MODEL terminates.

COMMENT

The COMMENT ('!') statement is used to add documentation to the model. Commetns have no effect on the execution of the model; they may appear anywhere in the model and can be used inline. When a comment is encountered, the rest of the line is considered a comment.

Syntax:    ! text

Example:   ! This line could give the author's name
           !
           %6 = 257;     !This is an in-line comment

PRINT

The PRINT statement allows a line of text to be output to the user's terminal when the model is run.

Syntax:     PRINT "text";

Example:    print "The Soil Model takes 15 minutes to run";

INPUT

The INPUT statement allows the model to prompt the user for constants and layers (image channels) which should be associated with layer variables.

Syntax:    INPUT "text" #x;            | numerical constant
           INPUT "text" $x;            | character constant
           INPUT "text" %x;            | layer variable

Example:   input "Enter layer for Tree Coverage: " %tree ;

Values entered by the user for a layer variable are checked to ensure the image channel exists on the database file.

INPUTA

The INPUTA statement allows the model to prompt the user for the source of attribute information to associate with a layer variable or a numeric array variable.

Syntax:           INPUTA "text" %x ;
            INPUTA "text" #x[];

Example:   inputa "Enter source of tree attributes: " %tree;
           inputa "Enter segment number for array data: " #a[];

When a layer variable is used (for example, %x), if a number is entered, a check is run to verify if this a TEXT (attribute), LUT, or PCT segment on the database file. If a file name is entered, this is checked to ensure that it is an existing text file and that it contains valid attribute data.

When a numeric array variable is used (for example, #x[]), only a number can be entered, and this is checked to ensure that it is an array segment (type ARR:181) on the database file.

SET

The SET statement associates a layer variable with a channel on the file or a numeric variable with value. The value can either be a constant or come from an entry in the parameter file.

Syntax:   SET %x = n ;
          SET #x = parm(n);

Example:  set %trees   = 1;
          set #minimum = imstat(11);
          set #maximum = 23.5;

SETA

The SETA statement associates a numeric array variable with a database segment containing array data or a layer variable with attribute data held in a text file on disk or a database segment containing TEXT (attribute), LUT, or PCT data.

Syntax:  SETA #x[] = n ;         | numeric array to segment number n
         SETA %x = n ;           | layer variable to segment number n
         SETA %x = "filename" ;  | layer variable to text file name

Example:  seta %3 = "attr.txt";
          seta #means[] = 3 ;

ASSIGNMENT

There are three types of assignments:

assignments to numeric variables
assignments to character variables
assignments to layer variables

Numeric variables:

Syntax:   #x = arithmetic expression ;

Example:  #cost = %crop.2 * 1.5 + log10(%rain) ;

Character variables:

Syntax:   $x = character expression ;

Example:  $x = "ABCDEF" ;

Layer variables:

The value assigned to the layer variable replaces its current value and will be written back to the PCIDSK database file. Note that the layer value is a real value until it is actually written to disk, at which time it is converted to the type that the channel has on disk.

Syntax:   %x = arithmetic expression ;

Example:  %3 = %crop.2 * 1.5 + log10(%rain);

Note: Assignment cannot be made to numeric array variables. Numeric variables are read-only, and get their contents from array segments held on PCIDSK database files.

The syntax for the possible IF ... EXTRIF ... ELSE ... ENDIF constructs are shown below:

 IF cond THEN               IF cond THEN             IF cond THEN
   statement;statement;statement;
      ...       ...       ...
   statement;statement;statement;
 EXTRIF cond THEN           ELSE     ENDIF;
   statement;statement;
      ...       ...
   statement;statement;
 ELSE       ENDIF;
   statement;
      ...
   statement;
 ENDIF;

statement can be an ASSIGNMENT, GOTO, LABEL, STOP or another IF statement.

cond is a condition made up of a series of logical expressions joined by logical operators. This has the syntax:

(exp relopr exp) logopr (exp relopr exp) ...

where:

exp          is an arithmetic or character expression
relopr       is a relational operator
logopr       is a logical operator

The following relational operators are available and will work on either arithmetic or character expressions:

=            equals
>            greater than
<            less than
>=           greater than or equal
<=           less than or equal
<>           not equal

The following logical operators are available:

and
or

   if (%tree.2 = "spruce") and (%rain > 10) then
      %result = 5;
   else
      %result = %rain / 3;
   endif;

GOTO

The GOTO statement allows execution to transfer to a different part of the model. The LABEL statement is used in conjunction with the GOTO statement to provide a transfer location.

Syntax:  GOTO ident ;

Example:  if (%1 = 3) then goto skip; endif;

Note: GOTO statements should be used sparingly, or not at all if possible. MODEL does not detect 'infinite' loops created using GOTO statements.

LABEL

The LABEL statement provides a transfer location for GOTO statements.

Syntax:   LABEL ident;

Example:  label loop; #i=#i+1; if (#i<10) then goto loop; endif;

STOP

The STOP statement allows the model to be terminated prematurely if an error condition is detected.

Syntax:    STOP "message" ;

Example:   if (%3 = 0) then stop "zero value detected"; endif;

The message and the (x,y) position of the pixel that was being processed is printed.

Note: Because buffers are not flushed, if a STOP statement is executed, output will not reflect the current point of processing.

SEMI-COLON

The SEMI-COLON (';') acts as a statement separator. This allows for more than one statement per line and statements that span more than one line. Each statement must end with a semicolon except for IF constructs, where the semicolon goes after the associated ENDIF.

Environments	PYTHON :: EASI :: MODELER
Batch Mode	Yes
Quick links	Description :: Parameters :: Parameter descriptions :: Details

MODEL

Image modeling

Description

Parameters

Parameter descriptions

Details