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 notation 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 prefixed with an
arobas (@). All other symbols will be interpreted as numeri-
cal operators or operands. This is mainly due to avoid con-
flicts between operands/operators and Unix file names. Exam-
ples: 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 character 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 (+), subtrac-
tion (-), multiplication (*), 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 operates 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, subtract 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 argument (cannot be omitted) is the logarithm
base (cannot be a cube!).
STANDARD ARITHMETIC EXPRESSIONS
Use the -s or --standard option to input standard arithmetic
expressions.
The possible operators are as above: addition '+', subtrac-
tion '-', 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 containing '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 argument '@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.