Image Manager (CVCore3D.dll) 14.0
Point Cloud Handling

Functions to work with PointCloud mesh objects. More...

Modules

 Point Cloud
 Cloud of 3D points.
 

Data Structures

struct  CVC3DCuboid
 3D rectangle More...
 
struct  CVC3DFactors
 Linear transformation factors for a point. More...
 
struct  CVC3DPlane
 3D plane in Hessian normal form. More...
 
struct  CVC3DPointCD
 Cartesian 3D point with confidence information (X, Y, Z, C) with double components. More...
 
struct  CVC3DPointCF
 Cartesian 3D point with confidence information (X, Y, Z, C) with float components. More...
 
struct  CVC3DPointD
 Cartesian 3D point (X, Y, Z) with double components. More...
 
struct  CVC3DPointF
 Cartesian 3D point (X, Y, Z) with float components. More...
 
struct  CVC3DPointHD
 Cartesian, homogeneous 3D point (X, Y, Z, W) with double components. More...
 
struct  CVC3DPointHF
 Cartesian, homogeneous 3D point (X, Y, Z, W) with float components. More...
 
struct  CVC3DRange
 One dimensional, inclusive range. More...
 
struct  CVC3DSensorSettings
 Camera sensor settings. More...
 

Typedefs

typedef cvbuint32_t * CVC3DPolygonIndexTable
 List of polygon indices. More...
 
typedef void * CVCOMPOSITE
 A PointCloud as seen from this library.
 

Enumerations

enum  CVC3DDownsampleMode { CVC3DDownsampleByFactor , CVC3DRemoveRandomly }
 
enum  CVC3DPointCloudFileFormat {
  CVC3DPCFF_Ascii , CVC3DPCFF_Ply , CVC3DPCFF_Stl , CVC3DPCFF_WavefrontObj ,
  CVC3DPCFF_Tiff , CVC3DPCFF_Pcd
}
 
enum  CVC3DPointCloudFlags {
  CVC3DPCF_DTFloat = 0 << 0 , CVC3DPCF_DTDouble = 1 << 0 , CVC3DPCF_XYZ = 0 << 0 , CVC3DPCF_XYZW = 1 << 5 ,
  CVC3DPCF_XYZConfidence = 1 << 6 , CVC3DPCF_WithConfidence = 1 << 12 , CVC3DPCF_NoExtrinsic = 1 << 24 , CVC3DPCF_NoMeshIndices = 1 << 25
}
 
enum  CVC3DPointCloudLayout {
  CVC3DPCL_Invalid , CVC3DPCL_Linear , CVC3DPCL_SeparatePlanar , CVC3DPCL_Planar ,
  CVC3DPCL_Interleaved
}
 

Functions

cvbres_t CVC3DCalculatePlaneFromPointDs (const CVC3DPointD *pPoints, size_t NumPoints, CVC3DPlane &Plane)
 Fits a plane into the given double pPoints. More...
 
cvbres_t CVC3DCalculatePlaneFromPointFs (const CVC3DPointF *pPoints, size_t NumPoints, CVC3DPlane &Plane)
 Fits a plane into the given float pPoints. More...
 
cvbres_t CVC3DConvertSparseToDensePointCloudAutomatic (CVCOMPOSITE SparseCloudIn, CVCOMPOSITE &DenseCloudOut, size_t &DroppedPoints)
 Creates a dense pointcloud from a sparse cloud. More...
 
cvbres_t CVC3DCreateCroppedPointCloud (CVCOMPOSITE PointCloudIn, const CVC3DCuboid &ClipBox, CVCOMPOSITE &PointCloudOut)
 Creates a new point cloud which only consists of the points inside the ClipBox. More...
 
cvbres_t CVC3DCreateDownsampledPointCloud (CVCOMPOSITE PointCloudIn, CVC3DDownsampleMode Mode, cvbint64_t Value, CVCOMPOSITE &PointCloudOut)
 Creates a new point cloud which has several points being removed dependent on the downsample Mode and Value. More...
 
cvbres_t CVC3DCreateDuplicatePointCloud (CVCOMPOSITE PointCloudIn, CVCOMPOSITE &PointCloudOut)
 Creates a new point cloud which is a copy from PointCloudIn. More...
 
cvbres_t CVC3DCreateFrustrumCroppedPointCloud (CVCOMPOSITE PointCloudIn, const CVC3DCuboid &ClipBox, const double Theta, const double Phi, CVCOMPOSITE &PointCloudOut)
 Creates a new point cloud which only consists of the points inside the ClipBox, where the orientation of the two boundary planes Z=Zmin and Z=Zmax can be modified by angles Theta and Phi. More...
 
cvbres_t CVC3DCreateFrustumCroppedPointCloud (CVCOMPOSITE PointCloudIn, const CVC3DCuboid &ClipBox, double Theta, double Phi, CVCOMPOSITE &PointCloudOut)
 Creates a new point cloud which only consists of the points inside the ClipBox, where the orientation of the two boundary planes Z=Zmin and Z=Zmax can be modified by angles Theta and Phi. More...
 
cvbres_t CVC3DCreatePlaneCroppedPointCloud (CVCOMPOSITE PointCloudIn, const CVC3DPlane &Plane, const CVC3DRange &Range, enum CVC3DCropRange CropRange, CVCOMPOSITE &PointCloudOut)
 Creates a new point cloud where points within or outside a range parallel to given Plane are cropped. More...
 
