ReconstructMe SDK  2.6.43-0
Real-time 3D reconstruction engine
Accessing and Modifying Options

How to interact with options in a generic way through reme_options_t

Accessing and manipulating options/parameters is central to every application. The Options interface provides methods to interact and manipulate parameters and options generic way in ReconstructMe API.

Basic Options Handling

The reme_options_t represents a generic options handle. Once created it is said to be empty, as it does not represent any specific options. In order to manipulate specific options, you need to bind it to a specific options using a specific function that usually carries bind in its function name. The page Options Bindings lists all known binders. Each binder documents the available parameters in the method's detail section using Google Protocol Buffer format.

Once the options object is bound, it directly manipulates the bound options. You can query values using reme_options_get, manipulate values using reme_options_set, or export/import options from and to files using reme_options_save_to_file and reme_options_load_from_file.

Following is an example to adjust reconstruction settings which contain settings for the volume, the resolution and specific algorithm parameters. See reme_context_bind_reconstruction_options for details.

First create context. This will initialize the reconstruction options with sensible default values.

// Create a new context that has default options applied

Next create an empty options object, not bound to any parameters.

// Create empty options binding, not bound to any specific options

In order to manipulate and access specific options it needs to be bound. In our case to reconstruction options.

// Bind the reconstruction options.

Think about the binding as a pointer to the internal options set. Every action we take on the options object reflects directly to the internal options set and as such influences the outcome of reme_context_compile.

We can read values

int res;
reme_options_get_int(c, o, "volume.resolution.x", &res);
printf("Volume size in x-dim is: %i", res);

Or write to individual option fields

// Increase resolution in all dimensions
reme_options_set_int(c, o, "volume.resolution.x", 512);
reme_options_set_int(c, o, "volume.resolution.y", 512);
reme_options_set_int(c, o, "volume.resolution.z", 512);

Options can be saved using a human read-able format

// Export options in a human read-able format
reme_options_save_to_file(c, o, "options.txt");

And restored at a later point in time

// Export options in a human read-able format
reme_options_load_from_file(c, o, "options.txt");

Repeated Options Fields

In case the options specification contains repeated fields such as the OpenCL informations below

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;

use the repeated methods to access these fields.

// Create empty options binding
reme_options_t o, o_sub;
reme_options_create(c, &o_sub);
// Bind to OpenCL infos
// See method documentation for protocol buffer specification
// See how many devices are available
int num_devices = 0;
reme_options_get_repeated_count(c, o, "devices", &num_devices);
printf("Found %i OpenCL compatible devices\n", num_devices);
// Each device is a nested message. Iterate over all of them
char name[256], vendor[256], type[256];
for (int i = 0; i < num_devices; i += 1) {
reme_options_bind_repeated_message(c, o, "devices", i, o_sub);
reme_options_get(c, o_sub, "name", name, 256);
reme_options_get(c, o_sub, "vendor", vendor, 256);
reme_options_get(c, o_sub, "type", type, 256);
printf("Device '%s' \n", name);
printf(" - by '%s' \n", vendor);
printf(" - type %s \n", type);

Typesafe Options Handling

All the above examples had in common that they were using a lazy-reflection based API through strings. ReconstructMe API allows you to use an alternative, type-safe approach using Google Protocol Buffers directly.

Using Google Protocol Buffers directly you can compile a getter/setter object for the programming language of your choice and use the built-in serialization mechanism to get a nice way to interop between your programming language and ReconstructMe API. Such compilers exist for all modern languanges such as C, C++, Java and .NET. See for details.

Here's an example of the type safe approach in C++ using the compile settings. It requires the generation of the class poisson_options through the use of protoc which ships with Google Protocol Buffers. The compiler protoc is invoked with the protocol buffer description (see reme_surface_bind_poisson_options) and it produces header and source files containing the class poisson_options. This class can then be used in your project.

First create the context and your options object as usual

// Create a new context that has default options applied
// Create empty options binding

Next bind the options

// Bind Poisson options

Now use the generated poisson_options class

poisson_options po;

To transfer the state of poisson_options to our reme_options_t we can use the built-in serialization mechnisms. This allows us to effectively serialize/deserialize option objects from string like buffers.

// In order to supply it to ReconstructMe SDK we use the built-in serialization mechanism.
std::string msg;
reme_options_set_bytes(c, o, msg.c_str(), static_cast<int>(msg.size()));

To read the current state of the Poisson options back to your poisson_options instance use

// We can also read the current settings in a similar fashion
const void *m;
int length;
reme_options_get_bytes(c, o, &m, &length);
po.ParseFromArray(m, length);
std::cout << po.DebugString() << std::endl;