Image Manager (CVCore3D.dll) 15.0
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

Supported methods for gap filling.

Enumerator
CVC3DGFM_LinearInterpolation 

Gaps in a range map are filled by linear interpolation.

◆ 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]RangeMapImageHandle of 2½D image.
[in]FactorsTransformation factor to apply to each coordinate.
[in]FlagsCVC3DPointCloudFlags specifying the kind of point cloud to be created.
[out]PointCloudVariable to receive the handle of the point cloud object as a CVCOMPOSITE.
Returns
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]RangeMap1Range map IImageVPA object to subtract from.
[in]RangeMap2Range map IImageVPA object to subtract from RangeMap1.
[out]DifferenceMapVariable to receive the resulting difference map.
Returns
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]PointCloudHandle to point cloud object to project.
[in]XRangeInput window along the x axis (inclusive).
[in]YRangeInput window along the y axis (inclusive).
[in]TargetWidthTarget width of RangeMap in pixels (greater or equal to 2).
[in]TargetHeightTarget height of RangeMap in pixels (greater or equal to 2).
[in]BackgroundValueBackground value (initialization value for RangeMap).
[out]RangeMapVariable to receive the resulting range map image.
Returns
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;
}
void * CVCOMPOSITE
cvbres_t CVCPlaneGetPixelPointer(OBJ hObj, cvbdim_t PlaneIndex, void *&pScan0, intptr_t &XInc, intptr_t &YInc)
void * IMG
cvbres_t CreateImageFromPointer(void *pImageMemory, size_t MemorySize, cvbdim_t Width, cvbdim_t Height, cvbdim_t NumPlanes, cvbdatatype_t DataType, intptr_t PitchX, intptr_t PitchY, intptr_t PitchPlane, const cvbval_t PlaneOrder[], PFFINALRELEASE ReleaseCallback, void *pPrivate, IMG &ImageOut)
DT_Signed
DT_Float
cvbbool_t ReleaseObject(OBJ &Object)
@ CVC3DPCF_XYZ
Create the point cloud with three Cartesian components x, y, z.
Definition: iCVCore3D.h:52
@ CVC3DPCF_DTFloat
Create the point cloud with float components.
Definition: iCVCore3D.h:49
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.
Definition: RangeMapExports.cpp:413
cvbres_t CVC3DCreateDensePointCloudFromRangeMap(OBJ RangeMapImage, CVC3DFactors Factors, cvbval_t Flags, CVCOMPOSITE &PointCloud)
Creates a new Cartesian 3D PointCloud from the given 2½D RangeMapImage.
Definition: RangeMapExports.cpp:134
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]OptionsOptions for gap filling.
[in,out]RangeMapRange map where gaps should be filled.
Returns
See also
CVC3DCreateRangeMapFromPointCloud, CVC3DCreateDifferenceMap