cvbres_t CVC3DCreateShrinkedDensePointCloud (CVCOMPOSITE DensePointCloudIn, CVCOMPOSITE &PointCloudOut)
 Creates a new dense point cloud where lines and columns at the borders containing only non-confident points are removed. More...
 
cvbres_t CVC3DCreateSparseFromDensePointCloud (CVCOMPOSITE DensePointCloudIn, CVCOMPOSITE &SparsePointCloudOut)
 Creates a sparse point cloud from a dense point cloud with confidence plane. More...
 
cvbres_t CVC3DCreateSparsePointCloudFromPointer (void **pPlaneBasePtrs, cvbdim_t NumPlanes, cvbdatatype_t Datatype, cvbint64_t NumPoints, intptr_t PlaneIncs[], PFFINALRELEASE ReleaseCallback, void *pPrivate, CVCOMPOSITE &PointCloud)
 Creates a PointCloud from the given memory without copying the data. More...
 
cvbres_t CVC3DLoadFile (const char *FileName, cvbval_t Flags, CVCOMPOSITE &PointCloud)
 Loads a 3D point, polygon or mesh file (ASCII string version). More...
 
cvbres_t CVC3DLoadFileW (const wchar_t *FileName, cvbval_t Flags, CVCOMPOSITE &PointCloud)
 Loads a 3D point, polygon or mesh file (Unicode string version). More...
 
cvbres_t CVC3DMemoryToPointCloud (void *Memory, size_t Size, cvbval_t Flags, CVC3DPointCloudFileFormat FileFormat, CVCOMPOSITE &PointCloud)
 Creates a point cloud from given Memory. More...
 
cvbres_t CVC3DPointCloudCalculateBoundingBox (CVCOMPOSITE PointCloud, CVC3DCuboid &BoundingBox)
 Calculates the minimum and maximum extent of the PointCloud. More...
 
cvbres_t CVC3DPointCloudCalculateCenterOfGravity (CVCOMPOSITE PointCloud, CVC3DPointD &Center)
 Calculates the center of gravity of the PointCloud. More...
 
cvbres_t CVC3DPointCloudCalculateCovarianceMatrix (CVCOMPOSITE PointCloud, CVC3DMatrix Covariance)
 Calculates the covariance matrix of the PointCloud. More...
 
cvbres_t CVC3DPointCloudCalculatePlaneFromCuboid (CVCOMPOSITE PointCloud, const CVC3DCuboid &AOI, CVC3DPlane &Plane)
 Fits a plane into the given pPoints. More...
 
cvbres_t CVC3DPointCloudGetPolygonTable (CVCOMPOSITE Mesh, CVC3DPolygonIndexTable &PolygonTable, cvbint64_t &NumPolygons)
 Gets the mesh's polygon vertex indices embedded into the PointCloud. More...
 
cvbres_t CVC3DPointCloudToMemory (CVCOMPOSITE PointCloud, cvbval_t Flags, CVC3DPointCloudFileFormat FileFormat, void *Memory, size_t Size)
 Saves the given PointCloud to the Memory in the given FileFormat. More...
 
cvbres_t CVC3DPointCloudToMemorySize (CVCOMPOSITE PointCloud, cvbval_t Flags, CVC3DPointCloudFileFormat FileFormat, size_t &Size)
 Determine the amount of memory needed for CVC3DMemoryToPointCloud. More...
 
cvbres_t CVC3DWriteFile (CVCOMPOSITE PointCloud, cvbval_t Flags, const char *FileName)
 Saves the given PointCloud to the file with the given FileName (ASCII string version). More...
 
cvbres_t CVC3DWriteFileW (CVCOMPOSITE PointCloud, cvbval_t Flags, const wchar_t *FileName)
 Saves the given PointCloud to the file with the given FileName (Unicode string version). More...
 

Detailed Description

Functions to work with PointCloud mesh objects.

Functions to create, copy and access PointCloud objects.

Functions to crop PointCloud objects.

Typedef Documentation

◆ CVC3DPolygonIndexTable

List of polygon indices.

This structure is filled in by CVC3DPointCloudGetPolygonTable from a pointcloud that was loaded with a mesh's face information. See the documentation there on interpretation of the contents.

Enumeration Type Documentation

◆ CVC3DDownsampleMode

Enumerator
CVC3DDownsampleByFactor 

Remove points by an integer factor.

CVC3DRemoveRandomly 

Remove a specified number of points randomly.

◆ CVC3DPointCloudFileFormat

Enumerator
CVC3DPCFF_Ascii 

Ascii file format.

This format is usually specified by the filename extensions: .asc, .xyz, .pts or .txt.

Mesh information is ignored when loading or storing with this format.

CVC3DPCFF_Ply 

Polygon file format.

This format is usually specified by the filename extension: .ply It can be in binary or text format. Reading supports both formats, while writing will be in binary.

Loading and storing mesh information is supported with both reads and writes.

CVC3DPCFF_Stl 

Stereo lithography file format.

This format is usually specified by the filename extension: .stl

Loading mesh information is supported. For writing stl, mesh information must be present.

CVC3DPCFF_WavefrontObj 

Wavefront object file format.

This format is usually specified by the filename extension: .obj Only reading is supported.

Loading mesh information is supported.

CVC3DPCFF_Tiff 

TIFF file format.

This format is usually specified by the filename extensions: .tif or .tiff Reading and writing is supported only with files, not memory.

Mesh information is ignored when loading or storing with this format.

