Image Manager (CVCImg.dll) 15.0
IPixelList Interface

Dynamic pixel data list. More...

Functions

cvbbool_t AddPixel (PIXELLIST PixelList, const double *Components)
 Adds the Pixel consisting of the given Components to the end of the given PixelList. More...
 
cvbbool_t ListPixel (PIXELLIST PixelList, cvbval_t Index, cvbval_t &X, cvbval_t &Y, cvbval_t &Z)
 Gets a Pixel's X, Y and Z __Component__s from the given PixelList at the given Index. More...
 
cvbbool_t ListPixelEx (PIXELLIST PixelList, cvbval_t Index, double *Components)
 Gets a Pixel's __Component__s from the PixelList at the given Index. More...
 
cvbbool_t ModifyListPixel (PIXELLIST PixelList, cvbval_t Index, const double *Components)
 Sets the Components of a Pixel in the PixelList at the given Index. More...
 
cvbval_t PixelListCount (PIXELLIST PixelList)
 Gets the number of __Pixel__s in the given PixelList. More...
 
cvbdim_t PixelListDimension (PIXELLIST PixelList)
 Gets the number of __Component__s in the given PixelList. More...
 
cvbbool_t RemoveAllPixels (PIXELLIST PixelList)
 Clears the PixelList. More...
 
cvbbool_t RemovePixel (PIXELLIST PixelList, cvbval_t Index)
 Removes a single entry from the PixelList at the given Index. More...
 
cvbbool_t TruncatePixelList (PIXELLIST PixelList, cvbval_t Size)
 Resizes the PixelList to have at most the given Size. More...
 

Detailed Description

Dynamic pixel data list.

A pixel list's Pixel consists of at least two components x and y, which are accessible via index 0 and 1 via ListPixelEx. Optionally up to 254 user defined data components can be added. The number of components is specified at the pixel list's creation via the Dimension parameter of CreatePixelList. The Dimension cannot be changed afterwards and every Pixel in the pixel list then has Dimension __Component__s.

If a CVB function returns a PIXELLIST see its documentation about the presence and meaning of additional __Component__s.

Note
If you want to be able to use the ListPixel function you need to create a pixel list with a Dimension of at least 3.

Function Documentation

◆ AddPixel()

cvbbool_t AddPixel ( PIXELLIST  PixelList,
const double *  Components 
)

Adds the Pixel consisting of the given Components to the end of the given PixelList.

Attention
The Pixel Component__s are being copied from the __double array pointed to by Components. Ensure that the array pointed to by Components has at least PixelListDimension elements.
Parameters
[in]PixelListPixel list handle of object to which the Pixel is added.
[in]ComponentsPointer to array of __Component__s. Must have at least PixelListDimension elements.
Returns
true if successful, false if
  • PixelList is invalid
  • Components is nullptr
See also
CreatePixelList, ModifyListPixel, PixelListDimension

◆ ListPixel()

cvbbool_t ListPixel ( PIXELLIST  PixelList,
cvbval_t  Index,
cvbval_t &  X,
cvbval_t &  Y,
cvbval_t &  Z 
)

Gets a Pixel's X, Y and Z __Component__s from the given PixelList at the given Index.

This form interprets the Pixel Component__s as x, y and z. Often the z __Component is used for the __Pixel__s value (e.g. intensity for gray value images).

