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 compile settings which contain settings for the volume, the resolution and specific algorithm parameters. See reme_context_bind_compile_options for details.

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

  // Create a new context that has default options applied
  reme_context_t c;
  reme_context_create(&c);

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

  // Create empty options binding, not bound to any specific options
  reme_options_t o;
  reme_options_create(c, &o);

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

  // Bind the compile options.
  reme_context_bind_compile_options(c, o);

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

  const char *value;
  int length;

  reme_options_get(c, o, "volume_size.x", &value, &length);
  printf("Volume size in x-dim is: %s", value);

Or write to individual option fields

  // Increase resolution in all dimensions
  reme_options_set(c, o, "volume_size.x", "512");
  reme_options_set(c, o, "volume_size.y", "512");
  reme_options_set(c, o, "volume_size.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 {
        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;
}

use the repeated methods to access these fields.

  // Create empty options binding
  reme_options_t o, o_sub;
  reme_options_create(c, &o);
  reme_options_create(c, &o_sub);

  // Bind to OpenCL infos
  // See method documentation for protocol buffer specification
  reme_context_bind_opencl_info(c, o);

  // 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

  const char *value;
  int length;

  for (int i = 0; i < num_devices; i += 1) {
    printf("----\n");

    reme_options_bind_repeated_message(c, o, "devices", i, o_sub);

    reme_options_get(c, o_sub, "name", &value, &length);
    printf("Device '%s' \n", value);

    reme_options_get(c, o_sub, "vendor", &value, &length);
    printf(" - by '%s' \n", value);

    reme_options_get(c, o_sub, "type", &value, &length);
    printf(" - type %s \n", value);

    // Note in the above code we must interleave get and printf
    // because of memory management rules.
  }

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 https://developers.google.com/protocol-buffers/ 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
  reme_context_t c;
  reme_context_create(&c);

  // Create empty options binding
  reme_options_t o;
  reme_options_create(c, &o);

Next bind the options

  reme_surface_t s;
  reme_surface_create(c, &s);

  // Bind Poisson options
  reme_surface_bind_poisson_options(c, s, o);

Now use the generated poisson_options class

  poisson_options po;
  po.set_depth(9);

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;
  
  po.SerializeToString(&msg);  
  reme_options_set_bytes(c, o, msg.c_str(), 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;