◆ CVC3DPointCloudFlags

Enumerator
CVC3DPCF_DTFloat 

Create the point cloud with float components.

CVC3DPCF_DTDouble 

Create the point cloud with double components.

CVC3DPCF_XYZ 

Create the point cloud with three Cartesian components x, y, z.

CVC3DPCF_XYZW 

Create the point cloud with four Cartesian, homogeneous components x, y, z, w.

CVC3DPCF_XYZConfidence 

Create the point cloud with three Cartesian components x, y, z and an interleaved confidence component.

This implies CVC3DPCF_WithConfidence.

CVC3DPCF_WithConfidence 

Create the point cloud with an additional confidence plane.

If CVC3DPCF_XYZConfidence is specified the confidence components are interleaved; an extra plane is generate otherwise.

CVC3DPCF_NoExtrinsic 

Only apply intrinsic calibration in CVC3DCreateCalibratedPointCloudFromRangeMap.

CVC3DPCF_NoMeshIndices 

Do not load mesh information in CVC3DLoadFile, even if present.

◆ CVC3DPointCloudLayout

Enumerator
CVC3DPCL_Invalid 

No known/supported point cloud format.

CVC3DPCL_Linear 

No known buffer layout.

For this layout only the plane roles CVCPR_CoordCartesian_X, CVCPR_CoordCartesian_Y and CVCPR_CoordCartesian_Z are known with their increments.

Thus the PointCloud composite either has no buffer or no buffer that can be mapped via a PFNC value.

CVC3DPCL_SeparatePlanar 

Each plane is in its own, contiguous buffer.

For each plane role CVCPR_CoordCartesian_X, CVCPR_CoordCartesian_Y and CVCPR_CoordCartesian_Z exists one distinct buffer. Increment to the next element is element sized as in a simple array.

If the component __cvbdatatype_t__s are float, the composite has at least three buffers with PFNC values Coord3D_A32f, Coord3D_B32f and Coord3D_C32f.

CVC3DPCL_Planar 

All planes are in one planar, contiguous buffer.

All plane roles CVCPR_CoordCartesian_X, CVCPR_CoordCartesian_Y and CVCPR_CoordCartesian_Z lay component wise one after the other. First all x, then all y and finally all z components.

If the component cvbdatatype_t is float, the composite has at least one buffer with a PFNC value of Coord3D_ABC32f_Planar.

CVC3DPCL_Interleaved 

All points are stored x,y,z interleaved as in CVC3DPointF.

All plane roles CVCPR_CoordCartesian_X, CVCPR_CoordCartesian_Y and CVCPR_CoordCartesian_Z lay point wise one after the other.

If the component cvbdatatype_t is float, the composite has at least one buffer with a PFNC value of Coord3D_ABC32f.

Function Documentation

◆ CVC3DCalculatePlaneFromPointDs()

cvbres_t CVC3DCalculatePlaneFromPointDs ( const CVC3DPointD pPoints,
size_t  NumPoints,
CVC3DPlane Plane 
)

Fits a plane into the given double pPoints.

Any plane in 3D space can be found. It uses a Hessian Normal representation for the plane.

Note
NumPoints must be at least 3. The pPoints should not be on the same line as the solution then is ambiguous.
The normal direction is set so that the distance to the origin is always positive.
Parameters
[in]pPointsPointer to array of points.
[in]NumPointsNumber of points in pPoints.
[out]PlaneReference to structure to be filled with plane data.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_PARAMETER) if parameters are invalid.
See also
CVC3DPointCloudCalculatePlaneFromCuboid

◆ CVC3DCalculatePlaneFromPointFs()

cvbres_t CVC3DCalculatePlaneFromPointFs ( const CVC3DPointF pPoints,
size_t  NumPoints,
CVC3DPlane Plane 
)

Fits a plane into the given float pPoints.

Any plane in 3D space can be found. It uses a Hessian Normal representation for the plane.

Note
NumPoints must be at least 3. The pPoints should not be on the same line as the solution then is ambiguous.
The normal direction is set so that the distance to the origin is always positive.
Parameters
[in]pPointsPointer to array of points.
[in]NumPointsNumber of points in pPoints.
[out]PlaneReference to structure to be filled with plane data.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_PARAMETER) if parameters are invalid.
See also
CVC3DPointCloudCalculatePlaneFromCuboid

◆ CVC3DConvertSparseToDensePointCloudAutomatic()

cvbres_t CVC3DConvertSparseToDensePointCloudAutomatic ( CVCOMPOSITE  SparseCloudIn,
CVCOMPOSITE DenseCloudOut,
size_t &  DroppedPoints 
)

Creates a dense pointcloud from a sparse cloud.

This function maps the points of a sparse pointcloud into a newly created dense pointcloud. First, a resolution is determined that minimizes the points lost by the conversion.

Similarly to CVC3DCreateRangeMapFromPointCloud, if multiple points map onto the same x, y position in the dense cloud, the one with the larger z value is retained. The output cloud always has a confidence plane, which is set to 0 if no point of the sparse cloud matched the location. It is set to 1 if a point of the sparse cloud could be mapped to that location.

If the sparse cloud has a w component, it is replicated as well.

