USGS

Isis 2 Documentation


boxfilter Documentation

boxfilter - Three dimensional boxcar filter on cube data
Performs Boxcar filtering on 32-bit, 16-bit or 8-bit 3-D cube files

Box filtering involves replacing each pixel in the core area of
a cube with the average in a box.  When it is extended in several
simple ways, it becomes an efficient general purpose tool for cube
processing.

boxfilter will filter standard 3-dimensional ISIS cube file.  boxfilter
filters only core data.  Suffixes are excluded from the filtering
process, but are always propagated unchanged to the output file subject
to the SFROM subcube specifier.

For details on the box filter see the references:

      M. J. McDonnell, Box-Filtering Techniques, Computer Graphics
      and Image Processing, Vol. 17, 1981, pages 65-70

      E. M. Eliason and L. A. Soderblom, An Array Processing System
      for Lunar Geochemical and Geophysical Data,
      Porc. Lunar Sci. Conf. (8th) , 1977, pages 1163-1170.


A rectangular odd-dimensioned box of dimension (s,l,b) is centered at
the sample, line and band position (i,j,k), the sum of the points of
this box is contained in S(i,j,k) and the number of valid points in the
box is contained in N(i,j,k).  The parameters LOW and HIGH indicate the
range of valid data.  An input pixel is considered invalid if the DN
value is less than LOW or greater than HIGH.  Handling of invalid pixels
and special pixel values (NULL, SATURATED, etc...) are determined mostly
by the MINREPL, REPLACE and SPECIAL input parameters.  During the
filtering process, the resulting pixel may become invalid.  If the
entire box contains no valid pixels, then the output pixel will be set
to the value specified by MINREPL, which could be any of the five
special pixel values OR the pixel value at the center of the box.  Some
filters will set the value at the center of the box to a special value
as specified by the REPLACE parameter.  Note that results that exceed
the minimim or maximum possible representable value of the output file
are set to LOW_REPRESENTATION_SATURATION (LRS) and
HIGH_REPRESENTATION_SATURATION (HRS), respectively.

Whenever possible, the filter is computed in its native bit type, i.e.,
the stored value.  This reduces memory requirements and time required
to process the filter.  Note that the DIV, VAR, SUM, STD, STDZ and NOIS
filters are always processed as 32-bit REAL values because of the nature
of the filters.  The resulting output of the DIV, VAR and SUM filters
is always a cube of core type 3 (32-bit REAL values).

The following are some terms and definitions that are used in the help
sections for input parameters to boxfilter:

Equations for Filtering Operations:
-----------------------------------

Let:    i, j, k    = Sample, line and band postion of boxcar center
        P(i,j,k)   = Original DN value of input cube
        S(i,j,k)   = Sum of points over the box centered at i,j,k
        N(i,j,k)   = Number of valid points in the box centered at
                     i,j,k
        LPF(i,j,k) = Low pass component of the the box centered at
                     i,j,k


Terms:  NUL        = NULL special pixel value
        LIS        = LOW_INSTRUMENT_SATURATION special pixel value
        LRS        = LOW_REPRESENTATION_SATURATION special pixel value
        HRS        = HIGH_REPRESENTATION_SATURATION special pixel value
        HIS        = HIGH_INSTRUMENT_SATURATION special pixel value

PROGRAMMER: Kris Becker, USGS, Flagstaff, Az.

ParmDescriptionDefault
FROM
Input cube file name
  (default extension is .cub)
NONE
SFROM
Input subcube specifier
--
TO
Output cube file name
  (default extension is .cub)
NONE
FILTER
LPF  = low pass filter
LPFZ = low pass filter
       (invalid data only)
LPFV = low pass filter
       (valid data only)
HPF  = high pass filter
DIV  = divide filter
TRIM = no filter, trim cube
       boundry
NOIS = performs a despike
       algorithm
