NAME extract - extract data from a cube SYNOPSIS extract -i infile [-o outfile] [mode] extract --in infile [--out outfile] [mode] DESCRIPTION extract is used to extract data from a cube. Several modes of extraction are implemented : plane extraction, cube extraction (continuously from one plane to another), pattern extraction, quadrant extraction, list of planes, and rectan- gle (slit) extraction. Details are given below on modes and syntax. COMMAND LINE extract receives always at least one option: the input file name, provided by -i or --in. Providing the output file name by -o or --out is not mandatory and sometimes not possible. Defaults for output names depend on the extraction mode. EXTRACTION MODES -m plane -b num -e num extracts planes to single files. Plane numbers go from 1 to the number of planes in the cube (NAXIS3). Default value for beginning plane is 1, default value for end plane is NAXIS3. To extract one plane only, give the same number for begin and end. -m cube -b num -e num extracts a cube from another, edge planes are included. Default value for begin plane is 1, default value for end plane is NAXIS3. -m quad -x 1234 extracts quadrants from a cube. Quadrants to extract shall be requested by a character string containing the quadrant numbers. Quadrants are named according to the following convention: 1 2 4 3 -m pattern -x 01101001... -s step extracts planes in a cube according to a pattern. A pattern is a character string containing only 0 and 1's, planes identified with a 1 are extracted, those with a 0 are not. The pattern is periodically repeated. The step option identifies how many planes are taken into account per cycle step. e.g. an extraction pattern of 01, with a step parameter of 5 would yield an actual extraction pattern of 0000011111. This parameter defaults to 1 plane per cycle step. -m list -f file This option uses a list of plane numbers given into a text file. It extracts the requested planes to one cube. It is mainly intended to be used with stcube which would first extract all statistical information from a cube, then use a selector program to extract plane numbers correspond- ing to planes which have interesting statistical values, and then extract only these planes to a cube. -m rect -x 'LLX LLY URX URY' This option extracts a rectangular area over the whole cube. Input option defines the area by feeding in the lower left corner and upper right corner coordinates. The rectangle itself limiting the area is included in the extracted part. Do not forget to input them within simple quotes! The coordinate system is given according to the FITS reference: First pixel in image is in lower left corner, and has coor- dinates (1,1). Last pixel in image is in upper right corner of the image and has coordinates (NAXIS1, NAXIS2). LLX and LLY are the coordinates of lower left corner. URX and URY are the coordinates of upper right corner. LONG OPTIONS Here are long option equivalents for all command-line switches: General options: -i = --in -o = --out Mode names: -m plane = --plane -m cube = --cube -m quad = --quadrant -m pattern = --pattern -m list = --list -m rect = --rectangle Mode options: -b = --begin -e = --end -x = --ext -f = --name FILES Input files shall all comply with FITS format Output files have the same pixel type as input files. NAMING SCHEMES In single file output, default name is 'out.fits'. In multi- ple file output, default names depend on the extraction mode: in plane mode : basename.0001.fits to basename.9999.fits in quadrant mode : basename.quad.1.fits to basename.quad.4.fits The original FITS header of the input FITS file (-i option) is conserved along, except for the following keywords: NAXIS, NAXISn, BITPIX, BSCALE, BZERO, which are related to the newly created file. HISTORY keywords are appended to the FITS header to indicate the eclipse process modifications. EXAMPLES To extract plane 53 out of cube 'incube.fits' (output name is optional, default would be incube.0053.fits): > extract -m plane -i incube.fits -b 53 -e 53 -o p53.fits To extract all planes of file 'incube.fits' to different FITS files (multiple file output, output name option is not considered): > extract -m plane -i incube.fits would generate files names such as incube.0001.fits and so on, to last plane number. To extract all planes from plane 10 to last one in 'incube.fits', into a single cube named 'truncated.fits': > extract -m cube -i incube.fits -b 10 -o truncated.fits To extract only quadrants 2 and 4 from 'incube.fits': (mul- tiple file output, output name option is not considered): > extract -m quad -x 24 -i incube.fits Output files are named 'incube.quad.2.fits' and 'incube.quad.4.fits'. To extract only even planes from 'incube.fits' to 'even.fits': > extract -m pattern -x '01' -i incube.fits -o even.fits To extract planes 2, 3, 5, 7 and 11 in cube incube.fits to one cube named partial.fits, create a file named listp for example, and type in the plane numbers: ---- beginning of file 'listp' ---- 2 3 5 7 ---- end of file 'listp' ----- The command is then: > extract -m list -f listp -i incube.fits -o partial.fits To extract both lower quadrants in a 256x256 image named in.fits, into an image named lower.fits: > extract -m rect -x '1 1 256 128' -i in.fits -o lower.fits The following commands are equivalent: > extract -m pattern -x '0000011111' -i infile.fits -o out.fits > extract -m pattern -x '01' -s 5 -i infile.fits -o out.fits SEE ALSO catcube, stcube BUGS Misuse of command line switches may result in undefined behaviour.