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 enum _reme_tune_profile	reme_tune_profile_t
	Auto-tuning profiles.
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,   REME_ERROR_NO_COLOR_SUPPORT = -6,   REME_ERROR_NO_FLOOR = -7 }
	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...
enum	_reme_tune_profile {   REME_TUNE_PROFILE_LOW_QUALITY = 0,   REME_TUNE_PROFILE_MID_QUALITY = 1,   REME_TUNE_PROFILE_MAX_QUALITY = 2 }
	Auto-tuning profiles. 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_reconstruction_options (reme_context_t c, reme_options_t o)
	Access the reconstruction 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_tune_reconstruction_options (reme_context_t c, reme_tune_profile_t profile)
	Auto-tune reconstruction settings.
reme_error_t	reme_context_compile (reme_context_t c)
	Compile OpenCL related kernels.
reme_error_t	reme_context_bind_error_info (reme_context_t c, reme_options_t o)
	Access current error state.
reme_error_t	reme_context_print_errors (reme_context_t c)
	Print all errors to standard error output and reset errors.

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 enum _reme_tune_profile reme_tune_profile_t

Auto-tuning profiles.

Defines for target profile to tune reconstruction settings for

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
REME_ERROR_NO_COLOR_SUPPORT	Color support not available. Enable in config.
REME_ERROR_NO_FLOOR	Floor detection failed.

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.

enum _reme_tune_profile

Auto-tuning profiles.

Defines for target profile to tune reconstruction settings for

Enumerator:

REME_TUNE_PROFILE_LOW_QUALITY	Low quality profile
REME_TUNE_PROFILE_MID_QUALITY	Mid quality profile
REME_TUNE_PROFILE_MAX_QUALITY	Maximum quality profile

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_colorize.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_point_and_shoot_with_colors.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_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_colorize.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_point_and_shoot_with_colors.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_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.

Invoke with a NULL function pointer to indicate that logging should be disabled.

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_reconstruction_options	(	reme_context_t	c,
		reme_options_t	o
	)

Access the reconstruction options.

The reconstruction options define the behaviour of the reconstruction process. Note that some options can be set during run-time and others require re-compilation by invoking reme_context_compile. The protocol buffer specification documents when a re-compilation is necessary.

Associated Protocol Buffers Specification

package LibReconstructMe;