STD  = Noise despike
STDZ = Noise despike
VAR  = Variance filter
SUM  = Summation filter
NONE
SAMP
Odd value that specifies the
box size in the sample dimension
NONE
LINE
Odd value that specifies the
box size in the line dimension
NONE
BAND
Odd value that specifies the
box size in the band dimension
NONE
LOW
Valid data minimum value
--
HIGH
Valid data maximum value
--
NORM
Normalization parameter used
for HPF filter option ONLY.
0.0
ADD
Specifies a fraction of the
original pixel to add back to
the HPF.  Use only with the
HPF option.
0.0
MULT
Multiplicative constant applied
to result of HPF, LPF, VAR, DIV
and SUM filters
1.0
MIN
The minimum number of valid
points that a box filter must
contain for processing to occur.
1
FRACTION
The fraction of the box filter
that must have valid data for
processing to occur.
0.0
STDH
High noise tolerance value used
in STD and STDZ filter options.
1.5
STDL
Low noise tolerance value used
in STD and STDZ filter options.
--
TOLMIN
Scaled tolerance value.  Use
only with the STD and STDZ
filter options.  See
additional help for details.
0.0
TOL2H
High noise tolerance value used
only in the NOIS filter option.
(See additional help for
details.)
--
TOL2L
Low noise tolerance value used
only in the NOIS filter option.
(See additional help for
details.)
--
MINREPL
Value to replace input pixel
when less than MIN points in
box.  Used in ALL filters with
exceptions.  See additional
help for details.
"NUL"
REPLACE
Value to replace input pixel
when valid value cannot be
generated by the filter.  Used
in the LPFV, HPF, DIV, NOIS,
STD and STDZ filters with
exceptions.  See additional
help for details.
"NUL"
SPECIAL
Specifies which special pixels
to process in the filter.  Used
only in the LPF, LPFZ, NOIS,
SUM and STD filters.  (See
additional help for details.)
"ALL"
MEMORY
Amount of memory boxfilter
is allowed to allocate
expressed in megabytes.
--
FORCORD
Lets the user control the access
order of the filtering process.
0 - boxfilter determines it
1 - Band SeQuential
2 - Band Interleaved by Line
3 - Band Interleaved by Pixel
0

ADDITIONAL NOTES:

ParmDescription
FROM
Input cube file name.  If the file extension is omitted,
then ".cub" will be assumed.
SFROM
SFROM specifies the subcube using a single string for all
three dimensions of the cube.  The order of the three
dimensions is always "samples:lines:bands".
If a dimension is left blank, all the data for that
dimension is selected.  The default value of NULL for SFROM
selects the entire cube.

Any application below can be used for any dimension.
To select specific data from any dimension:
  "10-100(3):11,12,15-20:1-10(2)" =  This example will
select every third sample starting with sample 10 thru 100.
It selects lines 11 and 12, and 15-20. It selects every
other band, starting with band 1 thru 10.

There are special characters that can be used for
selecting a subcube efficiently, such as "*","#", and "~".
For examples type "help sfrom" in TAE.

**NOTE** For more examples and explanation of the many
features of the SFROM parameter, tutor the sfrom.pdf or
refer to Introduction To ISIS, Section 6, of the ISIS
User's Manual **
TO
Output cube file name.  If the file extension is omitted,
then ".cub" will be assumed.
FILTER
Let:
P(i,j,k)    = Original DN of input image at line-sample
              i,j,k
S(i,j,k)    = Sum of valid points over the box centered at
              i,j,k
N(i,j,k)    = Number of valid points in the box at i,j,k
S2(i,j,k)   = Sum of square of valid points in box at i,j,k
LPF(i,j,k)  = Low pass filter component at i,j,k
HPF(i,j,k)  = High Pass component at i,j,k
DIV(i,j,k)  = Divide filter component at i,j,k
STDEV(i,j,k)= Standard deviation of box window at i,j,k
O(i,j,k)    = Ouput pixel value at i,j,k

Equations:

