Sensor

Acquire data from real-world sensors or from file streams. More...

Typedefs
typedef int	reme_sensor_t
	Handle referencing a sensor object.
typedef enum _reme_sensor_image_t	reme_sensor_image_t
	Image type enumeration.
typedef enum _reme_sensor_view_t	reme_sensor_view_t
	Sensor view type.
typedef enum _reme_sensor_trackmode_t	reme_sensor_trackmode_t
	Sensor tracking mode.
typedef enum _reme_sensor_trackhint_t	reme_sensor_trackhint_t
	Sensor tracking hint.

Enumerations
enum	_reme_sensor_image_t {   REME_IMAGE_AUX = 0,   REME_IMAGE_DEPTH = 1,   REME_IMAGE_VOLUME = 2 }
	Image type enumeration. More...
enum	_reme_sensor_view_t {   REME_SENSOR_VIEW_RAW = 0,   REME_SENSOR_VIEW_RECONSTRUCTED = 1 }
	Sensor view type. More...
enum	_reme_sensor_trackmode_t {   REME_SENSOR_TRACKMODE_AUTO = 0,   REME_SENSOR_TRACKMODE_LOCAL = 1,   REME_SENSOR_TRACKMODE_GLOBAL = 2 }
	Sensor tracking mode. More...
enum	_reme_sensor_trackhint_t {   REME_SENSOR_TRACKHINT_NONE = 0,   REME_SENSOR_TRACKHINT_USE_GLOBAL = 1 }
	Sensor tracking hint. More...
reme_error_t	reme_sensor_create (reme_context_t c, const char *driver, bool require_can_open, reme_sensor_t *s)
	Create a new sensor object.
reme_error_t	reme_sensor_destroy (reme_context_t c, reme_sensor_t *s)
	Destroy a previously created sensor object.
reme_error_t	reme_sensor_open (reme_context_t c, reme_sensor_t s)
	Open a sensor.
reme_error_t	reme_sensor_close (reme_context_t c, reme_sensor_t s)
	Close a an open sensor.
reme_error_t	reme_sensor_set_volume (reme_context_t c, reme_sensor_t s, reme_volume_t v)
	Set the working volume.
reme_error_t	reme_sensor_set_trackmode (reme_context_t c, reme_sensor_t s, reme_sensor_trackmode_t t)
	Set tracking mode.
reme_error_t	reme_sensor_set_trackhint (reme_context_t c, reme_sensor_t s, reme_sensor_trackhint_t t)
	Sets a tracking hint.
reme_error_t	reme_sensor_bind_camera_options (reme_context_t c, reme_sensor_t s, reme_options_t o)
	Access the sensor specific options that affect how the camera is opened.
reme_error_t	reme_sensor_bind_capture_options (reme_context_t c, reme_sensor_t s, reme_options_t o)
	Access the sensor specific capture options with their current values.
reme_error_t	reme_sensor_apply_capture_options (reme_context_t c, reme_sensor_t s, reme_options_t o)
	Apply capture options.
reme_error_t	reme_sensor_get_position (reme_context_t c, reme_sensor_t s, float *coordinates)
	Get the sensor position with respect to the world coordinate frame.
reme_error_t	reme_sensor_get_recovery_position (reme_context_t c, reme_sensor_t s, float *coordinates)
	Get the sensor recovery position with respect to the world coordinate frame.
reme_error_t	reme_sensor_get_incremental_position (reme_context_t c, reme_sensor_t s, float *coordinates)
	Get the incremental movement of the sensor.
reme_error_t	reme_sensor_set_position (reme_context_t c, reme_sensor_t s, const float *coordinates)
	Set the sensor position with respect to the world coordinate frame.
reme_error_t	reme_sensor_set_incremental_position (reme_context_t c, reme_sensor_t s, const float *coordinates)
	Set the incremental movement of the sensor.
reme_error_t	reme_sensor_set_recovery_position (reme_context_t c, reme_sensor_t s, const float *coordinates)
	Set the sensor recovery position with respect to the world coordinate frame.
