Image Manager (CVCImg.dll) 14.1
PixelList Handling

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

Modules

 IPixelList Interface
 Dynamic pixel data list.
 

Typedefs

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

Functions

PIXELLIST ConcatenatePixelLists (PIXELLIST PixelListA, PIXELLIST PixelListB)
 Creates a new IPixelList by concatenating two pixel lists. More...
 
cvbbool_t CopyPixelList (PIXELLIST Source, PIXELLIST &Target)
 Copy a complete pixel list. More...
 
PIXELLIST CreatePixelList (cvbdim_t Dimension)
 Creates a new empty IPixelList object. More...
 
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. More...
 
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). More...
 
cvbbool_t SortPixelsByValue (PIXELLIST PixelList)
 Sorts the PixelList in-place in descending order of gray scale values. More...
 
cvbbool_t SortPixelsEx (PIXELLIST PixelList, const double *ProjectionVector)
 Sort the PixelList in-place using a ProjectionVector. More...
 
cvbbool_t TransformPixelListCoordinates (PIXELLIST PixelList, TCoordinateMap CS)
 Transforms the PixelList in-place using the provided coordinate map CS. More...
 
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). More...
 

Detailed Description

Functions to create, access and modify IPixelList PIXELLIST handles.

Typedef Documentation

◆ 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]PixelListAFirst pixel list handle.
[in]PixelListBSecond 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]SourceSource pixel list to copy.
[in,out]TargetPixel 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]DimensionNumber 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]PixelListPixel list handle of object to be thinned-out.
[in]ProjectionVectorPointer to array of double Components of the sort-direction vector; must have at least PixelListDimension elements.
[in]LocalityPositive 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))
if(PixelListDimension(PixelList) < 3)
static const double QualityProjection[] = { 0, 0, -1 }; // quality descending
if(!SeparatePixels(PixelList, QualityProjection, Locality))
return CVC_ERROR(CVC_E_PARAMETER); // locality invalid
}
#define CVC_ERROR(a)
Definition: CVCError.h:18
@ CVC_E_OK
No Error occurred.
Definition: CVCError.h:58
@ CVC_E_PARAMETER
Definition: CVCError.h:64
@ CVC_E_NOPIXELLIST
At least one of the input handles does not point to a valid pixel list.
Definition: CVCError.h:114
@ CVC_E_NOTENOUGHDATA
The amount of input data is insufficient for the requested operation.
Definition: CVCError.h:116
cvbdim_t PixelListDimension(PIXELLIST PixelList)
Gets the number of __Component__s in the given PixelList.
Definition: PixelListExports.cpp:744
cvbbool_t IsPixels(OBJ PixelList)
Verifies whether the given PixelList handle has an IPixelList object.
Definition: PixelListExports.cpp:493
void * PIXELLIST
CVB dynamic pixel data list handle.
Definition: CVTypes.h:97
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.
Definition: PixelListExports.cpp:1399
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]PixelListPixel list handle of object to be sorted.
[in]XX sort direction vector.
[in]YY 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]PixelListPixel 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]PixelListPixel list handle of object to be sorted.
[in]ProjectionVectorPointer 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]PixelListPixel list handle of object to be transformed.
[in]CSCoordinate 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]PixelListPixel list handle of object to be transformed.
[in]AMatrix (2x2) to be used for the transformation.
[in]OffsetXX component for translation.
[in]OffsetYY component for translation.
Returns
true if successful; false if PixelList is invalid.
See also
TransformPixelListCoordinates