; HOLGR
;---------------------------------------------------------------
;! Read & process holography visibility data to telescope images
;# TASK UV ANALYSIS IMAGING
;-----------------------------------------------------------------------
;;  Copyright (C) 1996
;;  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
;---------------------------------------------------------------
HOLGR     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
HOLGR:  Task to read and process holography visibility data
INFILE
                                   Input data file name.
OUTNAME                            Output image name.
OUTDISK         0.0         9.0    Output disk number.
UVTAPER         0.0                Data tapering: (1) type,
                                   (2) width in cells to 0.5
OPTYPE                             Telescope type: 'PFOC' prime
                                   focus, 'SUBR' subreflector
FACTOR          0.0       100.0    Magnification
APARM                              Operating parameters.
                                    1: Frequency (GHz).
                                    2: Satellite elevation, deg.
                                       Use -1 for sidereal obj.
                                    3: Antenna diameter, m.
                                    4: Subreflector diameter, m.
                                    5: Focal length, m.
                                    6: Offset of the antenna
                                       vertex in x, in metres.
                                    7: As for 6 in y.
                                    8: As for 6 in z.
                                    9: 10000 * Ref ant. +
                                       100 * target ant. + IF#.
                                    10: Stokes (RR=1, LL=2)
                                       (9) and (10) used only
                                       if INFILE is not of form
                                       'AREA:FILE'
BPARM                              Data reduction parameters.
                                    1: Required map size, m.
                                    2: No. of pixels on a side
                                       of the output map (power
                                       of 2, maximum 512).
                                    3: Min. antenna scan angle
                                    4: Max. antenna scan angle
                                       0 => all data used.
                                       <0 => circular maximum.
                                    5: Amplitude scaling factor
                                    6: Fourier transform sign
                                    7: Minimum antenna aperture
                                       < 0 => circular min.
                                    8: Maximum antenna aperture
                                       < 0 => Circular max.
                                       (7,8) used for focus and
                                       pointing calculations.
                                    9: Correction control flags:
                                       read the HELP!
                                    10: >0 => logarithmic ampl.
                                        <0 => linear amplitudes.
CPARM                              Parameters for the gridding
                                   operation (see HELP).
DPARM                              Output maps, >0 => Save this.
                                    1,2: Regridded amplitude and
                                         phase of the observed
                                         antenna beam pattern.
                                      3: Weights used in the
                                         regridding procedure.
                                    4,5: Derived amplitude and
                                         phase of the aperture
                                         voltage distribution.
                                    6,7: Amplitude and phase of
                                         the point-spread func.
                                      8: Focus model corrections.
                                      9: Surface deviation map.
                                     10: Antenna power pattern
                                         (See HELP!)
XPARM                              Additional data reduction
                                   parameters.
                                    1,2: Cross-talk correction.
                                    3-6: Offset beam correction.
                                      7: Amplitude threshold for
                                         phase unwrapping.
----------------------------------------------------------------
HOLGR
Type: Task
Use:  HOLGR processes holography data.  It Fourier transforms
      the complex antenna pattern and to produce the complex
      voltage distribution in the aperture plane of the
      antenna.

      Data defining the amplitude and phase of the antenna
      pattern is obtained from a file.  The input data consists
      of four free format ASCII encoded values per record:
         1) Azimuth offset from source (degrees)
         2) Elevation offset from source (degrees)
         3) Amplitude (Volts or dB)
         4) Phase (degrees)

      HOLGR can compute and apply a variety of corrections to
      the data:
         1) The offset of the antenna vertex from the
            intersection of the azimuth and elevation axes.
            Such an offset produces a ramp in the antenna
            pattern phase.
         2) A pointing offset.  This produces a ramp in the
            aperture voltage distribution function.
         3) The offset of the antenna feed.  This produces a
            characteristic signature in the aperture voltage
            distribution function.

      Computation of the above corrections is predicated on
      reliable phase unwrapping; that is removing phase jumps
      of 360 degrees from the antenna pattern phase (for 1),
      or aperture voltage distribution function (for 2 and 3).
      HOLGR can reliably remove closed areas of phase
      discontinuities but does not attempt to resolve unclosed
      areas (see EXPLAIN).

      HOLGR provides a choice of Fourier transforms, either DFT
      (direct) or FFT (fast).  For the FFT, the antenna pattern
      data may be interpolated onto a regular grid using a
      variety of interpolation functions specified in CPARM.

      Up to ten different AIPS image files will be produced
      according to the options specified in DPARM.

      In the following description, (x,y) are distances in the
      antenna aperture plane and (l,m) are the corresponding
      direction cosines.  Do "EXPLAIN HOLGR" for a fuller
      description of the coordinate systems used.

