Projection of a COP on the XY plane. More...

#include <ZMap.hpp>

Public Member Functions
	ZMap (const COP &cop, const ZMapFactors &zFactors, bool pointCells=false)
	Creates a new zmap from a cloud of points.
	ZMap (const COP &cop, const Movement3D &movement, const ZMapFactors &zFactors, bool pointCells=false)
	Creates a new zmap from a moved cloud of points.
	ZMap (const ZMapFactors &zFactors)
	Create a void ZMap.
	ZMap (const std::string &fileName)
	Loads a zmap from a file.
	ZMap (sal3d_zmap zmap)
	Creates a new C++ object that holds a sal3d_zmap.
	ZMap (const ZMap &zmap)
	Copy constructor.
	~ZMap ()
	Destructor.
ZMap	copy () const
	Get a deep copy of the ZMap.
sal3d_zmap	c_zmap () const
	Returns the C pointer to the zmap.
ZMapFactors	getFactors () const
	Gets the ZMap's factors.
Frame	getFrame (int dataType=SAL3D_FLOAT_DATA_TYPE(32), float zmin=0, float zmax=0) const
	Gets a frame from the zmap.
Frame	getFrame (int dataType, float zmin, float zmax) const
	Gets a frame from the zmap.
float	getX (int iy) const
	Gets the x coordinate from the iy'th row.
float	getY (int ix) const
	Gets the y coordinate from the ix'th column.
float	getZ (int ix, int iy) const
	Gets the z coordinate from `ix`, `iy`.
void	getPoint (int ix, int iy, float &x, float &y, float &z) const
	Gets the point coordinates from `ix`, `iy`.
const Row	operator[] (int iy) const
	Gets the iy'th const row from the ZMap.
Row	operator[] (int iy)
	Gets the iy'th row from the ZMap.
ZMap &	operator= (const ZMap &rhs)
	Assignment operator.
ZMap	getDistanceToZMap (const ZMap &zmap) const
	Get the disparity map by comparing the two ZMaps.
ZMap	getFineDistanceToZMap (const ZMap &zmap, int windowSize) const
	Get the fine disparity map by comparing the two ZMaps.
ZMap	getDistanceToMovedCOP (const COP &cop, const Movement3D &movement) const
	Get the disparity map by comparing the ZMap to a moved COP.
ZMap	getFineDistanceToMovedCOP (const COP &cop, const Movement3D &movement, int windowSize) const
	Get the fine disparity map by comparing the ZMap to a moved COP.
void	saveToFile (const std::string &fileName) const
	Saves the ZMap to a file.

Detailed Description

Projection of a COP on the XY plane.

This class requires linking with core3d.lib (import library for core3d.dll).

The ZMap class was thought of as an easy way to compare different Clouds of Points, which is specially useful when those COPs represent two similar physical objects that we have previously aligned, since we can then get a map of differences between both objects.

Basically, a ZMap object is a two dimensional array representing a projection of a Cloud of Points on the XY plane, with every value of that array representing the Z coordinate at that point (if we take the XY plane as the floor, we can think of it as the height at that point).

The user can create a ZMap object from a Cloud of Points, by specifying the region of interest and the desired resolution. This is accomplished by filling the ZMapFactors structure with the limiting X and Y metric coordinates, and the number of points wanted in each axis. The metric information can be retrieved using getX(), getY(), getZ() and getPoint(), or if more efficient access is required, by getting a Row through the operator[].

As we have already pointed out, this class is specially useful to compare different COPs representing similar objects. The easiest way to accomplish this is with the function getDistanceToMovedCOP(). The ZMap resulting from this operation, which we refer to as a Disparity Map, will have the same factors as the base ZMap, and each value will represent the difference of heights between the base ZMap and a ZMap created from the COP with the same factors. If this distance cannot be computed due to the point not being defined in one or any of the operands, the resulting point in the disparity map will have a special value: +infinity when it is defined in the part but not on the model, -infinity when defined in the model but not the part, and NaN when it is not defined in any of them.

Constructor & Destructor Documentation

