% @(#)filterfill.hlq	19.1 (ESO-IPG) 02/25/03 13:30:32 
\se
SECTION./FILL
\es\co
FILTER/FILL                                                    10-OCT-1988  DB
\oc\su
FILTER/FILL inframe outframe rx,ry thresh
	fill up low-flux (below threshold) pixels with nearby high-flux pixels
\us\pu
Purpose:      (Partially) fill up low-flux (below threshold) pixels with
              flux from high pixels in neighborhood box of radius rx,ry.

\up\sy
Syntax:       FILTER/FILL inframe outframe rx,ry threshold
\ys\pa
              inframe   = name of input image
\ap\pa
              outframe  = name of result frame
\ap\pa
              rx,ry     = x and y radius of neighborhood box; default is 1,1
\ap\pa
              threshold = flux threshold, below and up to which pixels are
                          filled up; default is 0
\ap\no
Note:         1.) One possible application of this command is the preparation
                  of images for subsequent deconvolutions (DECONVOLVE/IMA
                  or REBIN/DECONVOLVE) that require a low, but non-negative
                  background. (The final, however not flux conserving, step
                  will probably have to be REPLACE/IMAGE.) Generally, it is
                  an efficient means to reduce background noise.
\\
              2.) The algorithm searches for low pixels (i.e. with a flux
                  below the threshold). Then it searches the box around
                  this central pixel for high pixels. In a third step,
                  it searches the neighborhood box around each of these
                  high pixels for other (secondary) low pixels. Finally,
                  the command redistributes flux from the high pixels
                  to the central pixel. All neighboring high pixels
                  contribute the same amount which is determined from
                  the following rules:
\\
                  a) The central low pixel does not receive more flux
                  than necessary to reach the threshold.
\\
                  b) A given high pixel contributes the same amount
                  to all low pixels in its respective neighborhood box.
\\
                  c) No high pixel will end up with a flux below the
                  threshold.
\\
              3.) The total flux is strictly conserved. The mean level
                  of the background will increase the more strongly the
                  more crowded the field is.
\\
              4.) The command can be iterated by using the result of
                  the previous iteration as input for the next one. In
                  the ith iteration, it will be the flux left over in the
                  ith-ranking pixel (counted in ascending order) which
                  limits the amount of flux that is re-shuffled. For
                  larger box dimensions, the difference between subsequent
                  iterations is, therefore, much smaller.
\on\exs
Examples:
\ex
              FILTER/FILL noisy filtered
              Frame noisy.bdf is filtered using a box of dimension
              [2*1+1,2*1+1] by as far as possible filling up negative-flux
              pixels from immediately neighboring high pixels (if any).
              Results will be in frame filtered.bdf.
\xe \sxe
