no.hiof.imagepr.filters
Class LocalHistogramFilter

java.lang.Object
  no.hiof.imagepr.filters.LocalHistogramFilter

All Implemented Interfaces:

no.hiof.imagepr.filters.ImageFilter

public class LocalHistogramFilter

extends java.lang.Object

implements no.hiof.imagepr.filters.ImageFilter

This class contain two methods which filter an image using local histogram equalization. The difference between these two methods is that one method receives and returns an image, the other method receives and returns a matrix. If you call the matrix-method, the matrix should be the intensityvalues of an intensityimage or the V-values of a HSV-image. This is the most common way to filter images using local histogram equalization. Although you can also use the matrix-method to filter the R-, G- and B-components in a RGB-image or the H- and/or S-component of a HSV-image if that is what best serve your application.

The user has three option of how the edges should be handled (By "edges" it's ment the pixels in the input-image that are so close to the edges that the local-histogram-mask can't be placed so the pixel is in center of the mask):

1. All edge-pixels get the same specific grayscale-intensity. This mean that the image will be croped, and there will be a frame around the filtered image.
2. The egdes are croped. This mean that the filtered image is smaller than the original image.
3. The egdes are filtered too. This mean that the a larger image is created and the original image is placed in the middel of the new one. All pixels that are outside the original image get the intensity-vaule of the pixel in the original image that are closest to the outside-pixel. Then the method described in the the previous point is being used on the new image. The filtered image has the same size as the original image.

This filter is implemented in a quite efficient way. This is done by just creating a new histogram for every row, not for every pixel. For all pixels, except for the first pixel on a row, the histogram is updated instead of recreated.

This gives the following estimate of how long time the filter will use to process the image:

- If the edges are filtered (point 3 above):  a(X * x * y) + b(X * Y * x) + c(64 * X * Y)

- Otherwise (point 1 and 2 above):  a((X - x) * x * y) + b((X - x) * (Y - y) * x) + c(64 * (X - x) * (Y - y))


X is the heigth of the image.

Y is the width of the image.

x is the heigth of the mask.

y is the width of the mask.

a, b and c are constants.

It's important to notice that this is only a rough estimate, and must of course be multiplied by a faktor that depends on your hardware and OS.

Pseudocode

If the user wants to filter an intensityimage, the intensityvalues of the image are filtered using local histogram equalization. If the user wants to filter a colorimage, the image is convered into a HSV-image (if isn't a HSV-image already), then the V-component of the image are filtered using local histogram equalization.

1. Make an array of 256 short-variabels (one for every possible intensity-value). Name this array sum.
2. If the user want to filter the edges too, then enlarge the image. How this is done is explaned above.
3. For every pixel in the image (going from top to buttom in the outer loop, and from left to right in the inner loop):
   1. If masks left edge is against the left egde of the image, then all set elements of sum to 0. Go througth every pixel in the mask, and increase the element of the array sum that has the same index as the intensity-value of the pixel by 1. This makes a histogram for the intensity-values of the image.
      
      Else update the histogram: 1) Go througth the the pixels in the image that are no longer in the mask, and decrease the element of the array sum that has the same index as the intensity-value of the pixel by 1. 2) Go througth the the pixels in the image that just has becomed a part of the mask, and increase the element of the array sum that has the same index as the intensity-value of the pixel by 1.
      
      Set the corresponding pixel of the output to count * 255 / maskSize, where count is the sum of all elements of the array sum that has an index equal to or lower than the intensity-value of center-pixel of the mask, and maskSize is the number of pixels in the mask.
4. If the user want to has the same intensity on all pixels in the egdes, then set all the edge-pixels to this intensity-value. Else decrease the size of the image by croping the edges.

Usage

1. Create a LocalHistogramFilter-objekt.
2. Set the filterparameters (maskHeight, maskWidth and edgeType). This can be done by giving the values as parameters to the constuctor, or by using the methods setMaskHeight, setMaskWidth, setEdgeType and setFilterParam (the first three set one parameter each, the last one sets all three parameters at once). If you don't set the parameters the default parameters are used (maskHeight = maskWidth = 3 and edgeType = FILTER_EDGES).
3. Filter an image by calling the method filter. The method takes an image as parameter. The image can either be an image-object or a matrix. The method returns the filtered image. The returned image is an image-object or a matrix depending on how the method was called.

Please notice that an LocalHistogramFilter-object only stores the filterparameters. It is not able to store the image itself.

Currently this filter can handle images of type IntensityImage, RGBImage, HSIImage and HSVImage. In all others cases the filter will return a null-pointer. The filter also return a null-pointer if the filtering-process for some reason failed.

Authors: Algoritm and testing by Øystein Igeland and Magnus Komperød. Implemented by Magnus Komperød.

Field Summary

static int	BLACK_EDGES The edges will be croped when the image is filtered.
static int	CROP_EDGES The edges will be croped when the image is filtered.
static int	DARK_GRAY_EDGES The edges will be croped when the image is filtered.
static int	FILTER_EDGES The edges will be filtered when the image is filtered.
static int	GRAY_EDGES The edges will be croped when the image is filtered.
static int	LIGHT_GRAY_EDGES The edges will be croped when the image is filtered.
static int	WHITE_EDGES The edges will be croped when the image is filtered.

Constructor Summary

LocalHistogramFilter()
Constuctor that sets the filterparameters to the default values (maskHeight = maskWidth = 3 and edgeType = FILTER_EDGES)

LocalHistogramFilter(int maskHeight, int maskWidth, int edgeType)
Constructor that sets the filterparameters to the values specified by the user.

