Options

Detailed Description

This module provides methods to interact and manipulate parameters, options and information that are not performance relevant in a generic way. ReconstructMe SDK uses Google Protocol Buffer to represent available options. Such a specification is a plain text file that describes the available fields. For example the options to drive the Poisson surface reconstruction are

// Poisson surface generation options
message poisson_options {
  optional int32 depth = 1 [default = 8];
  optional int32 solver_divide = 2 [default = 8];
  optional int32 iso_divide = 3 [default = 8];
  optional int32 minimum_samples_per_node = 4 [default = 1];
  optional float scale = 5 [default = 1];
  optional bool enable_clipping = 6 [default = false];
}

To modify and access the above fields you have two possibilities.

Lazy Dynamic Approach

The following code snippet uses the dynamic API that relies on reflection of available fields.

  reme_surface_t s;
  reme_surface_create(c, &s);

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

  // Modify the 'depth' field through a reflection like syntax.
  reme_options_set(c, o, "depth", "9");

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 the 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.
  }

Type Safe Approach

Alternatively 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 different languages. 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.

  reme_surface_t s;
  reme_surface_create(c, &s);

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

  // We've used the protocol buffer specification file (see documentation of reme_surface_bind_poisson_options) 
  // and the Google protocol buffer C++ compiler to generate a getter/setter class out of it. 

  poisson_options po;
  po.set_depth(9);

  // 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());
    
  // 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;

Typedef Documentation

typedef int reme_options_t

Handle referencing an options object.

A reme_options_t references a specific options class. Internally ReconstructMe SDK uses Google's protocol buffers to represent options and parameters. Protocol buffers a language-neutral, platform-neutral, extensible mechanism for serializing structured data.

In order to manipulate these protocol buffer options you have two options:

• use the lazy dynamic interface and manipulate variables through a reflection like mechanism.

  See Also

  reme_options_set

  reme_options_get

• use the typesafe interface and generate a structure from the protobuf specification file using the protobuf compiler. Interact with this class and pass ReconstructMe SDK a serialized string to its content.

  See Also

  reme_options_set_bytes

  reme_options_get_bytes

  https://developers.google.com/protocol-buffers/

Function Documentation

reme_error_t reme_options_create	(	reme_context_t	c,
		reme_options_t *	o
	)

Create a new options binding.

Creates an empty options binding.

Parameters

c	A valid context object
o	A pointer that will receive the options handle.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_lazy.cpp, example_reconstructmesdk_options_type_safe.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_options_destroy	(	reme_context_t	c,
		reme_options_t *	o
	)

Destroy a previously created options object.

Parameters

c	A pointer to a valid context object
o	A mutable pointer to a valid options handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_set	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		const char *	value
	)

Set a specific options field.

This method uses a reflection like mechanism to set the specified field value. Use the '.' character to separate nested fields. If any field encountered is repeated the first element is used.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
value	Value String representation of the value to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_lazy.cpp, example_reconstructmesdk_recorder.cpp, and example_reconstructmesdk_surface.cpp.

reme_error_t reme_options_get	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		const char **	value,
		int *	length
	)

Get a specific repeated options field.

This method uses a reflection like mechanism to get the specified field value. Use the '.' character to separate nested fields. If any field encountered is repeated the first element is used.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
value	Mutable pointer to receive the option value
length	Length of option value in characters.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_lazy.cpp.

reme_error_t reme_options_get_repeated	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		int	repeated_index,
		const char **	value,
		int *	length
	)

Get a specific repeated options field.

This method uses a reflection like mechanism to get the specified field value. Use the '.' character to separate nested fields. The repeated_index only affects the last part of the field description. Any parent repeated messages are accessed with index zero.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
repeated_index	When the target field is repeated the command applies to the i-th field.
value	Mutable pointer to receive the option value
length	Length of option value in characters.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_get_repeated_count	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		int *	length
	)

Return the number of elements in a repeated field.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field to manipulate
length	Number of elements in repeated field. If field is not repeated, returns 1.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_lazy.cpp.

reme_error_t reme_options_bind_message	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		reme_options_t	o_nested
	)

Bind options object to a nested message.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field containing the nested message
o_nested	A valid options object recieving the binding.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_bind_repeated_message	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		int	repeated_index,
		reme_options_t	o_nested
	)

Bind options object to a nested repeated message.

Parameters

c	A valid context object
o	A valid options object
field_name	Name of the field containing the nested message
repeated_index	When the target message is repeated the command applies to the i-th field.
o_nested	A valid options object recieving the binding.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_lazy.cpp.

reme_error_t reme_options_load_from_file	(	reme_context_t	c,
		reme_options_t	o,
		const char *	filename
	)

Set options by loading a human readable options representation from file.

This method uses protobuf's text format parser to read in the content of the file. This text format is very similar to json.

Parameters

c	A valid context object
o	A valid options object
filename	Path to file.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_recorder.cpp, and example_reconstructmesdk_sensor_multi_independent.cpp.

reme_error_t reme_options_save_to_file	(	reme_context_t	c,
		reme_options_t	o,
		const char *	filename
	)

Save options in a human readable file format.

This method uses protobuf's text format serializer to write in the content of the file. The output is similar to json.

Parameters

c	A valid context object
o	A valid options object
filename	Path to file.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_save_to_string	(	reme_context_t	c,
		reme_options_t	o,
		const char **	message,
		int *	length
	)

Get options as string using a human readable serialization.

This method uses protobuf's text format serializer to write in the content of the file. The output is similar to json.

Parameters

c	A valid context object
o	A valid options object
message	A mutable pointer that will receive the content of the message
length	A pointer that will receive the length of the serialized message in bytes

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_set_bytes	(	reme_context_t	c,
		reme_options_t	o,
		const void *	message,
		int	length
	)

Set options by reading a binary options representation.

This method uses protobuf's standard serialization format (binary) to read in the desired options value.

Parameters

c	A valid context object
o	A valid options object
message	A valid pointer to the serialized message
length	The length of the serialized message in bytes.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_type_safe.cpp.

reme_error_t reme_options_get_bytes	(	reme_context_t	c,
		reme_options_t	o,
		const void **	message,
		int *	length
	)

Get options by serializing them in a binary options representation.

This method uses protobuf's standard serialization format (binary) to serialize the current state of option values.

Parameters

c	A valid context object
o	A valid options object
message	A mutable pointer that will receive the address of the serialized message
length	A pointer that will receive the length of the serialized message in bytes

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options_type_safe.cpp.