LPF(i,j,k)   = MULT*S(i,j,k)/N(i,j,k)
HPF(i,j,k)   = NORM*(1-ADD)+P(i,j,k)*MULT*(1+ADD) -
               LPF(i,j,k)*MULT
DIV(i,j,k)   = MULT*(P(i,j)/LPF(i,j))-NORM
STDEV(i,j,k) = SQRT(S2(i,j,k)*N(i,j,k) -
               S(i,j,k)**2)/N(i,j,k)


Descriptions of Filter Options
------------------------------
LPF   = Low Pass filtering. Valid, invalid and selected
        special pixel values are always replaced by the
        result of low pass filtering.

LPFZ  = Low Pass filtering. Only invalid and selected
        special pixel values are replaced by the result of
        low pass filtering.  Valid pixels remain unchanged.

LPFV  = Low Pass filtering. Only valid pixels are replaced
        by the result of low pass filtering. Invalid pixels
        and special pixel values remain unchanged.

HPF   = High Pass filtering. Invalid and special pixel data
        are not included in the filtering process. This
        option will take the low-end invalid data and
        convert it to LRS, and take the high-end invalid
        data and convert it to HRS.

DIV   = Divide filtering. Invalid data and special pixel
        values are not included in the filtering process.
        This option will take the low-end invalid data and
        convert it to LRS, and take the high-end invalid
        data and convert it to HRS.  On a zero divide, the
        result will be NUL.

TRIM  = Trim option. This option does not perform any type
        of a filtering operation.  The option simply counts
        the number of valid values in the box.  If the
        number of valid points in the box is less than the
        minimum number specified by the user (FRACTION or
        MIN) then the center value of the box will be
        set to the specified by REPLACE parameter.

NOIS  = If the difference between the original sample,
        P(i,j,k), and the average value of the box filter,
        LPF(i,j,k), is greater than TOL2H OR if the
        difference between the original sample, P(i,j,k)
        and the average value of the box filter, LPF(i,j,k)
        is negative and its absolute value is greater than
        TOL2L then the point is considered noise and is
        replaced by LPF(i,j,k), otherwise P(i,j,k) will
        remain unchanged from the input pixel.  This option
        is used to despike a cube.

STD   = If the difference between the original sample,
        P(i,j,k) and the average value of the box,
        LPF(i,j,k) is greater that the number of standard
        deviations specified by STD, then the result will be
        the average value, else the output pixel at i,j,k
        will remain unchanged from the input pixel.  This
        option used to despike an image

        O(i,j,k) = P(i,j,k)
        If (P(i,j,k)-LPF(i,j,k)) > STDH*STDEV(i,j,k) and
           ABS(P(i,j,k)-LPF(i,j,k)) > TOLMIN then
             O(i,j,k) = LPF(i,j,k)

        If (LPF(i,j,k)-P(i,j,k)) > STDL*STDEV(i,j,k) and
           ABS(P(i,j,k)-LPF(i,j,k)) > TOLMIN then
             O(i,j,k) = LPF(i,j,k)

STDZ  = If the difference between the orignal sample,
        P(i,j,k) and the average value of the box,
        LPF(i,j,k) is greater that the number of standard
        deviations specified by STD, then the result will
        set to zero, else the output pixel at (i,j,k) will
        remain unchanged from the input pixel.  This option
        used to despike an image.

        O(i,j,k) = P(i,j,k)

        If (P(i,j,k)-LPF(i,j,k)) > STDH*STDEV(i,j,k) and
           ABS(P(i,j,k)-LPF(i,j,k)) > TOLMIN then
             O(i,j,k) = NULL

        If (LPF(i,j,k)-P(i,j,k)) > STDL*STDEV(i,j,k) and
           ABS(P(i,j,k)-LPF(i,j,k)) > TOLMIN then
             O(i,j,k) = NULL

VAR   = Variance filter.  Output is a normalized variance of
        the box at center of (i,j,k).

SUM   = Sum filter.  Output is the sum of all valid pixels
        in the box at center of (i,j,k)