reme_error_t	reme_sensor_reset (reme_context_t c, reme_sensor_t s)
	Resets the sensor to identity position.
reme_error_t	reme_sensor_get_image (reme_context_t c, reme_sensor_t s, reme_sensor_image_t it, reme_image_t i)
	Get a specific sensor image.
reme_error_t	reme_sensor_is_image_supported (reme_context_t c, reme_sensor_t s, reme_sensor_image_t it, bool *result)
	Test if a specific image type is available.
reme_error_t	reme_sensor_get_points (reme_context_t c, reme_sensor_t s, reme_sensor_view_t v, const float **coordinates, int *length)
	Get points corresponding to the current sensor view.
reme_error_t	reme_sensor_get_point_normals (reme_context_t c, reme_sensor_t s, reme_sensor_view_t v, const float **coordinates, int *length)
	Get point normals corresponding to the current sensor view.
reme_error_t	reme_sensor_get_track_time (reme_context_t c, reme_sensor_t s, int *track_time)
	Get the tracking time.
reme_error_t	reme_sensor_grab (reme_context_t c, reme_sensor_t s)
	Trigger frame grabbing.
reme_error_t	reme_sensor_prepare_images (reme_context_t c, reme_sensor_t s)
	Retrieve image data corresponding to the previous grab command for further processing.
reme_error_t	reme_sensor_prepare_image (reme_context_t c, reme_sensor_t s, _reme_sensor_image_t i)
	Retrieve specific image data for subsequent processing.
reme_error_t	reme_sensor_track_position (reme_context_t c, reme_sensor_t s)
	Attempts to track the sensor position.
reme_error_t	reme_sensor_update_volume (reme_context_t c, reme_sensor_t s)
	Update the bound volume using the current sensor data.

Detailed Description

Acquire data from real-world sensors or from file streams.

The sensor is responsible for acquiring real world data and feeding it into the reconstruction volume. The life-time of reme_sensor_t sensor is usually the following

• Create a new sensor (reme_sensor_create) using either the backend name or a specific sensor configuration file. Usually this method returns with success when the necessary drivers for the sensor where found. It does usually not mean that the sensor is actually there. We say usually, since you can force a test to open the sensor at this point using the require_can_open flag.
• Modify sensor parameters (reme_sensor_bind_camera_options).
• Open the sensor (reme_sensor_open).
• Work with sensor images (reme_sensor_grab, reme_sensor_prepare_images).
• Close sensor (reme_sensor_close).
• Destroy sensor (reme_sensor_destroy).

The one-minute example illustrates the basic usage.

Typedef Documentation

typedef int reme_sensor_t

Handle referencing a sensor object.

A reme_sensor_t represents a RGBD sensor. Associated methods allow to create, open and interact with sensors of various types.

typedef enum _reme_sensor_image_t reme_sensor_image_t

Image type enumeration.

Each sensor might provide different frame types that are all 2D images. Not all sensors support all frames, or the number of frames supported is configuration dependant.

typedef enum _reme_sensor_view_t reme_sensor_view_t

Sensor view type.

When dealing with sensor data ReconstructMe offers two types of views. The first view REME_SENSOR_VIEW_RAW corresponds to data passed as raw input to ReconstructMe. The second view type is REME_SENSOR_VIEW_RECONSTRUCTED and corresponds to a synthetic view generated by raytracing the volume from the current sensor to volume position.

The REME_SENSOR_VIEW_RECONSTRUCTED normally is much more smooth and has less holes than REME_SENSOR_VIEW_RAW, but naturally limits data to the size of the reconstruction volume.

typedef enum _reme_sensor_trackmode_t reme_sensor_trackmode_t

Sensor tracking mode.

Defines the basic tracking strategy to find the sensor position based on current and past sensor data.

typedef enum _reme_sensor_trackhint_t reme_sensor_trackhint_t

Sensor tracking hint.

Provides optional hints for the sensor tracking module.

Enumeration Type Documentation

enum _reme_sensor_image_t

Image type enumeration.

Each sensor might provide different frame types that are all 2D images. Not all sensors support all frames, or the number of frames supported is configuration dependant.

Enumerator:

REME_IMAGE_AUX	Auxiliary image if provided by sensor. Depending on the sensor type and its configuration the auxilary image can be of any type. Commonly this is either RGB or IR.
REME_IMAGE_DEPTH	Depth image. RGB 3 channels, 1 byte per channel
REME_IMAGE_VOLUME	Rendered image of the volume as viewed from the current sensor perspective. RGB 3 channels, 1 byte per channel.

enum _reme_sensor_view_t

Sensor view type.

When dealing with sensor data ReconstructMe offers two types of views. The first view REME_SENSOR_VIEW_RAW corresponds to data passed as raw input to ReconstructMe. The second view type is REME_SENSOR_VIEW_RECONSTRUCTED and corresponds to a synthetic view generated by raytracing the volume from the current sensor to volume position.

The REME_SENSOR_VIEW_RECONSTRUCTED normally is much more smooth and has less holes than REME_SENSOR_VIEW_RAW, but naturally limits data to the size of the reconstruction volume.

Enumerator:

REME_SENSOR_VIEW_RAW	Raw data view.
REME_SENSOR_VIEW_RECONSTRUCTED	Synthetic raytraced data view.

enum _reme_sensor_trackmode_t

Sensor tracking mode.

Defines the basic tracking strategy to find the sensor position based on current and past sensor data.

Enumerator:

REME_SENSOR_TRACKMODE_AUTO	Automatic mode. Try to use local search first. If that fails attempt to perform a global search followed by local search. If last tracking attempt was unsuccessful, start using global search immediately.
REME_SENSOR_TRACKMODE_LOCAL	Local search. Use local search only. Local search is fast and succeeds when the camera movement between two subsequent frames is small.
REME_SENSOR_TRACKMODE_GLOBAL	Global search. Use global search followed by a fine alignment of local search. Global search is slower than local search but succeeds in cases where the camera movement between two subsequent is rather frames large.

enum _reme_sensor_trackhint_t

Sensor tracking hint.

Provides optional hints for the sensor tracking module.

Enumerator:

REME_SENSOR_TRACKHINT_NONE	No hint
REME_SENSOR_TRACKHINT_USE_GLOBAL	Temporarily switch to global search until tracking is found again. This hint is automatically cleared when tracking is found. It is a convinient way of letting the tracking module know that tracking should be done using global search until we are sure that tracking is found again.

Function Documentation

reme_error_t reme_sensor_create	(	reme_context_t	c,
		const char *	driver,
		bool	require_can_open,
		reme_sensor_t *	s
	)

Create a new sensor object.

Creates a new sensor. The driver argument specifies which sensor to open. The following sensor drivers are currently available

• mskinect Microsoft Kinect for Windows and Kinect for XBox
• openni Asus Xtion, Asus Xtion Pro Live, Primsense Carmine 1.08, Primesense Carmine 1.09
• openni1 Same as above, but uses legacy OpenNI version 1 instead of OpenNI version 2
• file A generic file sensor to read previously recorded data

You might specify a specific driver backend

"openni" 

Alternatively you can specify a list of drivers to test, in which case it will return the first sensor that works.

"openni;mskinect;file" 

Or, specify file containing a sensor configuration file (see reme_sensor_bind_camera_options for camera specific options and Accessing and Modifying Options for background information about options)

"c:/drivers/asus_xtion_pro_live.txt;c:/drivers/my_file.txt" 

The drivers will be tested in the given order.

Set require_can_open to true to ensure the created sensor can be created and opened using either the default settings, or if file paths are specifed using the settings specified in the file.

No matter how require_can_open is set the sensor is returned in closed state. Use reme_sensor_open to open it.

Parameters

c	A valid context object
driver	The name of sensor driver to instance a sensor from
require_can_open	Ensures that the returned sensor can be opened using either the default sensor options.
s	A pointer that will receive the handle of the created sensor

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_sensor_destroy	(	reme_context_t	c,
		reme_sensor_t *	s
	)

