PixelList Handling

Functions to create, access and modify IPixelList PIXELLIST handles. More...

Topics
	IPixelList Interface
	Dynamic pixel data list.

Typedefs
typedef void *	PIXELLIST
	CVB dynamic pixel data list handle.

Functions
PIXELLIST	ConcatenatePixelLists (PIXELLIST PixelListA, PIXELLIST PixelListB)
	Creates a new IPixelList by concatenating two pixel lists.
cvbbool_t	CopyPixelList (PIXELLIST Source, PIXELLIST &Target)
	Copy a complete pixel list.
PIXELLIST	CreatePixelList (cvbdim_t Dimension)
	Creates a new empty IPixelList object.
cvbbool_t	SeparatePixels (PIXELLIST PixelList, const double *ProjectionVector, double Locality)
	Thin-out the PixelList in-place based on the given Locality prioritized by the ProjectionVector.
cvbbool_t	SortPixelsByPosition (PIXELLIST PixelList, cvbval_t X, cvbval_t Y)
	Sorts the PixelList in-place in a direction defined by the unit vector (X, Y).
cvbbool_t	SortPixelsByValue (PIXELLIST PixelList)
	Sorts the PixelList in-place in descending order of gray scale values.
cvbbool_t	SortPixelsEx (PIXELLIST PixelList, const double *ProjectionVector)
	Sort the PixelList in-place using a ProjectionVector.
cvbbool_t	TransformPixelListCoordinates (PIXELLIST PixelList, TCoordinateMap CS)
	Transforms the PixelList in-place using the provided coordinate map CS.
cvbbool_t	TransformPixelListMatrix (PIXELLIST PixelList, TMatrix A, double OffsetX, double OffsetY)
	Transforms the PixelList in-place using a provided matrix A and offset vector (OffsetX, OffsetY).

Detailed Description

Functions to create, access and modify IPixelList PIXELLIST handles.

Typedef Documentation

PIXELLIST

typedef void* PIXELLIST

CVB dynamic pixel data list handle.

The PIXELLIST is a reference counted OBJ handle. PIXELLIST objects normally only provide the IPixelList interface.

Basic Factory Function

---

PIXELLIST CreatePixelList(cvbdim_t Dimension)

---

Function Documentation

ConcatenatePixelLists()

PIXELLIST ConcatenatePixelLists	(	PIXELLIST	PixelListA,
		PIXELLIST	PixelListB )

Creates a new IPixelList by concatenating two pixel lists.

This function creates a new IPixelList with the the size of both pixel lists combined and copies the Pixel elements first from PixelListA into the new one and then the Pixel elements from PixelListB.

Note

The given PixelListA and PixelListB must have the same number of components (PixelListDimension).

Release the returned IPixelList via ReleaseObject if not needed anymore.

Parameters

[in]	PixelListA	First pixel list handle.
[in]	PixelListB	Second pixel list handle.

Returns

Newly created IPixelList object handle; nullptr if

• PixelListA is invalid
• PixelListB is invalid
• PixelListA and PixelListB have different PixelListDimension.

CopyPixelList()

cvbbool_t CopyPixelList	(	PIXELLIST	Source,
		PIXELLIST &	Target )

Copy a complete pixel list.

If Target contains a valid handle to a IPixelList object, the list is checked for dimensional compatibility. If the dimensions match (PixelListDimension), then Target is cleared (RemoveAllPixels). The __Pixel__s from Source are copied to Target. If Target is not a valid IPixelList, then a new list will be created and filled.

Note

If Target was newly created, release the object via ReleaseObject if not needed anymore.

Parameters

[in]	Source	Source pixel list to copy.
[in,out]	Target	Pixel list to copy into or newly created pixel list.

Returns

true if successful; false if

• Source is invalid
• Target is valid and has differing dimension from Source

CreatePixelList()

PIXELLIST CreatePixelList

(

cvbdim_t

Dimension

)

Creates a new empty IPixelList object.

An IPixelList contains __Pixel__s defined through at least a coordinate pair (x and y). It may also contain up to 254 custom __Component__s with arbitrary interpretation.

Note

Release the returned IPixelList via ReleaseObject when it is no longer needed.

Parameters

[in]

Dimension

Number of Pixel __Component__s each pixel element has. Valid values are in the range [2 .. 256].

Returns

Handle of the created IPixelList object; nullptr on error.

See also

IPixelList

SeparatePixels()

cvbbool_t SeparatePixels	(	PIXELLIST	PixelList,
		const double *	ProjectionVector,
		double	Locality )

Thin-out the PixelList in-place based on the given Locality prioritized by the ProjectionVector.

First the PixelList is sorted via SortPixelsEx(PixelList, ProjectionVector). __Pixel__s coming first in the sorted IPixelList are prioritized. All __Pixel__s lying inside the Locality of a prioritized Pixel are removed from the PixelList.

Note

