RangeMapHandling

Functions for PointCloud / range map conversion and operations on range maps. More...

Data Structures
struct	CVC3DGapFilling
	Options for gap filling with function CVC3DRangeMapFillGaps. More...

Enumerations
enum	CVC3DGapFillingMethod { CVC3DGFM_LinearInterpolation = 0 }
	Supported methods for gap filling. More...
enum	CVC3DPfncFormat { CVC3D_Coord3D_C64f = 0x814000BF }
	CVB custom PFNC constants. More...

Functions
cvbres_t	CVC3DCreateDensePointCloudFromRangeMap (OBJ RangeMapImage, CVC3DFactors Factors, cvbval_t Flags, CVCOMPOSITE &PointCloud)
	Creates a new Cartesian 3D PointCloud from the given 2½D RangeMapImage. More...
cvbres_t	CVC3DCreateDifferenceMap (IMG RangeMap1, IMG RangeMap2, IMG &DifferenceMap)
	Subtracts the given RangeMap2 from RangeMap1. More...
cvbres_t	CVC3DCreateRangeMapFromPointCloud (CVCOMPOSITE PointCloud, CVC3DRange XRange, CVC3DRange YRange, cvbdim_t TargetWidth, cvbdim_t TargetHeight, double BackgroundValue, IMG &RangeMap)
	Creates a new range map image via linear projection in negative z direction. More...
cvbres_t	CVC3DRangeMapFillGaps (const CVC3DGapFilling &Options, IMG RangeMap)
	This function fills gaps of given range map RangeMap. More...

Detailed Description

Functions for PointCloud / range map conversion and operations on range maps.

Enumeration Type Documentation

CVC3DGapFillingMethod

enum CVC3DGapFillingMethod

Supported methods for gap filling.

Enumerator
CVC3DGFM_LinearInterpolation	Gaps in a range map are filled by linear interpolation.

CVC3DPfncFormat

enum CVC3DPfncFormat

CVB custom PFNC constants.

Enumerator
CVC3D_Coord3D_C64f	Single double Z component buffer.

Function Documentation

CVC3DCreateDensePointCloudFromRangeMap()

cvbres_t CVC3DCreateDensePointCloudFromRangeMap	(	OBJ	RangeMapImage,
		CVC3DFactors	Factors,
		cvbval_t	Flags,
		CVCOMPOSITE &	PointCloud
	)

Creates a new Cartesian 3D PointCloud from the given 2½D RangeMapImage.

This function simply accesses the first plane of the given RangeMapImage and interprets the pixel data as depth information (z). The resulting point cloud will have ImageWidth(RangeMapImage) * ImageHeight(RangeMapImage) points.

The following BytesPerPixel as input for unsigned integer cvbdatatype_t values are supported: 1, 2 and 4. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported. Note, that only linear access is supported (check with GetLinearAccess function from the CVCUtilities.dll).

The resulting point cloud is created via CVC3DCreateDensePointCloud.

Note

This function does not take the RangeMapImage coordinate system into account.

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

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	Factors	Transformation factor to apply to each coordinate.
[in]	Flags	CVC3DPointCloudFlags specifying the kind of point cloud to be created.
[out]	PointCloud	Variable to receive the handle of the point cloud object as a CVCOMPOSITE.

Returns