Destroy a previously created sensor object.

Parameters

c	A pointer to a valid context object
s	A mutable pointer to a valid sensor handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_sensor_open	(	reme_context_t	c,
		reme_sensor_t	s
	)

Open a sensor.

Attempts to opens the specified sensor using the specified sensor options.

Parameters

c	A valid context object
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_sensor_close	(	reme_context_t	c,
		reme_sensor_t	s
	)

Close a an open sensor.

Indicates that no more grabbing is done from sensor. Re-opening a sensor is possible.

Parameters

c	A valid context object
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_sensor_set_volume	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_volume_t	v
	)

Set the working volume.

The sensor will use this volume to keep track of its position and it will also update into this volume. By default the sensor is assigned to the first volume available.

Parameters

c	A valid context object
s	A valid sensor object
v	A valid volume object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_set_trackmode	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_sensor_trackmode_t	t
	)

Set tracking mode.

Sets the overall tracking strategy. By default REME_SENSOR_TRACKMODE_AUTO is used.

Parameters

c	A valid context object
s	A valid sensor object
t	A valid tracking mode

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_point_and_shoot.cpp.

reme_error_t reme_sensor_set_trackhint	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_sensor_trackhint_t	t
	)

Sets a tracking hint.

The tracking hint is an external user supplied information to support the camera tracking module. Any tracking hint given remains active until the next call to reme_sensor_track_position.

Supplying tracking hints becomes useful when the caller has external knowledge unknown to the tracking module. For example the caller might set REME_SENSOR_TRACKHINT_USE_GLOBAL to indicate that the tracking module is should resort to global tracking in the next iteration.

Tracking hints are automatically cleared after the next call to reme_sensor_track_position.

Parameters

c	A valid context object
s	A valid sensor object
t	A valid tracking hint

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_scan_tilt.cpp, and example_reconstructmesdk_sensor_multi_independent.cpp.

reme_error_t reme_sensor_bind_camera_options	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_options_t	o
	)

Access the sensor specific options that affect how the camera is opened.

Associated Protocol Buffers Specification

Depending on the sensor chosen on create, different specs are needed, since each sensor supports a different set of parameters.

For openni sensors (OpenNI 2.x)

import "rgbdsensor/videostream.proto";

package LibRGBDSensor;

// OpenNI v2.0 sensor configuration
message openni2_sensor_config {

  // Default driver model
  optional string driver = 1 [default = "openni"];
  
  // Device ID
  optional int32 device_id = 2 [default = 0];

  optional LibRGBDSensor.videostream depth_stream = 3;
  optional LibRGBDSensor.videostream aux_stream = 4;
  
  // Map depth viewpoint to aux viewpoints.
  optional bool enable_align_viewpoints = 5 [default = false];
}

For mskinect sensors

import "rgbdsensor/videostream.proto";

package LibRGBDSensor;

// Kinect sensor configuration based on MSKinect driver
message mskinect_sensor_config {

  // Default driver model
  optional string driver = 1 [default = "mskinect"];
  
  // Device ID
  optional int32 device_id = 2 [default = 0];

  optional LibRGBDSensor.videostream depth_stream = 3;
  optional LibRGBDSensor.videostream aux_stream = 4;
  
  // Map depth viewpoint to aux viewpoints.
  optional bool enable_align_viewpoints = 5 [default = false];

  // Enable near mode
  optional bool enable_near_mode = 6 [default = true];
}

For file sensors

import "rgbdsensor/videostream.proto";

package LibRGBDSensor;

// OpenNI sensor configuration
message file_sensor_config {

  // Default driver model
  optional string driver = 1 [default = "file"];
  
  optional LibRGBDSensor.videostream depth_stream = 3;
  optional LibRGBDSensor.videostream aux_stream = 4;
  
  // Map depth viewpoint to aux viewpoints.
  optional bool enable_align_viewpoints = 5 [default = false];
}

For openni sensors (OpenNI 1.x)

import "rgbdsensor/videostream.proto";

package LibRGBDSensor;

// OpenNI 1.0 sensor configuration
message openni_sensor_config {

  // Default driver model
  optional string driver = 1 [default = "openni1"];
  
  // Device ID
  optional int32 device_id = 2 [default = 0];

  optional LibRGBDSensor.videostream depth_stream = 3;
  optional LibRGBDSensor.videostream aux_stream = 4;
  
  // Map depth viewpoint to aux viewpoints.
  optional bool enable_align_viewpoints = 5 [default = false];
}

Common to all configurations above is the usage of the LibRGBDSensor.videostream

import "rgbdsensor/intrinsics.proto";

package LibRGBDSensor;

// Defines properties of a video stream
message videostream {

  // Video stream type
  enum stream_type {
    STREAM_DEPTH = 1;
    STREAM_COLOR = 2;
    STREAM_IR = 3;
  }

  // Type of stream
  optional stream_type type = 1 [default = STREAM_DEPTH];

  // Enable or disable this stream
  optional bool enabled = 2 [default = true];
  
  // Defines the where the stream is c
  optional string source = 3 [default = ""];

  // Image size description
  message image_size_type {
    optional int32 width = 1 [default = 640];
    optional int32 height = 2 [default = 480];
  };

  // Defines the initial image size
  optional image_size_type image_size = 4; 

  // Unit description
  enum units_type {
    // No units
    UNIT_UNKNOWN = 0;
    // Unit is milli-meter
    UNIT_1MM = 1;
    // Unit is 0.1 milli-meter
    UNIT_100UM = 2;    
  }

  // Depth dimension
  optional units_type units = 5 [default = UNIT_UNKNOWN];

  // Mirror image
  optional bool mirror_enabled = 6 [default = false];

  // Target FPS
  optional int32 fps = 7 [default = 30];

  // Stream intrinsics
  optional LibRGBDSensor.intrinsics intrinsics = 8;
}

The referenced LibRGBDSensor.intrinsics has the following layout

package LibRGBDSensor;

// Camera intrinsics
message intrinsics {

  // Camera matrix
  optional double fx = 1 [default = 571.26];
  optional double fy = 2 [default = 571.26];
  optional double cx = 3 [default = 320];
  optional double cy = 4 [default = 240];
  
  // Radial distortion coefficients
  // Set to zero to disable certain calculations
  optional double k1 = 5 [default = 0];
  optional double k2 = 6 [default = 0];
  optional double k3 = 7 [default = 0];
  
  // Tangential distortion coefficients
  // Set to zero to disable certain calculations
  optional double p1 = 8 [default = 0];
  optional double p2 = 9 [default = 0];
  
}

Note

When radial or tangential distortion parameters are not equal zero a distortion correction will be performed.

Changing camera options take effect on the next call to reme_sensor_open.

Parameters

c	A valid context object
s	A valid sensor object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_sensor.cpp, and example_reconstructmesdk_sensor_multi_independent.cpp.

reme_error_t reme_sensor_bind_capture_options	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_options_t	o
	)

Access the sensor specific capture options with their current values.

Associated Protocol Buffers Specification

Depending on the sensor chosen on create, different specs are needed, since each sensor supports a different set of parameters.

For openni sensors

import "rgbdsensor/basic_frame_support.proto";

package LibRGBDSensor;

// OpenNI sensor capture parameter description
message openni_sensor_capture_parameter {

  // Frame specific information. Read-only.
  optional LibRGBDSensor.basic_frame_support frame_info = 1;

  // Infrared raw intensity multiplier. Read-Write.
  optional int32 ir_alpha = 2 [default = 4];  
  
}

For mskinect sensors

import "rgbdsensor/basic_frame_support.proto";

package LibRGBDSensor;

// Microsoft Kinect for Windows capture parameter description
message mskinect_sensor_capture_parameter {

  // Frame specific information. Read-only.
  optional LibRGBDSensor.basic_frame_support frame_info = 1;

  // Enable IR projector. Read-Write.
  optional bool enable_ir_projector = 2 [default = true];

  // Infrared raw intensity multiplier. Read-Write.
  optional int32 ir_alpha = 3 [default = 10];  

  // Elevation or tilt angle. Read-Write.
  // Extends the view range to to +/- 27 degrees. A value of 0 means perpendicular to gravity.
  // The movement of the motor is performed asynchronously. Only one asnychronous tilt movement
  // it allowed at any time. Too frequent changes to the tilt angle can cause damage to the motor.
  // Note that the IR projector is turned off while tilting, essentially making ReconstructMe blind
  // while the sensor moves.
  optional int32 tilt_angle = 4 [default = 0];

}

For file sensors

import "rgbdsensor/basic_frame_support.proto";

package LibRGBDSensor;

// File sensor capture parameter description
message file_sensor_capture_parameter {

  // Frame specific information. Read-only.
  optional LibRGBDSensor.basic_frame_support frame_info = 1;
  
}

Common to all configurations above is the frame_info field. It is mendatory for reconstruction and has the following structure

package LibRGBDSensor;

// Contains information on basic sensor image support.
message basic_frame_support {

  // Image size type
  message image_size {
    optional int32 width = 1 [default = 640];
    optional int32 height = 2 [default = 480];
  };
  
  // True when sensor supports depth stream
  optional bool supports_depth = 1;
  // True when sensor supports an auxilary stream
  optional bool supports_aux = 2;

  // Frame size of depth image in pixels
  optional image_size depth_size = 3;
  // Frame size of auxilary image in pixels
  optional image_size aux_size = 4;
  
}

Note

The capture options are updated with current value when reme_sensor_bind_capture_options is called.

Changing capture options without a call to reme_sensor_apply_capture_options has no effect.

Parameters

c	A valid context object
s	A valid sensor object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_scan_tilt.cpp, and example_reconstructmesdk_sensor.cpp.

reme_error_t reme_sensor_apply_capture_options	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_options_t	o
	)

Apply capture options.

Causes all capture options set to be applied at given sensor. In order to set only specific options, invoke reme_options_clear on the options target before setting the new values. Then invoke reme_sensor_apply_capture_options.

Parameters

c	A valid context object
s	A valid sensor object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_scan_tilt.cpp, and example_reconstructmesdk_sensor.cpp.

reme_error_t reme_sensor_get_position	(	reme_context_t	c,
		reme_sensor_t	s,
		float *	coordinates
	)

Get the sensor position with respect to the world coordinate frame.

Initially this is set to identity for all sensors. The position is modified when reme_sensor_track_position succeeds, or reme_sensor_set_position is called.

Parameters

c	A valid context object
s	A valid sensor object
coordinates	A constant pointer to constant Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_scan_tilt.cpp.

reme_error_t reme_sensor_get_recovery_position	(	reme_context_t	c,
		reme_sensor_t	s,
		float *	coordinates
	)

Get the sensor recovery position with respect to the world coordinate frame.

Whenever the sensor cannot find track, it puts itself into recovery pose. It then waits in the recovery pose for tracking to succeed. The recovery pose will be updated during ongoing tracking automatically. I.e when there is sufficient confidence that the last n-frames where tracked successfully, ReconstructMe generates a new recovery pose.

Initially this is set to identity for all sensors. The position is modified when reme_sensor_track_position succeeds several times, or reme_sensor_set_recovery_position is called.

Parameters

c	A valid context object
s	A valid sensor object
coordinates	A constant pointer to constant Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_get_incremental_position	(	reme_context_t	c,
		reme_sensor_t	s,
		float *	coordinates
	)

Get the incremental movement of the sensor.

When reme_sensor_track_position succeeds this position reflects the movement of the sensor between the last position of the sensor and the current position of the sensor.

Parameters

c	A valid context object
s	A valid sensor object
coordinates	A constant pointer to pre-allocated Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_set_position	(	reme_context_t	c,
		reme_sensor_t	s,
		const float *	coordinates
	)

Set the sensor position with respect to the world coordinate frame.

Initially this is set to identity for all sensors.

Parameters

c	A valid context object
s	A valid sensor object
coordinates	A pointer to constant Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_scan_tilt.cpp, and example_reconstructmesdk_sensor_printing.cpp.

reme_error_t reme_sensor_set_incremental_position	(	reme_context_t	c,
		reme_sensor_t	s,
		const float *	coordinates
	)

Set the incremental movement of the sensor.

Updates the world position of the sensor by the incremental position specified.

Parameters

c	A valid context object
s	A valid sensor object
coordinates	A pointer to constant Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_set_recovery_position	(	reme_context_t	c,
		reme_sensor_t	s,
		const float *	coordinates
	)

Set the sensor recovery position with respect to the world coordinate frame.

Whenever the sensor cannot find track, it puts itself into recovery pose. It then waits in the recovery pose for tracking to succeed. The recovery pose will be updated during ongoing tracking automatically. I.e when there is sufficient confidence that the last n-frames where tracked successfully, ReconstructMe generates a new recovery pose.

Initially this is set to identity for all sensors. The position is modified when reme_sensor_track_position succeeds several times, or reme_sensor_set_recovery_position is called.

Parameters

c	A valid context object
s	A valid sensor object
coordinates	A constant pointer to constant Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_reset	(	reme_context_t	c,
		reme_sensor_t	s
	)

Resets the sensor to identity position.

Forces the sensor to loose track.

Parameters

c	A valid context object
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On tracking success or the corresponding volume is empty.
REME_ERROR_UNSPECIFIED	is returned otherwise.

Examples:

example_reconstructmesdk_scan_tilt.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_sensor_get_image	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_sensor_image_t	it,
		reme_image_t	i
	)

Get a specific sensor image.

Each sensor might provide different frame types. Not all sensors support all frames, or the number of frames supported is configuration dependant. See reme_sensor_image_t for a complete enumeration of available image types.

Memory Management Rules Exception

The returned image remains valid until the sensor is destroyed or the dimension of the image changes. The pointer is recycled internally, which means that it will point to different values each time the sensor images are updated.

Parameters

c	A valid context object
s	A valid sensor object
it	Image type to access
i	A valid image object to receive image data

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_sensor_is_image_supported	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_sensor_image_t	it,
		bool *	result
	)

Test if a specific image type is available.

Each sensor might provide different frame types. Not all sensors support all frames, or the number of frames supported is configuration dependant. See reme_sensor_image_t for a complete enumeration of available image types.

Parameters

c	A valid context object
s	A valid sensor object
it	Image type to access
result	Whether image type is supported or not.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_get_points	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_sensor_view_t	v,
		const float **	coordinates,
		int *	length
	)

Get points corresponding to the current sensor view.

Depending on the choice of v (reme_sensor_view_t) this returns

• REME_SENSOR_VIEW_RAW the raw sensor points generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
• REME_SENSOR_VIEW_RECONSTRUCTED the synthetic raytraced sensor points generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.

The points are represented as an array of floats where each point consists of 4 coordinates Px Py Pz Pw Px Py Pz Pw ... . The w component is always zero. The i-th point starts at index i * 4 of coordinate array returned.

The number of points returned corresponds to the number of pixels of the native sensor. That is, if your sensor has a resolution of 640x480 (cols x rows) the number of returned normals is 640 * 480. The normals are returned in row-wise order. Those points that do not represent a valid data are marked with a sentinel value (NAN) in their x-coordinate. To access the point corresponding to pixel of row i and column j use i * cols * 4 + j * 4 where cols is the number of pixel columns of the native sensor.

Parameters

c	A valid context object
s	A valid sensor object
v	view type specification
coordinates	A mutable pointer to constant point data.
length	The number of coordinates returned. To get the number of points divide this value by 4.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_get_point_normals	(	reme_context_t	c,
		reme_sensor_t	s,
		reme_sensor_view_t	v,
		const float **	coordinates,
		int *	length
	)

Get point normals corresponding to the current sensor view.

Depending on the choice of v (reme_sensor_view_t) this returns

