ic(1) --- Imcat Users Guide --- section: imtools_ic --- last changed: Thu Jul 10 HST
ic - image calculatorSYNOPSIS
ic [options....] rpnexpr fitsfile...where options are:
"-u " print usage
"-c N1 N2 " create an image of this size
"-p pixtype " specify output pixtype
"-s seed " seed rand num generator
"-m magicsub " substitute magic value
"-h name val " add header comment 'name = val'
"-b BSCALE BZERO " add scaling header informationDESCRIPTION
"ic" does arithmetic on one or more images according to the reverse-polish notation expression 'rpnexpr'. Images are referred to in rpnexpr as '%1', '%2'.... and must all have the same size. If the fitsfilename is given as '-' then that file will be read from stdin. If fitsfilename is given as 'command |' then we read from a pipe executing that command.
'ic' operates on images a line at a time, and so can be used on very large images. A reference to an input image such as '%1' causes a line of that image to be pushed onto a stack. Single argument math functions operate on the line at the top of the stack and multi-argument functions pop lines as necessary and then push the resultant line. If any of the input images is flagged as MAGIC (as defined 'fits.h') then the result will be MAGIC also (though with '-m' option 'ic' will output 'magicsub' in place of the usual SHRT_MIN) Fits header comments are inherited from the first image - other comments are discarded. You may add extra comments with the -h option; see below. The functions supported include all of the standard C math library (including bessel functions j0(x), j1(x), jn(n,x), y0(x), y1(x), yn(n,x)) plus the operators '+', '-', '*', '/', and 'mult' is provided as a synonym for '*' to avoid potential problems if you invoke ic from a script. There are the logical operations '>', '<', '>=', '<=', '!=', '==' and the negation operator '!'. There is a random number generator 'rand' which generates a uniform random number on the range 0.0-1.0 and 'grand' which generates a zero-mean, unit variance normal variate. There are two functions 'xp', 'yp' to get the horixontal and vertical pixel positions respectively, and two further functions 'x', 'y' which return the position in units of the lenght of the side of the image. There is a constant MAGIC (defined in magic.h - and currently set to -32768) which is a flag for bad data. There is a function 'if' (a.k.a. '?') which mimics the C language '(c ? t : f)' which returns 't' or 'f' respectively depending on the truth or falseness of the condition 'c'. The rpn syntax for this expression is 't f c ?' in which '?' pops the condition 'c' followed by 'f' and then 't' and pushes 't' or 'f' as appropriate. The condition 'c' will of course most likely be a compound logical expression. There are functions 'max' and 'min' which pop two values and pushes the maximum or minimum respectively. There is also a function 'enter' which duplicates the top value of the stack, and a function 'swap' which unsurprisingly swaps the top two values on the stack. Use -c option (with no input images) to generate an image from scratch. Use -p option to specify output pixtpye which can be one of" 8 " 1-byte unsigned char
" 16 " 2-byte signed integer
" 32 " 4-byte signed int
"-32 " 4-byte floating point
"-64 " 8-byte floating pointOtherwise the output will have same pixtype as that of the first input image, or, with -c option, will have pixtype -32. Use the -b option to apply scaling of pixel values on output and record the BSCALE, BZERO values in the header. Otherwise the BSCALE, BZERO values (if any) are inherited from the (first) input image. The definition of BSCALE and BZERO is such that the internal values are computed from disk values as: f_internal = BZERO + BSCALE * f_disk Output goes to stdout. The '-h' option can be used to add new header values or to modify existing ones. If an existing name is provided then the existing value will be overwritten with the new value. Otherwise, or if the name is 'HISTORY' or 'COMMENT', the new header line will be appended. The -h option can be given repeatedly to insert a number of comments. EXAMPLES
Subtract b.fits from a.fits:
ic '%1 %2 -' a.fits b.fits Take sqrt of image to be read from stdin; output as float: ic -p -32 '%1 sqrt' - Create a 512 x 512 image with a linear horizontal ramp and multiply by 10: ic -c 512 512 'x 10 *' Replace all pixels in a.fits with value < 10 with MAGIC: ic '%1 MAGIC %1 10 > ?' a.fits Filter to clip image at fmin = 0.25 fmax = 0.75: ic '%1 0.25 max 0.75 min' - AUTHOR
Nick Kaiser - kaiser@hawaii.edu