// Collection of settings that define the behaviour of the reconstruction.
message reconstruction_settings {

  // Device number to carry out computations.
  // Use -1 to signal auto-choose.
  optional int32 device_id = 1 [default = -1];

  // -------------------------------------------------------------------------

  // Reconstruction volume settings type
  message volume_settings {

    // Minimum corner point type
    message min_3f {
      required float x = 1 [default = -500];
      required float y = 2 [default = -500];
      required float z = 3 [default = -500];
    }

    // Maximum corner point type
    message max_3f {
      required float x = 1 [default = 500];
      required float y = 2 [default = 500];
      required float z = 3 [default = 500];
    }

    // Volume resolution type
    message res_3i {
      required int32 x = 1 [default = 256];
      required int32 y = 2 [default = 256];
      required int32 z = 3 [default = 256];
    }
    
    // Minimum extension point of the volume in world space.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional min_3f minimum_corner = 1;

    // Maximum extension point of the volume in world space.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional max_3f maximum_corner = 2;

    // The volume is divided into small cuboids called voxels.
    // The number of voxels per dimension can differ, but must be divisable by
    // 128. 128 is the minimum resolution per dimension.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional res_3i resolution = 3;  
  }

  // Volume setup
  optional volume_settings volume = 2;

  // -------------------------------------------------------------------------

  // Point normals settings type
  message normal_settings {

    // Instead of calculation point normals through pixel neighbors,
    // fit a parametric plane through the neighborhood.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional bool pca_normals = 1 [default = false];

    // When pca_normals is enabled, this defines the neighborhood size.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional int32 half_kernel_size = 2 [default = 3];
  };

  // Point normals setup
  optional normal_settings point_normals = 3;

  // -------------------------------------------------------------------------

  // Depthmap erode settings type.
  // Inaccuracies of depthmaps can occur at sharp depth steps. Through erosion
  // sharp edges are eliminated.
  message depth_erode_settings {

    // Enables or disables eroding of depthmaps.
    optional bool enabled = 1 [default = false];

    // The half size of depth contour erosion kernel size in pixel.
    optional int32 half_kernel_size = 2 [default = 2];

    // The threshold for detecting sharp edges in the depth map.
    optional int32 minimum_depth_step = 3 [default = 30];
  };

  // Depthmap erosion setup
  optional depth_erode_settings depthmap_erosion = 4;

  // Color-map erosion settings type.
  // Inaccuracies of colorization can occur at sharp depth steps. Through colors are
  // invalidated at such sharp edges.
  message color_erode_settings {

    // Enables or disables eroding of color-maps. 
    optional bool enabled = 1 [default = true];

    // The half size of color contour erosion kernel size in pixel.
    optional int32 half_kernel_size = 4 [default = 2];

    // The threshold for detecting sharp edges in the depth map.
    optional int32 minimum_depth_step = 3 [default = 30];
  };

  // Color-map erosion setup
  optional color_erode_settings colormap_erosion = 5;

  // -------------------------------------------------------------------------

  // Depthmap bilateral filter settings type.
  // Smoothes the depthmap while preserving sharp depthmap edges.
  message bilateral_filter_settings {

    // Enables or disables smoothing of depthmaps
    optional bool enabled = 1 [default = true];

    // The half size of bilateral filter kernel size in pixel.
    optional int32 half_kernel_size = 2 [default = 3];

    // The half size of the Gaussian bilateral filter window in pixel space
    optional float sigma_pixel = 3 [default = 9.0];

    // The half size of the Gaussian bilateral filter window in depth space
    optional float sigma_depth = 4 [default = 30.0];
  };

  // Depthmap smoothing setup
  optional bilateral_filter_settings depthmap_smoothing = 6;

  // -------------------------------------------------------------------------
    
  // Data integration settings type.
  // Defines how adding data to the volume is carried out
  message integration_settings {

    // Defines the minimum thickness of objects in the volume.
    // Lower values allow you to scan thinner objects. Settings this value
    // too low results in reconstruction holes and incorrect tracking.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional float truncation = 1 [default = 20];

    // Each volume voxel smoothes data from the last integrations.
    // The maximum weight can be thought of as an moving average threshold.
    // Once reached the voxel starts to forget older values.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional int32 maximum_weight = 2 [default = 32];

    optional float maximum_depth = 3 [default = 1500];

    // Only points facing the camera in an angle no more than the given one
    // will be considered in integration. Value is in degrees.
    optional float maximum_angle = 4 [default = 70];

    // Enable support for colors in volume.
    optional bool use_colors = 5 [default = false];

    // Depth values beyond maximum_depth won't be integrated, but can be used for
    // object change detection. If the distance difference at a specific pixel between
    // the measured sensor depth and the old object depth is greater than minimum_deletion_distance,
    // the object will be erased from the global model.
    optional float minimum_deletion_distance = 6 [default = 40.0];
  }
  // Integration setup
  optional integration_settings data_integration = 7;
  
  // -------------------------------------------------------------------------

  // Data extraction settings type.
  // Defines how the volume is raytraced to generate synthetic sensor data,
  // which is used to align the current raw sensor data with the last camera
  // position.
  message extraction_settings {

    // Step factor of the ray marching algorithm. Specified in terms of
    // percent of data_integration.truncation
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional float step_factor = 1 [default = 0.7];

    // Numerical step length of gradient calculation
    // Estimating point normals in the volume is carried out using 
    // numerical differentation. This value value defines the 
    // the +/- distance of samples around the value to be differentiated.
    // Higher values will lead to smoother but maybe inaccurate normals.
    // A re-compilation the OpenCL code is required for changes to take effect.
    optional float gradient_step_length = 2 [default = 0.1];
  }

  // Raytracing setup
  optional extraction_settings data_extraction = 8;
  
  // -------------------------------------------------------------------------

  // Camera tracking alignment settings type.
  // Defines how tracking the camera position between frames behaves.
  message alignment_settings {

    // Local search parameters. Local search is fast and succeeds when 
    // the camera movement between two subsequent frames is small.
    message local_search_settings {

      // Maximum number of iterations to perform
      // A re-compilation the OpenCL code is required for changes to take effect.
      optional int32 maximum_iterations = 1 [default = 7];

      // Number of data pyramid levels to generate
      // A re-compilation the OpenCL code is required for changes to take effect.
      optional int32 pyramid_levels = 2 [default = 2];    

      // Maximum point distance between two points to establish correspondences
      // A re-compilation the OpenCL code is required for changes to take effect.
      optional float maximum_point_distance = 3 [default = 20];

      // Maximum normal angle deviation two points to establish correspondences
      // A re-compilation the OpenCL code is required for changes to take effect.
      optional float maximum_normal_angle = 4 [default = 30];
    }

    // Global search parameters. Global search is slower than local search but
    // succeeds in cases where the camera movement between two subsequent frames large.
    message global_search_settings {

      // Maximum number of seconds to search for tracking
      // A re-compilation the OpenCL code is required for changes to take effect.
      optional float maximum_seconds = 1 [default = 0.7];

      // Minimum inlier percentage to become a valid hypothesis.
      // A re-compilation the OpenCL code is required for changes to take effect.
      optional float minimum_inlier_percentage = 3 [default = 0.4];
    }

    // Verification of transform estimation.
    message verification_settings {
      // Maximum allowed average SDF change of voxels when tracking is established
      optional float maximum_sdf_change_on_track = 1 [default = 0.08];
    
      // Maximum allowed average SDF change of voxels when no tracking is present
      optional float maximum_sdf_change_no_track = 2 [default = 0.08];
    };

    // Local search parameters
    optional local_search_settings local_search = 1;

    // Global search parameters
    optional global_search_settings global_search = 2;

    // Verification settings
    optional verification_settings verification = 3;

    // Pad missing volume data with sensor data to increase tracking robustness when only portions 
    // of the volume are visible. Enabling this feature assumes a moving camera and a static scene.
    optional bool use_sensor_data_padding = 4 [default = false];

    // Anticipates the next position by trying to forecast. Useful to reduce the number of 
    // local search iterations. Enabling this feature assumes that the camera movement is kinda
    // smooth.
    optional bool use_position_forecast = 5 [default = true];
  }

  // Alignment setup
  optional alignment_settings camera_tracking = 9;

}

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_colorize.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_volume.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 {
        // Product string
        optional string name = 1 [default = "Unknown device name"];
        
        // Vendor string
        optional string vendor = 2 [default = "Unknown device vendor"];
    
        // Type of device
        optional device_type type = 3;

        // Global memory size in bytes.
        optional int64 global_memory_size = 4;

        // Internal ranking of device based on flops. 
        // Lower numbers are better ranks.
        optional int32 rank = 5;

    // Platform string. Devices might be found in multiple platforms (i.e using different drivers)
        optional string platform_name = 6 [default = "Unknown platform name"];
    }
    
  // List of devices.
    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_tune_reconstruction_options	(	reme_context_t	c,
		reme_tune_profile_t	profile
	)

