Documentation on maths

Task: maths
Purpose: Mathematical operations on images and image data
Categories: utility, map combination, map manipulation

        MATHS is a MIRIAD task which performs arithmetic expressions on a
        number of images. The expression to be performed is given in a
        FORTRAN-like syntax, and can consist of operators, real constants
        and FORTRAN functions. Normal FORTRAN precedence applies.
        Operators can be +, -, * and /, and all logical and relational
        operators (e.g. .and. .or. .not. .gt. .ge. etc). In MATHS convention,
        a positive value is considered TRUE, and a negative or zero value
        is considered FALSE. Functions
        appear only in the generic, rather than specific forms. For example
        use ``log10'' rather than ``alog10'', and ``max'' rather than
        ``amax1''. Integers and double precision constants are converted to
        reals. File names take the place of variables, and the expression
        is evaluated on each pixel of the image. When there is more than
        one file name in the input expression, the expression is evaluated
        at corresponding pixels of the input images. For example to average
        image ``fred'' with image ``bill'', use:

          exp=(fred+bill)/2

        When a file name starts with a numeric character, or contains a
        character which might be confused with an operator the file name
        should be bracketed by angular (   and   ). For example:

          exp=( 2ndtry +bill.dat)/2
         mask= bmap.fft .gt.0.5

        Files cannot take the name ``x,'' ``y'' or ``z''. MATHS interprets
        these as being the 3 independent variables of an image, which
        vary linearly between the limits set by the XRANGE, YRANGE and
        ZRANGE parameters. The user chooses the meaning of these units.
        For example, to create one cycle of a two dimensional sine wave
        along the x and y coordinate axes use:

          exp=sin(x)*sin(y) xrange=-3.14,3.14 yrange=-3.14,3.14

        In addition to the expression, MATHS also allows the user to specify
        a "mask expression". MATHS main expression is only evaluated at
        pixels where the "mask expression" is TRUE or positive valued. MATHS
        does not check for divide by zero, logs of a negative number
        or any similar problem. It will probably crash if this is attempted.
        Consequently, when performing potentially dangerous operations, it
        is best to guard the main expression by masking out dangerous
        situations.  The mask expression can also be used to prevent the
        calculation where doing so would be undesirable for other reasons
        (e.g. where the signal is too weak to get meaningful results).

        For example:

           exp=sqrt(fred) mask=fred.gt.0

Key: exp
        The expression to be evaluated.

Key: mask
        The mask expression. The expression given by "exp" is evaluated
        only at those pixels where the mask expression is TRUE or
        positive valued. Pixels, which fail this test, are marked as blank
        in the output image.

Key: region
        The region of interest in the input images. Full region 
        specifications are supported, however the output map will contain
        only the bounding box. (see also mask=)
        Default: full map.

Key: out
        The name of the output image.

Key: imsize
        The output image size. This is used only if there is no input
        images (i.e. the expression consists of a function of ``x'' and
        ``y'' only). No default.

Key: xrange
        When ``x'' is present in the input expression, then the x variable
        is varied linearly between the two limits set by XRANGE.

Key: yrange
        When ``y'' is present in the input expression, then the y variable
        is varied linearly between the two limits set by YRANGE.

Key: zrange
        When ``z'' is present in the input expression, then the z variable
        is varied linearly between the two limits set br ZRANGE.