Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions

Public Release
8.1.0
8.0.0
7.2.0
7.1.0
7.0.0
6.0.0
3.9.0
3.5.0

ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Application Documentation

kernfilter

Standard View | TOC | Home

Filter a cube through a kernel

Description
Categories
Groups
Examples
History

Description

This program uses a kernel gathered from an input file to filter a cube. The intent of the program is to allow a flexible, user-defined kernel to be applied to an image. This program is not recommended for cubes with significant numbers of special pixels as it will create more special pixels. A group of pre-made kernels has been provided, but the procedure to create a custom kernel is outlined below.

A kernel follows the rules and regulations of the Isis PVL (parameter value language). This means that several keywords must be inserted into the text document which will become the custom kernel. Any text editor should allow you to create a kernel, though the program will only read files with the .txt extension. In addition, there are some specifications that must be met.

A sample kernel file will appear in the form 
 
    Group=Kernel 
      Samples=2 
      Lines=1 
      Weight=1 
      Data= (1, -1)
    EndGroup
The "group" keyword should equal Kernel (Group=Kernel). This lets the program know that it is the users intent that the text file is used as a kernel.

The "lines" and "samples" keywords should match the amount of data that is supplied in the data keyword. In this example, there are 2 samples worth of data and 1 line worth. The keywords above thus reflect these values.

The "weight" is applied to all of the values in the kernel. It is often set to a fraction that allows for averaging, but it is a value that is used differently by each type of filter simulated by the kernel. Since the above filter uses no averaging, the weight is simply 1.

The "data" defines a set of multiplicative constants. These multiplicative constants are the weights that the kernfilter will use on the input image. In our example, assume that the DNs being examined are 10 and 20. The first DN (10) would be multiplied by the first weight (1). The second DN (20) would be multiplied by the second weight (-1). The two products (10 and -20) would then be added together and the resultant sum (-10) would be output. The set of data should be enclosed in parentheses. For organizational purposes, one may insert as much or as little white space as they desire but they must separate each constant with a comma.

Finally, the document should be finished with the keyword "EndGroup" to signify that no more information is provided.

Categories

Parameter Groups

Files

Name Description
FROM Input cube to be filtered
TO Output cube
KERNEL The kernel that describes the filter to be applied

Files: FROM

Description

Use this parameter to select the filename. All bands within the file will be filtered.

Type cube
File Mode input
Filter *.cub

Files: TO

Description

This file will contain the results of the filter

Type cube
File Mode output
Pixel Type real
Filter *.cub

Files: KERNEL

Description

Use this parameter to select the file to be used as the kernel. The input kernel is by default found in the "kernels" directory and includes several examples that can be used to filter images.

Type filename
File Mode input
Default Path $ISISROOT/appdata/templates/kernels/
Filter *.txt

Examples

Example 1

Using the highpassCircle5x5.txt kernel

Description

This example assumes that a kernel named "highpassCircle5x5.txt" (which is provided with the program) exists in the "kernels" file that is created by default. The program does not actually run a highpass algorithm on the cube. Instead, it weighs the pixels with a common algorithm that adds all of the weighted pixel values together and outputs that sum as the center pixel of the boxcar. The weights, which are provided by the user-specified parameter "kernel" define the characteristics of that final sum. In this example, the kernel "highpassCircle5x5.txt" (which is provided with the program) is selected. The kernel weights are as follows: 
        0  -1  -1  -1   0
       -1  -1  -1  -1  -1
       -1  -1  24  -1  -1     x .04
       -1  -1  -1  -1  -1
        0  -1  -1  -1   0
Thus, the highpass filter is simulated. The center pixel will be multiplied by 24. Then this value will be added to the values of its surrounding pixels (all of these values will either have a sign change since they were multiplied by -1 in this filter or they will be 0, since 0 and -1 are the only weight values that the filter holds, except for the center pixel). Finally, after all of the addition has been done, the final sum of all of the weights that were multiplied by either 24, or -1, or 0, will be multiplied by .04, which equals 1/25. The reason all of the pixels are multiplied by 1/25 is that there are 25 spots in the 5 by 5 kernel, and thus the image will be normalized.

Command Line

kernfilter from= peaks.cub to=highpass.cub kernel=highpassCircle5x5.txt
The kernfilter program has been loaded with a kernel that will simulate a circular highpass filter with a 5 x 5 boxcar.

