Image filtering functions


Typedefs

typedef enum _cpl_border_mode_ cpl_border_mode
 The border mode type.
typedef enum _cpl_filter_mode_ cpl_filter_mode
 The filter mode type.

Enumerations

enum  _cpl_border_mode_
 These are the supported border modes. For a kernel/mask of width 2n+1, the n left- and rightmost image columns do not have raw pixels for the whole kernel/mask. The same holds for the top and bottom image rows. The border mode defines the filtering of such border pixels. More...
enum  _cpl_filter_mode_
 These are the supported filter modes. More...

Functions

cpl_error_code cpl_image_filter (cpl_image *self, const cpl_image *other, const cpl_matrix *kernel, cpl_filter_mode filter, cpl_border_mode border)
 Filter an image using a kernel.
cpl_error_code cpl_image_filter_mask (cpl_image *self, const cpl_image *other, const cpl_mask *mask, cpl_filter_mode filter, cpl_border_mode border)
 Filter an image using a mask.

Detailed Description

This module provides functions to filter images.

The filtering modes (linear, median, morphological filtering) take the bad pixels map (bpm) into account to avoid them to corrupt their neighbours.

Synopsis:
   #include "cpl_image_filter.h"
Usage: define the following preprocessor symbols as needed, then include this file

Typedef Documentation

typedef enum _cpl_border_mode_ cpl_border_mode

The border mode type.

typedef enum _cpl_filter_mode_ cpl_filter_mode

The filter mode type.


Enumeration Type Documentation

enum _cpl_border_mode_

These are the supported border modes. For a kernel/mask of width 2n+1, the n left- and rightmost image columns do not have raw pixels for the whole kernel/mask. The same holds for the top and bottom image rows. The border mode defines the filtering of such border pixels.

CPL_BORDER_FILTER Filter the border using the reduced number of pixels. If in median filtering the number of pixels is even choose any one of the two central values.
CPL_BORDER_CROP Crop the filtered image.
CPL_BORDER_NOP Do not modify the border of the filtered image.
CPL_BORDER_COPY Copy the border of the raw image

enum _cpl_filter_mode_

These are the supported filter modes.

CPL_FILTER_LINEAR A linear filter. The kernel elements are used as weights like this:

    Kernel 1 2 3    Image        ...
           4 5 6         ... 1.0 2.0 3.0 ...
           7 8 9         ... 4.0 5.0 6.0 ...
                         ... 7.0 8.0 9.0 ...
                                 ...
    

The filtered value corresponding to the pixel whose value is 5.0 is: $\frac{(1*1.0+2*2.0+3*3.0+4*4.0+5*5.0+6*6.0+7*7.0+8*8.0+9*9.0)}{1+2+3+4+5+6+7+8+9}$

CPL_FILTER_AVERAGE An average filter, i.e. the output pixel is the arithmetic average of the surrounding (1 + 2 * hsizex) * (1 + 2 * hsizey) pixels. The cost per pixel is O(hsizex*hsizey). The two images may have different pixel types. When the input and output pixel types are identical, the arithmetic is done with that type, e.g. int for two integer images. When the input and output pixel types differ, the arithmetic is done in double precision when one of the two images have pixel type CPL_TYPE_DOUBLE, otherwise float is used.
CPL_FILTER_AVERAGE_FAST The same as CPL_FILTER_AVERAGE, except that it uses a running average, which will lead to a significat loss of precision if there are large differences in the magnitudes of the input pixels. The cost per pixel is O(1) if all elements in the kernel are used, otherwise the filtering is done as for CPL_FILTER_AVERAGE.
CPL_FILTER_MEDIAN A median filter. The pixel types of the input and output images must be identical. All border modes are supported.
CPL_FILTER_STDEV The filtered value is the standard deviation of the included input pixels.

       mask                  Image        ...
              1   0   1           ... 1.0 2.0 3.0 ...
              0   1   0           ... 4.0 5.0 6.0 ...
              1   0   1           ... 7.0 8.0 9.0 ...
                                          ...
       

The pixel with value 5.0 will have a filtered value of: std_dev(1.0, 3.0, 5.0, 7.0, 9.0)

CPL_FILTER_MORPHO A Morphological filter. The kernel elements are used as weights on the sorted values covered by the kernel:

    Kernel 1 2 3    Image        ...
           4 5 6         ... 4.0 6.0 5.0 ...
           7 8 9         ... 3.0 1.0 2.0 ...
                         ... 7.0 8.0 9.0 ...
                                 ...
    

