; MCUBE
;---------------------------------------------------------------
;! collects n-dimensional images into n+1-dimensional image
;# TASK ANALYSIS SPECTRAL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1997-1999, 2003, 2005, 2009-2010
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
MCUBE     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
MCUBE:  Task to collect a set of n-dim maps into a (n+1)-dim map
INNAME                             Input name(name).
INCLASS                            Input name(class).
INSEQ           0.0      9999.0    Input name(seq. #). 0=>high
                                   First sequence # in the set
INDISK          0.0         9.0    Input disk drive #. 0=>any
IN2SEQ          0.0      9999.0    Last sequence # in set.
IN3SEQ                             Sequence # increment.
OUTNAME                            Output name(name).
OUTCLASS                           Output name(class).
OUTSEQ         -1.0      9999.0    Output name(seq. #).
                                     0 => highest unique
OUTDISK         0.0         9.0    Output image disk drive #
                                     0 => highest with space
DOALIGN        -2.0         1.0    Alignment control parm
AXREF           0.0     16384.0    n+1 axis pixel of map INSEQ.
                                   0 => 1
AX2REF          0.0     16384.0    n+1 axis pixel of map IN2SEQ
                                   0 => opposite end from INSEQ
NPOINTS         2.0     32768.0    Number of pixels on axis n+1
DOCONCAT       -1.0         2.0    > 1 => make a SEQ.NUM or
                                   FQID axis no matter what
----------------------------------------------------------------
MCUBE
Type: Task
Use:  MCUBE will take a set of maps with n actual (more than 1 pixel
      deep) dimensions and convert them into an image of n+1 actual
      dimensions.  It can also expand the n'th dimension, making the
      cube longer on its "cube" axis.  If the output image specified
      already exists, then the input maps are inserted in the output
      image in the appropriate places.  This allows the n+1-dim image to
      be built up a bit at a time and allows replacement with corrected
      n-dim or n+1-dim images.  If the output map already exists, then
      AXREF, AX2REF, and NPOINTS are ignored.  MCUBE does not handle
      BLC and TRC except to do image alignments internally when
      DOALIGN > -2.  MCUBE supports TELL but only with OPTELL
      'ABOR','QUIT'.

      Sometimes it is useful to combine dissimilar images or ones with
      parameters that do not lie on a regular axis (e.g. ones at
      frequencies that are widely and randomly separated) into a
      cube.  The DOCONCAT adverb allows you to override MCUBE's
      coordinate logic and force the creation of a SEQ.NUM or FQID
      output axis.  The FQID axis will replace FREQuency axes,
      SEQ.NUM. will replace all others.

      Task FQUBE is now available to perform combinations of images,
      building an FQID axis from input FREQ and FQID axes.  This may
      be easier to use when building cubes that have frequencies that
      do not fall on a regular grid.  Task SPIXR will analyze such
      cubes to fit images of spectral-index.  A task to do
      "rotation-measure" synthesis is under development and requires
      such cubes as input.
Adverbs:
  INNAME......Input name of images(name).   Standard defaults.
              Must be the same for all input images.
  INCLASS.....Input name of images(class).  Standard defaults.
              Must be the same for all input images.
  INSEQ.......First seq no. of the images.  0 => highest.
  INDISK......Disk drive # of images.       0 => any.
              May vary between images if INDISK is set to 0.
  IN2SEQ......Last sequence # in set of input images.  If the output
              image exists, there is no default.  If output is new, 0 =>
              INSEQ + (NPOINTS-1) * IN3SEQ.
  IN3SEQ......Sequence # increment.  0 => 1.
              Thus, MCUBE uses sequence numbers INSEQ to IN2SEQ by
              IN3SEQ in the usual loop sense.
  OUTNAME.....Output name of image(name).   Standard defaults.
  OUTCLASS....Output name of image(class).  Standard defaults.
  OUTSEQ......Output name of image(seq. #). 0 => highest unique.
  OUTDISK.....Disk drive # of output image. 0 => highest with space.
  DOALIGN.....Controls how the images are to be aligned on axes 1 - n-1
              (see HELP DOALIGN).  True (>.1) means that the images must
              agree in their coordinates, though not necessarily in the
              reference pixel position.  Alignment is by coordinate
              values (if DOALIGN > -0.1) or by offsets from the
              reference pixel positions (if DOALIGN <= -0.1).  NOTE: all
              real axes (>1 point) are aligned.  DOALIGN = -2 means to
              ignore the headers totally and align at (1,1).
              The DOALIGN adverb only controls how images are lined up
              using their current pixel values.  They are not
              regridded.  OHGEO or HGEOM must be used if there are
              different celestial coordinate reference values since
              the geometries are fundamentally different.
  AXREF.......The pixel position of map INSEQ on axis n+1. 0 = 1
  AX2REF......The pixel position of map IN2SEQ on axis n+1. 0 => NPOINTS
  NPOINTS.....The number of pixels on axis n+1.
  DOCONCAT....> 1 => force MCUBE to make a SEQ.NUM or FQID axis even
              if there are other axes that differ.  NOte the > 1 usage
              so that other uses of DOCONCAT do not force this option.

The following is a bit simplistic, but is helpful for building
spectral cubes:

    1. NPOINTS defines the number of planes in the cube.
    2. The interval between planes is given by: frequency of map
       (IN2SEQ) - frequency of (INSEQ) divided by (AX2REF - AXREF).
    3. The reference pixel on the frequency axis should be one.
    4. The maps can be loaded in any order (ascending or descending
       frequency), and not all intermediate planes need be filled,
       i.e. all is set by the first and last maps.
    5. If AX2REF is not specified, then NPOINTS is used.
    6. If you are assembling a cube from mini-cubes (e.g., 8-plane
       cubes), then AX2REF must specify the plane to be occupied by
       the FIRST plane of the LAST mini-cube.
----------------------------------------------------------------
MCUBE:  Task which constructs an n+1 dim R*4 map from a set of
        n-dimensional maps.  Can also build an n-dim map from a set of
        n-dim maps or expand the last real dimension of a single
        n-dimensional map.
RELATED PROGRAMS: TRANS, AXDEF, CNVRT, OHGEO, HGEOM

               PURPOSE

     MCUBE combines a set of n-dimensional maps into one n or n+1
dimensional map. This is especially useful for spectral-line
observations.  A set of maps at different frequencies can be put into
one 3 dimensional image with frequency as the third axis or one or more
3-dimensional images may be built into one larger 3-dimensional image.
In this way the number of catalog entries can be reduced considerably
and operations that have to be done on all maps can be done with one
command without having to tie up a terminal.  The axes of the cube can
be interchanged and or reversed with TRANS.  Several spectral line
programs require as input a cube, e.g. TVMOVIE, BLANK, XGAUS and MOMNT.
     The cube can be built up a bit at the time and maps in the cube can
also be replaced.  However the first time MCUBE is run the dimensions
are fixed with NPOINTS and the input image size and these can be
increased later only by creating a new, larger cube.  The axis increment
on the n+1 axis is determined by taking

       [AXVAL(IN2SEQ) - AXVAL(INSEQ)] / (AX2REF - AXREF)

For each input n-dim map, MCUBE checks that the coordinate value on the
n+1 axis corresponds fairly closely with some pixel on that axis in the
output image.  If it does not MCUBE does not write that image into the
output cube.  Headers can be corrected with AXDEF, the AXVALs need be
regularly spaced and AXINC should be equal to the spacing. The output of
MCUBE is real and can be converted to integer with CNVRT.

              COMMENTS

INSEQ,IN2SEQ  The maps are put into the cube as a set.  These are the
              first and the last sequence number in the set.  One can do
              every INSEQ3'rd sequence number if needed.
AXREF,AX2REF  These state where to put the first and last map of the set
              into the cube. The increment in the cube need not be the
              same as in the set.  E.g., if one has made a series of R
              and L maps, one can by taking AX2REF=2*IN2SEQ -1 and
              AXREF=INSEQ first put in all the Rmaps and then later add
              all the Lmaps.
NPOINTS       The number of points of the n+1 axis. It should be equal
              to the total number of maps that you eventually want to
              put into the cube.

              HINTS

1. MCUBE is a very general program which tries to build n or n+1
   dimensional images from a set of n dimensional images using solely
   the information in the image headers.  Thus, this information needs
   to be correct and relatively accurate.
2. The output axis increment is determined from the axis values of the
   INSEQ and IN2SEQ maps.  For greatest accuracy, these should be chosen
   to be at opposite ends of the output axis.
3. If the two reference images have identical headers, then MCUBE will
   create an axis called "SEQ.NUM." and use the map sequence number as
   the axis value.
4. The input images may already be cubes on the desired axis if that
   axis is the highest numbered "real" (> 1 point) axis. (Use TRANS if
   it is not.)  In this case, you may even build, from a single input
   cube (i.e. INSEQ = IN2SEQ), a cube having an axis increment equal to
   that in the input header and having NPOINTS on the relevant axis.
   Images having n+1 and n dimensions may also be mixed, but INSEQ
   should then point to an n+1 dimension image.  NOTE: when building n+1
   dimensional images from n+1 dimensional images, the output axis may
   have an increment of 1/m (m an integer) of the input and AXREF and
   AX2REF refer to the pixel position of the first n-dimensional "plane"
   in INSEQ and IN2SEQ, respectively.
5. MCUBE reports where it puts each n-dimensional "plane" in the n+1
   dimensional "cube."  When building a new cube, it also fills each
   unused plane with blanks and reports these.  Watch these outputs
   carefully to make sure that MCUBE has done what you expected.
