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]	PixelList	Pixel list handle of object to which the Pixel is added.
[in]	Components	Pointer 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]	PixelList	Pixel list handle of object to retrieve the Pixel __Component__s from.
[in]	Index	Index of the Pixel in the PixelList to be retrieved. Valid range is [0 .. PixelListCount[ (exclusive).
[out]	X	Variable to receive the x component.
[out]	Y	Variable to receive the y component.
[out]	Z	Variable 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]	PixelList	Pixel list handle of object to retrieve the pixel components from.
[in]	Index	Index of the Pixel in the PixelLIst to be retrieved. Valid range is [0 .. PixelListCount[ (exclusive).
[out]	Components	Pointer 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))
    return CVC_ERROR(CVC_E_NOPIXELLIST);
  if(Index < 0 || Index >= PixelListCount(PixelList))
    return CVC_ERROR(CVC_E_INVALIDINDEX);
    
  std::vector<double> components(PixelListDimension(PixelList));
  if(!ListPixelEx(PixelList, Index, components.data())
    return CVC_ERROR(CVC_E_ERROR); // unexpected error
    
  Components.swap(components);
  return CVC_ERROR(CVC_E_OK);
}

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]	PixelList	Pixel list handle of object to be modified.
[in]	Index	Index of the Pixel to be modified. Range is [0 .. PixelListCount[ (exclusive).
[in]	Components	Pointer 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]

PixelList

Pixel 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]

PixelList

Pixel 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]

PixelList

Pixel 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]	PixelList	Pixel list handle of object to remove from.
[in]	Index	Index 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]	PixelList	Pixel list handle of object to resize.
[in]	Size	Positive number of pixels to be at most in the PixelList.

Returns

true if successful; false if PixelList is invalid or Size is negative.