AIPS HELP file for MCUBE in 31DEC25
As of Mon Dec 9 13:41:57 2024
MCUBE: Task to collect a set of n-dim maps into a (n+1)-dim map
INPUTS
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
HELP SECTION
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'.
MCUBE will comment on the absence of sequence numbers between
INSEQ and IN2SEQ, but will happily do without any missing ones.
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.
EXPLAIN SECTION
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.