ReconstructMe SDK  2.0.819-89134
Real-time 3D reconstruction engine
 All Classes Files Functions Typedefs Enumerations Enumerator Groups Pages
Typedefs | Enumerations
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.

Logging severity levels.

Defines the severity of a given logging message

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
sevseverity level
messagethe log message
user_infooptional pointer as specified by at reme_context_add_log_callback

Enumeration Type Documentation

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.

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.

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)
reme_error_t reme_context_destroy ( reme_context_t c)
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
cA valid context object
versionA mutable pointer that receives the null terminated string
lengthlength of string in bytes
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn 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
cA valid context object
lcLogging callback function pointer
user_dataA pointer to optional user data to be passed to the callback function
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn 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
cA valid context object
oA valid options binding
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn 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
cA valid context object
oA valid options binding
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn 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
cA valid context object
profileProfile to tune for
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn 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
cA valid context object
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn 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
cA valid context object
oA valid options binding
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_error_handling.cpp.
reme_error_t reme_context_print_errors ( reme_context_t  c)