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 extrac-
tion are implemented : plane extraction, cube extraction (continuously
from one plane to another), pattern extraction, quadrant extraction,
list of planes, and rectangle (slit) extraction.
Details are given below on modes and syntax.
Command Line
extract receives always at least one option: the input file name, pro-
vided 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 begin-
ning 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 parame-
ter 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 corresponding 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 coordinates
(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 multiple 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 con-
served 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’: (multiple 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.