; 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.