• REME_SENSOR_VIEW_RAW the raw sensor normals generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
• REME_SENSOR_VIEW_RECONSTRUCTED the synthetic raytraced sensor normals generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.

The point normals are represented as an array of floats where each point consists of 4 coordinates Px Py Pz Pw Px Py Pz Pw ... . The w component is always zero. The i-th normal starts at index i * 4 of coordinate array returned.

The number of normals returned corresponds to the number of pixels of the native sensor. That is, if your sensor has a resolution of 640x480 (cols x rows) the number of returned normals is 640 * 480. The normals are returned in row-wise order. Those normals that do not represent a valid data are marked with a sentinel value (NAN) in their x-coordinate. To access the normal corresponding to pixel of row i and column j use i * cols * 4 + j * 4 where cols is the number of pixel columns of the native sensor.

Parameters

c	A valid context object
s	A valid sensor object
v	view type specification
coordinates	A mutable pointer to constant normal data.
length	The number of coordinates returned. To get the number of normals divide this value by 4.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_get_track_time	(	reme_context_t	c,
		reme_sensor_t	s,
		int *	track_time
	)

Get the tracking time.

The tracking time corresponds to the number of frames in which tracking succeeded. In case tracking fails the counter gets negative.

Parameters

c	A valid context object
s	A valid sensor object
track_time	The tracking time

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_sensor_grab	(	reme_context_t	c,
		reme_sensor_t	s
	)

Trigger frame grabbing.

Provides a synchronization point to trigger image generation of all image types. This method is intended to be fast.

In order to synchronize frame grabbing from multiple sensors, call this method in sequence for each sensor before calling reme_sensor_retrieve.

Parameters

c	A valid context object
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_FAILED_TO_GRAB	Failed to grab from sensor. This is not necessarily an error, you might re-try.
REME_ERROR_UNSPECIFIED	Is returned otherwise.

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_sensor_prepare_images	(	reme_context_t	c,
		reme_sensor_t	s
	)

Retrieve image data corresponding to the previous grab command for further processing.

Updates the internal state of all images and prepares the required data structures on the computation device.

Parameters

c	A valid context object
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_sensor_prepare_image	(	reme_context_t	c,
		reme_sensor_t	s,
		_reme_sensor_image_t	i
	)

Retrieve specific image data for subsequent processing.

In case REME_IMAGE_AUX or REME_IMAGE_DEPTH is passed, this method will fetch the data into internal memory. In case REME_IMAGE_VOLUME is passed, the previously prepared REME_IMAGE_DEPTH will be uploaded to the computation device for subsequent processing (reme_sensor_track_position, reme_sensor_update_volume).

This method is especially useful (when compared to reme_sensor_prepare_images) when only depth and image data is required. For example when recording, there is no need for REME_IMAGE_VOLUME and it should be skipped so no time is wasted waiting for the data to be uploaded to the computation device.

Parameters

c	A valid context object
s	A valid sensor object
i	Image type to prepare

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_recorder.cpp, and example_reconstructmesdk_sensor.cpp.

reme_error_t reme_sensor_track_position	(	reme_context_t	c,
		reme_sensor_t	s
	)

Attempts to track the sensor position.

Tries to track the sensor movement by matching the current depth data against the perspective from the last position. Initially the sensor position is the identity position, unless otherwise specified.

The tracking behaviour is affected by the tracking strategy (reme_sensor_set_trackmode) and any external tracking hint (reme_sensor_set_trackhint). Any tracking hint will be cleared after calling this method.

Parameters

c	A valid context object
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On tracking success or the corresponding volume is empty.
REME_ERROR_TRACK_LOST	When the tracking did not succeed. In this case the sensor is repositioned into latest recovery pose.
REME_ERROR_UNSPECIFIED	is returned otherwise.

Examples:

example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_sensor_update_volume	(	reme_context_t	c,
		reme_sensor_t	s
	)

Update the bound volume using the current sensor data.

Uses the current sensor position as the perspective to update the volume.

Parameters

c	A valid context object
s	A valid sensor object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.