Access and manipulate transformation matrices. More...

reme_error_t	reme_transform_set_predefined (reme_context_t c, reme_transform_t t, float *coordinates)
	Set the matrix to a predefined transform. More...

reme_error_t	reme_transform_look_at (reme_context_t c, const float eye, const float ref, const float up, float coordinates)
	Defines a viewing transformation. More...

reme_error_t	reme_transform_compensate_tilt (reme_context_t c, const float cur_coordinates, int tilt_angle_diff, float new_coordinates)
	Compensate a tilt movement. More...

reme_error_t	reme_transform_make_relative (reme_context_t c, const float a_t, const float b_t, float *c_t)
	Calculate the relative transform between two coordinate frames. More...

reme_error_t	reme_transform_get_projected_angle (reme_context_t c, const float plane_normal, const float a_t, const float b_t, float angle)
	Calculate the signed projected angle in radians between two sensor positions in a given plane. More...

reme_error_t	reme_transform_invert (reme_context_t c, const float m_t, float inv_t)
	Invert the given transformation. More...

reme_error_t	reme_transform_multiply (reme_context_t c, const float a_t, const float b_t, float *m_t)
	Multiply two transforms. More...

Detailed Description

Access and manipulate transformation matrices.

In the ReconstructMe SDK rigid transformations are represented using 4x4 floating point homogeneous matrices. The upper 3x3 part contains the rotation matrix. The last column contains the translation vector. The last row is constant.

| Rxx Rxy Rxz Tx |
| Ryx Ryy Ryz Ty |
| Rzx Rzy Rzz Tz |
|   0   0   0  1 |

The memory layout is row-major. Flattened to a one dimensional array the above matrix is transformed into

| Rxx Rxy Rxz Tx Ryx Ryy Ryz Ty Rzx Rzy Rzz Tz 0 0 0 1|

Coordinate systems are represented by 4x4 single precision floating point homogeneous matrices. The upper 3x3 part contains the basis vectors in columns, the last column contains the origin of the frame and the last row is constant.

Function Documentation

◆ reme_transform_set_predefined()

reme_error_t reme_transform_set_predefined	(	reme_context_t	c,
		reme_transform_t	t,
		float *	coordinates
	)

Set the matrix to a predefined transform.

Parameters

c	A valid context object
t	A predefined transform type
coordinates	A pointer to mutable Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_bust.cpp, and example_reconstructmesdk_memory_management.cpp.

◆ reme_transform_look_at()

reme_error_t reme_transform_look_at	(	reme_context_t	c,
		const float *	eye,
		const float *	ref,
		const float *	up,
		float *	coordinates
	)

Defines a viewing transformation.

This method works similarily to gluLookAt. It defines a viewing transformation based on the eye coordinates, a viewing reference point and an up vector. This method simplifies specifying sensor positions (reme_sensor_set_position).

First, the view direction is vz is calculated by vz = ref - eye. This vector is normalized to unit length vz = vz / |vz| and becomes the z-vector of the viewing transformation. Next, the up vector is normalized to unit length up = up / |up|.

The cross product vx = -up x vz will become the x-axis of the viewing transformation after normalization vx = vx / |vx|.

Finally the cross product of vy = vz x vx defines the y-axis of the viewing transformation. The origin of the viewing transformation is set to the eye coordinates.

The final matrix becomes

| vx.x vy.x vz.x eye.x |
| vx.y vy.y vz.y eye.y |
| vx.z vy.z vz.z eye.z |
|    0    0    0     1 |

Parameters

c	A valid context object
eye	three dimensional vector defining the eye coordinates
ref	three dimensional vector defining the reference point coordinates
up	three dimensional vector defining the up vector
coordinates	A pointer to mutable Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_sensor_printing.cpp.

◆ reme_transform_compensate_tilt()

reme_error_t reme_transform_compensate_tilt	(	reme_context_t	c,
		const float *	cur_coordinates,
		int	tilt_angle_diff,
		float *	new_coordinates
	)

Compensate a tilt movement.

Popular 3D scanners such as the Microsoft Kinect and others have a motorized base that allows enlargement of the interaction space by tilting the sensor. These sensors, however, turn of the IR projector while the tilt is in progress, essentially making ReconstructMe blind while the tilt occurs. Since ReconstructMe currently relies on small movements between frames it will often loose track after the tilt completes.

This method allows you to compensate for such a blind tilt by specifying +/- tilt angle difference. As most sensors make the tilt relative to the gravitation vector the tilt angle difference can only be calculated accurately for sensors that stand on a fixed platform and are not moved by hand. After tilting it is currently advised to skip a couple of depth frames to compensate wrong data from a recent projector turn-on.

This method assumes that the tilt axis is parallel to the sensor positive sensor x-axis. It also assumes that the origin of the tilt movement is placed at roughly (0, 30, -25) with respect to the sensor coordinate system. As such, this compensation will currently only work for Kinect for Windows sensors. While this is an inaccurate measurement and the assumpations are partly wrong, the solution works in most cases as ReconstructMe is able to compensate for the remaining error.

Note that you cannot tilt arbitrary large angles as the Kinect limits the tilt-angle to +/- 27 degrees and a large tilt may force a lot of new data to be integrated which could trigger track-lost detection.

Note that starting with ReconstructMe 1.4 global registration is added which should be activated for the first frame after the tilt. This will greatly help to improve the tracking.

Warning MSDN states that tilting too often can cause damage to the tilt motor.

Parameters

c	A valid context object
cur_coordinates	Current sensor position before the tilt.
tilt_angle_diff	+/- difference of tilt angles before and after the tilt in degrees. I.e angles moved.
new_coordinates	Updated sensor position to compensate for tilting.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_scan_tilt.cpp.

◆ reme_transform_make_relative()

reme_error_t reme_transform_make_relative	(	reme_context_t	c,
		const float *	a_t,
		const float *	b_t,
		float *	c_t
	)

Calculate the relative transform between two coordinate frames.

Given two coordinate frames, a_t and b_t in the same parental coordinate frame, calculate b_t with respect to a_t. The result is stored in c_t.

Parameters

c	A valid context object
a_t	A pointer to non mutable Transform data.
b_t	A pointer to non mutable Transform data.
c_t	A pointer to mutable Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

◆ reme_transform_get_projected_angle()

reme_error_t reme_transform_get_projected_angle	(	reme_context_t	c,
		const float *	plane_normal,
		const float *	a_t,
		const float *	b_t,
		float *	angle
	)

Calculate the signed projected angle in radians between two sensor positions in a given plane.

Given two coordinate frames, a_t and b_t this method calculates the signed projected angle in the plane through the origin given by the unit length plane_normal. The resulting angle is returned in the interval [-PI, PI]. This method only takes the positional offset between the two frames into account and ignores its orientation.

Use this method to determine when the sensor has turned a specific amount around a given axis. To do so, you would pass plane_normal the rotation axis of interest, a_t the previous sensor position and b_t the current sensor position. By accumulating the resulting angles you are able to detect when a full rotation is complete (i.e fabs(sum(angles)) > 2*PI)

Parameters

c	A valid context object
plane_normal	Immutable pointer to plane normal. Normal is expected as array of 4 floating point values `x y z w`.
a_t	A pointer to non mutable Transform data.
b_t	A pointer to non mutable Transform data.
angle	Resulting angle.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_bust.cpp.

◆ reme_transform_invert()

reme_error_t reme_transform_invert	(	reme_context_t	c,
		const float *	m_t,
		float *	inv_t
	)

Invert the given transformation.

Parameters

c	A valid context object
m_t	A pointer to non mutable Transform data.
inv_t	A pointer to mutable Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:: example_reconstructmesdk_marker.cpp.

◆ reme_transform_multiply()

reme_error_t reme_transform_multiply	(	reme_context_t	c,
		const float *	a_t,
		const float *	b_t,
		float *	m_t
	)

Multiply two transforms.

Parameters

c	A valid context object
a_t	A pointer to non mutable Transform data.
b_t	A pointer to non mutable Transform data.
m_t	A pointer to mutable Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure