BLOCK - Smooths an NDF using a one- or two-dimensional square or rectangular box filter.

Description:

This application smooths an NDF using a one- or two-dimensional square or rectangular box filter. Each output pixel is either the mean or the median of the input pixels within the filter box. The mean estimator provides one of the fastest methods of smoothing an image and is often useful as a general-purpose smoothing algorithm when the exact form of the smoothing point-spread function is not important.

The NDF may have up to three dimensions. If it has three dimensions, then the filter is applied in turn to each plane in the cube and the result written to the corresponding plane in the output cube. The orientation of the smoothing plane can be specified using the AXES parameter.

Usage:

block in out box [estimator]

Parameters:

AXES(2) = _INTEGER (Read)

This parameter is only accessed if the NDF has exactly three significant pixel axes. It should be set to the indices of the NDF pixel axes which span the plane in which smoothing is to be applied. All pixel planes parallel to the specified plane will be smoothed independently of each other. The dynamic default is the indices of the first two significant axes in the NDF. []

BOX(2) = _INTEGER (Read)

The x and y sizes (in pixels) of the rectangular box to be applied to smooth the image. If only a single value is given, then it will be duplicated so that a square filter is used, except where the image is one-dimensional, for which the box size along the insignificant dimension is set to 1. The values given will be rounded up to positive odd integers, if necessary.

ESTIMATOR = LITERAL (Read)

The method to use for estimating the output pixel values. It can be either "Mean" or "Median". ["Mean"]

IN = NDF (Read)

The input NDF containing the one- or two-dimensional image to which box smoothing is to be applied.

OUT = NDF (Write)

The output NDF which is to contain the smoothed image.

TITLE = LITERAL (Read)

The title for the output NDF. A null value will cause the title of the input NDF to be used. [!]

WLIM = _REAL (Read)

If the input image contains bad pixels, then this parameter may be used to determine the number of good pixels which must be present within the smoothing box before a valid output pixel is generated. It can be used, for example, to prevent output pixels from being generated in regions where there are relatively few good pixels to contribute to the smoothed result.

By default, a null (!) value is used for WLIM, which causes the pattern of bad pixels to be propagated from the input image to the output image unchanged. In this case, smoothed output values are only calculated for those pixels which are not bad in the input image.

If a numerical value is given for WLIM, then it specifies the minimum fraction of good pixels which must be present in the smoothing box in order to generate a good output pixel. If this specified minimum fraction of good input pixels is not present, then a bad output pixel will result, otherwise a smoothed output value will be calculated. The value of this parameter should lie between 0.0 and 1.0 (the actual number used will be rounded up if necessary to correspond to at least 1 pixel). [!]

Examples:

block aa bb 9

Smooths the two-dimensional image held in the NDF structure aa, writing the result into the structure bb. The smoothing box is 9 pixels square. If any pixels in the input image are bad, then the corresponding pixels in the output image will also be bad. Each output pixel is the mean of the corresponding input pixels.

block spectrum spectrums [5,1] median title="Smoothed spectrum"

Smooths the one-dimensional data in the NDF called spectrum using a box size of 5 pixels, and stores the result in the NDF structure spectrums. Each output pixel is the median of the corresponding input pixels. If any pixels in the input image are bad, then the corresponding pixels in the output image will also be bad. The output NDF has the title "Smoothed spectrum".

block ccdin(123,) ccdcol [1,9]

Smooths the 123$^{\rm rd}$ column in the two-dimensional NDF called ccdin using a box size of 9 pixels, and stores the result in the NDF structure ccdcol. The first value of the smoothing box is ignored as the first dimension has only one element. Each output pixel is the mean of the corresponding input pixels.

block in=image1 out=image2 box=[5,7] estimator=median

Smooths the two-dimensional image held in the NDF structure image1 using a rectangular box of size 5$\times$7 pixels. The smoothed image is written to the structure image2. Each output pixel is the median of the corresponding input pixels.

block etacar etacars box=[7,1] wlim=0.6

Smooths the specified image data using a rectangular box 7$\times$1 pixels in size. Smoothed output values are generated only if at least 60% of the pixels in the smoothing box are good, otherwise the affected output pixel is bad.

Timing

When using the mean estimator, the execution time is approximately proportional to the number of pixels in the image to be smoothed and is largely independent of the smoothing box size. This makes the routine particularly suitable for applying heavy smoothing to an image. Execution time will be approximately doubled if a variance array is present in the input NDF.

The median estimator is much slower than the mean estimator, and is heavily dependent on the smoothing box size.

Related Applications

KAPPA: CONVOLVE, FFCLEAN, GAUSMOOTH, MEDIAN; FIGARO: ICONV3, ISMOOTH, IXSMOOTH, MEDFILT.

Implementation Status:

• This routine correctly processes the AXIS, DATA, QUALITY, LABEL, TITLE, UNITS, WCS, and HISTORY  components of the input NDF and propagates all extensions. In addition, if the mean estimator is used, the VARIANCE  component is also processed. If the median estimator is used, then the output NDF will have no VARIANCE  component, even if there is a VARIANCE component in the input NDF.

• Processing of bad pixels and automatic quality masking are supported. The bad-pixel flag  is also written for the data and variance arrays.

• All non-complex numeric data types can be handled. Arithmetic is performed using single-precision floating point, or double precision if appropriate.