Adverbs:
  INFILE......Input visibility file name in the form AREA:FILE,
              where AREA is a directory logical name or
              environment variable, and FILE is an operating
              system specific file name.  If INFILE = 'ANT' or
              is blank, then INFILE will be set to
                          'FITS:HOLOnn-mmssii'
              where nn is the moving antenna number and mm
              is the reference antenna number (= 0 if more than
              one reference antenna is used), ss is
              the Stokes, and ii is the IF.  If INFILE contains
              only a logical name, as INFILE = 'AREA:', then
              'AREA:HOLOnn-mmssii' will be used. The values of
              nn, mm, ss, and ii come from APARMs (9) and (10).
  OUTNAME.....Output image name (12 characters).  If the last 7
              characters are blank, they are set to 'nn-mmss'.
  OUTDISK.....Output disk number.
  UVTAPER.....Tapering of data during the gridding process:
              (1) Type: 1 Gaussian, 2 Exponential, 3 Linear
              (2) Radius in cells for taper of 0.5.  0 => N/3.
              (Remember that the max radius of the data must be
              < N/2 just to avoid aliasing.)
  OPTYPE......The model used for removing the effects of
              primary focus offset.  'PFOC' = Prime Focus.
              'SUBR' = Cassegrain system.
  FACTOR......The magnification.  Used only if OPTYPE = 'SUBR'

Operating parameters: all are required (NO defaults).
  APARM(1)....Observing frequency (GHz).
  APARM(2)....Satellite elevation, degrees. Set = -1. for
              VLA data (true l,m); set = +1. for sky az,el;
              set = actual elevation for true az,el
  APARM(3)....Antenna diameter, in metres.  Used only for
              blanking the phase map and computing the gain.
  APARM(4)....Subreflector diameter, in metres.  Used only for
              blanking the phase map and computing the gain.
  APARM(5)....Focal length, in metres.  This is used in
              correcting for the focus and feed offset, and in
              computing the surface deviation map.
  APARM(6-8)..Offset of the antenna vertex in (x,y,z) from the
              intersection of the azimuth and elevation axes, in
              metres.
  APARM(9)....10000 * Reference antenna number + 100 * 2nd
              (moving) antenna number + IF number.  Used only
              for default names (i.e., if INFILE = 'AREA:')
  APARM(10)...Stokes ID (1 - 4 => RR, LL, RL, LR).  Used only
              for default names (i.e., if INFILE = 'AREA:')

Data reduction control parameters.
  BPARM(1)....Required map size, in metres.
  BPARM(2)....Number of pixels on a side of the output map
              (power of 2, maximum 512).
  BPARM(3,4)..Range of |l| and |m| to use for transform.
  BPARM(5)....Scaling factor for the input amplitudes.
  BPARM(6)....Fourier transform control.  If negative, the phase
              read from the data file is negated.  If the
              absolute value is 2, a direct Fourier transform
              will be done, otherwise, an FFT.
  BPARM(7,8)..Range of |x| and |y| used in correcting for
              pointing, focus, and feed offset.  Negative values
              denote a range of SQRT(x*x + y*y).  See also
              BPARM(9).
  BPARM(9)....Decimal encoded control parameters
                  1: Inhibit the "phase closure" part of the
                     phase unwrapping of the antenna pattern
                     (A_PHA) map.
                  2: Inhibit all phase unwrapping of A_PHA.
                 10: inhibit determination of a phase ramp in
                     the l-m data and use APARM(6,7,8) instead,
                100: Inhibit the "phase closure" part of the
                     phase unwrapping of the antenna aperture
                     (V_PHA) map.
                200: Inhibit all phase unwrapping of V_PHA.
               1000: inhibit correction for pointing, focus, and
                     feed offset.
               2000: inhibit focus and feed offset (but solve for
                     pointing).
               4000: Disable the zero phase offset term.
  BPARM(10)...Switch for logarithmic or linear data
              >= 0 for logarithmic data (as for PKS)
              < 0  for linear data (for the VLA).

