AIPS NRAO AIPS HELP file for CONVL in 31DEC24



As of Tue Mar 19 1:26:50 2024


CONVL: Task to convolve two images.

INPUTS

                                   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 #
OPCODE                             Operation desired:
                                      GAUS, GMOD, IMAG, IMAC,
                                      DCON, DGAU
BLC                                Bottom left corner
TRC                                Top right corner
                                   Convolving image (IMAG, DGAU)
IN2NAME                               Image name (name)
IN2CLASS                              Image name (class)
IN2SEQ             0.0      9999.0    Image name (seq. #)
IN2DISK            0.0         9.0    Image disk drive #
                                   Convolved 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                             Size of box to find position
                                   of max in output image (IMAC)
BMAJ            -999.9             FWHM(asec) maj. axis output.
                                   beam - required except IMAG
BMIN            -999.9             FWHM(asec) min. axis output
                                   beam.
BPA             -360.0       360.0 position angle
FACTOR                             Unit conversion factor;
                                   clip inv Gaussian level DCON
DOBLANK         -1.0         1.0   >= 0 => reblank output images
                                   where input was blanked
BADDISK                            Disks to avoid for scratch.

HELP SECTION

CONVL
Type: Task
Use:  CONVL convolves your map with a either an eliptical gaussian or a
      specified convolving image.  Strictly, only the inner quarter of
      the map is properly convolved, but for the Gaussian this problem
      may not be apparent.  CONVL uses a 2D FFT, and so it cannot
      properly handle images containing blanks.  It will (in 31DEC04)
      replace blanks with 0.0, do the convolution, and then put the
      blanks back.  Nonetheless, the effect of the 0.0 will be felt in
      non-blank pixels.  The second image must not contain blanked
      pixels.  CONVL surrounds images with sizes other than a power of
      2 with zeroes up to the next power of 2, convolves using the 2D
      FFT, and then removes the borders for output.
Adverbs:
  INNAME......The input image name.     Standard defaults.
  INCLASS.....The input image class.    Standard defaults.
  INSEQ.......The input image seq. #.   0 => highest.
  INDISK......The input image disk drive #. 0 => any.
  OPCODE......A code indicating the desired operation.
              'GAUS' => convolve the image to the specified Gaussian.
              'GMOD' => convolve the image with the specified Gaussian
              'IMAG' => convolve image 1 with the second image.
              'IMAC' => crosscorelate image 1 with the second image.
              'DCON' => deconvolve the image from specified Gaussian.
              'DGAU' => convolve the image with the deconvolution of
                    the Gaussian and the second image (Gaussian
                    divided by image in Fourier space)
              blank => 'GAUS'
  BLC.........The bottom left corner of a subimage to be convolved.
                 (0's => 1,1,1,1,1,1,1)
  TRC.........The top right corner of the subimage to be convolved.
                 (0's => all of image from BLC)
  IN2NAME.....The convolving image name.  Standard defaults.  Must be
              same size and cell spacing as INNAME.
  IN2CLASS....The convolving image class. Standard defaults.
  IN2SEQ......The convolving image seq . #. 0 => highest.
  IN2DISK.....The convolving image disk drive #.  0 => any
  OUTNAME.....The output image name.   Standard defaults.
  OUTCLASS....The output image class.  Standard defaults.
  OUTSEQ......The output image seq. #. 0 => highest unique.
              Input file (only) may be overwritten.
  OUTDISK.....The clean disk drive no. 0 => highest with space
  IMSIZE......Size of the box used to calculate max position in the
              output image. Used only if OPCODE='IMAC'
              Must be odd!!!     0 => 5, 5
  BMAJ........Required for all OPCODEs except IMAG: the FWHM (asec)
              major axis of the desired output beam.  0 -> Clean beam
              for DCON only, for GAUS task finds smallest beam that
              will work, for rest it is an error.  Other than
              IMAG, it will be deconvolved from the clean beam if the
              input image is a clean image.  If the deconvolution
              fails, the program will terminate.
              NOTE: as of 29 June 2010, the task will read a CG table
              if present and determine the Clean beam for each channel
              from it.  The Gaussian used will then vary from channel
              to channel and will be fully reported in the messages
              and the history file.
  BMIN........The FWHM (asec) minor axis of the output beam.
              If <= 0 BMIN = BMAJ
  BPA.........The position angle in the unrotated image of BMAJ.
  FACTOR......All OPCODEs except DCON: the conversion factor for the
              image units.  This value of FACTOR if specified should
              be the ratio of the new beam area to the old beam area.
              If FACTOR is > 0.0, it will be used to convert from
              JY/(old beam) to JY/(new beam).  If FACTOR is 0.0 or
              less, it will be determined from the output beam size
              and any CLEAN beam stored in the catalog.  If FACTOR is
              not given and cannot be computed it is set to 1.0 and
              the map units are changed to "UNDEFINE".  If flux per
              pixel output is desired then use FACTOR=1.0.

              If the input image is not measured in JY/BEAM,
              OPCODE=GAUS, and FACTOR <= 0, then
                 FACTOR = NPIXINBEAM
                        = ALFA * BMAJ * BMIN / (Xspace*Yspace)
              where NPIXINBEAM is the number of pixels in the
              convolving beam and
                 ALFA = PI / (4 * ln(2)) = 1.13309

              DCON only: FACTOR is instead the limit in the value of
              1/Gaussian.  <= 1.01 => 1000.
  DOBLANK.....>= 0 => reblank those pixels that were blanked in the
              input image.  This still leaves pixels around the
              blanked affected by the use of 0.0 in the convolution.
              NOTE the nonstandard usage where = 0 is TRUE.
              < 0 => leave previously blanked pixels at whatever the
              convolution produced from the 0.0 used instead of the
              blank value.
  BADDISK.....This array contains the numbers of disks on which it is
              desired that scratch files not be located.  BADDISK has no
              effect on input and output maps.

EXPLAIN SECTION

A remark about convolving a map which has been CLEANed
      (added by DCW, 15 October 84)

In the help text above under the heading for BMAJ it says:
"[BMAJ] will be deconvolved from the clean beam if the image is
a clean image." What this really means is that CONVL will
attempt to produce a map which has the desired clean beam
shape, and in the process it will account for an existing beam
as declared in the header. This is done by deriving the
parameters of a Gaussian which when convolved with the existing
clean beam will produce the desired beam (the parameters of
this beam are listed in the history file). Obviously this
scheme only works when the desired beam is larger than the
existing beam (use the DGAU option if you want to deconvolve).
Please note that AIPS has tools for inserting clean beam
parameters into headers if they are not already there.

OPCODE 'GMOD' ignores the Clean beam information and simply convolves
with the specified Gaussian having parameters BMAJ, BMIN, and BPA.

A preliminary explanation of the 'DGAU' option
      (added by DCW, 26Sept84)

Suppose that the second image contains the beam pattern of the
first image. Then DGAU will convert the effective beam of the
input image to the specified Gaussian. If the specified
Gaussian is narrower than the original beam this amounts to a
simple linear deconvolution scheme. The operation is done by
dividing the transform of the specified Gaussian by the
transform of the second image, and multiplying the quotient by
the input image. The quotient is set to zero when the transform
of the second image is zero.

An important application of DGAU is "cleaning up" the seeing
profile of an optical image. This is done by specifying a
circular Gaussian which is a good fit to the observed profile
(i.e., the second image). DGAU will then correct for the
ellipticity of the profile and its excess intensity in the
wings, producing an image which has a nice Gaussian beam,
although no resolution enhancement.


AIPS