% @(#)coadd_imag.hlq	19.1 (ESO-ECF) 02/25/03 13:25:03
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1992 European Southern Observatory
%.IDENT      coadd_imag.hlq
%.AUTHOR     RNH, ECF/ESO
%.KEYWORDS   MIDAS, help files, COADD/IMAGE 
%.PURPOSE    On-line help file for the command:  COADD/IMAGE
%.VERSION    1.0  14-SEP-1992 : Creation, RNH
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
COADD/IMAGE					14-SEP-1992, RNH
\oc\su
COADD/IMAGE in_spec PSFs niter decon coaddr [flags] [xsub,ysub] [Firstim]
	Co-add or restore images using Lucy algorithm
\us\pu
Purpose: 
          Co-add or restore images using Lucy algorithm
\up\sy
Syntax:   
          COADD/IMAGE in_spec PSFs niter decon coaddr [flags] [xsub,ysub]
                      [Firstim]
\ys\pa
          in_spec = single or more image frames separated by a comma;\\
             the images must be well-aligned with each other and must have
             same size as well as dimensions which are powers of two.
\ap\pa
          PSFs = point-spread-function images to match the input images;\\
             the PSFs must be the same size and shape as the data images.\\
             They must be non-negative everywhere and must be normalised so
             that the total intensity for each image is 1.0.
\\
             The peak of the PSFs should be positioned centrally in the frame
             and the PSFs should be well aligned with each other.
\ap\pa
          niter = number of iterations to be applied
\ap\pa
          decon = name of output deconvolved image;
\\
             this frame will be the result of applying the Lucy-Richardson
             restoration algorithm to the input images.
\\
             If there are multiple images the information from all of them is
             combined.
\\
             If there is only one image and one PSF this result is the standard
             Lucy-Richardson restored image.
\ap\pa
          coaddr = root name for output co-added images\\
             The co-added output images are the results of convolving the
             deconvolved image with each of the PSFs in turn.\\
             They are named by appending \_1, \_2 etc to the string supplied 
             here
\ap\pa
          Flags = control switches, four Y/N flags; defaulted to  YYNN\\
             (1) verbose - if "Y" lots of messages explaining what is happening
                 during the restoration are displayed. If "N" the program
                 keeps quiet until all is done.
\\
             (2) accel - whether or not the accelerated version of the
                 algorithm is used.
\\
                 If this is turned on the correction factor image which is
                 applied at each iteration is multiplied by a factor which
                 maximises the increase in likelihood (and hence the
                 improvement in the restoration) within the limits imposed by
                 the non-negativity requirement.
\\
                 This normally leads to quicker restoration and is recommended
                 whether or not you have understood the last sentence.
\\
             (3) Whether or not there is a first estimate image. If so the
                 restoration starts from this point, if not it starts from
                 a constant image with the same total flux as the data. This
                 option is mainly useful if you want to continue a restoration
                 to more iterations without having to start again.
\\
             (4) Whether or not the restoration uses sub-sampling. It is often
                 advantageous to restore onto a more finely sampled grid than
                 the original data, particularly if the latter is not well
                 sampled. For more details see the notes below.
\ap\pa
          xsub,ysub = optional X and Y sub-sampling factors. These values are
              only needed if the subsampling flag above has been set to Y.
\ap\pa
          Firstim = the name of the starting image if there is one. If the
              flag has been set to state that there is a starting image this
              one will be read and used as the initial estimate image. If not
              it is ignored. 
\ap\see
See also:
          DECONVOLVE/IMAGE, DECONVOLVE/FLUCY
\ees\no
Note: 
          This program has a dual purpose:
\\
          Image restoration to enhance resolution and the contrast of fine
          scale features and the co-adding of images with different
          point-spread-functions, eg, CCD frames taken in differing seeing 
          conditions.
\\
          Both operations are based on the image restoration scheme devised
          by Richardson and Lucy and the generalisation of the method for
          image co-addition was also suggested by Leon Lucy.
\\
          This command always produces both a deconvolved image and the
          result of convolving this with the PSFs of the input frames.
\\
          If the program is being used simply to do a normal restoration then
          the former will be the desired output and the latter may be
          disregarded (however it will be found to be very similar to the input
          with the pixel-to-pixel small-scale noise removed and hence may have
          its uses).
\\
          For simple restorations 40 iterations will typically be a good
          compromise between enhanced sharpness and obtrusive artefacts,
          although this number depends on the signal-to-noise of the data
          and other factors which make experimentation essential.
\\
          In the case of image co-addition the optimal result is normally the
          output co-added image which corresponds to the sharpest input PSF.
\\
          E.g., if you have three input images taken in 0.3,0.8 and 1.2 arcsec
          seeing then the optimal result will be the one matching the
          0.3arsec PSF.
\\
          The deconvolved image may have smaller star images but
          it will also suffer from the unavoidable artefacts present in
          restorations.
\\
          For this sort of work it is best to go to quite high numbers of
          iterations to try to get close to the maximum likelihood result.
\\
          Sub-sampling may be done if the PSF can be obtained on a finer grid
          than the data itself. In this case the data should be expanded by
          pixel replication (not re-sampling or interpolation) so that the size
          and number of pixels matches that of the sub-sampled PSFs.
\\
          Then the restoration/co-addition may be performed in the normal way
          except that the sub-sampling flag should be set to Y and the
          appropriate values for the X and Y sub-sampling factors also given.
\on\exs
Examples:
\ex
          COADD/IMAGE galaxy psf 10 gal_10 qqq
            Do a standard Lucy-Richardson restoration of the image
            `galaxy.bdf' using the PSF `psf.bdf'.
\\
            10 iterations are applied (accelerated as that is the default)
            and the result written to `gal_10.bdf'.
\\
            The result of convolving `gal_10.bdf' with `psf.bdf' is written to
            the scratch file `qqq.bdf' and will probably be disgarded.
\xe\ex
          COADD/IMAGE gal1,gal2 psf1,psf2 100 gal_a100 gal_ca
            Co-add the images `gal1.bdf' and `gal2.bdf' using the corresponding
            PSFs `psf1.bdf' and `psf2.bdf'.
\\
            100 iterations (accelerated) will be performed. The deconvolved
            result will be written to `gal_a100.bdf' and the co-added images to
            `gal_ca_1.bdf' and `gal_ca_2.bdf'.
\xe\ex
          COADD/IMAGE galaxy psf 10 gal_20 qqq2 YYYN ? gal_10
            Continue the restoration in the first example to another 10
            iterations.
\\
            This shows the use of the `first estimate' flag which is set to "Y"
            and the input first estimate image name is given as `gal_10 'on the
            command line.
\\
            The result will be written to `gal_20.bdf'.
            The normal "verbose" and "accel" flags are retained.
\xe\ex
          COADD/IMAGE biggal psfsub 10 gal_s40 qqq YYNY 2,2 
            This is an example of using the sub-sampling restoration option.
            The input `biggal.bdf' is the same frame as above except with the
            pixels duplicated in both X and Y.
\\
            The PSF `psfsub.bdf' is an image of the same size and with the same
            pixel grid containing a sub-sampled PSF.
            The result will be `gal_s40.bdf', also on the finer pixel grid.
            The "subsample" flag has been set and the sub-sampling factors in
            both X and Y are given on the command line.
\xe\sxe
