Binary Morphology

Functions
int	rapp_morph_worksize_bin (int width, int height)
	Compute the minimum size of the working buffer needed by the binary morphological functions.
int	rapp_morph_erode_rect_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int wrect, int hrect, void *restrict work)
	Erosion with a rectangular structuring element.
int	rapp_morph_dilate_rect_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int wrect, int hrect, void *restrict work)
	Dilation with a rectangular structuring element.
int	rapp_morph_erode_diam_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int radius, void *restrict work)
	Erosion with a diamond structuring element.
int	rapp_morph_dilate_diam_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int radius, void *restrict work)
	Dilation with a diamond structuring element.
int	rapp_morph_erode_oct_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int radius, void *restrict work)
	Erosion with an octagon structuring element.
int	rapp_morph_dilate_oct_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int radius, void *restrict work)
	Dilation with an octagon structuring element.
int	rapp_morph_erode_disc_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int radius, void *restrict work)
	Erosion with a approximately disc-shaped structuring element.
int	rapp_morph_dilate_disc_bin (uint8_t *restrict dst, int dst_dim, const uint8_t *restrict src, int src_dim, int width, int height, int radius, void *restrict work)
	Dilation with an approximately disc-shaped structuring element.

---

Detailed Description

Overview

These functions perform dilation and erosion on binary images using pre-defined structuring elements (SEs for short). Four different SE shapes are available:

1. Rectangular solid bricks with sides 1 - 63 pixels.
2. Right-angle diamonds with a radius between 2 and 32 pixels.
3. Regular octagons with a radius between 2 and 32 pixels.
4. Discs with a radius between 2 and 32 pixels.

By radius we mean half the width of the axis-aligned bounding box of the shape, rounded up to the nearest integer. For example, a 3x3 square is said to have the radius 2.

The rectangle and diamond shapes are exact. Octagons cannot be represented exactly on the pixel grid, but they are optimal approximations with respect to the euclidian error. The disc shapes are sub-optimal approximations, meaning that the error is greater than the minimum error. The error is nevertheless small – around one pixel for larger discs.

Performance

The various structuring element shapes are decomposed into smaller operations using separation and logarithmic decomposition. This, combined with the bit-parallel operations possible on binary images, makes it feasible to use very large structuring elements. See the benchmarks for actual performance figures.

Usage

All functions need a user-allocated working buffer. The minimum size in bytes of the buffer is given by rapp_morph_worksize_bin(), and must be aligned on rapp_alignment boundaries. As with most other RAPP functions, the images must also be aligned.

Padding

The user is responsible for padding the source buffer. The padding needed depends on the size of the structuring element, and may thus be different in vertical and horizontal directions for rectangular structuring elements. For them, the required padding is bounded by min(side / 2, 16), where side is the size of the structuring element in that direction, horizontally and vertically, and side / 2 is rounded down to the nearest integer. For other objects, the padding is bounded by min(radius - 1, 16). If the source buffer is padded with values other than all-zeros or all-ones the behaviour is undefined.

Next section: Border Padding

---

Function Documentation

int rapp_morph_worksize_bin	(	int	width,
		int	height
	)

Compute the minimum size of the working buffer needed by the binary morphological functions.

Parameters:

	width	The image width in pixels.
	height	The image height in pixels.

Returns:

The minimum buffer size in bytes, or a negative error code on error.

int rapp_morph_erode_rect_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	wrect,
		int	hrect,
		void *restrict	work
	)

Erosion with a rectangular structuring element.

All SE sizes up to and including 63x63 pixels are supported, except the 1x1 degenerate case.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	wrect	The width of the SE rectangle, in the range 2 - 63.
	hrect	The height of the SE rectangle, in the range 2 - 63.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.

int rapp_morph_dilate_rect_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	wrect,
		int	hrect,
		void *restrict	work
	)

Dilation with a rectangular structuring element.

All SE sizes up to and including 63x63 pixels are supported, except the 1x1 degenerate case.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	wrect	The width of the SE rectangle, in the range 2 - 63.
	hrect	The height of the SE rectangle, in the range 2 - 63.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.

int rapp_morph_erode_diam_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	radius,
		void *restrict	work
	)

Erosion with a diamond structuring element.

All SE radii from 2 up to 32 pixels are supported.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	radius	The diamond radius, in the range 2 - 32.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.

int rapp_morph_dilate_diam_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	radius,
		void *restrict	work
	)

Dilation with a diamond structuring element.

All SE radii from 2 up to 32 pixels are supported.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	radius	The diamond radius, in the range 2 - 32.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.

int rapp_morph_erode_oct_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	radius,
		void *restrict	work
	)

Erosion with an octagon structuring element.

All SE radii from 2 up to 32 pixels are supported.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	radius	The diamond radius, in the range 2 - 32.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.

int rapp_morph_dilate_oct_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	radius,
		void *restrict	work
	)

Dilation with an octagon structuring element.

All SE radii from 2 up to 32 pixels are supported.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	radius	The diamond radius, in the range 2 - 32.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.

int rapp_morph_erode_disc_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	radius,
		void *restrict	work
	)

Erosion with a approximately disc-shaped structuring element.

All SE radii from 2 up to 32 pixels are supported.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	radius	The diamond radius, in the range 2 - 32.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.

int rapp_morph_dilate_disc_bin	(	uint8_t *restrict	dst,
		int	dst_dim,
		const uint8_t *restrict	src,
		int	src_dim,
		int	width,
		int	height,
		int	radius,
		void *restrict	work
	)

Dilation with an approximately disc-shaped structuring element.

All SE radii from 2 up to 32 pixels are supported.

Parameters:

[out]	dst	Destination pixel buffer.
	dst_dim	Destination buffer row dimension.
[in]	src	Source pixel buffer with padding.
	src_dim	Source buffer row dimension.
	width	The image width in pixels.
	height	The image height in pixels.
	radius	The diamond radius, in the range 2 - 32.
	work	Internal working buffer.

Returns:

A negative error code on error, zero otherwise.