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.