Options

Generic options object to manipulate system settings. More...

Typedefs
typedef int	reme_options_t
	Handle referencing an options object.
reme_error_t	reme_options_create (reme_context_t c, reme_options_t *o)
	Create a new options binding.
reme_error_t	reme_options_destroy (reme_context_t c, reme_options_t *o)
	Destroy a previously created options object.
reme_error_t	reme_options_set (reme_context_t c, reme_options_t o, const char *field_name, const char *value)
	Set the value of options field.
reme_error_t	reme_options_set_int (reme_context_t c, reme_options_t o, const char *field_name, int value)
	Set a specific integer options field.
reme_error_t	reme_options_set_real (reme_context_t c, reme_options_t o, const char *field_name, float value)
	Set a specific real options field.
reme_error_t	reme_options_set_bool (reme_context_t c, reme_options_t o, const char *field_name, bool value)
	Set a specific boolean options field.
reme_error_t	reme_options_get (reme_context_t c, reme_options_t o, const char *field_name, char *value, int length, int index=0)
	Get the value of an options field as string.
reme_error_t	reme_options_get_int (reme_context_t c, reme_options_t o, const char *field_name, int *value, int index=0)
	Get the value of an integer options field.
reme_error_t	reme_options_get_real (reme_context_t c, reme_options_t o, const char *field_name, float *value, int index=0)
	Get the value of a real options field.
reme_error_t	reme_options_get_bool (reme_context_t c, reme_options_t o, const char *field_name, bool *value, int index=0)
	Get the value of a boolean options field.
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.
reme_error_t	reme_options_clear (reme_context_t c, reme_options_t o)
	Clear options.
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.
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.
reme_error_t	reme_options_copy (reme_context_t c, reme_options_t o_src, reme_options_t o_dst)
	Copy the content of the source options to the destination options.
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.
reme_error_t	reme_options_load_from_string (reme_context_t c, reme_options_t o, const char *message, int length)
	Set options by loading a human readable options representation from a given string.
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.
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.
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.
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.

Detailed Description

Generic options object to manipulate system settings.

This module provides methods to interact and manipulate parameters and options generic way. Once a reme_options_t is created it is 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.

See Accessing and Modifying Options for more details and examples.

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_calibration.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_error_handling.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_printing.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.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 the value of 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	String to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, and example_reconstructmesdk_sensor.cpp.

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

Set a specific integer 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 to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.

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

Set a specific real 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 to set

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_colorize.cpp, and example_reconstructmesdk_point_and_shoot_with_colors.cpp.

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

Set a specific boolean 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 to set

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, and example_reconstructmesdk_surface.cpp.

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

Get the value of an options field as string.

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 access
value	Pre-allocated buffer to assign the string to
length	Length of buffer
index	Repeated field index

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_error_handling.cpp, and example_reconstructmesdk_options.cpp.

reme_error_t reme_options_get_int	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		int *	value,
		int	index = 0
	)

Get the value of an integer 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 access
value	Value to assign to
index	Repeated field index

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_options.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, and example_reconstructmesdk_volume.cpp.

reme_error_t reme_options_get_real	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		float *	value,
		int	index = 0
	)

Get the value of a real 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 access
value	Value to assign to
index	Repeated field index

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_error_t reme_options_get_bool	(	reme_context_t	c,
		reme_options_t	o,
		const char *	field_name,
		bool *	value,
		int	index = 0
	)

Get the value of a boolean 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 access
value	Value to assign to
index	Repeated field index

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_sensor.cpp.

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_error_handling.cpp, and example_reconstructmesdk_options.cpp.

reme_error_t reme_options_clear	(	reme_context_t	c,
		reme_options_t	o
	)

Clear options.

Clearing option values means to reset them into an empty state. If you retrieve a value from an empty field, the fields default value (see associated .proto file) will be returned. When the field does not have any default value assigned, an error will be returned.

Clearing is useful when one wants to introduce an optional state. For example, reme_sensor_apply_capture_options will only apply those capture options that are not empty. Take note that by default the bound capture options, i.e reme_sensor_bind_capture_options will contain the current set values. Therefore, clear those options before setting individual option values.

Parameters

c	A valid context object
o	A valid options object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_error_handling.cpp, example_reconstructmesdk_scan_tilt.cpp, and example_reconstructmesdk_sensor.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

Examples:

example_reconstructmesdk_calibration.cpp.

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.cpp.

reme_error_t reme_options_copy	(	reme_context_t	c,
		reme_options_t	o_src,
		reme_options_t	o_dst
	)

Copy the content of the source options to the destination options.

This method requires the two option sets involved to be of the same type.

Parameters

c	A valid context object
o_src	A valid options object to copy from
o_dst	A valid options object to copy to

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.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_options.cpp, and example_reconstructmesdk_recorder.cpp.

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

Set options by loading a human readable options representation from a given string.

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

Parameters

c	A valid context object
o	A valid options object
message	Immutable pointer to start of string.
length	Number of characters in string.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

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

Examples:

example_reconstructmesdk_calibration.cpp, and example_reconstructmesdk_options.cpp.

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.