Context

Fundamental building block in reconstruction. More...

Typedefs
typedef struct _reme_context *	reme_context_t
	Handle referencing a context object.
typedef enum _reme_error	reme_error_t
	Status enumeration.
typedef enum _reme_log_severity	reme_log_severity_t
	Logging severity levels.
typedef void(*	reme_log_callback_t )(reme_log_severity_t sev, const char *message, void *user_info)
	Callback function prototype to receive logging information.

Enumerations
enum	_reme_error {   REME_ERROR_SUCCESS = 0,   REME_ERROR_UNSPECIFIED = -1,   REME_ERROR_FAILED_TO_GRAB = -2,   REME_ERROR_TRACK_LOST = -3,   REME_ERROR_INVALID_LICENSE = -4,   REME_ERROR_NO_CALIBRATION_TARGET = -5 }
	Status enumeration. More...
enum	_reme_log_severity {   REME_LOG_SEVERITY_INFO = 2,   REME_LOG_SEVERITY_WARNING = 3,   REME_LOG_SEVERITY_ERROR = 4 }
	Logging severity levels. More...
reme_error_t	reme_context_create (reme_context_t *c)
	Create a new reme_context_t object.
reme_error_t	reme_context_destroy (reme_context_t *c)
	Destroy a previously created reme_context_t object.
reme_error_t	reme_context_get_version (reme_context_t c, const char **version, int *length)
	Get the ReconstructMe SDK version string.
reme_error_t	reme_context_set_log_callback (reme_context_t c, reme_log_callback_t lc, void *user_data=0)
	Set the logging callback.
reme_error_t	reme_context_bind_compile_options (reme_context_t c, reme_options_t o)
	Access the compile time options.
reme_error_t	reme_context_bind_opencl_info (reme_context_t c, reme_options_t o)
	Access platform OpenCL information.
reme_error_t	reme_context_compile (reme_context_t c)
	Compile OpenCL related kernels.
reme_error_t	reme_context_get_last_error (reme_context_t c, const char **msg, int *length)
	Get the last error message.
reme_error_t	reme_context_get_first_error (reme_context_t c, const char **msg, int *length)
	Get the first error message.
reme_error_t	reme_context_get_error_count (reme_context_t c, int *length)
	Return the number of error messages pending.
reme_error_t	reme_context_pop_last_error (reme_context_t c)
	Remove last error, putting the previous-last error at the end.
reme_error_t	reme_context_pop_first_error (reme_context_t c)
	Remove first error, putting the second-first error in front.

Detailed Description

Fundamental building block in reconstruction.

The context is responsible for life-time management of all objects involved in the reconstruction process. It additionally maintains the the communication channel to the OpenCL device used for reconstruction.

Typedef Documentation

typedef struct _reme_context* reme_context_t

Handle referencing a context object.

A reme_context_t contains the complete state of the current reconstruction process, including sensor objects, reconstruction volumes and surface objects. reme_context_t objects are central to ReconstructMe SDK and all operations always require such a context as input.

typedef enum _reme_error reme_error_t

Status enumeration.

A reme_error_t contains the available status codes as returned by all methods of ReconstructMe SDK. In case of error, use reme_context_get_last_error to get the latest details.

typedef enum _reme_log_severity reme_log_severity_t

Logging severity levels.

Defines the severity of a given logging message

typedef void(* reme_log_callback_t)(reme_log_severity_t sev, const char *message, void *user_info)

Callback function prototype to receive logging information.

Receives logging information consisting of severity level and message. Use reme_context_set_log_callback to register a new callback.

It allows passing of an optional void pointer to user specified data.

Parameters

sev	severity level
message	the log message
user_info	optional pointer as specified by at reme_context_add_log_callback

Enumeration Type Documentation

enum _reme_error

Status enumeration.

A reme_error_t contains the available status codes as returned by all methods of ReconstructMe SDK. In case of error, use reme_context_get_last_error to get the latest details.

Enumerator:

REME_ERROR_SUCCESS	No error occurred
REME_ERROR_UNSPECIFIED	Unspecified error occurred
REME_ERROR_FAILED_TO_GRAB	Could not grab from sensor
REME_ERROR_TRACK_LOST	Camera tracking lost
REME_ERROR_INVALID_LICENSE	Failed to verify license
REME_ERROR_NO_CALIBRATION_TARGET	Calibration target was not found in image

enum _reme_log_severity

Logging severity levels.

Defines the severity of a given logging message

Enumerator:

REME_LOG_SEVERITY_INFO	Used to inform about changes in state.
REME_LOG_SEVERITY_WARNING	Used to indicate potential problems and unwanted behaviour.
REME_LOG_SEVERITY_ERROR	Genuine errors without a recovering strategy.

Function Documentation

reme_error_t reme_context_create

(

reme_context_t *

c

)

Create a new reme_context_t object.

Parameters

c	A pointer that will receive the created context handle

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_error_handling.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_memory_management.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_options_type_safe.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_context_destroy

(

reme_context_t *

c

)

Destroy a previously created reme_context_t object.

Destroys all associated handles and memory allocated.

Parameters