SAMP
Specifies the size of the box along the SAMPLE dimension.
Must be an odd number.
LINE
Specifies the size of the box along the LINE dimension.
Must be an odd number.
BAND
Specifies the size of the box along the BAND dimension.
Must be an odd number.
LOW
The LOW parameter is supplied to further limit the input
data range that is considered valid for processing.  A
value that is less than LOW is processed as if it were a
special pixel value.  If this parameter is the TAE NULL
parameter value, then the minimium valid value for the
pixel type is used.
HIGH
The HIGH parameter is supplied to further limit the input
data range that is considered valid for processing.  A
value that is greater than HIGH is processed as if it were
a special pixel value.  If this parameter is the TAE NULL
parameter value, then the maximum valid value for the
pixel type is used.
NORM
Normalization coefficient for the HPF filter option.  Since
the result of the high pass may be negative, this parameter
will be added to the result of the difference between the
average of the box, LPF(i,j,k), and the original pixel
value, P(i,j,k).
ADD
Specifies the fraction of the original cube pixel value to
add to the result of the high pass filter. An ADD value of
0 will produce only the high pass component to the output
cube. An ADD value of 1 will add the original cube pixel
value to the result of the high pass component.
MULT
This parameter is multiplied to the result of the HPF,
LPF,or VAR filtering. For more details, see the
equations in the FILTER parameter description.
MIN
This parameter and parameter FRACTION have the same effect
only MIN specifies number of points and FRACTION
specifies a fraction of the box.
FRACTION
If there are less points in the box than this fraction
then the result will be handled as specified by the MINREPL
parameter.  FRACTION and MIN should not both be specified.
STDH
STDH and STDL parameters represent tolerance values used
in the STD and STDZ filter options.

If the difference between the original sample, P(i,j,k), and
the average value of the box filter, LPF(i,j,k), is greater
then STDH standard deviations of the box window, then the
point is considered a noisy pixel.

If the difference between the original sample, P(i,j,k), and
the average value of the box filter, LPF(i,j,k), is less
than STDL standard deviations of the box window, then the
point is considered a noisy pixel.

STDH and STDL typically ranges from 1.0 to 1.5. To remove
more noise from an image, make STDH and STDL =1.0, to remove
less noise from an image make STDH and STDL =1.5.  Sometimes
if STDH and STDL are too small, then real data will be
considered noise.

IF STDL is not provided on input from the user, then the
program will set STDL equal to STDH and the low and high
difference will be matched.
STDL
See help on STDH for information of STDL parameter
TOLMIN
Minimum tolerance value used in the STD and STDZ filter
options.  If the difference between the original pixel,
P(i,j,k), and the average value of the box filter,
LPF(i,j,k), is less than than TOLMIN then the the output
pixel at (i,j,k) will remain unchanged from the input pixel.
Without this safeguard, very uniform image areas (low
standard deviation) will be excessively smoothed, creating
areas of constant DN.
TOL2H
Tolerance value used only in the NOIS filter option. If the
difference between the original sample, P(i,j,k) and the
average value of the box filter, LPF(i,j,k) is greater than
TOL2H then the point is considered noise and is replaced by
LPF(i,j,k).
TOL2L
Tolerance value used only in the NOIS filter option. If the
difference between the original sample, P(i,j,k) and the
average value of the box filter, LPF(i,j,k) is negative and
its absolute value is greater than TOL2L then the point is
considered noise and is replaced by LPF(i,j,k).
MINREPL
Filters: ALL with exceptions note below

This parameter is used to specify what the replacement value
for the case where there are not enough points in the box as
specified by the MIN parameter.  Note that if the point at
the center of the box is already a special pixel value, it
will be preserved.

