Image Manager (CVCore.dll) 15.0
IPlane

Represents a single CVB plane. More...

Typedefs

typedef void * CVPLANE
 CVB plane handle. More...
 
typedef void(* PFFINALRELEASE) (void *pBufferBase, void *pPrivate)
 Release callback for plane created with CVCCreatePlaneFromPointer. 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_PixRGB_RGB ,
  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
}
 Roles for planes. More...
 

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

CVB plane handle.

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

◆ PFFINALRELEASE

typedef void(* PFFINALRELEASE)(void *pBufferBase, void *pPrivate)

Release callback for plane created with CVCCreatePlaneFromPointer.

In this callback, the implementer can take the necessary steps to e.g. clean up memory or other resources allocated for a CVCCreatePlaneFromPointer call.

Parameters
[in]pBufferBaseThe base pointer of the buffer to be released.
[in]pPrivateUser context pointer given to the function CVCCreatePlaneFromPointer.

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

Roles for planes.

A plane role describes the components of the plane. They can coarsely be separated in 4 sets:

  1. pixel roles (normally for 2D images)
  2. coordinate roles (normally for point clouds)
  3. additional features (normally for point clouds)
  4. not generically defined use cases
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_PixRGB_RGB 

Red-green-blue channel 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]DataTypeThe type identifier for the data in the plane.
[in]RoleThe meaning of this plane.
[in]pBaseThe base pointer of the plane.
[in]DimensionThe dimension of the plane.
[in]LengthsThe lengths of the plane for each dimension.
[in]IncrementsThe increments of the plane for each dimension.
[in]OnReleaseThe pointer to a function that is called when the plane is released.
[in]pPrivateThe pointer to an arbitrary object; it will be passed to OnRelease when it is called. The pointer can be NULL.
[out]hPlaneThe 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]hPlanePlane 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]hPlanePlane handle to query.
[out]pBaseVariable 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]hPlanePlane handle to query.
[out]DataTypeVariable 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]hPlanePlane handle to query.
[in]DimensionDimension to access the increment for.
[out]IncrementVariable to receive the offset in bytes to the next element in the given Dimension.
Returns

◆ 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]hPlanePlane handle to query.
[in]DimensionDimension to access the increment for.
[out]LengthVariable to receive the number of elements in the given Dimension.
Returns

◆ 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]hObjIPlaneEnum or IImageVPA object to query.
[in]PlaneIndexPlane index to get access to.
[out]pScan0Variable to receive the pointer to the first pixel in the first scan line.
[out]XIncVariable to receive the offset to the next pixel in scan line (in bytes).
[out]YIncVariable to receive the offset to the next line (in bytes).
Returns

◆ 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]hPlanePlane handle to query.
[out]RankVariable 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]hPlanePlane handle to query.
[out]RoleVariable 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.