User's Guide

FILTER

Performs a low-pass, high-pass, or median filter

Function:

Performs a low-pass, high-pass, or median filter on an input image. Low-pass filters and median filters are used most often for noise suppression or smoothing, while high-pass filters are typically used for image enhancement.
For subcommands -ILOW, -VLOW, and -HIGH, a valid range for the input data is specified as MINVAL and MAXVAL (inclusive). Input values within this range are valid, and values outside the range are invalid (THRVAL may be used to specify a valid range relative to the pixel data values). The output values are calculated using all input values, valid input values, or invalid input values, depending on the subcommand specified.
Subcommand -DESPIKE uses a low-pass filter and performs a despike algorithm on all the input image pixels; subcommand -LOW applies a low-pass filter to all the input image pixels; subcommand -VLOW applies a low-pass filter to all valid input image pixels; subcommand -ILOW applies a low-pass filter to all nonvalid input image pixels; subcommand -HIGH applies a high-pass filter to all valid input image pixels; subcommand -MED applies a median filter to all input image pixels.

Parameters:

Subcommand -DESPIKE:

Performs a low-pass filter to despike an image. If the difference between the original pixel and the mean value of the box around that pixel is greater than TOLVAL, then the output is the average value; otherwise the output pixel value is unchanged from the input pixel.

IN
Input image. The input data type may be BYTE, INTEGER*2, INTEGER*4, or REAL*4. Window and/or band options may be specified.

OUT
Output image. The output image will be the same size and contain the same number of bands as specified in IN. The output data type will be ODTYPE.

TOLVAL
Tolerance value. The tolerance used in the check for despiking an image.

KERNDIM(3,3)
Kernel dimensions. The number of lines and samples per line in the sampling kernel. The values must be odd numbers between 1 and 501. The smallest kernel allowed is 1 x 3 or 3 x 1.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE 
  = I*2:   INTEGER*2 
  = I*4:   INTEGER*4 
  = R*4:   REAL*4 

Subcommand -LOW:

Performs a low-pass filter. Performs a low-pass filter that changes all input data and calculates the output using all the data in the kernel.

IN
Input image. The input data type may be BYTE, INTEGER*2, INTEGER*4, or REAL*4. Window and/or band options may be specified.

OUT
Output image. The output image will be the same size and contain the same number of bands as specified in IN. The output data type will be ODTYPE.

KERNDIM(3,3)
Kernel dimensions. The number of lines and samples per line in the sampling kernel. The values must be odd numbers between 1 and 501. The smallest kernel allowed is 1 x 3 or 3 x 1.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE 
  = I*2:   INTEGER*2 
  = I*4:   INTEGER*4 
  = R*4:   REAL*4 

Subcommand -VLOW:

Performs a low-pass filter on valid data. Performs a low-pass filter that changes only valid data and calculates the output using only the valid data in the kernel. For nonvalid input data, the output is determined by the value of INVALOPT.

IN
Input image. The input data type may be BYTE, INTEGER*2, INTEGER*4, or REAL*4. Window and/or band options may be specified.

OUT
Output image. The output image will be the same size and contain the same number of bands as specified in IN. The output data type will be ODTYPE.

MINVAL(0.0)
Minimum value. The valid data limit for the low end of the input data. Pixels with a value less than MINVAL are invalid.

MAXVAL(255.0)
Maximum value. The valid data limit for the high end of the input data. Pixels with a value greater than MAXVAL are invalid.

THRVAL(--)
Threshold value. The threshold value which determines how much the value of some given pixel within the kernel can deviate from the value of the pixel to be replaced. If the difference between the value of the pixel to be replaced and the value of some given pixel within the kernel is greater than THRVAL, the given pixel within the kernel is invalid.

KERNDIM(3,3)
Kernel dimensions. The number of lines and samples per line in the sampling kernel. The values must be odd numbers between 1 and 501. The smallest kernel allowed is 1 x 3 or 3 x 1.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE 
  = I*2:   INTEGER*2 
  = I*4:   INTEGER*4 
  = R*4:   REAL*4 
SCALFACT(1.0)
Scale factor. Multiplicative constant applied to the low-pass or high-pass components of the input filter kernel.

