morphology

morphology — morphological operators, rank filters and related image analysis

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

enum                VipsOperationMorphology;
int                 vips_morph                          (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         VipsOperationMorphology morph,
                                                         ...);
int                 vips_rank                           (VipsImage *in,
                                                         VipsImage **out,
                                                         int width,
                                                         int height,
                                                         int index,
                                                         ...);
int                 vips_countlines                     (VipsImage *in,
                                                         double *nolines,
                                                         VipsDirection direction,
                                                         ...);
int                 vips_median                         (VipsImage *in,
                                                         VipsImage **out,
                                                         int size,
                                                         ...);
int                 im_label_regions                    (VipsImage *test,
                                                         VipsImage *mask,
                                                         int *segments);

Description

The morphological functions search images for particular patterns of pixels, specified with the mask argument, either adding or removing pixels when they find a match. They are useful for cleaning up images --- for example, you might threshold an image, and then use one of the morphological functions to remove all single isolated pixels from the result.

If you combine the morphological operators with the mask rotators im_rotate_imask45(), for example) and apply them repeatedly, you can achieve very complicated effects: you can thin, prune, fill, open edges, close gaps, and many others. For example, see `Fundamentals of Digital Image Processing' by A. Jain, pp 384-388, Prentice-Hall, 1989 for more ideas.

Beware that VIPS reverses the usual image processing convention, by assuming white objects (non-zero pixels) on a black background (zero pixels).

The mask you give to the morphological functions should contain only the values 0 (for background), 128 (for don't care) and 255 (for object). The mask must have odd length sides --- the origin of the mask is taken to be the centre value. For example, the mask:

3 3 128 255 128 255 0 255 128 255 128

applied to an image with im_erode(), will find all black pixels 4-way connected with white pixels. Essentially, im_dilate() sets pixels in the output if any part of the mask matches, whereas im_erode() sets pixels only if all of the mask matches.

See im_andimage(), im_orimage() and im_eorimage() for analogues of the usual set difference and set union operations.

Details

enum VipsOperationMorphology

typedef enum {
	VIPS_OPERATION_MORPHOLOGY_ERODE,
	VIPS_OPERATION_MORPHOLOGY_DILATE,
	VIPS_OPERATION_MORPHOLOGY_LAST
} VipsOperationMorphology;

More like hit-miss, really.

See also: vips_morph().

VIPS_OPERATION_MORPHOLOGY_ERODE

true if all set

VIPS_OPERATION_MORPHOLOGY_DILATE

true if one set

VIPS_OPERATION_MORPHOLOGY_LAST


vips_morph ()

int                 vips_morph                          (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         VipsOperationMorphology morph,
                                                         ...);

Performs a morphological operation on in using mask as a structuring element.

The image should have 0 (black) for no object and 255 (non-zero) for an object. Note that this is the reverse of the usual convention for these operations, but more convenient when combined with the boolean operators. The output image is the same size as the input image: edge pxels are made by expanding the input image as necessary.

Mask coefficients can be either 0 (for object) or 255 (for background) or 128 (for do not care). The origin of the mask is at location (m.xsize / 2, m.ysize / 2), integer division. All algorithms have been based on the book "Fundamentals of Digital Image Processing" by A. Jain, pp 384-388, Prentice-Hall, 1989.

For VIPS_OPERATION_MOPHOLOGY_ERODE, the whole mask must match for the output pixel to be set, that is, the result is the logical AND of the selected input pixels.

For VIPS_OPERATION_MOPHOLOGY_DILATE, the output pixel is set if any part of the mask matches, that is, the result is the logical OR of the selected input pixels.

See the boolean operations vips_andimage(), vips_orimage() and vips_eorimage() for analogues of the usual set difference and set union operations.

Operations are performed using the processor's vector unit, if possible. Disable this with --vips-novector or IM_NOVECTOR.

in :

input image

out :

output image

mask :

morphology with this mask

morph :

operation to perform

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_rank ()

int                 vips_rank                           (VipsImage *in,
                                                         VipsImage **out,
                                                         int width,
                                                         int height,
                                                         int index,
                                                         ...);

vips_rank() does rank filtering on an image. A window of size width by height is passed over the image. At each position, the pixels inside the window are sorted into ascending order and the pixel at position index is output. index numbers from 0.

It works for any non-complex image type, with any number of bands. The input is expanded by copying edge pixels before performing the operation so that the output image has the same size as the input. Edge pixels in the output image are therefore only approximate.

For a median filter with mask size m (3 for 3x3, 5 for 5x5, etc.) use

vips_rank( in, out, m, m, m * m / 2 );

The special cases n == 0 and n == m * m - 1 are useful dilate and expand operators.

See also: vips_conv(), vips_median(), vips_spcor().

in :

input image

out :

output image

width :

width of region

height :

height of region

index :

select pixel

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_countlines ()

int                 vips_countlines                     (VipsImage *in,
                                                         double *nolines,
                                                         VipsDirection direction,
                                                         ...);

Function which calculates the number of transitions between black and white for the horizontal or the vertical direction of an image. black<128 , white>=128 The function calculates the number of transitions for all Xsize or Ysize and returns the mean of the result Input should be one band, 8-bit.

See also: vips_morph(), vips_zerox(), vips_conv().

in :

input image

nolines :

output average number of lines

direction :

count lines horizontally or vertically

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error.

vips_median ()

int                 vips_median                         (VipsImage *in,
                                                         VipsImage **out,
                                                         int size,
                                                         ...);

A convenience function equivalent to:

vips_rank( in, out, size, size, (size * size) / 2 );

See also: vips_rank().

in :

input image

out :

output image

size :

size of region

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

im_label_regions ()

int                 im_label_regions                    (VipsImage *test,
                                                         VipsImage *mask,
                                                         int *segments);

im_label_regions() repeatedly scans test for regions of 4-connected pixels with the same pixel value. Every time a region is discovered, those pixels are marked in mask with a unique serial number. Once all pixels have been labelled, the operation returns, setting segments to the number of discrete regions which were detected.

mask is always a 1-band IM_BANDFMT_UINT image of the same dimensions as test.

This operation is useful for, for example, blob counting. You can use the morphological operators to detect and isolate a series of objects, then use im_label_regions() to number them all.

Use im_histindexed() to (for example) find blob coordinates.

See also: im_histindexed()

test :

image to test

mask :

write labelled regions here

segments :

return number of regions here

Returns :

0 on success, -1 on error.

See Also

boolean