The distance for the Locality is calculated in L1 norm which is not the Euclidean distance. Here the distance of the x- and y-distances are checked individually for performance reasons. Thus the Locality is a square and not a circle.

Attention

The array pointed to by ProjectionVector must have at least PixelListDimension elements!

Parameters

[in]	PixelList	Pixel list handle of object to be thinned-out.
[in]	ProjectionVector	Pointer to array of double Components of the sort-direction vector; must have at least PixelListDimension elements.
[in]	Locality	Positive minimum L1 distance in pixels between two neighboring __Pixel__s.

Returns

true if successful; false if

• PixelList is invalid
• ProjectionVector is nullptr
• Locality is smaller or equal to 0.

Example

If we have an IPixelList with x, y and quality __Component__s and we want to apply the Locality based on higher quality, then we can call:

#include <iCVCImg.h>
#include <CVCError.h>
 
cvbres_t SeparatePixelsByQuality(PIXELLIST PixelList, double Locality)
{
  if(!IsPixels(PixelList))
    return CVC_ERROR(CVC_E_NOPIXELLIST);
  if(PixelListDimension(PixelList) < 3)
    return CVC_ERROR(CVC_E_NOTENOUGHDATA);
 
  static const double QualityProjection[] = { 0, 0, -1 }; // quality descending
  if(!SeparatePixels(PixelList, QualityProjection, Locality))
    return CVC_ERROR(CVC_E_PARAMETER); // locality invalid
    
  return CVC_ERROR(CVC_E_OK);
}

See also

SortPixelsEx

SortPixelsByPosition()

cvbbool_t SortPixelsByPosition	(	PIXELLIST	PixelList,
		cvbval_t	X,
		cvbval_t	Y )

Sorts the PixelList in-place in a direction defined by the unit vector (X, Y).

Parameter Examples

Sort Direction	X	Y
Y axis ascending	0	1
45° from top/left to right bottom	1	1

Parameters

[in]	PixelList	Pixel list handle of object to be sorted.
[in]	X	X sort direction vector.
[in]	Y	Y sort direction vector.

Returns

true if successful, false if PixelList is invalid.

See also

SortPixelsEx

SortPixelsByValue()

cvbbool_t SortPixelsByValue

(

PIXELLIST

PixelList

)

Sorts the PixelList in-place in descending order of gray scale values.

In other words the PixelList is sorted based on its third Component.

Parameters

[in]

PixelList

Pixel list handle of object to be sorted.

Returns

true if successful; false if

• PixelList is invalid
• The number of components (PixelListDimension) of PixelList is less than 3.

See also

SortPixelsEx

SortPixelsEx()

cvbbool_t SortPixelsEx	(	PIXELLIST	PixelList,
		const double *	ProjectionVector )

Sort the PixelList in-place using a ProjectionVector.

The list's Pixel elements are sorted by their inner product using the ProjectionVector. This is the generalized variant of SortPixelsByPosition which only sorts by the first two components x and y and SortPixelsByValue which sorts by the third component.

Attention

The ProjectionVector must have at least PixelListDimension elements!

Parameter Examples

Sort Direction	ProjectionVector
Rising X axis	[1, 0, .. ]
Falling Z axis	[0, 0, -1, .. ]
45° from top/left to right bottom	[1, 1, .. ]

Only the relevant part up to the needed component index is shown. Minimal length must be honored and the omitted values are set to 0.

Parameters

[in]	PixelList	Pixel list handle of object to be sorted.
[in]	ProjectionVector	Pointer to array of double __Component__s of the vector; must have at least PixelListDimension elements.

Returns

true if successful, false if

• PixelList is invalid.
• ProjectionVector is nullptr.

See also

SortPixelsByPosition, SortPixelsByValue

TransformPixelListCoordinates()

cvbbool_t TransformPixelListCoordinates	(	PIXELLIST	PixelList,
		TCoordinateMap	CS )

Transforms the PixelList in-place using the provided coordinate map CS.

Only the first two components of PixelList are updated (x and y). Any other remaining components are not affected.

Calculation

Parameters

[in]	PixelList	Pixel list handle of object to be transformed.
[in]	CS	Coordinate system to be used for the transformation.

Returns

true if successful; false if PixelList is invalid.

See also

TransformPixelListMatrix

TransformPixelListMatrix()

cvbbool_t TransformPixelListMatrix	(	PIXELLIST	PixelList,
		TMatrix	A,
		double	OffsetX,
		double	OffsetY )

Transforms the PixelList in-place using a provided matrix A and offset vector (OffsetX, OffsetY).

See TransformPixelListCoordinates for detailed information on the calculation (where CS consists of A and (OffsetX and OffsetY)).

Parameters

[in]	PixelList	Pixel list handle of object to be transformed.
[in]	A	Matrix (2x2) to be used for the transformation.
[in]	OffsetX	X component for translation.
[in]	OffsetY	Y component for translation.

Returns

true if successful; false if PixelList is invalid.

See also

TransformPixelListCoordinates