; DCONV
;---------------------------------------------------------------
;! deconvolves a gaussian from an image
;# Task Imaging
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2009
;;  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
;-----------------------------------------------------------------------
DCONV     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
DCONV : Task to deconvolve an image, given a gaussian beam.
INNAME                             Image name (name)
INCLASS                            Image name (class)
INSEQ            0.0       9999.0  Image name (seq. #)
INDISK           0.0          9.0  Disk drive #
IN2NAME                            Second Image name (name)
IN2CLASS                           Second Image name (class)
IN2SEQ           0.0       9999.0  Second Image name (seq. #)
IN2DISK          0.0          9.0  Second Disk drive #
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           0.0       9999.0  Output image name (seq. #)
OUTDISK          0.0          9.0  Output 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
OPCODE                             'IN2C' : use weighting map,
                                   'UNWT' : no weighting map.
FACTOR           0.0          1.0  Points with less than FACTOR
                                   times the maximum # points in
                                   their vicinity are not cor-
                                   rected (Isolation criterion).
PIXSTD           0.0     999999.9  Stop criterion, rms.
PIXAVG           0.0     999999.0  Stop criterion, correction.
NITER            0.0        999.0  Max. # iterations.  0=>1
BMAJ             0.0       9999.0  Beam major axis (arcsec)
BMIN             0.0       9999.0  Beam minor axis (arcsec)
                                   0=> BMAJ
BPA           -360.0        360.0  Beam position angle. (N->E)
APARM                              (1) Lower limit output, (2)
                                   upper limit output, (1) and
                                   (2) 0: use scratch files.
                                   (3) type of gainfunction.
                                    0: triangle, 1:rectangle.
BADDISK          0.0         15.0  Disks to avoid for scratch
----------------------------------------------------------------
DCONV
Type: Task
Parameters :
INNAME     Image name (name)
INCLASS    Image name (class)
INSEQ      Image name (seq. #) 0=> lowest unique
INDISK     Disk drive #.
IN2NAME    Name second input image (name)
IN2CLASS   Name second input image (class)
IN2SEQ     Name second input image (seq. #) 0=> lowest unique
IN2DISK    Disk drive second input image.
OUTNAME    Name output image (name)
OUTCLASS   Name output image (class)
OUTSEQ     Name output image (seq. #) 0=> lowest unique
OUTDISK    Disk drive output image.
BLC        Bottom left corner of image. 0=> from catalog header.
TRC        Top right corner of image.   0=> from catalog header.
OPCODE     'IN2C' : use weighting map; 'UNWT' : no weighting.
FACTOR     Percentage of non-blanked pixels in neighbourhood
           needed to call pixel 'not isolated'.
PIXSTD     Stop iterations if rms difference between O and
           convolved T drops below PIXSTD.
PIXAVG     Stop iterations if increase in average correction per
           pixel drops below PIXAVG.
NITER      Maximum # iterations.
BMAJ       Major axis beam (arcsec).
BMIN       Minor axis beam (arcsec).
BPA        Position angle major axis (degrees, N=>E).
APARM      1: lower pixel limit; 2: upper pixel limit. If 1 and
           2 are zero, use scratch files. 3: shape of gain func-
           tion, 0: triangle, 1: rectangle   (see EXPLAIN file).
BADDISK    Disk(s) to avoid using for the 2 scratch files.
----------------------------------------------------------------
DCONV :
DCONV sharpens an image which is blurred by a gaussian.  I am
not quite sure of its usefulness in astronomical applications,
therefore I welcome suggestions.  I see its use mainly in cases
where (of a spectral line cube) only the moment maps are readily
available.
Use : DCONV solves the following equation for T (by iteration) :
                    B  o  W . T
           O   =   ------------
                    B  o  W
where O = O(x,y), the observed distribution;  B = B(x,y), the
gaussian beam;  W = W(x,y), an optional weighting map;
T = T(x,y), the unknown true distribution.  The  'o'  stands for
convolution.  If no map for weighting is specified, uniform
weights are assumed, and the equation becomes, provided B is
normalized to unity :
           O    =   B  o  T
The latter is solved by iterating :
           T(k) =   T(k-1) + G * (O  -  O(k)),
      with O(k) =   B o T(k-1),
           T(0) =   O,
           G the gain function (see below),
       and k the iteration number.
Without noise, the method works fine with G equal to unity.
Since usually noise will be present, G should assume values be-
tween 0 and 1, depending on the value of O(k) and the limits to
the values O(k) can assume.  These limits are set by APARM(1)
(lower) and APARM(2) (upper).
APARM(3) = 0  =>  triangular gain function:
   G = 0 at the user defined limits and beyond, and increases
   linearly to 1 halfway between the limits.
APARM(3) = 1  =>  rectangular gain function:
   G = 0 beyond the user defined limits, and G = 1 throughout
   between the limits.
The previous case applies when there are global (preferrably
physical) limits which hold all over the map, e.g. all inten-
sities should be > 0.
In other cases the limits are local rather than global. In a
velocity field a value of 200 km/s might be well possible at
one position, but extremely unlikely at the opposite end of
the map. In such circumstances, put both APARM(1) and (2) to
zero. Then the limits are determined per pixel by analyzing
the statistics of the pixel values in each pixel's neighbour-
hood in the original map (O). To achieve this, the adverb FAC-
TOR is needed to determine whether a pixel is isolated or not.
   Examples :
1)   deconvolve a total HI map, or any intensity map.
   Use uniform weighting (no second map), APARM(1) = 0 (don't
   allow negative flux densities).  Use a rectangular function
   with very large APARM(2), or a triangular one with APARM(2)
   in the order of the map maximum.  Set PIXSTD to 2 or 3 ti-
   mes the estimated rms noise in the map.
2)   deconvolve a velocity field, or any first moment map.
   Use a second (weighting) map, preferably the result of exa-
   mple 1.  Since there are no sensible fixed limits to the
   velocities, set APARM(1) and APARM(2) to 0.  This will cau-
   se DCONV to fill scratch files with the statistics of the
   input map, and to use these in determining the gain G. FAC-
   TOR = 0.5 eliminates most edge problems.  For PIXSTD try
   the estimated error per pixel. (This is usually much smal-
   ler than the velocity resolution).

     General :
   Do not iterate too long: after just a few iterations all time
   is likely to be spent trying to make a solution to either
   noise or a few badly specified points.