c	A pointer to a valid context object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_error_handling.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_memory_management.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_options_type_safe.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_context_get_version	(	reme_context_t	c,
		const char **	version,
		int *	length
	)

Get the ReconstructMe SDK version string.

Format is

<major>.<minor>.<build> - <revision> 

Parameters

c	A valid context object
version	A mutable pointer that receives the null terminated string
length	length of string in bytes

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_memory_management.cpp.

reme_error_t reme_context_set_log_callback	(	reme_context_t	c,
		reme_log_callback_t	lc,
		void *	user_data = 0
	)

Set the logging callback.

The function pointer must stay valid until the context is destroyed or reme_context_set_log_callback is invoked with a different function pointer.

Parameters

c	A valid context object
lc	Logging callback function pointer
user_data	A pointer to optional user data to be passed to the callback function

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_error_handling.cpp.

reme_error_t reme_context_bind_compile_options	(	reme_context_t	c,
		reme_options_t	o
	)

Access the compile time options.

Associated Protocol Buffers Specification

import "reconstructme/core/tracking_settings.proto";

package LibReconstructMe;

// Settings passed to compilation
message compile_settings {

  // Device id to carry out computations
  optional int32 device_id = 1 [default = -1];

  // Camera
  optional int32 camera_window_size_x = 2 [default = 7];
  optional int32 camera_window_size_y = 3 [default = 7];
  optional bool enable_distortion_correction = 4 [default = false];
  
  // Volume
  message min_3f {
    required float x = 1 [default = -500];
    required float y = 2 [default = -500];
    required float z = 3 [default = 400];
  }
  
  // Point3f for max-corner
  // Note, max_3f and min_3f are custom
  // messages to provide different defaults.
  message max_3f {
    required float x = 1 [default = 500];
    required float y = 2 [default = 500];
    required float z = 3 [default = 1400];
  }
  
  message res_3i {
    required int32 x = 1 [default = 256];
    required int32 y = 2 [default = 256];
    required int32 z = 3 [default = 256];
  }

  optional res_3i volume_size = 5;  
  optional min_3f volume_min = 6;
  optional max_3f volume_max = 7;
    
  // Integration    
  optional float integrate_truncation = 8 [default = 15];
  optional int32 integrate_max_weight = 9 [default = 32];
  
  // Extraction
  optional float extract_step_fact = 10 [default = 0.5];
  optional float gradient_step_fact = 11 [default = 0.25];
  
  // Alignment
  optional int32 icp_max_iter = 12 [default = 15];
  optional float icp_max_point_dist = 13 [default = 20];
  optional float icp_max_normal_angle = 14 [default = 30];
  optional float icp_truncate_dist = 15 [default = 1500];
  optional int32 icp_pyramid_levels = 16 [default = 3];
  optional bool enable_smooth_normals = 17 [default = false];

  // Optimization
  optional bool enable_optimizations = 18 [default = true];  
}

Parameters

c	A valid context object
o	A valid options binding

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp.

reme_error_t reme_context_bind_opencl_info	(	reme_context_t	c,
		reme_options_t	o
	)

Access platform OpenCL information.

Associated Protocol Buffers Specification

package LibOpenCLBridge;

message opencl_info {

    // Defines the type of the device
    enum device_type {
        CPU = 0;
        GPU = 1;
    }
    
    // Defines a device
    message device {
        optional string name = 1 [default = "Unknown device name"];
        optional string vendor = 2 [default = "Unknown device vendor"];
        optional device_type type = 3;
    }
    
    repeated device devices = 1;
}

Parameters

c	A valid context object
o	A valid options binding

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp.

reme_error_t reme_context_compile

(

reme_context_t

c

)

Compile OpenCL related kernels.

Based on the compile time settings reme_context_get_compile_options, try to compile for the selected OpenCL compatible device.

In case of error check the last error through reme_context_get_last_error to receive the full build log.

Note that a successful compilation will force all objects that communicate with the computation device to re-initialize. Foremost these are the reme_sensor_t and reme_volume_t objects. Data of these objects will be reset to empty state.

Parameters

c	A valid context object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_error_handling.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_context_get_last_error	(	reme_context_t	c,
		const char **	msg,
		int *	length
	)

Get the last error message.

Parameters

c	A valid context object
msg	A mutable pointer receiving the last error messge
length	Number of characters in error message

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_context_get_first_error	(	reme_context_t	c,
		const char **	msg,
		int *	length
	)

Get the first error message.

Parameters

c	A valid context object
msg	A mutable pointer receiving the last error messge
length	Number of characters in error message

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_error_handling.cpp, and example_reconstructmesdk_memory_management.cpp.

reme_error_t reme_context_get_error_count	(	reme_context_t	c,
		int *	length
	)

Return the number of error messages pending.

Parameters

c	A valid context object
length	Number of error messages.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_error_handling.cpp.

reme_error_t reme_context_pop_last_error

(

reme_context_t

c

)

Remove last error, putting the previous-last error at the end.

Parameters

c	A valid context object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_context_pop_first_error

(

reme_context_t

c

)

Remove first error, putting the second-first error in front.

Parameters

c	A valid context object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_error_handling.cpp.