; AXDEFINE
;---------------------------------------------------------------
;! Define or modify an image axis description
;# Verb Catalog
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1998, 2009
;;  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
;-----------------------------------------------------------------------
AXDEFINE  LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
AXDEFINE:  Verb to modify image axis description and values
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK          0.0         9.0    Disk drive #. 0=>any
NAXIS           0.0         7.0    Axis # to modify <= ndim+1
                                     0 => ndim + 1
AXTYPE                             New axis type
AXINC                              Axis increment 0 => no change
AXVAL                              Axis value at ref. pixel =
                                   AXVAL(1) + AXVAL(2).
AXREF                              Reference pixel location
----------------------------------------------------------------
AXDEFINE
Type: Verb
Use:  AXDEFINE is used to add or alter axis descriptions in the
      catalogue map header.  The last 1-point axis may also be
      removed from the header.
Adverbs:
  INNAME......Image name(name).       Standard defaults.
  INCLASS.....Image name(class).      Standard defaults.
  INSEQ.......Image name(seq. #).     0 => highest.
  INDISK......Disk drive # of image.  0 => any
  NAXIS.......Number of the axis to be modified.  If ndim+1,
              add a new 1-point axis as axis ndim+1. Otherwise,
              modify an existing axis.  0 => ndim+1.
  AXTYPE......Axis type (8 chars left justified). No default.
              Examples: 'VELO', 'FREQ', 'LAMBDA', 'TIME'
              To remove the last axis, set AXTYPE = ' ' and
              NAXIS to ndim.  Only works if there is 1 point
              on that axis.
  AXINC.......Axis increment to set. 0 => no change.
              Units are those of AXVAL.
  AXVAL.......Axis coordinate value at reference pixel. Value is
              AXVAL(1) + AXVAL(2) in double precision.  No
              default.  Units are mks, degrees, Jy.
              Note: velocities are meters/sec, therefore.
  AXREF.......Reference pixel location. No default.
----------------------------------------------------------------
AXDEFINE:  Verb to modify image axis description and values
DOCUMENTOR:  R. L. Brown  NRAO/CV
RELATED PROGRAMS:  IMHEADER, MCUBE, AXTDEF, ALTSWTCH

                         PURPOSE

     AXDEFINE is a general purpose utility program that allows
one to define or re-define the description (or label) of an
image axis.  Here it is important to note that AXDEFINE is
used to label an image axis; it does not in any way alter the
values which comprise the image.  The following are three
common uses of AXDEFINE.
   (1)  Suppose we mapped a galactic object and, in UVMAP, we
rotated the map so as to present the object in galactic coor-
dinates.  We use AXDEFINE to label the map ordinate and abscissa
as galactic longitude and latitude respectively.  The appro-
priate values for the new axes are entered through the para-
meters AXREF, AXVAL and AXINC.
   (2)  We are trying to build a spectral line data cube but
MCUBE complains that frequency does not increment properly
along what we wish to be the third axis of the cube.  Use
AXDEFINE to define the proper third-axis coordinate value for
each image to be used in the cube.
   (3)  We have now constructed a spectral line data cube and
we want to express the third axis coordinate as velocity not
frequency. Use AXDEFINE to label the third coordinate as
desired.
     IMHEADER may be used at any time to examine the header
information and axes descriptions associated with a particular
image.

                         COMMENTS

NAXIS:
     The image abscissa is referred to as axis number 1 and
the ordinate is axis number 2.  Use IMHEADER when in doubt.
The default value of NAXIS is to add a new axis with one
point (the present image) on that axis.

AXTYPE:
     New axis label (8 characters, left-justified).  Only
certain keywords are acceptable here because the program uses
these words to associate physical units appropriate for that
axis (e.g. one expresses 'DEC' in degrees not in, say,
Janskys).  Among the labels recognized in this sense are:

         RA. . . . .Any epoch you desire
         DEC. . . . Any epoch you desire
         GLON. . . .To designate galactic longitude
         GLAT. . . .To designate galactic latitude
         ELON. . . .Ecliptic longitude
         ELAT. . . .Ecliptic latitude
         LAMBDA. . .Wavelength (units are METERS!)
         FREQ. . . .Frequency (in Hz)
         VELO. . . .Velocity (note: in METERS/sec!!)
         FELO. . . .Velocity, optical convention
                              (units:  METERS/sec!!)
         DATE. . . .Julian date
         TIME. . . .Time (units are seconds)
         blank . . .Remove last axis.  Only work if there is
                    one point on this axis.

This list is amended periodically.  Check with your system
manager and/or GRIPE.

AXINC:
     The axis increment between successive points along the
axis specified by NAXIS.  The units are the same as those
specified by AXTYPE.  The increment, AXINC, may be positive
or negative.

AXVAL:
     With this parameter one specifies the value of the new
axis description at a single point along the axis.  That
point one must, of course, also specify; this is done with
AXREF.  AXVAL is expressed as AXVAL(1)+AXVAL(2) so that one
can enter a value with enough significant figures when
necessary (especially when specifying frequency, e.g.
AXVAL=1420.40E6, 5.75178E3).

AXREF:
     Any point along the axis to be relabeled.  At this point
the new axis will be given the value AXVAL.  AXREF wants a
single number--you're specifying a point along a coordinate
axis not a pixel location on a multi-dimensional image.