Method Summary

no.hiof.imagepr.Image	filter(no.hiof.imagepr.Image image) Filter an image using local-histogram-equalization.
short[][]	filter(short[][] matrix) Filter a matrix using local-histogram-equalization.
int	getEdgeType()
int	getMaskHeight()
int	getMaskWidth()
int	setEdgeType(int type) Sets the type of edge that the filtered image will get.
int	setFilterParam(int maskHeight, int maskWidth, int edgeType) Update the filterparameters (maskHeight, maskWidth and edgeType)
int	setMaskHeight(int height) Sets the maskheight.
int	setMaskWidth(int width) Sets the maskwidth.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CROP_EDGES

public static final int CROP_EDGES

The edges will be croped when the image is filtered.

See Also:

Constant Field Values

FILTER_EDGES

public static final int FILTER_EDGES

The edges will be filtered when the image is filtered.

See Also:

Constant Field Values

BLACK_EDGES

public static final int BLACK_EDGES

The edges will be croped when the image is filtered. A black frame will be added to the filtered image so that the filtered image is as big as the input-image.

See Also:

Constant Field Values

DARK_GRAY_EDGES

public static final int DARK_GRAY_EDGES

The edges will be croped when the image is filtered. A dark gray frame will be added to the filtered image so that the filtered image is as big as the input-image.

See Also:

Constant Field Values

GRAY_EDGES

public static final int GRAY_EDGES

The edges will be croped when the image is filtered. A gray frame will be added to the filtered image so that the filtered image is as big as the input-image.

See Also:

Constant Field Values

LIGHT_GRAY_EDGES

public static final int LIGHT_GRAY_EDGES

The edges will be croped when the image is filtered. A light gray frame will be added to the filtered image so that the filtered image is as big as the input-image.

See Also:

Constant Field Values

WHITE_EDGES

public static final int WHITE_EDGES

The edges will be croped when the image is filtered. A white frame will be added to the filtered image so that the filtered image is as big as the input-image.

See Also:

Constant Field Values

Constructor Detail

LocalHistogramFilter

public LocalHistogramFilter()

Constuctor that sets the filterparameters to the default values (maskHeight = maskWidth = 3 and edgeType = FILTER_EDGES)

LocalHistogramFilter

public LocalHistogramFilter(int maskHeight,
                            int maskWidth,
                            int edgeType)

Constructor that sets the filterparameters to the values specified by the user.

Parameters:

maskHeight - Must be an odd number, and equal to or greater than 3.

maskWidth - Must be an odd number, and equal to or greater than 3.

edgeType - Must be BLACK_EDGES, DARK_GARY_EDGES, GRAY_EDGES, LIGHT_GRAY_EDGES, WHITE_EGDES, FILTER_EDGES, CROP_EDGES or an integer in the range 0 - 255.

Method Detail

setMaskHeight

public int setMaskHeight(int height)

Sets the maskheight.

Parameters:

height - Must be an odd number, and equal to or greater than 3.

Returns:

0 if update is successful, else 1.

setMaskWidth

public int setMaskWidth(int width)

Sets the maskwidth.

Parameters:

width - Must be an odd number, and equal to or greater than 3.

Returns:

0 if update is successful, else 1.

setEdgeType

public int setEdgeType(int type)

Sets the type of edge that the filtered image will get.

Parameters:

type - Must be BLACK_EDGES, DARK_GARY_EDGES, GRAY_EDGES, LIGHT_GRAY_EDGES, WHITE_EGDES, FILTER_EDGES, CROP_EDGES or an integer in the range 0 - 255.

Returns:

0 if update is successful, else 1.

setFilterParam

public int setFilterParam(int maskHeight,
                          int maskWidth,
                          int edgeType)

Update the filterparameters (maskHeight, maskWidth and edgeType)

Parameters:

maskHeight - Must be an odd number, and equal to or greater than 3.

maskWidth - Must be an odd number, and equal to or greater than 3.

edgeType - Must be BLACK_EDGES, DARK_GARY_EDGES, GRAY_EDGES, LIGHT_GRAY_EDGES, WHITE_EGDES, FILTER_EDGES, CROP_EDGES or an integer in the range 0 - 255.

Returns:

If setMaskHeight failed to be set 1 is returned, if setMaskWidth failed to be set 2 is returned, if edgeType failed to be set 4 is returned. If several parameters failed to be set the corresponding sum is returned. 0 is returned if everything succeed.

getMaskHeight

public int getMaskHeight()

Returns:

The maskheight.

getMaskWidth

public int getMaskWidth()

Returns:

The maskwidth.

getEdgeType

public int getEdgeType()

Returns:

The edgetype.

filter

public no.hiof.imagepr.Image filter(no.hiof.imagepr.Image image)

Filter an image using local-histogram-equalization. This method can handle IntensityImage, RGBImage, HSIImage and HSVImage. If a different class of Image are received a null-pointer is returned.

Specified by:

filter in interface no.hiof.imagepr.filters.ImageFilter

Parameters:

image - The image to be filtered (input-image).

Returns:

The filtered image (output-image). If the method fails to filter the image, a null-pointer is returned.

filter

public short[][] filter(short[][] matrix)

Filter a matrix using local-histogram-equalization.

Specified by:

filter in interface no.hiof.imagepr.filters.ImageFilter

Parameters:

matrix - The matrix to be filtered. The matrix should be the intensityvalues of an intensityimage or the V-value of an HSV-image.

Returns:

The filtered matrix. If the method fails to filter the matrix, a null-pointer is retured.