Parameters
[in]SparseCloudInThe source sparse point cloud.
[out]DenseCloudOutReceives the newly created and filled dense point cloud.
[out]DroppedPointsThe number of source points that overlapped in x and y and thus got dropped.
Returns
  • CVC_ERROR (#CVC_E_OK) on success
  • CVC_ERROR(CVC_E_ERROR) else

◆ CVC3DCreateCroppedPointCloud()

cvbres_t CVC3DCreateCroppedPointCloud ( CVCOMPOSITE  PointCloudIn,
const CVC3DCuboid ClipBox,
CVCOMPOSITE PointCloudOut 
)

Creates a new point cloud which only consists of the points inside the ClipBox.

The given PointCloudIn must have a valid CVC3DPointCloudLayout.

Note
PointCloudOut has the same planes as PointCloudIn. If the input point cloud is dense, points outside the bounding box are set non-confident. Lines and columns at the borders containing only non-confident points are removed via function CVC3DCreateShrinkedDensePointCloud. If PointCloudIn is dense and does not contain a confidence plane, it will be added to PointCloudOut.

If the input point cloud is sparse, PointCloudOut has the same properties as if a new point cloud was created via CVC3DCreateSparsePointCloud.

If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.
Parameters
[in]PointCloudInHandle to point cloud object to copy from.
[in]ClipBoxCuboid defining the bounds for the points to be copied (min/max are inclusive).
[out]PointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloudIn is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_EMPTYRESULT) if clipping PointCloudIn resulted in an empty point cloud.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.
See also
CVC3DPointCloudCalculateBoundingBox, CVC3DCreateFrustumCroppedPointCloud, CVC3DCreatePlaneCroppedPointCloud, CVC3DCreateShrinkedDensePointCloud

◆ CVC3DCreateDownsampledPointCloud()

cvbres_t CVC3DCreateDownsampledPointCloud ( CVCOMPOSITE  PointCloudIn,
CVC3DDownsampleMode  Mode,
cvbint64_t  Value,
CVCOMPOSITE PointCloudOut 
)

Creates a new point cloud which has several points being removed dependent on the downsample Mode and Value.

The following removal strategies are supported (Mode):

  • CVC3DDownsampleByFactor: Every Value-th point will be removed. Thus if Value is two, every second point will be removed. Value must be greater than one.
  • CVC3DRemoveRandomly: Value number of points will be randomly removed. Value must be less than the number of points in PointCloudIn.

The given PointCloudIn must have a valid CVC3DPointCloudLayout.

Note
CVC3DDownsampleByFactor and CVC3DRemoveRandomly are a crude, but fast way of removing points as they don't take the point values into account.
PointCloudOut has the same properties as if a new point cloud was created via CVC3DCreateSparsePointCloud.
If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.
Parameters
[in]PointCloudInHandle to point cloud object to copy from.
[in]ModeDownsample strategy as described above.
[in]ValuePositive, non-null downsample value as described above.
[out]PointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloudIn is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_PARAMETER) if Mode or Value have invalid values.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.

◆ CVC3DCreateDuplicatePointCloud()

cvbres_t CVC3DCreateDuplicatePointCloud ( CVCOMPOSITE  PointCloudIn,
CVCOMPOSITE PointCloudOut 
)

Creates a new point cloud which is a copy from PointCloudIn.

The given PointCloudIn must have a valid CVC3DPointCloudLayout.

Note
Depending on the PointCloudIn, the PointCloudOut has the same properties as if a new point cloud was created via CVC3DCreateSparsePointCloud or CVC3DCreateDensePointCloud respectively. Mesh information and additional planes are copied along.
Attention
The duplicated point cloud PointCloudOut may have a different point cloud layout as the input point cloud PointCloudIn.
If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.
Parameters
[in]PointCloudInHandle to point cloud object to copy.
[out]PointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloudIn is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.

◆ CVC3DCreateFrustrumCroppedPointCloud()

cvbres_t CVC3DCreateFrustrumCroppedPointCloud ( CVCOMPOSITE  PointCloudIn,
const CVC3DCuboid ClipBox,
const double  Theta,
const double  Phi,
CVCOMPOSITE PointCloudOut 
)

Creates a new point cloud which only consists of the points inside the ClipBox, where the orientation of the two boundary planes Z=Zmin and Z=Zmax can be modified by angles Theta and Phi.

For Theta, Phi = 0,0 the function will give the same result as CVC3DCreateCroppedPointCloud. Angle Theta tilts the two Z-boundary planes towards the (positive) Y-axis. Additionally, Phi rotates the tilted Z-boundary planes around the Z-axis (for Theta=0, Phi will have no effect, because it is then just an inplane-rotation). The two Z-boundary planes will stay parallel, but no longer necessarily orthogonal to the lateral boundary planes. Note, that only the Z-boundaries are tilted and not the whole bounding box, i.e. X- and Y-boundaries will stay the same.

The given PointCloudIn must have a valid CVC3DPointCloudLayout.

Note
PointCloudOut has the same properties as if a new point cloud was created via CVC3DCreateSparsePointCloud.
If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.
Parameters
[in]PointCloudInHandle to point cloud object to copy from.
[in]ClipBoxCuboid defining the bounds for the points to be copied (min/max are inclusive).
[in]ThetaTilt angle of the two Z-boundary planes Z=Zmin and Z=Zmax towards the positive Y-axis (in degrees).
[in]PhiRotation angle of the tilted Z-boundary planes around the Z-axis (in degrees). If Theta = 0, Phi will have no effect.
[out]PointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloudIn is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_NOINTERSECTION) if clipping PointCloudIn resulted in an empty point cloud.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.
See also
CVC3DPointCloudCalculateBoundingBox, CVC3DCreateCroppedPointCloud

◆ CVC3DCreateFrustumCroppedPointCloud()

cvbres_t CVC3DCreateFrustumCroppedPointCloud ( CVCOMPOSITE  PointCloudIn,
const CVC3DCuboid ClipBox,
double  Theta,
double  Phi,
CVCOMPOSITE PointCloudOut 
)

Creates a new point cloud which only consists of the points inside the ClipBox, where the orientation of the two boundary planes Z=Zmin and Z=Zmax can be modified by angles Theta and Phi.

For Theta, Phi = 0,0 the function will give the same result as CVC3DCreateCroppedPointCloud. Angle Theta tilts the two Z-boundary planes towards the (positive) Y-axis. Additionally, Phi rotates the tilted Z-boundary planes around the Z-axis (for Theta=0, Phi will have no effect, because it is then just an inplane-rotation). The two Z-boundary planes will stay parallel, but no longer necessarily orthogonal to the lateral boundary planes. Note, that only the Z-boundaries are tilted and not the whole bounding box, i.e. X- and Y-boundaries will stay the same.

The given PointCloudIn must have a valid CVC3DPointCloudLayout.

Note
PointCloudOut has the same planes as PointCloudIn. If the input point cloud is dense, points outside the bounding box are set non-confident. Lines and columns at the borders containing only non-confident points are removed via function CVC3DCreateShrinkedDensePointCloud. If PointCloudIn is dense and does not contain a confidence plane, it will be added to PointCloudOut.

If the input point cloud is sparse, PointCloudOut has the same properties as if a new point cloud was created via CVC3DCreateSparsePointCloud.

If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.
Parameters
[in]PointCloudInHandle to point cloud object to copy from.
[in]ClipBoxCuboid defining the bounds for the points to be copied (min/max are inclusive).
[in]ThetaTilt angle of the two Z-boundary planes Z=Zmin and Z=Zmax towards the positive Y-axis (in degrees).
[in]PhiRotation angle of the tilted Z-boundary planes around the Z-axis (in degrees). If Theta = 0, Phi will have no effect.
[out]PointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloudIn is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_EMPTYRESULT) if clipping PointCloudIn resulted in an empty point cloud.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.
See also
CVC3DPointCloudCalculateBoundingBox, CVC3DCreatePlaneCroppedPointCloud, CVC3DCreateCroppedPointCloud

◆ CVC3DCreatePlaneCroppedPointCloud()

cvbres_t CVC3DCreatePlaneCroppedPointCloud ( CVCOMPOSITE  PointCloudIn,
const CVC3DPlane Plane,
const CVC3DRange Range,
enum CVC3DCropRange  CropRange,
CVCOMPOSITE PointCloudOut 
)

Creates a new point cloud where points within or outside a range parallel to given Plane are cropped.

The Plane is defined by the hessian normal form:

Points are cropped within or outside a range parallel to the given Plane. The range is defined by Range. Note, that Range.Max and Range.Min are applied along normal direction.

In order to define a range around the plane, maximum and minimum range has to be positive and negative respectively.

With this function it is also possible to crop below or above a plane. Therefore a plane parallel to the xy plane has to be given and the minimum or maximum range has to be extended to infinite or very large values.

Note
PointCloudOut has the same planes as PointCloudIn. If the input point cloud is dense, points beyond the plane are set non-confident. Lines and columns at the borders containing only non-confident points are removed via function CVC3DCreateShrinkedDensePointCloud. If PointCloudIn is dense and does not contain a confidence plane, a confidence plane will be added to PointCloudOut.

If the input point cloud is sparse, PointCloudOut has the same properties as if a new point cloud was created via CVC3DCreateSparsePointCloud.

If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.

Parameters
[in]PointCloudInHandle to point cloud object to copy from.
[in]PlanePoints will be cropped parallel to this plane.
[in]RangePoints will be cropped within or outside this range.
[in]CropWithinBandIndicates whether points should be cropped within or outside the range.
[out]PointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloudIn is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_EMPTYRESULT) if clipping PointCloudIn resulted in an empty point cloud.
  • #CVC_ERROR (#CVC_E_PARAMETER) if given normal is zero.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.
See also
CVC3DCreateCroppedPointCloud, CVC3DCreateFrustumCroppedPointCloud, CVC3DCreateShrinkedDensePointCloud

◆ CVC3DCreateShrinkedDensePointCloud()

cvbres_t CVC3DCreateShrinkedDensePointCloud ( CVCOMPOSITE  DensePointCloudIn,
CVCOMPOSITE PointCloudOut 
)

Creates a new dense point cloud where lines and columns at the borders containing only non-confident points are removed.

Note
PointCloudOut has the same planes as PointCloudIn. Please ensure that PointCloudIn contains a confidence plane.
If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.
Parameters
[in]PointCloudInHandle to point cloud object to copy from.
[out]PointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if DensePointCloudIn is not a valid dense point cloud IComposite or confidence plane is missing.
  • #CVC_ERROR (#CVC_E_EMPTYRESULT) if shrinking PointCloudIn resulted in an empty point cloud.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.
See also
CVC3DCreateCroppedPointCloud, CVC3DCreateFrustumCroppedPointCloud, CVC3DCreateShrinkedDensePointCloud

◆ CVC3DCreateSparseFromDensePointCloud()

cvbres_t CVC3DCreateSparseFromDensePointCloud ( CVCOMPOSITE  DensePointCloudIn,
CVCOMPOSITE SparsePointCloudOut 
)