GUI Screenshot

kernfilter gui

Example GUI

Screenshot of the GUI with parameters set to simulate the highpass filter with a 5 x 5 circular boxcar.

Input Image

The image before the filter

Input image before kernfilter.

Parameter Name: FROM

This is the unfiltered image. Note the low frequency data (albedo) in the image. The highpass filter that this kernel mimics is intended to filter this type of data out.

Output Image

The image after the filter

Output image after kernfilter

Parameter Name: TO

The filtered image. Just as an actual 5 x 5 circular highpass filter would do, this kernel has removed albedo, allowing the user to see more terrain. Since a 5x5 filter is considered relatively small, features which are considered relatively small will still be visible.

Example 2

Using the smoothPyramid5x5.txt kernel

Description

This example assumes that a kernel named "smoothPyramid5x5.txt" (which is provided with the program) exists in the "kernels" file that is created by default. The program simulates a smoothing algorithm that takes an average of the DNs in the boxcar. The kernel weights pixels that are nearest to the center higher than those at the edges of the boxcar. The kernel weights are as follows 
 
          1  2  3  2 1 
          2  4  6  4  2
            3  6  9  6  3      x  1/81 
          2  4  6  4  2 
          1  2  3  2  1
The pixels in the boxcar are assigned weights that inversely reflect their distance from the center of the boxcar. The pixel at the very center will be multiplied by 9 and then added to all of the values that were multiplied by the other weights in the boxcar. Note that all of the weights add up to 81. This is why the final output is divided by 81; it allows the center pixel to be an average of the weights. Thus, the blur appears as though a smoothing algorithm applying weight in a pyramidal fashion had been applied.

Command Line

kernfilter from= peaks.cub to=smooth.cub kernel=smoothPyramid5x5.txt
This example has loaded the smoothPyramid5x5.txt kernel, which will smooth the input image using weights that are dispersed in a pyramidal fashion. The boxcar is 5 x 5.

GUI Screenshot

kernfilter gui

Example GUI

Screenshot of the GUI with parameters set to perform the smoothing filter with a 5 x 5 boxcar.

Input Image

The image before the filter

Input image before kernfilter.

Parameter Name: FROM

This is the image as it was taken originally with no smoothing.

Output Image

The image after the filter

Output image after kernfilter

Parameter Name: TO

The image after the filter. Although possibly hard to detect, everything about the pictures is a little blurred, and smoother, than in the original. A larger filter size would further increase this effect.

Example 3

Using the derivativeNWtoSE2x2.txt kernel

Description

This example assumes that a kernel named "derivativeNWtoSE2x2.txt" (which is provided with the program) exists in the "kernels" file that is created by default. This program serves the purpose of bringing out areas of high contrast. It does so by finding the difference of 2 pixels on a diagonal from each other. The weights are as follows 
 
          1   0 
          0  -1  x 1.0
The top left pixel receives the value of itself minus the pixel down right of itself. The other two pixesl do not matter. Anywhere where is significant change from the top left to the bottom right then shows it with brighter or darker pixels than the surrounding gray where there was little difference and the DNs are at or close to zero.

Command Line

kernfilter from=peaks.cub to=derivative.cub kernel=derivativeNWtoSE2x2.txt
The kernfilter program has been loaded with a kernel that will find the difference between 2 diagonal pixels.

GUI Screenshot

kernfilter gui

Example GUI

Screenshot of the GUI with parameters set to perform the derivative from NW to SE with a 2x2 boxcar.

Input Image

The image before the filter

Input image before kernfilter.

Parameter Name: FROM

This is the image as it was taken originally.

Output Image

The image after the filter

Output image after kernfilter

Parameter Name: TO

The processed image now appears to have a light source in the northwest and shadows and bright spots in areas of significant contrast in the original.

History

Drew Davidson2004-07-26 Original version
Drew Davidson2004-07-27 Added application test
Drew Davidson2004-08-16 Added examples
Elizabeth Miller2006-07-24 Moved kernel files to the $base/templates/kernels folder
Mackenzie Boyd2009-07-27 Added error checking for kernel input, modified special pixel handling to null resultant pixel, added example, added application test, changed pixel type to real.