Auto-tune reconstruction settings.

This function tries to tune the reconstruction settings with respect to a given quality profile (reme_tune_profile_t). It takes into account the specified device limitations and adjusts settings to for single volume scan.

Note

Quality is often inversely related to speed - a low quality profile will perform faster than a high quality profile setting.

The tuning algorithm reads the following reconstruction fields (see reme_context_bind_reconstruction_options)

• device_id
• volume.minimum_corner and volume.maximum_corner
• data_integration.use_colors

The tuning algorithm tunes the following reconstruction fields

• volume.resolution
• data_integration.truncation
• depthmap_erosion.*
• colormap_erosion.*

Note

Compiling (reme_context_compile) is required for the changed parameters to take effect.

Parameters

c	A valid context object
profile	Profile to tune for

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, and example_reconstructmesdk_sensor_printing.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_colorize.cpp, example_reconstructmesdk_error_handling.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_point_and_shoot_with_colors.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_context_bind_error_info	(	reme_context_t	c,
		reme_options_t	o
	)

Access current error state.

Associated Protocol Buffers Specification

// Current error state
message error_info {
  // List of error messages in order of arrival.
  repeated string messages = 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_error_handling.cpp.

reme_error_t reme_context_print_errors

(

reme_context_t

c

)

Print all errors to standard error output and reset errors.

Parameters

c	A valid context object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_error_handling.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_options.cpp, example_reconstructmesdk_options_type_safe.cpp, example_reconstructmesdk_point_and_shoot_with_colors.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.