Creates a sparse point cloud from a dense point cloud with confidence plane.

Non-confident points will be removed and the confidence plane is not kept. PointCloudOut has the same planes as PointCloudIn (except confidence).

If this function returns successfully you need to release the returned PointCloudOut via ReleaseObject if not needed anymore.
Parameters
[in]DensePointCloudInHandle to point cloud object to copy from.
[out]SparsePointCloudOutVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloudIn is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_EMPTYRESULT) if clipping PointCloudIn resulted in an empty point cloud.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.
See also
CVC3DCreateCroppedPointCloud, CVC3DCreateShrinkedDensePointCloud

◆ CVC3DCreateSparsePointCloudFromPointer()

cvbres_t CVC3DCreateSparsePointCloudFromPointer ( void **  pPlaneBasePtrs,
cvbdim_t  NumPlanes,
cvbdatatype_t  Datatype,
cvbint64_t  NumPoints,
intptr_t  PlaneIncs[],
PFFINALRELEASE  ReleaseCallback,
void *  pPrivate,
CVCOMPOSITE PointCloud 
)

Creates a PointCloud from the given memory without copying the data.

This function creates a view on the given memory buffer(s) and creates a point cloud from it. It does not own the memory given. If you need to get notified on the disposal of the created PointCloud, you can pass a ReleaseCallback with its pPrivate. The base pointer passed to the ReleaseCallback will be pPlaneBasePtrs[0].

Note
If the given buffer is a contiguous X, Y, Z array, additional data will be allocated to support direct access with our processing and display.
If the planes do not result in a contiguous X, Y, Z point array, most algorithms will use CVC3DCreateDuplicatePointCloud on the PointCloud internally (or something similar).
If this function returns successfully you need to release the returned PointCloud via ReleaseObject if not needed anymore.
Attention
Take care to specify the correct memory layout as access violations/segmentation faults or worse may occur! These effects will first be visible when actually accessing the buffer, not when creating the point cloud view.
Also take care that the referenced memory buffer stays valid as long as this object lives.
Currently only the single precision (float) Datatype is supported: DT_Float | DT_Signed | 32. Also currently NumPlanes must be 3.
Parameters
[in]pPlaneBasePtrsBase pointers of the X, Y, Z and optionally W component planes.
[in]NumPlanesNumber of pPlaneBasePtrs.
[in]DatatypeDatatype of the pPlaneBasePtrs.
[in]NumPointsNumber of elements in each plane.
[in]PlaneIncsOffset to the next component in the respective plane in bytes.
[in]ReleaseCallbackOptional callback to get notified when the returned PointCloud is released.
[in]pPrivatePrivate data pointer, e.g. object pointer, to be passed to the ReleaseCallback.
[out]PointCloudVariable to receive the handle of the resulting point cloud.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_INVALIDDIMENSION) if NumPlanes is not 3 or 4.
  • #CVC_ERROR (#CVC_E_PARAMETER) if parameters are invalid.
  • #CVC_ERROR (#CVC_E_INVALIDDATATYPE) if non float Datatype was given.
  • #CVC_ERROR (#CVC_E_MEMORY) if not enough memory was available to create the point cloud.

◆ CVC3DLoadFile()

cvbres_t CVC3DLoadFile ( const char *  FileName,
cvbval_t  Flags,
CVCOMPOSITE PointCloud 
)

Loads a 3D point, polygon or mesh file (ASCII string version).

The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Stereo Lithography stl
Wavefront OBJ obj
TIFF tif, tiff
ASCII asc, pts, txt, xyz
PCL Format pcd

The resulting point cloud is created via CVC3DCreateSparsePointCloud except for TIFF which maybe created via CVC3DCreateDensePointCloud if the image height is larger than one.

Note
TIFF files are interpreted as point clouds. Supported are three sample float or double files. The samples are interpreted as x,y,z. Thus if you want to load a TIFF as a range map, use LoadImageFile from the CVCImg library and call CVC3DCreateDensePointCloudFromRangeMap.
The following point types are supported as PCL format: PointXYZ, PointXYZI, PointXYZRGB, PointXYZNormal. If the point cloud contains additional layer only X,Y,Z is read. Pcd files without xyz coordinates are not supported.
If this function returns successfully you need to release the returned PointCloud via ReleaseObject if not needed anymore.
Parameters
[in]FileNameFull path to the file to load.
[in]FlagsCVC3DPointCloudFlags specifying the kind of point cloud to be created.
[out]PointCloudVariable to receive the loaded object.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_PARAMETER) if FileName is NULL or Flags have an unsupported combination.
  • #CVC_ERROR (#CVC_E_FILEIO) if FileName is not accessible/existent
  • #CVC_ERROR (#CVC_E_NOTSUPPORTED) if the file format is not supported

◆ CVC3DLoadFileW()

cvbres_t CVC3DLoadFileW ( const wchar_t *  FileName,
cvbval_t  Flags,
CVCOMPOSITE PointCloud 
)

Loads a 3D point, polygon or mesh file (Unicode string version).

The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Stereo Lithography stl
Wavefront OBJ obj
TIFF tif, tiff
ASCII asc, pts, txt, xyz
PCL Format pcd

The resulting point cloud is created via CVC3DCreateSparsePointCloud except for TIFF which maybe created via CVC3DCreateDensePointCloud if the image height is larger than one.