Regridding parameters.
  CPARM(1)....Type of interpolation to apply in gridding 'l'.
                1: Pillbox, (don't use for regularly sampled data)
                2: Exponential,
                3: Sinc,
                4: Sinc*Exponential,
                5: Spheroidal (default).

                   NEGATE to obtain natural weighting.
                   (default = uniform)

  CPARM(2)....Support radius in l, in cells.
  CPARM(3-5)..Parameters defining the interpolation function
              in 'l'. Do HELP UVnTYPE for n=1,2,3,4,5.
  CPARM(6-10).Corresponding parameters for 'm'.

Output option flags.
  The particular map will be stored if the associated DPARM is
  greater than zero.  If all are <= 0, DPARM(4,5) will both be
  set to 1.
  DPARM(1,2)..Regridded amplitude and phase of the observed
              antenna beam voltage pattern (A_AMP, A_PHA).
  DPARM(3)....Weights used in the regridding procedure (WGT) -
              includes the weights for uniform (vs natural)
              weighting.
  DPARM(4,5)..Derived amplitude and phase of the aperture
              voltage distribution, (V_AMP, V_PHA). The focus
              model, if requested, will be removed from the
              phase image.
  DPARM(6,7)..Amplitude and phase of the point-spread function.
              This indicates the blurring in the derived
              aperture voltage map (P_AMP, P_PHA).
  DPARM(8)....Map of the phase corrections removed by the focus
              model (MODEL).
  DPARM(9)....Map of the surface deviations of the antenna
              (V_DEV). Units are in metres. The focus offset
              model, if requested, will be removed.
  DPARM(10)...The interpolated antenna power pattern (A_PWR).
              Set it = to the desired interpolation factor, with
              anything >0 and < 2 => 2.  Must be a power of 2 <=
              2048 / NPIX, where NPIX = BPARM(2).

Additional data reduction parameters.
  XPARM(1,2)..Cross-talk correction; a constant offset may arise
              in the observed antenna beam voltage pattern due
              to cross-talk between the signals from the
              reference and target antennas.  This produces a
              spike of the specified amplitude and phase at the
              centre of the aperture voltage distribution map.
  XPARM(3-6)..Offset beam correction; large maps may sometimes
              encompass a nearby satellite which appears as an
              offset beam in the A_AMP map.  This may be removed
              during data gridding by specifying the azimuth and
              elevation offsets (deg), and the amplitude factor
              and phase offset (deg).  Uniform weighting must be
              used.
  XPARM(7)....Amplitude threshhold for unwrapping the V_PHA map.
              Pixels in the V_PHA map with corresponding
              amplitude in the V_AMP map below this threshhold
              will be treated as being blank for the purpose of
              phase unwrapping only.
----------------------------------------------------------------
HOLGR:   Process antenna holography data.
Author:  Mark Calabretta
Related tasks: HOLSR

Coordinate systems:

   Antenna aperture coordinates are described by a right-handed
   system, (x,y,z), centred on the point of intersection of the
   azimuth and elevation axes.  The xy-plane is parallel to the
   aperture plane; the x-axis is parallel to the elevation axis
   and increases to the right as the dish is seen from above.
   The y-axis increases towards the top of the dish; the z-axis
   points skyward more-or-less along the optical axis.

   (l,m,n) are the direction cosines which correspond to the
   (x,y,z) coordinates.  Note that the (l,m) plane is projected
   onto the sky with the l-axis in the direction of decreasing
   azimuth and the n-axis towards increasing elevation.  It is
   therefore left-handed as seen from the earth.

   The azimuth and elevation offsets in the data file refer to
   the position of the telescope beam on the sky.

   A POSITIVE azimuth offset samples a point in the antenna
   pattern at a NEGATIVE azimuth offset and this corresponds
   to a POSITIVE value of l.

   A POSITIVE elevation offset samples a point in the antenna
   pattern at a NEGATIVE elevation offset and this corresponds
   to a NEGATIVE value of m.

   If the satellite is at (Az0,El0) and the antenna is pointing
   at (Az,El) the (l,m,n) coordinates are

      l =  sin(Az-Az0)*cos(El0)
      m = -cos(Az-Az0)*cos(El0)*sin(El) + sin(El0)*cos(El)
      n =  cos(Az-Az0)*cos(El0)*cos(El) + sin(El0)*sin(El)

Phase unwrapping:

   The algorithm used for phase unwrapping is based on an
   equivalence operator defined such that two pixels are
   equivalent iff there is a path between them which does not
   cross a discontinuity.  The path is restricted to horizontal
   and vertical steps between neighbouring pixels.  A
   discontinuity is defined as a phase step of greater than
   180 degrees.

   This equivalence operator partitions the phase map into a
   number of equivalence classes referred to as "patches".
   Adjacent patches can be made equal to each other via the
   addition or subtraction of an integral multiple 360 degrees.

   While the algorithm is reliable it does not attempt to
   resolve open-ended discontinuities.  The extent to which
   phase unwrapping succeeds can be judged by the "phase
   unwrapping index" reported before and after HOLGR attempts to
   unwrap a phase map.  This consists of a simple count of the
   total number discontinuous boundaries between neighbouring
   pixels.

   In the "phase closure" part of the unwrapping algorithm these
   open-ended discontinuities are reduced to the shortest path
   connecting the end-points.
----------------------------------------------------------------