The filtered value corresponding to the pixel whose value is 5.0 is: $\frac{(1*1.0+2*2.0+3*3.0+4*4.0+5*5.0+6*6.0+7*7.0+8*8.0+9*9.0)}{1+2+3+4+5+6+7+8+9}$


Function Documentation

cpl_error_code cpl_image_filter ( cpl_image *  self,
const cpl_image *  other,
const cpl_matrix *  kernel,
cpl_filter_mode  filter,
cpl_border_mode  border 
)

Filter an image using a kernel.

Parameters:
self Filtered image
other Image to filter
kernel Pixel weigths
filter CPL_FILTER_LINEAR, CPL_FILTER_MORPHO
border CPL_BORDER_FILTER
Returns:
CPL_ERROR_NONE or the relevant CPL error code
See also:
cpl_image_filter_mask
The kernel must have an odd number of rows and an odd number of columns and at least one non-zero element.

For a filtered pixel at least one input pixel with a non-zero weight must be available. Output pixels where this is not the case are set to zero and flagged as rejected.

In-place filtering is not supported, but if the two images have the same pixel type, then the input pixel buffer may overlap all but the 1+H first rows of the output pixel buffer, where 1+2*H is the number of rows in the kernel.

Supported modes: CPL_FILTER_LINEAR: CPL_BORDER_FILTER CPL_FILTER_MORPHO: CPL_BORDER_FILTER

Example:
     cpl_image_filter(filtered, raw, kernel, CPL_FILTER_LINEAR,
                                             CPL_BORDER_FILTER);
Beware that the 1st pixel - at (1,1) - in an image is the lower left, while the 1st element in a matrix - at (0,0) - is the top left. Thus to shift an image 1 pixel up and 1 pixel right with the CPL_FILTER_LINEAR and a 3 by 3 kernel, one should set to 1.0 the bottom leftmost matrix element

Possible _cpl_error_code_ set in this function:

cpl_error_code cpl_image_filter_mask ( cpl_image *  self,
const cpl_image *  other,
const cpl_mask *  mask,
cpl_filter_mode  filter,
cpl_border_mode  border 
)

Filter an image using a mask.

Parameters:
self Filtered image
other Image to filter
mask Pixels to use, if set to CPL_BINARY_1
filter CPL_FILTER_MEDIAN, CPL_FILTER_AVERAGE, CPL_FILTER_STDEV
border CPL_BORDER_FILTER
Returns:
CPL_ERROR_NONE or the relevant CPL error code
The mask must have an odd number of rows and an odd number of columns.

In standard deviation filtering the mask must have at least two elements set to CPL_BINARY_1, for others at least one element must be set to CPL_BINARY_1.

Supported pixel types are: CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE.

In median filtering the two images must have the same pixel type.

In standard deviation filtering a filtered pixel must be computed from at least two input pixels, for other filters at least one input pixel must be available. Output pixels where this is not the case are set to zero and flagged as rejected.

In-place filtering is not supported, but if the two images have the same pixel type, then the input pixel buffer may overlap all but the 1+h first rows of the output pixel buffer, where 1+2*h is the number of rows in the mask.

Supported modes: CPL_FILTER_MEDIAN: 1x1 mask or no bad pixels & mask all ones: CPL_BORDER_FILTER, CPL_BORDER_COPY, CPL_BORDER_NOP, CPL_BORDER_CROP. Otherwise: CPL_BORDER_FILTER CPL_FILTER_AVERAGE: CPL_BORDER_FILTER CPL_FILTER_AVERAGE_FAST: CPL_BORDER_FILTER CPL_FILTER_STDEV: CPL_BORDER_FILTER

Example:
     cpl_image_filter_mask(filtered, raw, mask, CPL_FILTER_MEDIAN,
                                                CPL_BORDER_FILTER);
To shift an image 1 pixel up and 1 pixel right with the CPL_FILTER_MEDIAN filter and a 3 by 3 kernel, one should set to CPL_BINARY_1 the bottom leftmost mask element - at row 3, column 1, i.e.
     cpl_mask * mask = cpl_mask_new(3, 3);
     cpl_mask_set(mask, 1, 1);

The mask required to do a 5 x 5 median filtering is created like this:

     cpl_mask * mask = cpl_mask_new(5, 5); 
     cpl_mask_not(mask);

Possible _cpl_error_code_ set in this function:


Generated on Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7