Note
TIFF files are interpreted as point clouds. Supported are three sample float or double files. The samples are interpreted as x,y,z. Thus if you want to load a TIFF as a range map, use LoadImageFile from the CVCImg library and call CVC3DCreateDensePointCloudFromRangeMap.
The following point types are supported as PCL format: PointXYZ, PointXYZI, PointXYZRGB, PointXYZNormal. If the point cloud contains additional layer only X,Y,Z is read. Pcd files without xyz coordinates are not supported.
If this function returns successfully you need to release the returned PointCloud via ReleaseObject if not needed anymore.
Parameters
[in]FileNameFull path to the file to load.
[in]FlagsCVC3DPointCloudFlags specifying the kind of point cloud to be created.
[out]PointCloudVariable to receive the loaded object.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_PARAMETER) if FileName is NULL or Flags have an unsupported combination.
  • #CVC_ERROR (#CVC_E_FILEIO) if FileName is not accessible/existent
  • #CVC_ERROR (#CVC_E_NOTSUPPORTED) if the file format is not supported

◆ CVC3DMemoryToPointCloud()

cvbres_t CVC3DMemoryToPointCloud ( void *  Memory,
size_t  Size,
cvbval_t  Flags,
CVC3DPointCloudFileFormat  FileFormat,
CVCOMPOSITE PointCloud 
)

Creates a point cloud from given Memory.

The following data formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz

The resulting point cloud is created via CVC3DCreateSparsePointCloud .

If this function returns successfully you need to release the returned PointCloud via ReleaseObject if not needed anymore.
Parameters
[in]MemoryBuffer containing the data that is to be read.
[in]SizeThe number of bytes in the Memory buffer.
[in]FlagsCVC3DPointCloudFlags specifying the kind of point cloud to be created.
[in]FileFormatThe data format the buffer is in.
[out]PointCloudVariable to receive the loaded object.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_PARAMETER) if Memory is NULL, Size is 0, or Flags have an unsupported combination.
  • #CVC_ERROR (#CVC_E_NOTSUPPORTED) if the \ FileFormat is not supported
See also
CVC3DPointCloudToMemory

◆ CVC3DPointCloudCalculateBoundingBox()

cvbres_t CVC3DPointCloudCalculateBoundingBox ( CVCOMPOSITE  PointCloud,
CVC3DCuboid BoundingBox 
)

Calculates the minimum and maximum extent of the PointCloud.

Parameters
[in]PointCloudPoint cloud of which to calculate the extend.
[out]BoundingBoxVariable to receive the extent.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud IComposite.
See also
CVC3DCreateCroppedPointCloud, CVC3DCreateFrustumCroppedPointCloud

◆ CVC3DPointCloudCalculateCenterOfGravity()

cvbres_t CVC3DPointCloudCalculateCenterOfGravity ( CVCOMPOSITE  PointCloud,
CVC3DPointD Center 
)

Calculates the center of gravity of the PointCloud.

Parameters
[in]PointCloudPoint cloud of which to calculate the extend.
[out]CenterVariable to receive the center.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud IComposite.

◆ CVC3DPointCloudCalculateCovarianceMatrix()

cvbres_t CVC3DPointCloudCalculateCovarianceMatrix ( CVCOMPOSITE  PointCloud,
CVC3DMatrix  Covariance 
)

Calculates the covariance matrix of the PointCloud.

The trace of this matrix contains the components variances (xx, yy, zz). The other cells the respective covariances (xy, xz, ...).

Parameters
[in]PointCloudPoint cloud of which to calculate the extend.
[out]CovarianceMatrix to be filled.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_PARAMETER) if Covariance is nullptr.
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud IComposite.

◆ CVC3DPointCloudCalculatePlaneFromCuboid()

cvbres_t CVC3DPointCloudCalculatePlaneFromCuboid ( CVCOMPOSITE  PointCloud,
const CVC3DCuboid AOI,
CVC3DPlane Plane 
)

Fits a plane into the given pPoints.

Any plane in 3D space can be found. It uses a Hessian Normal representation for the plane.

Note
NumPoints must be at least 3. The pPoints should not be on the same line as the solution then is ambiguous.
The normal direction is set so that the distance to the origin is always positive.
Parameters
[in]PointCloudPoint cloud of which points are to be taken.
[in]AOICuboid of the region of points to be considered for plane fit.
[out]PlaneReference to structure to be filled with plane data.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud IComposite.
  • #CVC_ERROR (#CVC_E_NOINTERSECTION) if AOI resulted in an no points.
  • #CVC_ERROR (#CVC_E_PARAMETER) if parameters are invalid.
See also
CVC3DCalculatePlaneFromPointFs, CVC3DCalculatePlaneFromPointDs

◆ CVC3DPointCloudGetPolygonTable()

cvbres_t CVC3DPointCloudGetPolygonTable ( CVCOMPOSITE  Mesh,
CVC3DPolygonIndexTable PolygonTable,
cvbint64_t &  NumPolygons 
)

Gets the mesh's polygon vertex indices embedded into the PointCloud.

If PointCloud was loaded with mesh information, this is retrieved otherwise NumPolygons is set to 0 and an error code is returned.

