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 con-
stants (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
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 divi-
sion 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 expres-
sion.
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 log-
arithm base (cannot be a cube!).
Standard Arithmetic Expressions
Use the -s or --standard option to input standard arith+-
metic expressions.
The possible operators are as above: addition `+', sub-
traction `-', multiplication `*', division `/', exponenti-
ation `^', logarithm `l'. To these, add the possibility
to use parentheses `(' and `)' to enforce operator prior-
ity. 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 fol-
lowing:
"@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.