Function: PRESMOOTH
Purpose: Calculate convolution function parameters for use in
smoothing to a bigger (rotated) beam and determine
scale factor to be able to preserve definition of
brightness temperature.
Files: presmooth.shl
Author: M. Vogelaar
Category: CONVOLUTION
Use: INTEGER PRESMOOTH( APsetin, IN CHARACTER*(*)
APsubin, IN INTEGER
oldbeam, IN REAL ARRAY
oldPA, IN REAL
newbeam, IN/OUT REAL ARRAY
newPA, IN/OUT REAL
fitsize, IN INTEGER ARRAY
cutoffratio IN REAL
decim IN INTEGER ARRAY
tol IN REAL
epsilon IN REAL
clip IN REAL
conbeam OUT REAL ARRAY
conPA OUT REAL
scalefac OUT REAL
APgridspac OUT REAL ARRAY )
PRESMOOTH:
0 : Pre-smoothing was successful
-1 : Could not find major axis in AP header (BMMAJ)
-2 : Could not find minor axis in AP header (BMMAJ)
-3 : Could not find pos. angle of beam in AP header (BMPA)
-4 : Unsuitable combination of new beam parameters!
-5 : Axis units not equal!
-6 : Cannot convert units to seconds of arc!
-7 : No grid spacings in header of this AP set!
-8 : Convolution region too big!
-9 : Central max. of AP is not a maximum!
-10: No convergence after max. steps
-11: AP too small for this convolution
APsetin Name of antenna pattern to be
used in iteration towards new beam.
APsubin Subset level of AP. Only one level
is allowed and the subset must be 2-dim.
oldbeam Major and minor axis of AP in seconds of arc.
If the values are blank on input, the items
(BMMAJ, BMMIN) are examined in the AP header
on subset level. If nothing could be found,
the pre smoothing is aborted and error (-1)
or (-2) is returned.
oldPA Rotation angle of the major axis of the beam
wrt. the North in the direction of the East.
The angle is in degrees. If on input, the value
is blank, the routine tries to find a value
(BMPA) in the header on given subset level.
If nothing could be found, error (-3) is returned.
newbeam Major and minor axes in seconds of arc of the
wanted beam. If the iteration stops, the convol-
ved beam is fitted once again but with the angle
as free parameter. The results are values close
to the new beam and are consistent with the
results obtained with the program ANTPAT. These
results are returned in 'newbeam' and 'newPA'
so that they can be used to update the header of
a smoothed AP.
newPA Rotation angle of the major axis of the wanted beam
wrt. the North in the direction of the East.
The angle is in degrees.
fitsize Minimum size of convolved part of AP used in
a least squares fit.
cutoffratio This is the ratio of the gaussian function values
at central point and a point x on the boundary.
It determines the border of your gaussian
convolution function. Outside this border all
function values are set to zero.
decim Integer regrid values. The values are needed in the
fitting process to be able to compare the wanted
properties of a smoothed AP with the values obtained
by other fitting programs (like QFIT, ANTPAT).
tol Fitting of the new beam stops when successive
iterations fail to produce a decrement in
reduced chi-squared less than TOLERANCE. If its value
is less than the minimum tolerance possible, it will
be set to this value. This means that maximum accuracy
can be obtained by setting TOLERANCE=0.0.
epsilon Stop iteration if calculated new beam sizes
and wanted beam sizes don't differ more than epsilon
(percentage!).
clip When fitting the convolved AP in the iteration,
take only values greater than 'clip'. If 'clip'
equals blank on input, fit all AP data.
conbeam Output convolution beam (major x minor) in seconds
of arc
conPA Angle of the major axis (N->E)
in degrees of the 2-dim gaussian that
represents the convolution function.
scalefac After iteration, a scale factor is calculated with
which the smoothed image can be rescaled so that
the definition of brightness temperature is preserved.
APgridspac The grid spacings used to construct the convolution
function inside this routine are returned so that
the same convolution function can be constructed in
the calling environment.
Description: The function PRESMOOTH is used to determine the
convolution function needed to convolve data
in 'APsetin' in order to get a beam with the characte-
ristics defined in 'newbeam'. To preserve the definition
of brightness temperature, a scale factor is determined.
The sizes in 'fitsize' determine the size of the
AP box used in the lsqfit routine. The sizes
cannot exceed 255 and must be odd. If they are
not odd, 1 is subtracted in size. The minimum size
is 3.
If the initial 'fitsize' is not allowed, the routine
generates a warning and will adjust the value.
If the values are accepted, they will be used to
determine the AP box to read the data. The routine
assumes that the position of the centre of the AP
is always 0,0
In most cases the beam of the original distribution
can be found in the header of the AP ('oldbeam')
If the values are blank on input, the routine tries
to find the beam in the header of 'APsetin', but
if this fails, it will return with an error. The
errors are:
PRESMOOTH = -1; could not find major axis in AP
header (BMMAJ)
PRESMOOTH = -2; could not find minor axis in AP
header (BMMAJ)
PRESMOOTH = -3; could not find pos. angle of beam
in AP header (BMPA)
If the old beam is known and the wanted beam is
known ('newbeam'), the routine calculates the con-
volution parameters. If it cannot find a suitable
set, a warning is given and error (-4) is returned.
The AP cannot be used in the iteration if the units
of the axes are not equal to each other, error (-5)
or if the units cannot be converted to 'ARCSEC',
error (-6), or if the grid spacing cannot be found
in the AP header (CDELT#), error (-7).
If the wanted new beam needs a convolution function
greater than 255*255 pixels, a warning is generated
and error (-8) is returned.
If the central maximum of the AP is not a maximum,
the routine is aborted with error (-9) and a
warning. The central value is only compared with the
image value at the right and the image value at
above the central position. If the AP is not big
enough for a convolution function, abort and return
with error (-11).
It is possible that there is no convergence within
'maxiters' steps. Abort with an error (-10) message
in that case.
Notes: The function FUNC and the subroutine
DERV must be defined outside this function.
Updates: Sep 10, VOG, Document created