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