sal3d::ZMap::ZMap	(	const COP &	cop,
		const ZMapFactors &	zFactors,
		bool	pointCells = `false`
	)		`[inline]`

Creates a new zmap from a cloud of points.

The given ZMapFactors specifies the region of the COP that will be taken to create the ZMap, as well as the size of this created ZMap.

Parameters:

[in]	cop	The cloud of points to create the zmap from.
[in]	zFactors	The factors to select the region of interest and resolution of the zmap.
[in]	pointCells	Don't use neighbouring information from the COP to fill the ZMap, project only points to ZMap cells.

Exceptions:

sal3d::Error On error

References sal3d::COP::c_cop(), and sal3d::Movement3D::c_movement_3d().

Referenced by copy(), getDistanceToZMap(), and getFineDistanceToZMap().

sal3d::ZMap::ZMap	(	const COP &	cop,
		const Movement3D &	movement,
		const ZMapFactors &	zFactors,
		bool	pointCells = `false`
	)		`[inline]`

Creates a new zmap from a moved cloud of points.

The movement is applied to the COP and the result is then converted to a ZMap.

Parameters:

[in]	cop	The cloud of points to create the zmap from.
[in]	movement	The Movement3D matrix that specifies the transformation to be applied to the cop.
[in]	zFactors	The factors to select the region of interest and resolution of the zmap.
[in]	pointCells	Don't use neighbouring information from the COP to fill the ZMap, project only points to ZMap cells.

Exceptions:

sal3d::Error On error

References sal3d::COP::c_cop(), and sal3d::Movement3D::c_movement_3d().

sal3d::ZMap::ZMap ( const ZMapFactors & zFactors ) [inline]

Create a void ZMap.

The ZMap values will not be initialized.

Parameters:

[in] zFactors The factors related with the ZMap

Exceptions:

sal3d::Error On error

sal3d::ZMap::ZMap ( const std::string & fileName ) [inline, explicit]

Loads a zmap from a file.

Parameters:

[in] fileName The name of the file to use to load the zmap.

Exceptions:

sal3d::Error On error

sal3d::ZMap::ZMap ( sal3d_zmap zmap ) [inline, explicit]

Creates a new C++ object that holds a sal3d_zmap.

The new C++ ZMap object will get the ownership of the zmap. That means that you should not call sal3d_zmap_release() to this zmap, otherwise it would be called twice.

Parameters:

[in] zmap The C sal3d_zmap to use to create this object.

Exceptions:

sal3d::Error On error

sal3d::ZMap::ZMap ( const ZMap & zmap ) [inline]

Copy constructor.

Parameters:

[in] zmap The zmap to copy from.

Exceptions:

sal3d::Error On error

sal3d::ZMap::~ZMap ( ) [inline]

Destructor.

If the reference counter reaches zero, the object is destroyed and its memory released.

Member Function Documentation

sal3d_zmap sal3d::ZMap::c_zmap ( ) const [inline]

Returns the C pointer to the zmap.

Warning:: Never call sal3d_zmap_release() with the pointer returned by this function or the application will fail.

Returns:: The pointer to sal3d's zmap C interface.

Referenced by sal3d::Viewer::display().

ZMap sal3d::ZMap::copy ( ) const [inline]

Get a deep copy of the ZMap.

This means that the object and its memory is duplicated. More information about this can be fount at Memory management: reference counting.

Returns:: A ZMap which is a hard copy of this.

Exceptions:

sal3d::Error On error

References ZMap().

ZMap sal3d::ZMap::getDistanceToMovedCOP	(	const COP &	cop,
		const Movement3D &	movement
	)		const `[inline]`

Get the disparity map by comparing the ZMap to a moved COP.

A new ZMap is created, with the same factors as the base ones, with each point representing the difference between the ZMap, and a ZMap created from the COP with also the same factors. If a point is not defined in any of the zmaps, the resulting point will hold a special value: +infinity when it is defined in the part but not on the model, -infinity when defined in the model but not the part, and NaN when it is not defined in any of them.

If more accuracy is needed for the comparisons on edges, the getFineDistanceToMovedCOP() can be used.

