Isis 2 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.
Parm | Description | Default |
---|---|---|
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 |
ADDITIONAL NOTES:
Parm | Description |
---|---|
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. |
Contact us online at the Isis Support Center: http://isisdist.wr.usgs.gov