Parameters
[in]PixelListPixel list handle of object to retrieve the Pixel __Component__s from.
[in]IndexIndex of the Pixel in the PixelList to be retrieved. Valid range is [0 .. PixelListCount[ (exclusive).
[out]XVariable to receive the x component.
[out]YVariable to receive the y component.
[out]ZVariable to receive the z component (maybe pixel value).
Returns
true if successful; false if
  • PixelList is invalid.
  • Index is out of range.
  • The number of components (PixelListDimension) of PixelList is less than 3.
See also
PixelListDimension, ListPixelEx, PixelListCount.

◆ ListPixelEx()

cvbbool_t ListPixelEx ( PIXELLIST  PixelList,
cvbval_t  Index,
double *  Components 
)

Gets a Pixel's __Component__s from the PixelList at the given Index.

The Component__s at index 0 is x and the one at index 1 is y. Any other available __Component is custom and dependent on the function that created the IPixelList PIXELLIST.

Attention
The Pixel Component__s are being copied into the __double array given by the Components pointer argument. Ensure that the size of the double array given to Components is large enough to contain all of a Pixel's __Component__s (see PixelListDimension).
Parameters
[in]PixelListPixel list handle of object to retrieve the pixel components from.
[in]IndexIndex of the Pixel in the PixelLIst to be retrieved. Valid range is [0 .. PixelListCount[ (exclusive).
[out]ComponentsPointer to a double array to be filled with the Pixel's components. Must have at least PixelListDimension elements.
Returns
true if successful, false if
  • PixelList is invalid
  • Index is out of range
  • Components is nullptr
Example
#include <vector>
#include <iCVCImg.h>
#include <CVCError.h>
cvbres_t GetPixelListComponents(PIXELLIST PixelList, cvbval_t Index, std::vector<double> &Components)
{
if(!IsPixels(PixelList))
if(Index < 0 || Index >= PixelListCount(PixelList))
std::vector<double> components(PixelListDimension(PixelList));
if(!ListPixelEx(PixelList, Index, components.data())
return CVC_ERROR(CVC_E_ERROR); // unexpected error
Components.swap(components);
}
#define CVC_ERROR(a)
Definition: CVCError.h:18
@ CVC_E_OK
No Error occurred.
Definition: CVCError.h:58
@ CVC_E_ERROR
Definition: CVCError.h:61
@ CVC_E_NOPIXELLIST
At least one of the input handles does not point to a valid pixel list.
Definition: CVCError.h:114
@ CVC_E_INVALIDINDEX
An index value in an indexed access exceeded its limits.
Definition: CVCError.h:175
cvbval_t PixelListCount(PIXELLIST PixelList)
Gets the number of __Pixel__s in the given PixelList.
Definition: PixelListExports.cpp:801
cvbdim_t PixelListDimension(PIXELLIST PixelList)
Gets the number of __Component__s in the given PixelList.
Definition: PixelListExports.cpp:744
cvbbool_t ListPixelEx(PIXELLIST PixelList, cvbval_t Index, double *Components)
Gets a Pixel's __Component__s from the PixelList at the given Index.
Definition: PixelListExports.cpp:714
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
See also
ModifyListPixel, PixelListDimension, ListPixel, PixelListCount

◆ ModifyListPixel()

cvbbool_t ModifyListPixel ( PIXELLIST  PixelList,
cvbval_t  Index,
const double *  Components 
)

Sets the Components of a Pixel in the PixelList at the given Index.

This overwrites all the Components of the Pixel at the given Index.

Attention
The Pixel Component__s are being copied from the __double array pointed to by Components. Ensure that the array pointed to by Components has at least PixelListDimension elements.
Parameters
[in]PixelListPixel list handle of object to be modified.
[in]IndexIndex of the Pixel to be modified. Range is [0 .. PixelListCount[ (exclusive).
[in]ComponentsPointer to array of __Component__s to be set. Must have at least PixelListDimension elements.
Returns
true if successful; false if
  • PixelList is invalid
  • Index is out of range
  • Components is nullptr
See also
ListPixelEx, AddPixel, PixelListCount, PixelListDimension

◆ PixelListCount()

cvbval_t PixelListCount ( PIXELLIST  PixelList)

Gets the number of __Pixel__s in the given PixelList.

Parameters
[in]PixelListPixel list handle of object to query.
Returns
Number of __Pixel__s in the PixelList; -1 on error.

◆ PixelListDimension()

cvbdim_t PixelListDimension ( PIXELLIST  PixelList)

Gets the number of __Component__s in the given PixelList.

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

Parameters
[in]PixelListPixel list handle of object to query.
Returns
Dimension (number of Component__s per __Pixel); 0 on error.

◆ RemoveAllPixels()

cvbbool_t RemoveAllPixels ( PIXELLIST  PixelList)

Clears the PixelList.

After calling this function PixelListCount returns 0.

Note
The PixelList is emptied, but not destroyed. Release it via ReleaseObject when it is no longer needed.
Parameters
[in]PixelListPixel list handle of object to clear.
Returns
true if successful; false if PixelList was empty before or PixelList was invalid.

◆ RemovePixel()

cvbbool_t RemovePixel ( PIXELLIST  PixelList,
cvbval_t  Index 
)

Removes a single entry from the PixelList at the given Index.

Parameters
[in]PixelListPixel list handle of object to remove from.
[in]IndexIndex in PixelList where to the remove the pixel.
Returns
true if successful; false if Index was out of range or PixelList was invalid.

◆ TruncatePixelList()

cvbbool_t TruncatePixelList ( PIXELLIST  PixelList,
cvbval_t  Size 
)

Resizes the PixelList to have at most the given Size.

Note
If Size is larger or equal to PixelListCount, this function does nothing and returns true.
Parameters
[in]PixelListPixel list handle of object to resize.
[in]SizePositive number of pixels to be at most in the PixelList.
Returns
true if successful; false if PixelList is invalid or Size is negative.