; FLATN
;---------------------------------------------------------------
;! Re-grid multiple fields into one image
;# Task IMAGING OOP
;-----------------------------------------------------------------------
;;  Copyright (C) 1997-2003
;;  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
;-----------------------------------------------------------------------
FLATN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FLATN: Re-grid multiple fields and pointings to one image
                                   Input images
INNAME                                Image name (name)
INCLASS                               Image name (class)
INSEQ              0.0      9999.0    Image name (seq. #)
INDISK             0.0         9.0    Image disk drive #
NFIELD             1.0      4096.0 Max number of fields per
                                      pointing
NMAPS              1.0             Number of pointings
                                   Output image
OUTNAME                               Image name (name)
OUTCLASS                              Image name (class)
OUTSEQ            -1.0      9999.0    Image name (seq. #)
OUTDISK            0.0         9.0    Image disk drive #
IMSIZE          0.0      8192.0    Output image size in pixels
COORDINA                           Central pixel coordinate
                                   all 0 => use observed
REWEIGHT        0.0         4.0    (1) Interpolation halfwidth
                                   (2) Minimum fraction of good
                                       pixels required (0->1/3)
DOWEIGHT        0.0                Weight image down by DOWEIGHT
                                   time radius from center
EDGSKP          0.0                Skip pixels around the edges
APARM                              (1) >0 => do 3-D corr.
                                      ONLY for snapshots
                                   (2) Parallactic angle (deg)
                                   (3) Zenith angle (deg)
                                   (4-8) radial scaling parms
                                   (9) Linear scaling
PBPARM                             Beam parameters:
                                   (1) Cutoff; (2) Use (3)-(7)
                                   (3)-(7) Beam shape
NOISE            0.0               Relative uncertainties by
                                   pointing
BADDISK          0.         36.    Disks to avoid for scratch
----------------------------------------------------------------
FLATN
Type: Task
Use: FLATN does an interpolation of a set of images (multiple fields
     produced by IMAGR of multiple pointings) to a single image of
     standard geometry centered on the pointing position of the first
     pointing or a user-specified position.

     Interpolation is done only in the first 2 dimensions.  FLATN will
     interpolate over blanked pixels so that it can fill in small
     blanked regions and handle edges without having to discard image
     area.  Where images overlap, they are averaged with weighting
     that accounts for the location within the pointing and for the
     distance from the center of each field.  If NMAPS > 1, the output
     image is corrected for the single-dish beam patterns.

     FLATN will search fields nnn through nnn+NFIELD-1 for sequence
     numbers INSEQ through INSEQ+NMAPS-1 where INCLAS=xxxnnn with nnn
     being a 3 digit number (no blanks - typically 001).
Adverbs:
  INNAME......The input image name.   Standard defaults.
  INCLASS.....The input image class.  The first 2-3 characters determine
              a base name and the last 4-3 are a numeric field number
              nnn (i.e. ICL001 or IIM012 or IC3245).  Class names for
              higher fields are nnn through nnn+NFIELD-1.  Old style
              names in which the last 2 characters represent the field
              number minus one in extended Hex are also supported.
  INSEQ.......The input image sequence number. 0 => high
  INDISK......The input image disk drive no. 0 => any
  NFIELD......The maximum number of fields imaged (1-4096) for any
              pointing.
  NMAPS.......The number of pointings - using INSEQ numbers INSEQ
              through INSEQ+NMAPS-1.  If NMAPS > 1, the output image
              will be corrected for a primary beam pattern.
              The product of NFIELD * NMAP is limited to 1048576.
  OUTNAME.....The output image name.  blank => Standard defaults based
              on INNAME.
  OUTCLASS....The output image class.  Standard behavior.
  OUTSEQ......The output image seq. no., 0=> highest unique
              If >0; image will be created if new, overwritten if image
              name exists.
  OUTDISK.....Output disk drive no., 0=> highest with space
  IMSIZE......Output image size in pixels [1=columns, 2=rows].  Default
              is the input image size but you should probably use
              something much larger.  (<= 8192)
  COORDINA....The RA and declination coordinates are found as:
              RA  = abs(CO(1)) + abs(CO(2))/60 + abs(CO(3))/3600
                  if any of CO(1), CO(2), CO(3) < 0: Xpos = -Xpos
              Dec = abs(CO(4)) + abs(CO(5))/60 + abs(CO(6))/3600
                  if any of CO(4), CO(5), CO(6) < 0: Ypos = -Ypos
              The units are standard FITS units (e.g degrees) except
              that right ascensions are in hours of time.
              RA = Dec = 0 => use the Observed RA and Dec (pointing
              position) or if they is 0, use the center of field 1.
  REWEIGHT....Interpolation kernel parameters:
              (1) Half width of the interpolating kernel
                  (1 - 4).  Default = 1
              (2) Minimum fraction of pixels in interpolation kernal
                  area required for non-blanked output.
                  <= 0 or >= 1  => 0.333
  DOWEIGHT....If >0, reduce the weight in each image by DOWEIGHT *
              Radius in arc seconds from the center pixel.  This is to
              give less weight to pixels more affected by non-planar
              affects.  Thus Wt = max (0.0001, 1.0 - DOWEIGHT*radius).
  EDGSKP......Omit EDGSKP pixels on all sides of the input images.  This
              is to avoid various edge effects from damaging the result.
  APARM.......Transformation parameters:
               (1) = if > 0 then apply 3-D corrections
                     SEE EXPLAIN OHGEO or FLATN
                   This really works well only for snapshots and for
                   fields that are not too far from the pointing
                   position.
               (2) Parallactic angle for 3-D correction if not
                   already a header keyword. (degrees)
               (3) Zenith angle for 3-D correction if not
                   already a header keyword. (degrees)
               (4-8) Parameters for radial scaling for primary
                     beam effects.
               (4) = Antenna FWHM at nominal sky frequency (deg)
                   0 => no scaling.
               (5) = Fractional bandwidth
               (6-8) C1, C2, C3
                   SEE EXPLAIN FLATN (or OHGEO)
               (9) Linear scaling factor, 0 => 1.0
                   SEE EXPLAIN FLATN (or OHGEO)
  PBPARM......Primary beam parameters:
              (1) Lowest beam value to believe: 0 -> 0.1
              (2) > 0 => Use beam parameters from PBPARM(3)-PBPARM(7)
              (3-7)..For all wavelengths, the beam is described by the
                function:
                   1.0 + X*PBPARM(3)/(10**3) + X*X*PBPARM(4)/(10**7) +
                   X*X*X*PBPARM(5)/(10**10) + X*X*X*X*PBPARM(6)/(10**13)
                   X*X*X*X*X*PBPARM(7)/(10**16)
                where X is (distance from the pointing position in arc
                minutes times the frequency in GHz)**2.  For the VLA,
                these parms are, by default, given by Perley's fits:
                      0.0738 GHz  -0.897  2.71   -0.242
                      0.3275      -0.935  3.23   -0.378
                      1.465       -1.343  6.579  -1.186
                      4.885       -1.372  6.940  -1.309
                      8.435       -1.306  6.253  -1.100
                     14.965       -1.305  6.155  -1.030
                     22.485       -1.417  7.332  -1.352
                     43.315       -1.321  6.185  -0.983
                For the ATCA, these are by default:
                  1.5 GHz  -1.049   4.238  -0.8473  0.09073  -5.004E-3
                  2.35     -0.9942  3.932  -0.7772  0.08239  -4.429E-3
                  5.5      -1.075   4.651  -1.035   0.12274  -6.125E-3
                  8.6      -0.9778  3.875  -0.8068  0.09414  -5.841E-3
                  20.5     -0.9579  3.228  -0.3807  0.0       0.0
                See explain for details
  NOISE.......Expected image noise per pointing.  0 -> 1; absolute
              scaling is not relevant.  This just scales one pointing
              relative to another.  The average value of NOISE is used
              for all pointings in excess of 64.
  BADDISK.....Disks to avoid for the scratch files.
----------------------------------------------------------------

RICK PERLEY'S REPORT - Primary Beam Parameters

	Polynomial Coefficients from LSq Fit to VLA Primary
	Beam raster scans.

	Functional form fitted:

		1 + G1.X^2 + G2.X^4 + G3.X^6

	where X = r.F,

	and 	r = radius in arcminutes
		F = frequency in GHz.

	Fits were made to 3% cutoff in power for 24 antennas.
Poor fits, and discrepant fits were discarded, and the most
consistent subset of antennas had their fitted coefficients
averaged to produce the following 'best' coefficients.


Freq.		G1		G2		G3
----------------------------------------------------------
0.0738          -0.897E-3       2.71 E-7        -0.242E-10
0.3275          -0.935          3.23            -0.378
1.285           -1.329          6.445           -1.146      *
1.465           -1.343          6.579           -1.186
4.885           -1.372          6.940           -1.309
8.435           -1.306          6.253           -1.100
14.965          -1.305          6.155           -1.030
22.485 (old)    -1.350          6.526           -1.090      *
22.485 (new)    -1.417          7.332           -1.352
43.315          -1.321          6.185           -0.983
-----------------------------------------------------------

	The estimated errors (from the scatter in the fitted
coefficients) are generally very small:

	G1: .003 at all bands except Q (.014)
	G2: .03 to .07 at all bands except Q (.15)
	G3: .01 to .02 at all bands except Q (.04)

	R. Perley  21/Nov/00

* The 1.285 and 22.485 old feed values are not used.

3-D Corrections:

   Corrections can be made for the distortion of an image made by a
coplanar array which is not normal to the field center.  This case
includes snapshots made with the VLA or syntheses made with an
east-west interferometer using u, v and ws in the sine (????-SIN)
projection.  In these cases the array elements are confined to a plane
(or are nearly so) but the normal to this plane is oriented in a
direction other than the center of the image produced.  This will
cause a distortion of the geometry but not of the image.  OHGEO will
correct for this distortion if APARM(1) > 0 and two parameters
("parallactic" angle and "zenith" angle are provided.  These are the
parallactic and zenith angles of the image center.  For east-west
arrays these values are from a "zenith" of the appropriate celestial
pole; for the VLA these are with respect to the instrumental zenith.
   The parallactic and zenith angles can be provided in degrees as
either catalog header keywords 'PARANGLE' and 'ZENANGLE' or as
APARM(2&3) in which case they will be converted into header keywords.
Note: for VLA snapshots task WFCLN and IMAGR can provide the necessary
catalog keywords.
   The 3D correction is based on the distance from the tangent point
which may be the same as the pointing position (DO3DIMAG false) or
different (DO3DIMAG true in IMAGR).  The coordinate reference pixel
must give the tangent point position.  The x and y coordinates must be
RA and Declination or vice versa or this program will not work
properly.
   Note: this correction will not correct for image distortion caused
by a noncoplanar array such as an image made from VLA data consisting
of multiple snapshots or an extended synthesis.

Radial Scaling for Primary Beam Effects.

In synthesis observations the variation of the primary antenna
gain over the observed bandpass can cause the effective
observing frequency to vary radially from the antenna pointing
position.  This will cause a radial variation in apparent image
scale; usually a contraction of the scale with increasing
radius.  A correction can be made for this using parameters
APARM(4-8).
   Note there may also be a constant scale error due to an
incorrect assumed central frequency.  This correction will not
correct for this effect.
   The radial corrections are based on the position offset from the
original pointing center and this information MUST be in the catalog
header.  GETHEAD can obtain these values using keywords 'OBSRA' and
'OBSDEC' to see if non-zero values are present.

APARM(4)
   If APARM(4) is larger than zero the a radial scaling is done.
This value is the antenna primary beam FWHM in degrees at the
nomimal sky frequency.  For the VLA (25 m antenna) this is
7.203E8/Freq (Hz).

APARM(5)
   This value is the fractional bandpass which is the true
bandpass divided by the nominal frequency.

APARM(6-8)
   These coefficients, called C1, C2 and C3, parameterize the
beam shape.  For a Gaussian beam C1 = 2*log(2)/3 = 0.4621, C2=0
and C3=0.  For a uniformly illuminated circular aperture (a good
approximation for the VLA) C1=0.46, C2=0 and C3=0.58 gives a
good approximation out to a distance of FWHM.
NOTE: THIS CORRECTION CAN GIVE VERY VERY WRONG ANSWERS OUTSIDE
OF THE FWHM!!!

Linear scaling:

   An error in the assumed center frequency of data used to make
a synthesis image will cause a misscaling of the image as
discussed in the previous section.  If the assumed bandpass
shape is incorrect there will be a constant scaling error over
the entire image.  This effect can be corrected in a number of
other tasks (UVADC, WFCLN) and if this correction has already
been applied it should NOT be reapplied here.  This factor is
the ratio of the true centroid frequency to the assumed
frequency.
   If APARM(9) is greater than 0 then it is used as an overall
scaling factor which is used in addition to any scaling from
APARM(4-8).
