RangeMapHandling

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

Enumerations
enum	CVC3DPfncFormat { CVC3D_Coord3D_C64f = 0x814000BF }

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...

Detailed Description

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

Enumeration Type Documentation

CVC3DPfncFormat

enum CVC3DPfncFormat

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 signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

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.

Note

RangeMap1/RangeMap2 are contiguous float images with the following supported cvbdatatype_t:

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

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.

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