The mesh information is stored in PolygonTable as 32-bit unsigned
integers. The first value always specifies how many vertex indices a polygon has. After the number of indices, exactly this number of values follow. They are the indices of points in PointCloud. All these points constitute a single face of the mesh. If not having reached the last polygon, the next integer is the number of indices of the next polygon. NumPolygons contains the number of polygons.
Parameters
[in]MeshHandle to pointcloud object with mesh information.
[out]PolygonTablePointer to receive the address to the index table.
[out]NumPolygonsThe number of polygons represented in PolygonTable.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_NOTPRESENT) if PointCloud does not contain mesh information.
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud IComposite.

◆ CVC3DPointCloudToMemory()

cvbres_t CVC3DPointCloudToMemory ( CVCOMPOSITE  PointCloud,
cvbval_t  Flags,
CVC3DPointCloudFileFormat  FileFormat,
void *  Memory,
size_t  Size 
)

Saves the given PointCloud to the Memory in the given FileFormat.

The data format to be used is determined by the FileFormat. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz

CVC3DPointCloudToMemorySize can be used to determine the required size for Memory.

Note
Exporting polygon information is only supported for ply, obj and stl. For the other formats this function only saves the point (or vertex) data. Applications expecting polygon information will fail to load the saved files.
Stereo Lithography (STL) is only supported if polygon information is present.
Parameters
[in]PointCloudPoint cloud object to save.
[in]FlagsIgnored so far.
[in]FileFormatThe data format to be used for the export.
[in,out]MemoryThe buffer, that the export should be written to.
[in]SizeThe size of the buffer in bytes.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud.
  • #CVC_ERROR (#CVC_E_NOTSUPPORTED) if the file format is not supported
  • #CVC_ERROR (#CVC_E_NOTENOUGHDATA) if the Size of the buffer is too small.
  • #CVC_ERROR (#CVC_E_PARAMETER) if the Memory is NULL or Size is 0.
See also
CVC3DPointCloudToMemorySize, CVC3DMemoryToPointCloud

◆ CVC3DPointCloudToMemorySize()

cvbres_t CVC3DPointCloudToMemorySize ( CVCOMPOSITE  PointCloud,
cvbval_t  Flags,
CVC3DPointCloudFileFormat  FileFormat,
size_t &  Size 
)

Determine the amount of memory needed for CVC3DMemoryToPointCloud.

The data format to be considered is determined by the FileFormat. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
ASCII asc, pts, txt, xyz
Parameters
[in]PointCloudPoint cloud object to save.
[in]FlagsIgnored so far.
[in]FileFormatThe data format to be used for the export.
[in,out]SizeThe size of the buffer in bytes.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud.
  • #CVC_ERROR (#CVC_E_NOTSUPPORTED) if the file format is not supported
See also
CVC3DMemoryToPointCloud, CVC3DPointCloudToMemory

◆ CVC3DWriteFile()

cvbres_t CVC3DWriteFile ( CVCOMPOSITE  PointCloud,
cvbval_t  Flags,
const char *  FileName 
)

Saves the given PointCloud to the file with the given FileName (ASCII string version).

The type of file to be saved is determined by the FileName extension. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
TIFF tif, tiff
ASCII asc, pts, txt, xyz
PCL Format pcd
Note
Exporting polygon information is only supported for ply, obj and stl. For the other formats this function only saves the point (or vertex) data. Applications expecting polygon information will fail to load the saved files.
Stereo Lithography (STL) is only supported if polygon information is present.
When saving to TIFF the file will contain three float or double samples per point (x,y,z) depending on the cvbdatatype_t of the PointCloud. For dense clouds width and height are set accordingly; for sparse clouds the width is one and the height is the number of points. Thus TIFF is the only format that preserves the dense point cloud lattice.
Parameters
[in]PointCloudPoint cloud object to save.
[in]FlagsIgnored so far.
[in]FileNameFull path where to save the file to.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud.
  • #CVC_ERROR (#CVC_E_PARAMETER) if FileName is NULL
  • #CVC_ERROR (#CVC_E_FILEIO) if writing to FileName is not possible
  • #CVC_ERROR (#CVC_E_NOTSUPPORTED) if the file format is not supported

◆ CVC3DWriteFileW()

cvbres_t CVC3DWriteFileW ( CVCOMPOSITE  PointCloud,
cvbval_t  Flags,
const wchar_t *  FileName 
)

Saves the given PointCloud to the file with the given FileName (Unicode string version).

The type of file to be saved is determined by the FileName extension. The following file formats are supported:

Name Extension(s)
Polygon File Format ply
Wavefront OBJ obj
Stereo Lithography stl
TIFF tif, tiff
ASCII asc, pts, txt, xyz
PCL Format pcd
Note
Exporting polygon information is only supported for ply, obj and stl. For the other formats this function only saves the point (or vertex) data. Applications expecting polygon information will fail to load the saved files.
Stereo Lithography (STL) is only supported if polygon information is present.
When saving to TIFF the file will contain three float or double samples per point (x,y,z) depending on the cvbdatatype_t of the PointCloud. For dense clouds width and height are set accordingly; for sparse clouds the width is one and the height is the number of points. Thus TIFF is the only format that preserves the dense point cloud lattice.
Parameters
[in]PointCloudPoint cloud object to save.
[in]FlagsIgnored so far.
[in]FileNameFull path where to save the file to.
Returns
  • #CVC_ERROR (#CVC_E_OK) on success
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud.
  • #CVC_ERROR (#CVC_E_PARAMETER) if FileName is NULL
  • #CVC_ERROR (#CVC_E_FILEIO) if writing to FileName is not possible
  • #CVC_ERROR (#CVC_E_NOTSUPPORTED) if the file format is not supported