Name
       ccube - cube/image computer

Synopsis
       ccube [options] <arithmetic_expression> [outcube]

Description
       ccube  is  a  calculator  which allows operation between cubes, between
       cubes and constants, and also between constants (for  the  same  price,
       you won a wonderful on-line calculator).

Expressions
       Arithmetic  expressions  support both standard and polish reverse nota-
       tion operations. Be careful however, that  to  avoid  all  ambiguities,
       FITS  files given in an expression are only identified by the fact that
       they contain a "fits" or "FITS" extension (suffix), or if they are pre-
       fixed  with  an  arobas  (@).  All other symbols will be interpreted as
       numerical operators or operands. This is mainly due to avoid  conflicts
       between operands/operators and Unix file names. Examples: the slash (/)
       is both a division sign and the root directory, "1/2" may be the result
       of  the  division of 1 by 2, or a file named ’2’ located in a directory
       named ’1’, and so on.

       See the following paragraphs for a detailed  description  of  supported
       expressions and operators.

Polish Reverse Notation (prn)
       Int  this  mode  (default)  all  arithmetic  expressions use the Polish
       Reverse Notation (PRN).

       An arithmetic expression must be provided enclosed in quotes.

       Separate arguments by spaces. "2 1+" is invalid, "2 1 +" is Ok.

       Cube arguments are names which contain "fits" or "FITS", or any charac-
       ter  string which begins with an arobas ’@’. The arobas is stripped and
       the rest of the string is taken as an input file name. e.g. to  compute
       with  a  file  named ’b012’, give as argument ’@b012’ in the arithmetic
       expression.

       Possible arithmetic operations are: addition (+), subtraction (-), mul-
       tiplication (*), division (/), exponentiation (^), logarithm (l).

       Operands  are  processed from left to right. e.g. to divide an image by
       2, the order is "image.fits 2 /".

       Two cubes may be added/subtracted/multiplied/divided if and only if:
       1. They have the same number of planes:
       The operation is repeated plane by plane: plane n of first  cube  oper-
       ates with plane n of second cube.
       2. The second cube has only one plane:
       The  operation  is  repeated on all planes of first cube, with the only
       plane in second cube.

       All operators are binary. To use the minus ’-’ as unary operator,  sub-
       tract from zero (see examples below).

       A  logarithm  (l)  is  also  considered as a binary operator. Its first
       argument is the object which logarithm will be taken, the second  argu-
       ment (cannot be omitted) is the logarithm base (cannot be a cube!).

Standard Arithmetic Expressions
       Use  the  -s  or --standard option to input standard arithmetic expres-
       sions.

       The possible operators are as above:  addition  ’+’,  subtraction  ’-’,
       multiplication  ’*’,  division  ’/’, exponentiation ’^’, logarithm ’l’.
       To these, add the possibility to use parentheses ’(’ and ’)’ to enforce
       operator  priority. The operator priority is given below, in decreasing
       order of priority:

       exponentiation
       logarithm
       multiplication and division (same priority level)
       addition and subtration (same prioriry level)

       Blanks are stripped off before processing an arithmetic expression,  so
       feel free to make notations clear by adding some.

       As  in  PRN  above, file names are identified as character strings con-
       taining ’fits’ or ’FITS’, or any character string containing an  arobas
       ’@’.  The  arobas is stripped and the rest of the string is taken as an
       input file name e.g. to compute with a file named ’b012’, give as argu-
       ment ’@b012’ in the arithmetic expression.

Examples
       All  the following examples are given first in PRN and then in standard
       notation.

       To compute: out.fits = in.fits * 2
       > ccube "in.fits 2 *" out.fits
       > ccube -s "in.fits * 2" out.fits

       To compute: out.fits = (obj.fits - sky.fits) / ff.fits
       > ccube "obj.fits sky.fits - ff.fits /" out.fits
       > ccube -s "(obj.fits - sky.fits)/ff.fits" out.fits

       To compute: out.fits = (obj1 + obj2)/2
       > ccube "@obj1 @obj2 + 2 /" out.fits
       > ccube -s "(@obj1 + @obj2) / 2" out.fits
       > ccube -s "(@obj1+@obj2)/2" out.fits

       To compute the log in base 10 of an image named ’image.fits’, type:
       > ccube "image.fits 10 l" out.fits
       > ccube -s "image.fits l 10" out.fits

       To compute the square of an image: out.fits = in.fits ^ 2
       > ccube "in.fits 2 ^" out.fits
       > ccube -s "in.fits^2" out.fits

       To exponentiate an image, e.g. out.fits = 1.01 ^ input_im
       > ccube "1.01 @input_im ^" out.fits
       > ccube -s "1.01 ^ @input_im" out.fits

       Here is an example showing that PRN does not use parentheses:

       > ccube -s "(2*3) + 2*(4*(1+2))"
       is equivalent to:
       > ccube "2 3 * 2 1 + 4 * 2 * +"

       With images:
       "(obj.fits - sky.fits) / (ff.fits - dark.fits)"
       Becomes:
       "obj.fits sky.fits - ff.fits dark.fits - /"

       Invalid syntax with PRN may be due to lack of separators:
       "1 3+" and "1 2 3 +*" are invalid.
       "1 3 +" and "1 2 3 + *" are Ok.

       In standard notation, it is Ok to stack operators, as long as there  is
       no ambiguity ("1 2" differs from "12" !):
       "1+3" and "1*(2+3)" are ok.

       With  PRN,  invalid syntax may be returned if some objects are still on
       the stack when no operator remains. The following:
       "@im1 @im2 2 *" will cause an error message, because an object (im1) is
       still on the stack after all operators have been used.

       To  use  the minus ’-’ as unary operator to negate an image subtract it
       from zero:
       out = - in
       is given as:
       > ccube "0 @in -" out
       > ccube -s "0-@in" out

Options
       --polish or -p
              Polish reverse notation for arithmetic expressions. This is  the
              default.

       --standard or -s
              Standard notation for arithmetic expressions.

Files
       Input files shall all comply with FITS format.
       Default output file name is ’comp.fits’.

Bugs
       Unary operators are not supported, they should.