Parameters:

[in]	cop	The cop that, after being converted to ZMap, will be used for the comparison.
[in]	movement	The movement matrix to apply to the cop before comparing it to the ZMap.

Exceptions:

sal3d::Error On error

References getDistanceToZMap(), and getFactors().

ZMap sal3d::ZMap::getDistanceToZMap ( const ZMap & zmap ) const [inline]

Get the disparity map by comparing the two ZMaps.

A new ZMap is created, with the same factors as the base ones, with each point representing the difference between them. If a point is not defined in any of the zmaps, the resulting point will hold a special value: +infinity when it is defined in the part but not on the model, -infinity when defined in the model but not the part, and NaN when it is not defined in any of them.

If more accuracy is needed for the comparisons on edges, the getFineDistanceToZMap() can be used.

Warning:: The ZMap passed as parameter must have the same parameters as this, otherwise the comparison will fail.

Parameters:

[in] zmap The zmap to be compared with.

Exceptions:

sal3d::Error On error

References ZMap().

Referenced by getDistanceToMovedCOP().

ZMapFactors sal3d::ZMap::getFactors ( ) const [inline]

Gets the ZMap's factors.

Returns:: The factors with which the ZMap was created.

Exceptions:

sal3d::Error On error

Referenced by getDistanceToMovedCOP(), getFineDistanceToMovedCOP(), getX(), and getY().

ZMap sal3d::ZMap::getFineDistanceToMovedCOP	(	const COP &	cop,
		const Movement3D &	movement,
		int	windowSize
	)		const `[inline]`

Get the fine disparity map by comparing the ZMap to a moved COP.

A new ZMap is created, with the same factors as the base one, with each point representing the difference between the ZMap, and a ZMap created from the COP with also the same factors. This function differs from getDistanceToMovedCOP() in that each point is not only compared to the corresponding point in the other ZMap, but to all the points within a window of the specified size. The resulting value is the minimum computed distance between them. This means that using a window of size 1 is like using the getDistanceToMovedCOP() function. All the special values still apply (NaN, +infinity and -infinity).

Remarks:: The window size should be an odd number, otherwise it is reduced 1 from the specified value to make it so.

Parameters:

[in]	cop	The cop that, after being converted to ZMap, will be used for the comparison.
[in]	movement	The movement matrix to apply to the cop before comparing it to the ZMap.
[in]	windowSize	The size of the window to be used the comparison.

Exceptions:

sal3d::Error On error

References getFactors(), and getFineDistanceToZMap().

ZMap sal3d::ZMap::getFineDistanceToZMap	(	const ZMap &	zmap,
		int	windowSize
	)		const `[inline]`

Get the fine disparity map by comparing the two ZMaps.

A new ZMap is created, with the same factors as the base ones, with each point representing the difference between them. This function differs from getDistanceToZMap() in that each point is not only compared to the corresponding point in the other ZMap, but to all the points within a window of the specified size. The resulting value is the minimum computed distance between them. This means that using a window of size 1 is like using the getDistanceToZMap() function. All the special values still apply (NaN, +infinity and -infinity).

Remarks:: The window size should be an odd number, otherwise it is reduced 1 from the specified value to make it so.

Warning:: The ZMap passed as parameter must have the same parameters as this, otherwise the comparison will fail.

Parameters:

[in]	zmap	The zmap to be compared with.
[in]	windowSize	The size of the window to be used the comparison.

Exceptions:

sal3d::Error On error

References ZMap().

Referenced by getFineDistanceToMovedCOP().

Frame sal3d::ZMap::getFrame	(	int	dataType = `SAL3D_FLOAT_DATA_TYPE(32)`,
		float *	zmin = `0`,
		float *	zmax = `0`
	)		const `[inline]`

Gets a frame from the zmap.

This function creates a Frame of the desired datatype and fills it with the data of the ZMap. If datatype is SAL3D_FLOAT_DATA_TYPE(32) no conversion will take place. Otherwise, the data is rescaled to fit the whole range of the output datatype, with some special values. If datatype is unsigned, they are:

0: undefined point
1: -infinity
2: infinity

And if datatype is signed:

-range_limit: undefined point
-(range_limit-1): -infinity
range_limit: infinity

If zmin and zmax pointers are provided, the floats are filled with the limit values of the input range.

Parameters:

[in]	dataType	The zmap to copy from.
[out]	zmin	Pointer to a float that will be filled with the lowest value found in the ZMap.
[out]	zmax	Pointer to a float that will be filled with the highest value found in the ZMap.

Returns:: The Frame created from the ZMap.

Exceptions:

sal3d::Error On error

Frame sal3d::ZMap::getFrame	(	int	dataType,
		float	zmin,
		float	zmax
	)		const `[inline]`

Gets a frame from the zmap.

This function creates a Frame of the desired datatype and fills it with the data of the ZMap. Only the range from zmin to zmax is taken from the ZMap to compute the scaling. If datatype is SAL3D_FLOAT_DATA_TYPE(32) no conversion will take place. Otherwise, the data is rescaled to fit the whole range of the output datatype, with some special values. If datatype is unsigned, they are:

0: undefined point
1: -infinity
2: infinity

And if datatype is signed:

-range_limit: undefined point
-(range_limit-1): -infinity
range_limit: infinity

Parameters:

[in]	dataType	The zmap to copy from.
[in]	zmin	Lower limit to be taken as the input range.
[in]	zmax	Higher limit to be taken as the input range.

Returns:: The Frame created from the ZMap.

Exceptions:

sal3d::Error On error

void sal3d::ZMap::getPoint	(	int	ix,
		int	iy,
		float &	x,
		float &	y,
		float &	z
	)		const `[inline]`

Gets the point coordinates from ix, iy.

Parameters:

[in]	ix	The column index from which we want to know the 3D coordinates.
[in]	iy	The row index from which we want to know the 3D coordinates.
[out]	x	The x metric coordinate of the point.
[out]	y	The y metric coordinate of the point.
[out]	z	The z metric coordinate of the point.

References getX(), and getY().

float sal3d::ZMap::getX ( int iy ) const [inline]

Gets the x coordinate from the iy'th row.

Parameters:

[in] iy The row index from which we want to know the corresponding x.

Returns:: The x coordinate in the zmap corresponding to the iy row.

References getFactors().

Referenced by getPoint().

float sal3d::ZMap::getY ( int ix ) const [inline]

Gets the y coordinate from the ix'th column.

Parameters:

[in] ix The column index from which we want to know the corresponding y.

Returns:: The y coordinate in the zmap corresponding to the ix column.

References getFactors().

Referenced by getPoint().

float sal3d::ZMap::getZ	(	int	ix,
		int	iy
	)		const `[inline]`

Gets the z coordinate from ix, iy.

Parameters:

[in]	ix	The column index from which we want to know the corresponding z.
[in]	iy	The row index from which we want to know the corresponding z.

Returns:: The z coordinate in the zmap corresponding to the ix,iy position.

ZMap& sal3d::ZMap::operator= ( const ZMap & rhs ) [inline]

Assignment operator.

Parameters:

[in] rhs The zmap to copy from.

Returns:: A reference to this object.

const Row sal3d::ZMap::operator[] ( int iy ) const [inline]

Gets the iy'th const row from the ZMap.

Parameters:

[in] iy The row index to get. The allowed range is 0..height - 1.

Returns:: The const iy'th row of the ZMap.

Exceptions:

sal3d::Error On error

Row sal3d::ZMap::operator[] ( int iy ) [inline]

Gets the iy'th row from the ZMap.

Parameters:

[in] iy The row index to get. The allowed range is 0..height - 1.

Returns:: The iy'th row of the ZMap.

void sal3d::ZMap::saveToFile ( const std::string & fileName ) const [inline]

Saves the ZMap to a file.

Parameters:

[in] fileName The name of the file to use to save the zmap. The used extension for this type of files is .zmp.

Exceptions:

sal3d::Error On error

The documentation for this class was generated from the following file:

ZMap.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation