Represents a single CVB plane. More...

Typedefs
typedef void *	CVPLANE
	CVB plane handle. More...

Enumerations
enum	{ CVCD_X = 0 , CVCD_Y = 1 , CVCD_Z = 2 }

enum	CVCPlaneRole { CVCPR_Undefined = -1 , CVCPR_PixMono = 0 , CVCPR_PixRGB_R , CVCPR_PixRGB_G , CVCPR_PixRGB_B , CVCPR_PixYUV_Y , CVCPR_PixYUV_U , CVCPR_PixYUV_V , CVCPR_PixHSV_H , CVCPR_PixHSV_S , CVCPR_PixHSV_V , CVCPR_PixLAB_L , CVCPR_PixLAB_A , CVCPR_PixLAB_B , CVCPR_PixConfidence , CVCPR_CoordCartesian_X = 0x1000 , CVCPR_CoordCartesian_Y , CVCPR_CoordCartesian_Z , CVCPR_CoordCartesian_W , CVCPR_CoordPolar_Rho , CVCPR_CoordPolar_Phi , CVCPR_CoordCylindrical_Rho , CVCPR_CoordCylindrical_Phi , CVCPR_CoordCylindrical_Z , CVCPR_CoordSpherical_Rho , CVCPR_Normal_X = 0x1100 , CVCPR_Normal_Y , CVCPR_Normal_Z , CVCPR_Point_Planarity , CVCPR_Point_Variation , CVCPR_Point_Sphericity , CVCPR_Point_Linearity , CVCPR_Point_Curvature , CVCPR_Custom = 0x10000000 }

Functions
cvbres_t	CVCCreatePlaneFromPointer (cvbdatatype_t DataType, CVCPlaneRole Role, void pBase, cvbdim_t Dimension, cvbint64_t Lengths[], intptr_t Increments[], PFFINALRELEASE OnRelease, void pPrivate, CVPLANE &hPlane)
	Creates a plane from user memory. More...

cvbbool_t	CVCIsPlane (CVPLANE hPlane)
	Tests whether the given hPlane handle is a valid plane object. More...

cvbres_t	CVCPlaneGetBasePtr (CVPLANE hPlane, void *&pBase)
	Gets the pointer to the first element of the given hPlane. More...

cvbres_t	CVCPlaneGetDataType (CVPLANE hPlane, cvbdatatype_t &DataType)
	Gets the CVB data type of the given hPlane. More...

cvbres_t	CVCPlaneGetIncrement (CVPLANE hPlane, cvbdim_t Dimension, intptr_t &Increment)
	Gets the offset in bytes to move to the next element in the given Dimension. More...

cvbres_t	CVCPlaneGetLength (CVPLANE hPlane, cvbdim_t Dimension, cvbint64_t &Length)
	Gets the number of elements in the given Dimension. More...

cvbres_t	CVCPlaneGetPixelPointer (OBJ hObj, cvbdim_t PlaneIndex, void *&pScan0, intptr_t &XInc, intptr_t &YInc)
	Gets access to the image data if it is linear. More...

cvbres_t	CVCPlaneGetRank (CVPLANE hPlane, cvbdim_t &Rank)
	Gets the number of dimensions the given hPlane spans over. More...

cvbres_t	CVCPlaneGetRole (CVPLANE hPlane, CVCPlaneRole &Role)
	Gets the role of the plane. More...

Detailed Description

Represents a single CVB plane.