For some filters, a MINREPL=NONE would not make sense.  If
"NONE" is specified for the following filters, boxfilter
will override it with the NUL value (all other special
pixels values are allowed):

  SUM  - Propagation of data value would yield incorrect
         interpretation for obvious reasons.

  DIV  - Requires a special pixel because of scale
         differences and obviously incorrect interpretation
         of propagation of an existing data value.

  VAR  - Propagation of data value would yield incorrect
         interpretation for obvious reasons.

  HPF  - Propagation of data value would yield incorrect
         interpretation because of the nature of change the
         filter generates, a rather large shift in data
         range (scale).
REPLACE
Filters: DIV, NOIS, STD, STDZ

This parameter is used to specify what the replacement value
for occurances in filters where valid data needs to be
replaced by a special pixel value.  This condition occurs
when (a) the result cannot be computed because of
insufficient data (e.g., NOIS and STD has only one point in
box), (b) computation of filter value would result in
invalid operation (e.g., divide by 0.0 in DIV, NOIS, STD),
and (c) the function of the filter is to identify cases
where results are set to a special pixel (STDZ).

This parameter will not be used in cases where the
resulting computation of the filter operation cannot be
represented in the output file, i.e., result exceeds the
minimum or maximum representable value in the output file.
For these cases, LRS and HRS are used, respectively.

A value of REPLACE=NONE will result in the input pixel value
to be propagated to the output file unaltered except for the
DIV filter option.  This option has significant data
representation differences that does not allow for the input
pixel value to be preserved.
SPECIAL
Values:  NONE, [+-] NUL, [+-] LIS, [+-] LRS, [+-] HRS,
         [+-] HIS, ALL
Filters: LPF, LPFZ, NOIS, SUM, VAR, STD

This parameter is used to specify how special pixels are
processed in certain filters.  It allows the user to control
the treatment in filters that typically replace all special
pixels with the result of the filtering operation.  Note
that non-special pixel values are always treated as before
for all filters.

For example, the NOIS filter previously treated special
pixels as noise and replaced all of them with the LPF of the
box.  This would almost always result in fabrication of data
on limbs, for instance, where pixel values are typically the
NULL value.  With this new parameter, setting SPECIAL=NONE
will result in replacement of only data this is not a
special pixel value.

Each of the special pixel denotions can be preceded by a or - sign that allows inclusion or exclusion of the special
pixel.  Hence, an equation of sorts, mask, can be generated
from combinations of these denotions.  Spaces or commas can
be used to seperate denotions and the existance of these
imply a + sign.  Here are a few examples:

  SPECIAL="NONE+LRS+HRS"
  SPECIAL="LRS+HRS"
  SPECIAL="LRS,HRS"
  SPECIAL="ALL-NUL-LIS-HIS"
  Translation:  Only replace LRS and HRS special pixels.
                NUL, LIS and HIS are propagated to the
                output file unaltered.  All the examples
                result in the same mask.

  SPECIAL="NUL"
  Translation:  Replace only NUL special pixels.

  SPECIAL="NONE"
  Translation:  Do not replace any special pixel value.
                Only valid data values are subject to
                alteration in the filter.


Note that this parameter is a string that has no valid
qualifier attached to it.  Therefore, there is a possibility
of entering an invalid value.  If this occurs, boxfilter
will terminate with an appropriate message.
MEMORY
Number of megabytes of memory that boxfilter is allowed to
allocate.  The default is around 12MB.  This could be used
in cases where the default is not sufficient to process
a given file because of size.  Or, it could be used in an
attempt to increase efficiency by making more data readily
available (i.e., buffered) during processing.  For systems
that do not have large amounts of memory (RAM or swap), it
could be set to smaller values.

Note that simply using large amounts of memory may not
actually increase efficiency because it could invoke
excessive system paging.  There is a limit as to what an
efficient amount of memory usage would be for any
application.
FORCORD
The user may force the access order of the processing
phase by setting this parameter.  It may be useful
for efficient processing where boxfilter determines
the order and it may not be as efficient.

Last updated: Jan 31 2005
File: pdfs2.html

Contact us online at the Isis Support Center: http://isisdist.wr.usgs.gov

ISIS Documentation Home Page