INVALOPT(1)
Invalid pixel option. The method of assigning a value to the output pixel when the input image pixel is invalid (less than MINVAL or greater than MAXVAL). Options 1 and 2 are set depending on whether the input pixel is less than MINVAL or greater than MAXVAL.
  = 1:  Set to (MINVAL - 1) or to (MAXVAL + 1).  The 
        output pixel is set to (MINVAL - 1) if the 
        input pixel value is less than MINVAL or set 
        to (MAXVAL + 1) if the input pixel is greater
        than MAXVAL.
  = 2:  Set to 0 or 255.  The output pixel is set to 
        0 if the input pixel value is less than MINVAL 
        or set to 255 if the input pixel is greater 
        than MAXVAL.
  = 3:  Set to input pixel value.  The output pixel 
        is set to the value of the input pixel.

Subcommand -ILOW:

Performs a low-pass filter on nonvalid data. Performs a low-pass filter that changes only nonvalid data and calculates the output using only the valid data in the kernel. For valid input data, the output is set to the input pixel value.

IN
Input image. The input data type may be BYTE, INTEGER*2, INTEGER*4, or REAL*4. Window and/or band options may be specified.

OUT
Output image. The output image will be the same size and contain the same number of bands as specified in IN. The output data type will be ODTYPE.

MINVAL
Minimum value. The valid data limit for the low end of the input data. Pixels with a value less than MINVAL are invalid.

MAXVAL
Maximum value. The valid data limit for the high end of the input data. Pixels with a value greater than MAXVAL are invalid.

THRVAL(--)
Threshold value. The threshold value which determines how much the value of some given pixel within the kernel can deviate from the value of the pixel to be replaced. If the difference between the value of the pixel to be replaced and the value of some given pixel within the kernel is greater than THRVAL, the given pixel within the kernel is invalid.

KERNDIM(3,3)
Kernel dimensions. The number of lines and samples per line in the sampling kernel. The values must be odd numbers between 1 and 501. The smallest kernel allowed is 1 x 3 or 3 x 1.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE 
  = I*2:   INTEGER*2 
  = I*4:   INTEGER*4 
  = R*4:   REAL*4 
SCALFACT(1.0)
Scale factor. Multiplicative constant applied to the low-pass or high-pass components of the input filter kernel.

Subcommand -MED:

Performs a median filter. Performs a median filter that changes all input data and calculates the output using all the data in the kernel. Because a median filter requires that a histogram be generated for each kernel passed over the input image, the processing time is much greater than for a high- or low-pass filter. For INTEGER*4 and REAL*4 data types, histogram generation time can be up to ten times longer; therefore, these data types are not allowed for median filters.

IN
Input image. The input data type may be BYTE or INTEGER*2. Window and/or band options may be specified.

OUT
Output image. The output image will be the same size and contain the same number of bands as specified in IN. The output data type will be ODTYPE.

KERNDIM(3,3)
Kernel dimensions. The number of lines and samples per line in the sampling kernel. The values must be odd numbers between 1 and 51. The smallest kernel allowed is 1 x 3 or 3 x 1.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE 
  = I*2:   INTEGER*2 
  = I*4:   INTEGER*4 
  = R*4:   REAL*4 

Subcommand -HIGH:

Performs a high-pass filter. Performs a high-pass filter that changes only valid data and calculates the output using only the valid data in the kernel. For nonvalid input data, the output is determined by the value of INVALOPT.

IN
Input image. The input data type may be BYTE, INTEGER*2, INTEGER*4, or REAL*4 if THRVAL is null. However, only BYTE and INTEGER*2 data are allowed if a non-zero value is entered for THRVAL. Window and/or band options may be specified.

OUT
Output image. The output image will be the same size and contain the same number of bands as specified in IN. The output data type will be ODTYPE.

MINVAL(0.0)
Minimum value. The valid data limit for the low end of the input data. Pixels with a value less than MINVAL are invalid.

MAXVAL(255.0)
Maximum value. The valid data limit for the high end of the input data. Pixels with a value greater than MAXVAL are invalid.

THRVAL(--)
Threshold value. The threshold value which determines how much the value of some given pixel within the kernel can deviate from the value of the pixel to be replaced. If the difference between the value of the pixel to be replaced and the value of some given pixel within the kernel is greater than THRVAL, the given pixel within the kernel is invalid.

THRVAL(--)
Threshold value. The threshold value which determines how much the value of a pixel within the kernel can deviate from the value of the pixel to be replaced. If the difference between the value of the pixel to be replaced and the value of a pixel within the kernel is greater than THRVAL*STDDEV (standard deviation for present kernel), that pixel is invalid. Values for THRVAL should usually vary between 1 and 3, with 2 being the recommended first attempt. Other values may work better for specific applications.

KERNDIM(3,3)
Kernel dimensions. The number of lines and samples per line in the sampling kernel. The values must be odd numbers between 1 and 501. The smallest kernel allowed is 1 x 3 or 3 x 1.

ODTYPE(SAME)
Output data type. The data type of the output image.
  = SAME:  Same as input
  = BYTE:  BYTE 
  = I*2:   INTEGER*2 
  = I*4:   INTEGER*4 
  = R*4:   REAL*4 
SCALFACT(1.0)
Scale factor. Multiplicative constant applied to the low-pass or high-pass components of the input filter kernel.

ADDBACK(0.0)
Addback. A constant from 0.0 to 1.0 that specifies what fraction of the center kernel value is to be added back to the filter kernel.

THRPERC(0)
Threshold percentage. The minimum percentage of valid data that must be present in the kernel for filtering to occur. If the percentage of valid data in the kernel is less than THRPERC, the output is set to zero. If the percentage of valid data in the kernel is greater than or equal to this value, the high-pass filter is applied to the kernel.

OFFSET(127.5)
Offset value. A value added to the high-pass filter value. This is usually used in order to center a histogram of the output image. Generally, OFFSET is defined as (MAXVAL - MINVAL) / 2.

INVALOPT(1)
Invalid pixel option. The method of assigning a value to the output pixel when the input image pixel is invalid (less than MINVAL or greater than MAXVAL). Options 1 and 2 are set depending on whether the input pixel is less than MINVAL or greater than MAXVAL.
  = 1:  Set to (MINVAL - 1) or to (MAXVAL + 1).  The 
        output pixel is set to (MINVAL - 1) if the 
        input pixel value is less than MINVAL or set 
        to (MAXVAL + 1) if the input pixel is greater
        than MAXVAL.
  = 2:  Set to 0 or 255.  The output pixel is set to 
        0 if the input pixel value is less than MINVAL 
        or set to 255 if the input pixel is greater 
        than MAXVAL.
  = 3:  Set to input pixel value.  The output pixel 
        is set to the value of the input pixel.
LOWVAL(--)
Minimum output value. The minimum pixel value of the output image.

HIGHVAL(--)
Maximum output value. The maximum pixel value of the output image.

Examples:

LAS> filter-low in=dc out=low kerndim=(13,5) odtype=4
The output is a REAL*4 image whose pixel values are the mean of all the values in each 13 x 5 input kernel.
LAS> filter-vlow in=dc out=vlow kerndim=(5,5) invalopt=3
The output image is the same data type as the input image. If the input pixel value is valid (between 0 and 255, inclusive), the output pixel value is the mean of the valid values in the 5 x 5 kernel. Otherwise, the output pixel value is set to the input pixel value.
LAS> filter-high in=dc out=high minval=500 maxval=1000 kerndim=(51,51) odtype=4 offset=750
The output is a REAL*4 image whose pixel values are the result of applying a high-pass filter with a 51 x 51 kernel to input image DC.
LAS> filter-med in=dc out=med kerndim=(7,7) odtype=2
The output is an INTEGER*2 image whose pixel values are median values of a 7 x 7 kernel passed over each pixel in the input image.
LAS> filter-high in=dc out=high minval=500 maxval=1000 thrval=2. kerndim=(5,5) invalopt=3
The output image is the same data type as the input image. If the input pixel value is valid, the output pixel value is the mean of the valid values in the 5 x 5 kernel. Otherwise, the output pixel value is set to the input pixel value. Pixel status (valid/invalid) is determined using the values of MINVAL, MAXVAL, and THRVAL. A valid pixel in the kernel is one whose value:
```
	    (1) lies somewhere between MINVAL and MAXVAL (inclusive)
	    (2) does not deviate from the input value of the pixel
		to be replaced by more than THRVAL*STDDEV (inclusive),
                where STDDEV is the standard deviation for the present
                kernel.
```

Description/Algorithm:

The boxcar filtered image is created by passing a user-specified window (called a kernel or box) over an input image on a pixel-by-pixel basis. As each input pixel is passed over, the value of the corresponding output pixel is calculated according to the user-specified options and the value of the surrounding valid pixels.
The following symbols are used in the filter formulas:
  P(i,j)  = original value of the input image at line-sample i,j
  S(i,j)  = sum of input pixels in the kernel centered at i,j
  N(i,j)  = number of valid pixels in the window centered at i,j 
  SCALFACT= scale factor 
  ADDBACK = fraction of the center pixel value to be added back
  OFFSET  = value used in order to center the histogram of output 
           image

The formulas for each type of filter are as follows: 

LOW-PASS
--------

Low(i,j) = (S(i,j) / N(i,j)) * SCALFACT

MEDIAN
------

Median(i,j) = the median pixel value of the current kernel
   
HIGH-PASS
---------

High(i,j) = (OFFSET * (1-ADDBACK)) + 
            (P(i,j) * SCALFACT * (1+ADDBACK)) -   
            (S(i,j)/N(i,j) * SCALFACT)   

Nonfatal Error Message:

[filter-warn] Nonfatal error encountered.
The image data is probably valid and therefore saved. The message that is displayed immediately preceding this message is the specific error that was encountered. Processing continues.

Fatal Error Messages:

[filter-fatal] Fatal error encountered
A fatal error was encountered during processing. The output image is not deleted, and processing is terminated. The error message that is displayed immediately preceding this message is the specific error that was encountered.
[filter-window] Invalid window specified
The specified window to filter within the image is invalid.
[filter-kerbnd] Invalid kernel or boundary
The kernel or computed boundary values are out of range. Check the input kernel size.
[filter-dtype] Invalid data type
The data type is invalid.
[filter-maxram] Invalid maximum RAM specified
The amount of maximum RAM is invalid. Check the header file containing the MAXRAM definition.
[filter-diftyp] Input images are not of same data type
The output image's data type was to be the same as the input image, but the input images are not of the same data type. The user can either ensure all input images have the same data type or specify ODTYPE, the data type of the output image.
[filter-small] Invalid kernel size -- Too small
The kernel cannot be smaller than 3 x 1 or 1 x 3.
[filter-large] Invalid kernel size -- Too large
The specified kernel is larger than the input image.
[filter-minmax] Invalid values for MINVAL and MAXVAL
The range specified with MINVAL and MAXVAL is not valid. MAXVAL must be greater than MINVAL.
[filter-thrval] Invalid value for THRVAL
The value of THRVAL must be greater than zero.
[filter-kernel] Invalid kernel size
The boundary dimensions cannot be determined because the input kernel size is invalid.
[filter-smallb] Buffer too small for full kernel
The specified amount of RAM available is too small to load a full kernel into memory. Reduce the kernel size, or increase the value of MAXRAM and recompile.
[filter-windsiz] Input images do not have the same window size
Define the window dimensions such that they are of equal size.
[filter-mdtype] Median filters allow only BYTE or INTEGER*2 input
The data type of the input images can only be BYTE or INTEGER*2 when using a median filter.
[filter-odd] Invalid kernel size -- Kernel values must be odd
The kernel dimensions specified contain even numbers. Reset the values for KERNDIM with odd numbers.
[filter-medlim] Invalid kernel size -- Median filters limited to 51 by 51
The specified kernel dimensions exceed the limit for median filters. The maximum kernel size allowed for median filters is 51 by 51.
[filter-tdtype] THRVAL filters allow only BYTE or INTEGER*2 input
The data type of the input images can only be BYTE or INTEGER*2 when using a filter with the THRVAL activated (non-NULL value).
[filter-ftype] Invalid filter type
An invalid filter type was encountered. Memory may have been corrupted if this error is encountered.
[filter-alloc] Error allocating dynamic memory
A problem in allocating the dynamic memory required for filtering was encountered.

User Notes:

At the image edge, the pixel values are mirrored to fill the kernel area falling outside of the image. The center pixel of the kernel is not mirrored.
Example: IMAGE is a four line by four sample image:
```
	
	             A  B  C  D
		     E  F  G  H
		     I  J  K  L
		     M  N  O  P
```
A 3 x 3 kernel applied to pixel values A, D, M, and P would appear as:
```
	f  e  f      g  h  g       j  I  J       K  L  k
	b  A  B      C  D  c       n  M  N       O  P  o
	f  E  F	     G  H  g       j  i  j	 k  l  k
```
No scaling is performed in converting to the output data type. If the output from the filter calculation exceeds a bound of the ODTYPE specified, the output is set to that bound.