; OHGEO
;---------------------------------------------------------------
;! Geometric interpolation with correction for 3-D effects
;# Task IMAGE-UTIL OOP
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1996, 1998, 2000
;;  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
;-----------------------------------------------------------------------
OHGEO     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
OHGEO: Interpolate an image to the geometry of another.
                                   Input image
INNAME                                Image name (name)
INCLASS                               Image name (class)
INSEQ              0.0      9999.0    Image name (seq. #)
INDISK             0.0         9.0    Image disk drive #
                                   Image defining geometry
IN2NAME                               Image name (name)
IN2CLASS                              Image name (class)
IN2SEQ             0.0      9999.0    Image name (seq. #)
IN2DISK            0.0         9.0    Image disk drive #
                                   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 #
BLC             0.0      4096.0    Bottom left corner of image
                                     0=>entire image
TRC             0.0      4096.0    Top right corner of image
                                     0=>entire image
IMSIZE          0.0      4096.0    Output image size in pixels
REWEIGHT        0.0         4.0    (1) Interpolation halfwidth
                                   (2) Minimum fraction of good
                                       pixels required (0->1/3)
AXREF                              X axis reference pixel
AX2REF                             Y axis reference pixel
APARM                              (1) >0 => do 3-D corr.
                                   (2) Parallactic angle (deg)
                                   (3) Zenith angle (deg)
                                   (4-8) radial scaling parms
                                   (9) Linear scaling
----------------------------------------------------------------
OHGEO
Type: Task
Use: OHGEO does an interpolation of one image to the geometry defined by
     another.  Optionally corrections can be made for 3-D distortions
     caused by a misaligned, but coplanar array (e.g. VLA snapshots).

     Another option is radial scaling of the image to correct for the
     interaction of a finite bandpass and the antenna primary beam size.

     Interpolation is done only in the first 2 dimensions.  Unlike
     HGEOM, OHGEO will interpolate over blanked pixels so that it can
     fill in small blanked regions and handle edges without having to
     discard image area.
     NOTE: the input subimage is read into dynamically allocated memory.
     Very large input arrays may cause swapping on your computer.
Adverbs:
  INNAME......The input image name.   Standard defaults.
  INCLASS.....The input image class.  Standard defaults.
  INSEQ.......The input image sequence number. 0 => high
  INDISK......The input image disk drive no. 0 => any
  IN2NAME.....The template image name.  blank => actual
  IN2CLASS....The template image class.  Standard defaults
  IN2SEQ......The template image seq no. 0 => any
  IN2DISK.....The template image disk drive no. 0 => any
  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
  BLC..........The bottom left-hand pixel of the input image
               which becomes the bottom left corner of the
               input subimage.  The value (0,0) means (1,1).
  TRC..........The top right-hand pixel of the input image
               which becomes the top right corner of the
               subimage.  The value (0,0) means take the top
               right hand corner of the image.
  IMSIZE.......Output image size in pixels [1=columns, 2=rows]
               Default is second input image size. The output size is
               independent of the input size.  If IMSIZE is all 0 and
               AXREF and AX2REF are zero, then AXREF and AX2REF are
               taken from the 2nd image.
  REWEIGHT.....Interpolation kernal 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
  AXREF........X-axis reference pixel;
  AX2REF.......Y-axis reference pixel;  If BOTH AXREF and AX2REF are
               zero, but IMSIZE is not, then the numeric center of the
               input (sub)image is placed at the numeric center of the
               output image.  If IMSIZE is all 0 and both AXREF and
               AX2REF are zero, then AXREF and AX2REF are taken as the
               refernce pixels of the 2nd image.
  APARM........Transformation parameters:
               (1) = if > 0 then apply 3-D corrections
                     SEE EXPLAIN OHGEO
               (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 OHGEO
               (9) Linear scaling factor, 0 => 1.0
                   SEE EXPLAIN OHGEO
----------------------------------------------------------------
OHGEO:  Task to interpolate one image to the geometry of another
Documentor:  W. D. Cotton, NRAO
Related Programs: HGEOM, UVADC, WFCLN

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

On the Relation of Input Image Size to Output Image Size:

The adverb IMSIZE specifies the dimensions of the output image.
If it is set to zero then the default applies and the output
image is the same size as the second input. But if it is nonzero
it means EXACTLY what it says: the output will have dimensions
specified by IMSIZE regardless of what the dimensions of the
input image happen to be. Suppose the input image is 800-square
and BLC and TRC are zero (i.e., all of the image). If IMSIZE is
100-square then the output is 100-square.  On the other hand, if
IMSIZE is bigger than the input, say 1000-square, the result is
that the input images to the output and regions which are outside
the input image will be blank in the output.  Note that
the portion of the input which is used is delimited by BLC and
TRC completely independently of IMSIZE.

The pixel position of the "reference pixel" is specified by the
header of the second image.  It is not affected by BLC, TRC.
If IMSIZE is smaller than the second input image then the
output image will be centered on the center (NOT reference
pixel) of the input subimage (as defined by BLC, TRC).  This
will affect the value of the reference pixel which in this case
may not be inside the output image.

