V1CHAPT09.MEM







                                   CHAPTER 9    IMAGE ARITHMETIC





            9.1 INTRODUCTION



                 Most image  arithmetic  may  be  conveniently  performed  by

            option AR which calls the subroutine ARITHMETIC.  This subroutine

            accepts as input an arithmetic expression, parses it and  applies

            it  to a set of input maps, leaving the result in a set of output

            maps.  Because of the considerable  power  of  the  program,  the

            possibility  of  the  user  corrupting  or  deleting data exists.

            Please exercise care in using this option; check your expressions

            carefully before pressing RETURN.





            9.2 INVOKING "ARITHMETIC" FROM MIIPS



                 After entering  MIIPS,  enter  the  two  letter  option  for

            ARITHMETIC,  "AR".  The program then prompts the user to enter an

            arithmetic expression:



                 Enter the expression to be evaluated:

                 EXPRESSION=



            A  at this stage will cause ARITHMETIC to  exit  back  to

            MIIPS.   ARITHMETIC  will  attempt  to  parse any other string of

            characters which is entered.  If  a  new  output  file  is  being

            created  and  the  size is not inferred from one or more files on

            the right hand side of the equals sign,  ARITHMETIC  will  prompt

            the user for a choice of data types for the new expression.



                 Enter the data format for the new file:  (I2, R4  (default),

                 R8, or C8)

                 FORMAT=



            Having completed the evaluation  of  the  expression,  ARITHMETIC

            asks  if  you  want  to  go  around  again  to  evaluate  another

            expression , or exit back to MIIPS.


                                                                Page 2





            9.3 GENERAL FORMAT OF EXPRESSIONS



                 Expressions accepted by ARITHMETIC are of the form:



                    Output = input expression



            where the input expression (to the  right  of  the  "=")  may  be

            arbitrarily  complicated,  except  that  no  more  than ten input

            operands (either files or constants) will be accepted.



            The following are examples of valid expressions:



            A<1>=3.141                  - pixels in map 1 of the file  A  are

                                        given a value of 3.141 .



            A<1>=B<1>*3.141             - pixels in map 1 of the file  A  are

                                        given  values  3.141 times the values

                                        of the corresponding pixels in map  1

                                        of the file B.



            A<1>=(B<1>+C<1>)/D<1>        - the sum of maps B<1> and  C<1>  is

                                        divided by map D<1>, the result being

                                        put into map A<1>.





            9.3.1 LEGAL OPERATORS



                 The following operators are available in ARITHMETIC, and may

            be applied to any operand (ie., any map or constant):



                    +         - addition

                    -         - subtraction

                    /         - division

                    *         - multiplication

                    **        - exponentiation

                    LN        - natural logarithm, e.g., LN(X<1>)

                    LOG       - logarithm to the base 10, e.g., LOG(X<1>)

                    SUM       -  sum  of  pixel   values   in   maps,   e.g.,

                              SUM(X<1,2,5>)



            All these operators apply to two operands, e.g., A+B, A<1>**B<1>,

            etc.,  except  LN,  LOG,  and  SUM,  where  the single operand is

            enclosed in parentheses.



            Note:  the expression A<1>=-B<1> is not  valid.   To  negate  the

            map, the appropriate expression is, A<1>=0.0-B<1>.


                                                                Page 3





            9.3.2 LEGAL FILE NAMES



                 All  files  must  be  SAD  files.   Filenames  can  be   any

            acceptable   VAX   filename,   including   device  and  directory

            specifications.  For example, the following is  a  valid  operand

            for an ARITHMETIC expression:



                    USER$DISK3:[MIIPS.SAD]XYZ<1:3>



            This file specification is interpreted as meaning the first three

            maps of the file XYZ.SAD on the area USER$DISK:[SAD].





            9.3.3 CONSTANTS



                 Constants are valid ARITHMETIC  operands.   ARITHMETIC  will

            accept constants in any valid FORTRAN format (ie., I, F, E, and D

            formats).  For example, the following are valid expressions:



                    A<1>=1.414



                    A<1>=1+2+3000.42



                    A<1>=1.4E2





            9.3.4 PARENTHESES



                 Parentheses  may  be  added  to  an  expression  to  resolve

            ambiguities  and  to  determine  the  order  of  evaluation of an

            expression.  Expression evaluation rules are identical  to  those

            of  FORTRAN.   For  example, the expression B<1>+C<1>/D<1> (where

            the division is performed before the addition) differs  from  the

            expression  (A<1>+C<1>)/D<1>  (where  the  addition  is performed

            before the division).





            9.3.5 RESTRICTIONS



                 Quite complicated expressions, including several  levels  of

            parenthesis,   can  be  evaluated  using  ARITHMETIC.   The  only

            limitation is that a maximum of ten operands (files or constants)

            may   be   used   in  the  input  expression.   More  complicated

            expressions should be broken down into smaller sub-expressions.


                                                                Page 4





            9.4 SPECIFYING MAP NUMBERS



                 Because files may contain  more  than  one  map,  ARITHMETIC

            provides a means for specifying which maps in an input expression

            will be operated on, and for specifying which maps in the  output

            file will receive the results.





            9.4.1 SIMPLE EXPRESSIONS



                 A map number specification  can  consist  of  a  single  map

            number  (e.g.,  FILENAME<23>),  a  list  of  map  numbers  (e.g.,

            FILENAME<23:27> or FILENAME<1,4,33>)  or  a  default  map  number

            (e.g., FILENAME<> or simply FILENAME).

                 As a general rule the map number specification of the output

            file  determines how many maps will be involved in the evaluation

            of the expression.

                 When the output file has a  SINGLE  map  number,  only  that

            specific  map  in  the  output file is affected.  For example, in

            each of the following expressions only map 1 of the file  OUT  is

            affected:



                  OUT<1>=1000.3

                  OUT<1>=IN<3>

                  OUT<1>=IN<1:13>       (equivalent to OUT<1>=IN<1>)

                  OUT<1>=IN<3,6,72,77>  (equivalent to OUT<1>=IN<3>)

                  OUT<1>=IN             (equivalent to OUT<1>=IN<1>)



                 When the output file has a LIST of map numbers,  only  those

            maps  are  affected  in the output file.  For example, in each of

            the following expressions only maps 3 to 5 of the  file  OUT  are

            written:



                  OUT<3:5>=1000.3

                  OUT<3:5>=IN<3>        (equivalent to the three separate ex-

                                        pressions OUT<3>=IN<3>,OUT<4>=IN<3>,

                                        OUT<5>=IN<3>)

                  OUT<3:5>=IN<7:9>      (equivalent to the three separate ex-

                                        pressions OUT<3>=IN<7>,OUT<4>=IN<8>,

                                        OUT<5>=IN<9>)

                  OUT<3:5>=IN


                                                                Page 5





            When the output file has  a  default  map  number  specification,

            however,  the  number  of maps to be written is determined by the

            the input expression, and  these  maps  are  created  immediately

            following  the  current  last  map  in  the output file (ie., the

            output file is extended).  For example, if the file  OUT  already

            exists  and has 6 maps in it, then the following expressions will

            create new maps starting at map 7:



                  OUT=1000.3      (equivalent to OUT<7>=1000.3)

                  OUT=IN<1>       (equivalent to OUT<7>=IN<1>)

                  OUT=IN<3:5>     (equivalent to OUT<7>=IN<3>,OUT<8>=IN<4>,

                                  OUT<9>=IN<5>)





            9.4.2 Complex Input Expressions



                 When an input expression comprises two or more  files,  each

            file  may  have  a  map  number specification in one of the three

            forms described in 9.4.1.  An order of precedence is  applied  to

            the   evaluation   of   expressions   which  contain  map  number

            specifications of differing types.

                 In increasing order of precedence  the  specifications  are:

            single  map number, default map number , and list of map numbers.

            The expression as a whole can be regarded as having a map  number

            specification  of  the same type as the constituent specification

            with the highest precedence.



            The following examples illustrate this principle:



            (i) A<1:4>=B<1>*C<5:8>



            In this case the input expression has a combination of  a  single

            (B<1>)  and  a list (C<1:4>) map number specification.  Hence the

            whole  expression  is  regarded  as  having  a  list  map  number

            specification.  This expression is equivalent to the four simpler

            expressions:



                    A<1>=B<1>*C<5>



                    A<2>=B<1>*C<6>



                    A<3>=B<1>*C<7>



                    A<4>=B<1>*C<8>


                                                                Page 6





            (ii) A<31:32>=B<1>*C



            In this case the input expression has  combination  of  a  single

            (B<1>)  and  a  default  (C) map number specification.  The whole

            expression  is  regarded  as  having   a   default   map   number

            specification.   This expression is equivalent to the two simpler

            expressions:



                    A<31>=B<1>*C<31>



                    A<32>=B<1>*C<32>



            (iii) A<32:33>=B<1:2>*C



            This  expression  has  the  same  effect  as  the   two   simpler

            expressions:



                    A<32>=B<1>*C<1>



                    A<33>=B<2>*C<2>


                                                                Page 7





            9.5 DATA TYPES



                 ARITHMETIC caters for INTEGER*2, REAL*4, REAL*8, and COMPLEX

            data types.  In general, output maps will have the same data type

            as the input maps.   For  example,  adding  two  maps  containing

            REAL*4  data  will  produce  a  REAL*4  output  map.   Mixed mode

            arithmetic is catered for, e.g., adding a map  containing  REAL*4

            data  to  a  map  containing  REAL*8 data.  The result of a mixed

            expression will have the data type of the most precise element of

            the  expression.  For example, adding an I2 map to an R4 map will

            produce an R4 result; adding an R4 map to an R8 map will  produce

            an R8 result.





            9.6 MAP SIZES



                 If an output file already exists, and new  maps  are  to  be

            created  or  existing  maps  overwritten,  then the size (both in

            terms of number of pixels and data type) of the new maps must  be

            exactly the same as the size of the existing maps.





            9.7 HEADER INFORMATION



                 When more than one file appears in an input expression,  the

            question  arises  as to where the output file will get its header

            information from.  In the current version of ARITHMETIC the first

            file  mentioned  in  the  input  expression is pirated for header

            information.  For example, in the expression A=B<1>*C<1>,  header

            information  in  map  one  of file B will be copied to map one of

            file A.  Any header information in file C is ignored.

                 This method of operation may be changed later to  allow  the

            user  to  specify  which  input  file header information is to be

            taken from.