; PATGN
;---------------------------------------------------------------
;! Task to create a user specified test or primary-beam pattern
;# TASK IMAGING
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2000-2005
;;  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
;-----------------------------------------------------------------------
PATGN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
PATGN     Task to create a user specified test pattern.
IMSIZE                             Output image size (cells)
CELLSIZE                           Cellsize arc seconds.
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
OPCODE                             Operation code. ZONE, GAUS,
                                      LRTZ, RADI, POLY
                                      BEAM, ATCA
CPARM                              Function parameters.
PBPARM                             Primary beam parameters
                                   (1) Cutoff; (2) Use (3)-(7)
                                   (3)-(7) Beam shape
----------------------------------------------------------------
PATGN
Task:  Task which creates a user specified test pattern.
Adverbs:
  IMSIZE.....Desired image size in cells.  (default 256)
  CELLSIZE...Desired cell spacing.         (default 1.0)
  OUTNAME....Output image name (name).  Standard behavior with default =
             'PATGN MAP'.
  OUTCLASS...Output image name (class).    Standard defaults.
  OUTSEQ.....Output image name (seq. #).   0 => highest unique.
  OUTDISK....Disk drive # of output image. 0 => highest number with
             sufficient space.
  OPCODE.....User specified operation code:
             'ZONE' => Zone plate test pattern.  This pattern is based
                on a linearly swept FM signal.  The intensity at each
                point is given by:
                          |A*cos (2*PI*FMAX* RADIUS**2 / PERIOD)
                          |           RADIUS <= PERIOD/2
                f(RADIUS)=|
                          |A * cos (2*PI * FMAX * ((PERIOD/2)-
                          | (RADIUS-PERIOD)**2 / PERIOD)
                          | PERIOD/2 <= RADIUS <= 3*PERIOD/2
                 where A = amplitude (max/min intensity), FMAX = maximum
                 frequency (0<=FMAX<=0.5), RADIUS = distance from the
                 center point, PERIOD = number of pixels in the cycle
                 (from zero to FMAX and back to zero) and center =
                 CPARM(1,2), A = CPARM(3), PERIOD = CPARM(4), and FMAX =
                 CPARM(5).  This pattern contains a wide variety of
                 frequency at all possible angles.
             'GAUS' => Gaussian profile.  This pattern is a
                 two-dimensional normal distribution with a specified
                 r.m.s.  The intensity at each point is given by:
                 f(RADIUS) = C(3) + (C(4)-C(3)) *
                             EXP (-((0.707/C(5))**2*RADIUS**2))
                 where c = CPARM and 0.707/C(5) is the height of a
                 normal distribution with r.m.s.= C(5).
             'LRTZ' => Lorentzian profile.  This pattern is similar to
                 the Gaussian distribution.  The intensity at each point
                 is given by:
                 f(RADIUS) = C(3) + (C(4)-C(3)) *
                             (1 / (1 + (RADIUS/C(5))**2))
             'BEAM' => Do an image of the primary beam; by default, the
                 primary beam of the VLA.
             'ATCA' => Do an image of the primary beam; by default, the
                 primary beam of the ATCA.
             'RADI' => Do a polynomial in the radius from the
                 reference pixel
             'POLY' => Do a polynomial in x and y (from the reference
                 pixel)
  CPARM......CPARM(1) and CPARM(2) are the x and y pixel coordinates
             of the function center, resp.  If both are zero, center
             set to (IMSIZE(1) + 1) / 2 and (IMSIZE(2) + 2) / 2.

             If OPCODE is 'ZONE':
                CPARM(3) is the amplitude of the signal (max/min
                   intensity, 0 => 1.0),
                CPARM(4) is the period of the signal in arc seconds
                   (0 => 320*IMSIZE(1)/512 * CELLS(1)),
                CPARM(5) is the maximum frequency of the signal
                   (ABS(CPARM(5)) > 0.5 => CPARM(5)=0.5).

             If OPCODE is 'GAUS' or 'LRTZ':
                CPARM(3) is the lower limit on the output
                   intensity (default 0.0),
                CPARM(4) is the upper limit (default 1.0),
                CPARM(5) is the width of the distribution in arc
                   seconds (0 => CELLS(1)/SQRT(2)).  For 'GAUS' this
                   is the r.m.s. (the FWHM is 2.35482*CPARM(5)).  For
                   'LRTZ' it is the Lorentz one-half width at one-half
                   maximum.

             If OPCODE is 'BEAM':
                CPARM(3) is the observing frequency in GHz; default
                   1.420
                PBPARM(1) = value below which pattern is blanked (if 0
                     use the beam calculator's idea of "outside", so
                     set to < 0 to have no blanking)
                PBPARM(2) is logical code: true (> 0) => use
                     BMPARM(3-7) to define the beam.
                  Otherwise use default parameters for the VLA (or
                  ATCA where appropriate)
                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

             If OPCODE is 'ATCA':
                CPARM(3) is the observing frequency in GHz; default
                   1.420
                PBPARM(1) = value below which pattern is blanked (if 0
                     use the beam calculator's idea of "outside", so
                     set to < 0 to have no blanking)
                PBPARM(2) is logical code: true (> 0) => use
                     BMPARM(3-7) to define the beam.
                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 data from Chris
                Phillips:
                  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

             If OPCODE is 'RADI':
                The function is taken to be CPARM(3) + R*CPARM(4) +
                   R*R*CPARM(5) + R^3 * CPARM(6) + R^4 * CPARM(7) +
                   R^5 * CPARM(8) + R^6 * CPARM(9) + R^7 * CPARM(10)
                where R is the radius in arc seconds.

             If OPCODE is 'POLY':
                The function is taken to be CPARM(3) + X*CPARM(4) +
                   Y*CPARM(5) + X^2 * CPARM(6) + Y^2 * CPARM(7) +
                   X^3 * CPARM(8) + Y^3 * CPARM(9) + X^4 * CPARM(10) +
                   Y^4 * PBPARM(1) + X*Y * PBPARM(2) +
                   X*X*Y * PBPARM(3) + X*Y*Y * PRPARM(4) +
                   (X^3)*Y * PBPARM(5) + (Y^3)*X * PBPARM(6) +
                   (X*Y)^2 * PBPARM(7)
                where X and Y are the signed distance from the
                reference pixel in arc seconds in the x and y axis.
----------------------------------------------------------------
PATGN:  Task which creates a user specified test pattern.
DOCUMENTOR: Thad A. Polk, NRAO.
RELATED PORGRAMS: AIPS, All AIPS image tasks.

                          PURPOSE

     PATGN is designed to produce a variety of test patterns
for use in image processing tasks.  It generates regular or
symmetric images which can be tailored to the users needs. In
particular, the patterns can be used to test the response of
various processing algorithms.  The necessary control
information can be passed to the program via OPCODE and CPARM.
For information about compiling, link-editing, and running PATGN
see HELP NEWTASK or the AIPS programmers' manual.

               DETAILS ABOUT SPECIFIC OPCODES

GAUS: this is the Gaussian profile.  With this OPCODE, the user
       can produce an image based on a normal distribution of
       specified width.  These images could be used in a variety
       of ways.  For example, one could convolve the test
       pattern with other images to blur them, or simply to test
       the convolution algorithm.
LRTZ: this is the Lorentzian profile.  It is similar to the
       Gaussian profile except that the peak is less sharp, with
       the tails of the distribution being wider.  Its uses are
       similar to those described for the Gaussian profile.
ZONE: this is the Zone Plate pattern.  It produces an image that
       is circularly symmetric with dark and light bands
       alternating.  The bands are wide at the refernce point,
       get thinner until the distance from the reference point
       is half the specified period and then get wider again.
       This pattern produces a wide variety of frequencies
       (alternation of light and dark) at all possible angles
       and is thus very useful in testing the frequency response
       of various processing algorithms.  For example, one could
       run the pattern through an algorithm, run the result
       through an inverse operation and compare final picture
       with the original and determine what sort of artifacts
       the algorithm produces and at what angle and frequency
       these artifacts tend to appear.

BEAM: Rick Perley's report


	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.
