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 rectangle (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 extrac-
tion 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 cor-
responding 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 feed-
ing 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 mul-
tiple 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 base-
name.quad.4.fits
The original FITS header of the input FITS file (-i
option) is conserved along, except for the following key-
words: 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 consid-
ered):
> 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.