Contour Code Processing

Functions
I32	contour8 (image *a, I32 x0, I32 y0, I32 dir, I32 thr, U32 lng, U32 **dst)
	Create Contour Code of a Shape at a Pixel Image (8-Connected). More...
void	cdisp (image *a, U32 *src, I32 col, void(*func)())
	Display Contour Code. More...
I32	ccxy (I32 *src, I32 *xy, I32 *tbl, U32 maxcount)
	Convert Contour Code (CC) into xy Array. More...
I32	edgecontours_from_edgeimage (image *src, I32 thr, I32 minlength, I32 maxcount, I32 *xylist, U8 *maglist, U8 *dirlist, I32 *nr)
	calculates all edge contours of an edge image More...
I32	subpixel_edgecontour (image *src, image *edg, I32 thr, I32 minlength, I32 maxcount, I32 *xylist, U8 *maglist, U8 *dirlist, I32 *nr)
	perform a subpixel precise calculation of all edge contours of an edge image More...
#define	cdisp_d(a, src, col)   cdisp(a, src, col, (void (*)())wpix)
	Draws Contour Code in a given Color. More...
#define	cdisp_x(a, src, col)   cdisp(a, src, col, (void (*)())xorpix)
	XORs a Contour Code of a given Color with an Image. More...

Detailed Description

Macro Definition Documentation

cdisp_d

#define cdisp_d	(		a,
			src,
			col
	)		cdisp(a, src, col, (void (*)())wpix)

The macro draws contour code as described in the cdisp() function using a given color.

cdisp_d() is a macro which calls cdisp() with basic function wpix() as an argument.

cdisp_x

#define cdisp_x	(		a,
			src,
			col
	)		cdisp(a, src, col, (void (*)())xorpix)

The macro XORscontour code as described in the cdisp() function with the image's underlying grey values and writes the result to the position.

cdisp_x() is a macro which calls cdisp() with basic function xorpix() as an argument.

Function Documentation

contour8()

I32 contour8	(	image *	a,
		I32	x0,
		I32	y0,
		I32	dir,
		I32	thr,
		U32	lng,
		U32 **	dst
	)

This function generates the contour code (CC) of an object or an edge starting at (x0, y0) in image variable a.

The function has the advantage that for a given object in the source image it is guaranteed that the generated contour will be closed unless one of the conditions described with the error code are met.

dir has two meanings:

• The value of dir indicates the direction in which the contour has been found (according to the contour code values from 0=up to 7=upper left). In other words: in the reverse direction must be at least one white pixel.
• The second meaning of dir is the direction of movement for the contour-following algorithm. dir > 0 means positive direction (counter-clockwise), dir < 0 means negative direction (clockwise). Negative values of dir are the logical NOT of the corresponding positive value (0..7). thr is the threshold for the underlying binarisation. If (pix < thr) the pixel pix is assumed to be black.

lng is the maximum code length allowed (number of bytes in memory for contour). Since additional information is stored, there must be at least (16 + lng) bytes of memory available. **dst is a handle for the destination address in memory. It will be updated to the next available address when the function finishes. The function will only take black pixels as contour pixels. For this reason the starting pixel (x0,y0) must be black. It must also be a contour pixel which means, that it must have at least one white neighbor. If all neighbors are white, it is a so called isolated pixel - no contour code will be generated.

Although the pointer to the destination is a U32 *, the contour code itself is stored as byte values.

Return values

-1	Invalid starting pixel (not black) - no contour code generated.
0	Isolated pixel or pixel inside object - no contour code generated.
1	Closed contour (end pixel = starting pixel / same direction).
2	Contour stops at left corner of image variable.
4	Contour stops at right corner of image variable.
8	Contour stops at upper corner of image variable.
16	Contour stops at lower corner of image variable.
32	Space exhausted (CC lenght > lng).

Some of the conditions could be true at the same time. (example: contour stops at the left upper corner of the image variable). In this case the individual codes will be added (example: 2+8 = 10).

Memory Consumption

None.

See also

cdisp().

cdisp()

void cdisp	(	image *	a,
		U32 *	src,
		I32	col,
		void(*)()	func
	)

This function displays the contour code data (CC) of an object or an edge starting at address src in image variable a. The contour will be displayed in color col. The nature of drawing is specified by passing the pointer (* func)() to cdisp(). The following macros use this function: cdisp_d(), cdisp_x(a, src, col), cdisp_o(a, src, col), cdisp_z(a, src, col).

Memory Consumption

None.

See also

contour8().

ccxy()

I32 ccxy	(	I32 *	src,
		I32 *	xy,
		I32 *	tbl,
		U32	maxcount
	)

This function converts contour code data (CC) of an object or an edge into a list of x/y-values stored beginning at address xy. src is the source contour code (CC), xy the x/y coordinate list where the function places its output and maxcount is the maximum number of coordinates to be written to xy.

tbl is a pointer to the following table:

int tbl[16] = { 0, 1, 1, 1, 0,-1,-1,-1, -1,-1, 0, 1, 1, 1, 0,-1};

The function returns the number of contour pixels or -1 on overflow for xy.

edgecontours_from_edgeimage()

I32 edgecontours_from_edgeimage	(	image *	src,
		I32	thr,
		I32	minlength,
		I32	maxcount,
		I32 *	xylist,
		U8 *	maglist,
		U8 *	dirlist,
		I32 *	nr
	)

This function calculates all contours from an edge image. If the input pixel value ≥ thr, the pixel is considered to belong to a contour.

The function outputs a list of pixellists, i.e. a number of pixellists following each other separated by the number of elements in the following xylist.

The following C-program may clarify the usage:

 I32 x, y, *xylist;
 I32 index, elements, i, j;

 xylist = (I32 *)vcmalloc(20000);
 edgecontours_from_edgeimage(&src, 10, 10, 10000, xylist, &n);

 index = 0;

 for(i=0; i<n; i++)
   {
    elements = xylist[2*index+0];
    index++;

   for(j=0; j< elements; j++)
     {
      x = xylist[2*(j+index)];
     y = xylist[2*(j+index) + 1];
      printf("j: %d x: %d y: %d\n", j, x, y);
      }

   index += elements;
   }

vcfree(xylist);

Parameters

src	pointer to image variable, must be of type IMAGE_VECTOR
thr	threshold for gradient binarization
maxcount	number of (x/y)-elements available in xylist
minlength	minimum required contour length
xylist	pointer to the list of xylist arrays for output
nr	number of contour pixellists in the output list (output)

The search algorithm is destructive, i.e. it clears all pixels that are found to zero in the gradient magnitude image. This should result in a completely empty gradient image, or at least one with all pixels below the threshold thr.

Return values

ERR_TYPE	wrong image type for src
ERR_MEMORY	out of memory for internal array (size = 2*src->dx+4 bytes)

See also

contour8(), subpixel_edgecontour().

subpixel_edgecontour()

I32 subpixel_edgecontour	(	image *	src,
		image *	edg,
		I32	thr,
		I32	minlength,
		I32	maxcount,
		I32 *	xylist,
		U8 *	maglist,
		U8 *	dirlist,
		I32 *	nr
	)

This function performs a subpixel precise calculation of all edge contours in an edge image. If the input pixel value ≥ thr, the pixel is considered to belong to a contour. The resulting x-/y-coordinates in the output pixel-list are of fixpoint type 15.7. If required, the output coordinates can be converted in floating-point coordinates by the following example C-program:

 float xf, yf;
 I32 *xylist;
 I32 index, elements, i, j;

 xylist = (I32 *)vcmalloc(20000);

 subpixel_edgecontour(&src, &gradient,  10, 100, 10000, xylist, &n);

 index = 0;

 for(i=0; i<n; i++)
   {
  elements = xylist[2*index+0];
  index++;

   for(j=0; j< elements; j++)
     {
    xf = (float)xylist[2*(j+index)]     / 128.0;
     yf = (float)xylist[2*(j+index) + 1] / 128.0;
    printf("j: %d xf: %f yf: %f\n", j, xf, yf);
    }

 index += elements;
 }

vcfree(xylist);

The function first makes a call to function edgecontours_from_edgeimage() to get all contour pixels from the edge image. Therefore the number of output contour pixels is the same as if the function edgecontours_from_edgeimage() had been called instead.

In order to get a subpixel result, the original grey image is analysed after this first step. For each element in the contour list the edge in the original image is searched in the direction of the edge gradient. The subpixel position is determined in this direction. This will result in non-integer values for x and y in general. (i.e. x and y will not be multiples of 128 in this particular fixpoint format). If the edge is vertical, the y-coordinate will mostly be an integer value and the x-coordinate will be subpixel-precise. For a horizontal edge it will be vice versa.

Parameters

src	pointer to image variable for original image (IMAGE_GREY)
edg	pointer to image variable for edge image (IMAGE_VECTOR)
thr	threshold for gradient binarization
minlength	minimum required contour length
maxcount	number of (x/y)-elements available in xylist
xylist	pointer to xylist array for output
maglist	pointer to magnitude array for output or NULL
dirlist	pointer to direction array for output or NULL
nr	number of contour pixellists in the output list (output)

The search algorithm is destructive, i.e. it clears all pixels that are found to zero in the gradient magnitude image. This should result in a completely empty gradient image, or at least one with all pixels below the threshold thr.

This function uses some interpolation tables which are allocated and calculated automatically for the first call of the function. The tables may be set by the user using the function AffineInitTable(1) (mode=1) and HoughInit(). Please make sure to call the function AffineDeinitTable() and HoughDeinit() when the tables are no longer needed.

Return values

ERR_TYPE	wrong image type for src
ERR_MEMORY	out of memory for internal array (size = 2*src->dx+4 bytes)

See also

edgecontours_from_edgeimage(), vc_draw_edgecontours_d().

Return values

ERR_MEMORY

if Memory Allocation fails.