• CVC_ERROR (CVC_E_OK) on success
• CVC_ERROR (CVC_E_PARAMETER) if Factors contain NaN or Flags have an unsupported combination.
• CVC_ERROR (CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object.
• CVC_ERROR (CVC_E_MEMORY) if not enough memory was available to create the point cloud.

See also

CVC3DCreateCalibratedPointCloudFromRangeMap, CVC3DCreateRangeMapFromPointCloud

CVC3DCreateDifferenceMap()

cvbres_t CVC3DCreateDifferenceMap	(	IMG	RangeMap1,
		IMG	RangeMap2,
		IMG &	DifferenceMap
	)

Subtracts the given RangeMap2 from RangeMap1.

The following BytesPerPixel as input for unsigned integer cvbdatatype_t values are supported: 1, 2 and 4. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported. Note, that only linear access is supported (check with GetLinearAccess function from the CVCUtilities.dll).

The output difference map will be double for double input images (cvbdatatype_t: DT_Float | DT_Signed | 64 ), for all other images it will be float (cvbdatatype_t: DT_Float | DT_Signed | 32).

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

Parameters

[in]	RangeMap1	Range map IImageVPA object to subtract from.
[in]	RangeMap2	Range map IImageVPA object to subtract from RangeMap1.
[out]	DifferenceMap	Variable to receive the resulting difference map.

Returns

• CVC_ERROR (CVC_E_OK) on success
• CVC_ERROR (CVC_E_PARAMETER) if input data types or sizes do not match.
• CVC_ERROR (CVC_E_INVALIDDATATYPE) if input data type is not float or double.
• CVC_ERROR (CVC_E_WRONGOBJECT) if RangeMap1 and/or RangeMap2 are not a valid IImageVPA range map objects.
• CVC_ERROR (CVC_E_MEMORY) if not enough memory was available to create the range map DifferenceMap.

See also

CVC3DRangeMapFillGaps

CVC3DCreateRangeMapFromPointCloud()

cvbres_t CVC3DCreateRangeMapFromPointCloud	(	CVCOMPOSITE	PointCloud,
		CVC3DRange	XRange,
		CVC3DRange	YRange,
		cvbdim_t	TargetWidth,
		cvbdim_t	TargetHeight,
		double	BackgroundValue,
		IMG &	RangeMap
	)

Creates a new range map image via linear projection in negative z direction.

Projects a cuboid from the given PointCloud into a 2½D Image. The cuboid is defined via the given XRange and YRange. In z-range the cuboid is limited to the BackgroundValue as minimum.

The projection done is linear (no perspective projection) and no interpolation is done. If multiple points from PointCloud fall into the same target Image pixel, the point with the largest z component is set. If no point falls into certain RangeMap pixel locations, the BackgroundValue is set.

The given PointCloud must have a valid CVC3DPointCloudLayout.

Note

RangeMap is a contiguous float image depending on the cvbdatatype_t of the given PointCloud:

• (cvbdatatype_t DT_Float | DT_Signed | 32 / PFNC value Coord3D_C32f).
• (cvbdatatype_t DT_Float | DT_Signed | 64 / PFNC value CVC3D_Coord3D_C64f).

The RangeMap coordinate system is the default coordinate system.

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

Parameters

[in]	PointCloud	Handle to point cloud object to project.
[in]	XRange	Input window along the x axis (inclusive).
[in]	YRange	Input window along the y axis (inclusive).
[in]	TargetWidth	Target width of RangeMap in pixels (greater or equal to 2).
[in]	TargetHeight	Target height of RangeMap in pixels (greater or equal to 2).
[in]	BackgroundValue	Background value (initialization value for RangeMap).
[out]	RangeMap	Variable to receive the resulting range map image.

Returns

• CVC_ERROR (CVC_E_OK) on success
• CVC_ERROR (CVC_E_PARAMETER) if input window or target size are invalid.
• CVC_ERROR (CVC_E_WRONGOBJECT) if PointCloud is not a valid point cloud IComposite.
• CVC_ERROR (CVC_E_MEMORY) if not enough memory was available to create the range map RangeMap.

Example

When creating a point cloud from a range map and then recreating the range map from the point cloud with the same ranges/sizes (parallel projection), both range maps are identical.

#include <cassert>
#include <iCVCore3D.h>
 
static const float RangeData[] =
{
  .0f, .0f, .0f, .0f, .0f, 
  .0f, 't', 't', 't', .0f, 
  .0f, .0f, 't', .0f, .0f, 
  .0f, .0f, 't', .0f, .0f, 
  .0f, .0f, 't', .0f, .0f, 
  .0f, .0f, 't', .0f, .0f, 
  .0f, .0f, .0f, .0f, .0f
};
static const cvbdim_t RangeDataWidth = 5;
static const cvbdim_t RangeDataHeight = 7;
 
IMG CreateTestRangeMap();
 
int main()
{
  IMG inputRangeMap = CreateTestRangeMap();
  
  // forward transform: do not scale the point cloud
  CVCOMPOSITE pointCloud = nullptr;
  cvbres_t result = CVC3DCreateDensePointCloudFromRangeMap(inputRangeMap, { 1.0, 1.0, 1.0 }, CVC3DPCF_DTFloat | CVC3DPCF_XYZ, pointCloud);
  assert(result >= 0);
  
 
  // backward transform
  IMG outputRangeMap = nullptr;
  result = CVC3DCreateRangeMapFromPointCloud(pointCloud, 
    { 0, RangeDataWidth-1 },            // x-range
    { 0, RangeDataHeight-1 },           // y-range
    RangeDataWidth, RangeDataHeight,    // target size
    .0,                                 // background
    outputRangeMap); 
  assert(result >= 0);
  
  
  // test
  float *pOutputBase = nullptr;
  intptr_t outputXInc = 0, outputYInc = 0;
  result = CVCPlaneGetPixelPointer(outputRangeMap, 0, reinterpret_cast<void *&>(pOutputBase), outputXInc, outputYInc);
  assert(result >= 0);
  // check if the range map is a contiguous 2d-array
  assert(outputXInc == sizeof(float));
  assert(outputYInc == static_cast<intptr_t>(sizeof(float)) * RangeDataWidth);
  
  for(int y = 0; y < RangeDataHeight; y++)
  {
    const float *pInputLine = RangeData + y * RangeDataWidth;
    const float *pOutputLine = pOutputBase + y * RangeDataWidth;
    
    for(int x = 0; x < RangeDataWidth; x++)
    {
      assert(pOutputLine[x] == pInputLine[x]);
    }
  }
  
  
  // clean up
  ReleaseObject(outputRangeMap);
  ReleaseObject(pointCloud);
  ReleaseObject(inputRangeMap);
}
 
static void __stdcall nop_release(void *, void *) {}
 
IMG CreateTestRangeMap()
{
  IMG hRangeMap = nullptr;
  cvbres_t result = CreateImageFromPointer(
    const_cast<float*>(RangeData), sizeof(RangeData),
    RangeDataWidth, RangeDataHeight,    // size
    1,                                  // one plane
    DT_Float | DT_Signed | 32,          // float data type
    sizeof(float),                      // x-inc in bytes
    RangeDataWidth * sizeof(float),     // y-inc in bytes
    0,                                  // no plane offset (single plane)
    nullptr,                            // default plane order (single plane)
    &nop_release, nullptr,              // no release as we have static data
    hRangeMap
  );
  assert(result >= 0);
  return hRangeMap;
}

See also

CVC3DCreateDensePointCloudFromRangeMap, CVC3DRangeMapFillGaps

CVC3DRangeMapFillGaps()

cvbres_t CVC3DRangeMapFillGaps	(	const CVC3DGapFilling &	Options,
		IMG	RangeMap
	)

This function fills gaps of given range map RangeMap.

Gaps will be filled by interpolating values of pixels surrounding the gap. If larger gaps should be ignored, the maximum size of gaps to be filled has to be set with Options.

The following BytesPerPixel as input for unsigned integer cvbdatatype_t values are supported: 1, 2 and 4. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported. Note, that only linear access is supported (check with GetLinearAccess function from the CVCUtilities.dll).

Note

• Only mono images with one plane are supported.
• Only range maps with at least 3 columns are supported.

Parameters

[in]	Options	Options for gap filling.
[in,out]	RangeMap	Range map where gaps should be filled.

Returns

• CVC_ERROR (CVC_E_OK) on success
• CVC_ERROR (CVC_E_WRONGOBJECT) if RangeMap is not a valid range map.
• CVC_ERROR (CVC_E_INVALIDDIMENSION) if RangeMap is to small.
• CVC_ERROR (CVC_E_MEMORY) if not enough memory was available to create the range map RangeMap.

See also

CVC3DCreateRangeMapFromPointCloud, CVC3DCreateDifferenceMap