An IPlane is a linear (not necessary contiguous) data plane (see CVCImg library documentation for an explanation of CVB's plane concept). For a description on what linear means see CVCPlaneGetPixelPointer.

A plane has a certain role (see CVCPlaneRole) which describes the image component's interpretation. This combined with its DataType enables correct component access.

To navigate inside an IPlane you can first use the BasePtr to access the logical first component. The Rank describes the number of **Dimension**s in the plane. For example:

2:	standard 2D images
1:	3D point clouds (array of x,y,z points)

And for each Dimension the Length and the Increment to the next element are given. For a 2D image (Rank is two):

0 (CVCD_X):	Length means width in pixels and Increment is the X-increment in bytes
1 (CVCD_Y):	Length means height in pixels and Increment is the Y-increment in bytes

Attention: If you access image data via the IPlane interface, you bypass the VPAT. That is only possible if your image both supports the IImageVPA and the IPlaneEnum interface. With the IPlane interface you see the buffer as is (e.g. as delivered by the transport layer). Any rotation, mirroring, etc done via the VPAT is not applied then. If you need that, use the GetLinearAccess function from the CVCUtilities library.

Typedef Documentation

◆ CVPLANE

CVPLANE

CVB plane handle.

The CVPLANE is a reference counted OBJ handle. CVPLANE objects at least implement the IPlane interface.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Helper labels to identify dimensions

Enumerator
CVCD_X	X dimension
CVCD_Y	Y dimension
CVCD_Z	Z dimension

◆ CVCPlaneRole

enum CVCPlaneRole

Enumerator
CVCPR_Undefined	Unknown/undefined value.
CVCPR_PixMono	Monochromatic, linear luminance value.
CVCPR_PixRGB_R	Red channel value.
CVCPR_PixRGB_G	Green channel value.
CVCPR_PixRGB_B	Blue channel value.
CVCPR_PixYUV_Y	Same as CVCPR_PixMono, but to distinguish YUV model.
CVCPR_PixYUV_U	Blue chrominance channel.
CVCPR_PixYUV_V	Red chrominance channel.
CVCPR_PixHSV_H	Hue channel value.
CVCPR_PixHSV_S	Saturation channel value.
CVCPR_PixHSV_V	Value (luminance) channel value.
CVCPR_PixLAB_L	Lightness channel value.
CVCPR_PixLAB_A	Green-red chrominance channel.
CVCPR_PixLAB_B	Blue-yellow chrominance channel.
CVCPR_PixConfidence	Confidence (probability density/percentage) or consistency (Boolean) value.
CVCPR_CoordCartesian_X	Cartesian X axis component.
CVCPR_CoordCartesian_Y	Cartesian Y axis component.
CVCPR_CoordCartesian_Z	Cartesian Z axis component.
CVCPR_CoordCartesian_W	Cartesian W axis component (homogeneous coordinates).
CVCPR_CoordPolar_Rho	Polar radius component.
CVCPR_CoordPolar_Phi	Polar azimuth angle component.
CVCPR_CoordCylindrical_Rho	Cylindrical radius component.
CVCPR_CoordCylindrical_Phi	Cylindrical azimuth angle component.
CVCPR_CoordCylindrical_Z	Cylindrical Z axis component.
CVCPR_CoordSpherical_Rho	Spherical radius component.
CVCPR_Normal_X	Normal in X.
CVCPR_Normal_Y	Normal in Y.
CVCPR_Normal_Z	Normal in Z.
CVCPR_Point_Planarity	Planarity of point. This is a measure for the planarity of the point considering neighboring points. The range of values is [0;1].
CVCPR_Point_Variation	Variation of point. This is a measure for the variation of the point considering neighboring points. The range of values is [0;1].
CVCPR_Point_Sphericity	Sphericity of point. This is a measure for the sphericity of the point considering neighboring points. The range of values is [0;1].
CVCPR_Point_Linearity	Linearity of point. This is a measure for the linearity of the point considering neighboring points. A high linearity means, that the points lie on one line. The range of values is [0;1].
CVCPR_Point_Curvature	Curvature of point.
CVCPR_Custom	Not generically defined use case.

Function Documentation

◆ CVCCreatePlaneFromPointer()

cvbres_t CVCCreatePlaneFromPointer	(	cvbdatatype_t	DataType,
		CVCPlaneRole	Role,
		void *	pBase,
		cvbdim_t	Dimension,
		cvbint64_t	Lengths[],
		intptr_t	Increments[],
		PFFINALRELEASE	OnRelease,
		void *	pPrivate,
		CVPLANE &	hPlane
	)

Creates a plane from user memory.

Attention: If successful, the returned hPlane must be freed via ReleaseObject if not needed anymore.

Parameters

[in]	DataType	The type identifier for the data in the plane.
[in]	Role	The meaning of this plane.
[in]	pBase	The base pointer of the plane.
[in]	Dimension	The dimension of the plane.
[in]	Lengths	The lengths of the plane for each dimension.
[in]	Increments	The increments of the plane for each dimension.
[in]	OnRelease	The pointer to a function that is called when the plane is released.
[in]	pPrivate	The pointer to an arbitrary object; it will be passed to OnRelease when it is called. The pointer can be `NULL`.
[out]	hPlane	The created plane.

Returns: CVC_ERROR(CVC_E_ERROR) if hPlane could not be created; CVC_ERROR(CVC_E_OK) on success.

◆ CVCIsPlane()

cvbbool_t CVCIsPlane ( CVPLANE hPlane )

Tests whether the given hPlane handle is a valid plane object.

Parameters

[in] hPlane Plane handle to test.

Returns: true if hPlane is a valid plane object; false if not.

◆ CVCPlaneGetBasePtr()

cvbres_t CVCPlaneGetBasePtr	(	CVPLANE	hPlane,
		void *&	pBase
	)

Gets the pointer to the first element of the given hPlane.

Attention: CVB's plane model decomposes the buffer/pixel values in planes. To find out the role of this plane use the CVCPlaneGetRole function.

This then means if you have a RGB8 buffer and you have the CVCPR_PixRGB_B plane object, then the returned pBase has a two byte offset to the buffer's base pointer (see CVCBufferGetBasePtr).

Parameters

[in]	hPlane	Plane handle to query.
[out]	pBase	Variable to receive the base pointer of the plane.

Returns: CVC_ERROR(CVC_E_WRONGOBJECT) if hPlane is not an CVPLANE; CVC_ERROR(CVC_E_OK) on success.

◆ CVCPlaneGetDataType()

cvbres_t CVCPlaneGetDataType	(	CVPLANE	hPlane,
		cvbdatatype_t &	DataType
	)

Gets the CVB data type of the given hPlane.

The data type identifier defines whether the component value is e.g. an (unsigned) integer or floating point number and its bit-size. Other types are also encoded.

Parameters

[in]	hPlane	Plane handle to query.
[out]	DataType	Variable to receive the CVB data type of the plane.

Returns: CVC_ERROR(CVC_E_WRONGOBJECT) if hPlane is not an CVPLANE; CVC_ERROR(CVC_E_OK) on success.

◆ CVCPlaneGetIncrement()

cvbres_t CVCPlaneGetIncrement	(	CVPLANE	hPlane,
		cvbdim_t	Dimension,
		intptr_t &	Increment
	)

Gets the offset in bytes to move to the next element in the given Dimension.

For a normal image the Increment of Dimension 0 is the X-increment; Dimension 1 refers to the Y-increment respectively.

Attention: CVB's plane model decomposes the buffer/pixel values in planes. To find out the role of this plane use the CVCPlaneGetRole function.

These values are normally equal to the values returned by CVCBufferGetIncrement as only the base pointers are different. Notable differences are in compressed formats like YUV422_8.

Parameters

[in]	hPlane	Plane handle to query.
[in]	Dimension	Dimension to access the increment for.
[out]	Increment	Variable to receive the offset in bytes to the next element in the given Dimension.

Returns

#CVC_ERROR (#CVC_E_OK) on success
#CVC_ERROR (#CVC_E_WRONGOBJECT) if hPlane is not an CVPLANE
#CVC_ERROR (#CVC_E_INVALIDINDEX) if Dimension is out of bounds

◆ CVCPlaneGetLength()

cvbres_t CVCPlaneGetLength	(	CVPLANE	hPlane,
		cvbdim_t	Dimension,
		cvbint64_t &	Length
	)

Gets the number of elements in the given Dimension.

For a normal image the Length of Dimension 0 is the width; Dimension 1 refers to the height respectively.

Attention: CVB's plane model decomposes the buffer/pixel values in planes. To find out the role of this plane use the CVCPlaneGetRole function.

These values are normally equal to the values returned by CVCBufferGetLength as the number of components in one pixel is constant. Notable differences are in compressed formats like YUV422_8 where the length Dimension 0 for CVCPR_PixYUV_U and CVCPR_PixYUV_V is half of CVCPR_PixYUV_Y.

Parameters

[in]	hPlane	Plane handle to query.
[in]	Dimension	Dimension to access the increment for.
[out]	Length	Variable to receive the number of elements in the given Dimension.

Returns

#CVC_ERROR (#CVC_E_OK) on success
#CVC_ERROR (#CVC_E_WRONGOBJECT) if hPlane is not an CVPLANE
#CVC_ERROR (#CVC_E_INVALIDINDEX) if Dimension is out of bounds

◆ CVCPlaneGetPixelPointer()

cvbres_t CVCPlaneGetPixelPointer	(	OBJ	hObj,
		cvbdim_t	PlaneIndex,
		void *&	pScan0,
		intptr_t &	XInc,
		intptr_t &	YInc
	)

Gets access to the image data if it is linear.

An image plane is linear for this function if there are exactly one x-increment (offset to the next pixel in line) and y-increment (offset to the next line) value for the whole plane.

If linear access is not possible, you must access image data via CVCImage.dll's GetImageVPA function.

Example: cvbuint8_t * ToNextPixel(cvbuint8_t *pPixel, intptr_t xInc)

{

return pPixel + xInc;

}

cvbuint8_t * ToNextLine(cvbuint8_t *pPixel, intptr_t yInc)

{

return pPixel + yInc;

}

Note: This function differs from the CVCUtilities.dll's GetLinearAccess function in that this function ignores the VPAT if a IPlaneEnum interface is implemented. VPAT analysis is only done if no IPlaneEnum interface is available for convenience to be able to access pure IImageVPA images.

Attention: This means there may still be gaps between the pixels or increments may be negative!

Parameters

[in]	hObj	IPlaneEnum or IImageVPA object to query.
[in]	PlaneIndex	Plane index to get access to.
[out]	pScan0	Variable to receive the pointer to the first pixel in the first scan line.
[out]	XInc	Variable to receive the offset to the next pixel in scan line (in bytes).
[out]	YInc	Variable to receive the offset to the next line (in bytes).

Returns

#CVC_ERROR (#CVC_E_OK) on success
#CVC_ERROR (#CVC_E_LINEAR_ONLY) if given plane is not linear
#CVC_ERROR (#CVC_E_WRONGOBJECT) if hObj is not a CVPLANEENUM or IMG.
#CVC_ERROR (#CVC_E_INVALIDINDEX) if PlaneIndex is out of bounds

◆ CVCPlaneGetRank()

cvbres_t CVCPlaneGetRank	(	CVPLANE	hPlane,
		cvbdim_t &	Rank
	)

Gets the number of dimensions the given hPlane spans over.

A normal image has a rank of 2 (width and height dimension). A point cloud has a rank of 1 (array of X, Y, or Z components).

Parameters

[in]	hPlane	Plane handle to query.
[out]	Rank	Variable to receive the number of dimensions in the given hPlane.

Returns: CVC_ERROR(CVC_E_WRONGOBJECT) if hPlane is not an CVPLANE; CVC_ERROR(CVC_E_OK) on success.

◆ CVCPlaneGetRole()

cvbres_t CVCPlaneGetRole	(	CVPLANE	hPlane,
		CVCPlaneRole &	Role
	)

Gets the role of the plane.

Roles specify the meaning of plane (which addresses one component in a buffer), e.g CVCPR_PixMono for a 2d monochrome image or CVCPR_CoordCartesian_X in a point cloud.

Parameters

[in]	hPlane	Plane handle to query.
[out]	Role	Variable to receive the role of the plane.

Returns: CVC_ERROR(CVC_E_WRONGOBJECT) if hPlane is not an CVPLANE; CVC_ERROR(CVC_E_OK) on success.


Contact Legal Privacy Statement	Copyright © 2023.
	All rights reserved.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ CVPLANE

Enumeration Type Documentation

◆ anonymous enum

◆ CVCPlaneRole

Function Documentation

◆ CVCCreatePlaneFromPointer()

◆ CVCIsPlane()

◆ CVCPlaneGetBasePtr()

◆ CVCPlaneGetDataType()

◆ CVCPlaneGetIncrement()

◆ CVCPlaneGetLength()

◆ CVCPlaneGetPixelPointer()

◆ CVCPlaneGetRank()

◆ CVCPlaneGetRole()