NxLibItem¶

class NxLibItem¶

NxLibItem. This class simplifies the concatenation of string and integer constants to an NxLib compatible item path specification via its operator[]. Assignment and comparison operators simplify the usage of NxLib tree items, almost as if using local variables.

Public Functions

NxLibItem(std::string const &_path = "")¶

Constructor

Parameters

_path: : References to an item path in the NxLib Tree. Empty path references the root node.

void operator<<(NxLibItem const &otherItem) const¶

Sets a new value to the item from another NxLibItem.

Parameters

otherItem: The NxLibItem to copy from.

void operator<<(std::string const &jsonString) const¶

Sets a new value to the item from a json formatted std::string.

Parameters

jsonString: Json formatted string.

void operator<<(char const *const jsonString) const¶

Sets a new value to the item from a json formatted char array.

Parameters

jsonString: Pointer to a char array.

NxLibItem const operator[](std::string const &subItemName) const¶

Creates an NxLibItem referencing a subnode of the current item.

Return

An NxLibItem referring to the subitem.

Parameters

subItemName: Access a JSON Object’s subitem by it’s name.

NxLibItem const operator[](int subItemIndex) const¶

Creates an NxLibItem referencing a subnode of the current item.

Return

An NxLibItem referring to the subitem.

Parameters

subItemIndex: Access an element of a JSON Array or a JSON Object subitem by it’s index.

int compare(int *returnCode, char const *const value) const¶

Compare the item’s value to a char* constant.

Return

-1: If the item’s value is smaller than the constant.

0: If the values are equal.

1: If the item’s value is larger than the constant.

Parameters

returnCode: The error code returned when accessing the item.
value: The value to compare the item’s value with.

template<typename T> int compare(T const &value) const¶

Compare the item’s value to a constant T. Templates will be generated by the compiler for the C++ types int, double, bool std::string and char*

Return

-1: If the item’s value is smaller than the constant.

0: If the values are equal.

1: If the item’s value is larger than the constant.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.

template<typename T> int compare(int *returnCode, T const &value) const¶

Compare the item’s value to a constant T. Templates will be generated by the compiler for the C++ types int, double, bool std::string and char*

Return

-1: If the item’s value is smaller than the constant.

0: If the values are equal.

1: If the item’s value is larger than the constant.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.
returnCode: The error code returned when accessing the item.

template<typename T> void set(T const &value) const¶

Set the item’s value to a constant.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to set.

void set(int *returnCode, int value) const¶

Set the item’s value to an int constant.

Parameters

returnCode: The error code returned when accessing the item.
value: The value to set.

void set(int *returnCode, double value) const¶

Set the item’s value to a double constant.

Parameters

returnCode: The error code returned when accessing the item.
value: The value to set.

void set(int *returnCode, bool value) const¶

Set the item’s value to a bool constant.

Parameters

returnCode: The error code returned when accessing the item.
value: The value to set.

void set(int *returnCode, std::string const &value) const¶

Set the item’s value to a string constant.

Parameters

returnCode: The error code returned when accessing the item.
value: The value to set.

void set(int *returnCode, char const *const value) const¶

Set the item’s value to a string constant.

Parameters

returnCode: The error code returned when accessing the item.
value: The value to set.

void setNull() const¶: Set the item’s value to Null.

void setNull(int *returnCode) const¶

Set the item’s value to Null.

Parameters

returnCode: The error code when accessing the item.

void setJson(std::string const &value, bool onlyWriteableNodes = false) const¶

Set the item’s value to a new value specified as JSON string. This might also be a representation of an entire subtree.

Parameters

value: The value to set.
onlyWriteableNodes: Specifies whether the function should try to write each single node into the existing tree structure instead of replacing the entire subtree. When specifying true here the function will not complain if certain nodes could not be written due to access restrictions. This can be used to restore the state of the library or the Parameters node of a camera if the tree state has previously been captured via nxLibGetJson. When this parameter is set to false, all items of the entire subtree must not be access restricted in order for the function call to succeed! If this parameter is set and the given JSON value does not match the current structure of the node, the function will return the error code NxLibItemTypeNotCompatible. This indicates, that there was not a single node with the same structure as in the JSON string and the function could never modify any value. In this case you probably tried to apply the JSON value to the wrong path.

void setJson(int *returnCode, std::string const &value, bool onlyWriteableNodes = false) const¶

Set the item’s value to a new value specified as JSON string. This might also be a representation of an entire subtree.

Parameters

returnCode: The error code returned when accessing the item.
value: The value to set.
onlyWriteableNodes: Specifies whether the function should try to write each single node into the existing tree structure instead of replacing the entire subtree. When specifying true here the function will not complain if certain nodes could not be written due to access restrictions. This can be used to restore the state of the library or the Parameters node of a camera if the tree state has previously been captured via nxLibGetJson. When this parameter is set to false, all items of the entire subtree must not be access restricted in order for the function call to succeed! If this parameter is set and the given JSON value does not match the current structure of the node, the function will return the error code NxLibItemTypeNotCompatible. This indicates, that there was not a single node with the same structure as in the JSON string and the function could never modify any value. In this case you probably tried to apply the JSON value to the wrong path.

template<typename T> T const &operator=(T const &value) const¶

Sets a new value to the item. This operator is templated and simply maps to the corresponding set function.

Return

The current item.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: T The value to set on the item.

template<typename T> bool operator==(T const &value) const¶

Compare the item’s value to a constant for equality. All comparison operators are templates and map to a corresponding call to the compare() member function.

Return

Boolean result of the comparison.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.

template<typename T> bool operator!=(T const &value) const¶

Compare the item’s value to a constant for inequality. All comparison operators are templates and map to a corresponding call to the compare() member function.

Return

Boolean result of the comparison.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.

template<typename T> bool operator>(T const &value) const¶

Compare the item’s value to a constant. All comparison operators are templates and map to a corresponding call to the compare() member function.

Return

Boolean result of the comparison.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.

template<typename T> bool operator<(T const &value) const¶

Compare the item’s value to a constant. All comparison operators are templates and map to a corresponding call to the compare() member function.

Return

Boolean result of the comparison.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.

template<typename T> bool operator>=(T const &value) const¶

Compare the item’s value to a constant. All comparison operators are templates and map to a corresponding call to the compare() member function.

Return

Boolean result of the comparison.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.

template<typename T> bool operator<=(T const &value) const¶

Compare the item’s value to a constant. All comparison operators are templates and map to a corresponding call to the compare() member function.

Return

Boolean result of the comparison.

Template Parameters

T: Templated type. Can be int, double, bool, std::string and char*.

Parameters

value: The value to compare the item’s value with.

template<typename T> T as(int *returnCode) const¶

Reads the item’s value in a specified format. The format is given as type argument to the template. The template maps the C++ types std::string, int, double and bool to the member functions asString, asInt, asDouble and asBool.

Return

The item value in the type specified as template parameter.

Template Parameters

T: Templated type. Can be int, std::string, char*, double and bool.

Parameters

returnCode: The error code returned when accessing the item.

std::string asString(int *returnCode) const¶

Reads the item’s value in std::string format.

Return

The item value as std::string value.

Parameters

returnCode: The error code returned when accessing the item.

int asInt(int *returnCode) const¶

Reads the item’s value as integer.

Return

The item value as int value.

Parameters

returnCode: The error code returned when accessing the item.

double asDouble(int *returnCode) const¶

Reads the item’s value as integer.

Return

The item value as double value.

Parameters

returnCode: The error code returned when accessing the item.

bool asBool(int *returnCode) const¶

Reads the item’s value as boolean.

Return

The item value as boolean value.

Parameters

returnCode: The error code returned when accessing the item.

std::string asJson(int *returnCode, bool prettyPrint = false, int numberPrecision = 18, bool scientificNumberFormat = true) const¶

Try to read this tree item and return its JSON representation.

Return

The item value as JSON string if the item exists. This might also be an entire subtree in JSON representation.

Parameters

returnCode: The error code returned when accessing the item.
prettyPrint: When true the JSON string will be formatted with line breaks and tabs.
numberPrecision: Specifies the accuracy of numbers.
scientificNumberFormat: Specifies if the scientific exponential notation should be used.

std::string asJsonMeta(int *returnCode, int numLevels = -1, bool prettyPrint = false, int numberPrecision = 18, bool scientificNumberFormat = true) const¶

Retrieves an item value or an entire subtree in JSON representation including item metadata (protection, extended type, internal flags). This function is only intended to be used by NxTreeEdit to visualize the entire tree state.

Return

The item value as JSON string if the item exists with meta data.

Parameters

returnCode:
numLevels: The depth of the returned subtree. Nodes in lower levels will be omitted.
prettyPrint: Specify true here to format the resulting string with line breaks and tabs.
numberPrecision: The floating point precision of the returned numbers.
scientificNumberFormat: Specifies if the scientific exponential notation should be used.

std::string asJson(bool prettyPrint = false, int numberPrecision = 18, bool scientificNumberFormat = false) const¶

Try to read this tree item and return its JSON representation.

Return

The item value as JSON string if the item exists.

Parameters

prettyPrint: Specify true here to format the resulting string with line breaks and tabs.
numberPrecision: The floating point precision of the returned numbers.
scientificNumberFormat: Specifies if the scientific exponential notation should be used.

std::string asJsonMeta(int numLevels = -1, bool prettyPrint = false, int numberPrecision = 18, bool scientificNumberFormat = true) const¶

Retrieves an item value or an entire subtree in JSON representation including item metadata (protection, extended type, internal flags). This function is only intended to be used by NxTreeEdit to visualize the entire tree state.

Return

The item value as JSON string with meta data, if the item exists.

Parameters

numLevels: The depth of the returned subtree. Nodes in lower levels will be omitted.
prettyPrint: Specify true here to format the resulting string with line breaks and tabs.
numberPrecision: The floating point precision of the returned numbers.
scientificNumberFormat: Specifies if the scientific exponential notation should be used.

template<typename T> T as() const¶

Reads the item’s value in a specified format.

Return

The item value in the specified format.

Template Parameters

T: Templated type. Can be std::string, char*, int, double, bool.

std::string asString() const¶

Reads the item’s value in std::string format.

Return: The item value as std::string value.

int asInt() const¶

Reads the item’s value in an integer format.

Return: The item value as int value.

double asDouble() const¶

Reads the item’s value in double format.

Return: The item value as double value.

bool asBool() const¶

Reads the item’s value in bool format.

Return: The item value as boolean value.

bool isNull(int *returnCode) const¶

Returns whether the item is of type Null or not.

Return

true if the item was of the corresponding JSON type, otherwise false

Parameters

returnCode: The error code returned when accessing the item.

bool isString(int *returnCode) const¶

Returns whether the item is of type String or not.

Return

true if the item was of the corresponding JSON type, otherwise false

Parameters

returnCode: The error code returned when accessing the item.

bool isNumber(int *returnCode) const¶

Returns whether the item is of type Number or not.

Return

true if the item was of the corresponding JSON type, otherwise false

Parameters

returnCode: The error code returned when accessing the item.

bool isBool(int *returnCode) const¶

Returns whether the item is of type Bool or not.

Return

true if the item was of the corresponding JSON type, otherwise false

Parameters

returnCode: The error code returned when accessing the item.

bool isArray(int *returnCode) const¶

Returns whether the item is of type Array or not.

Return

true if the item was of the corresponding JSON type, otherwise false

Parameters

returnCode: The error code returned when accessing the item.

bool isObject(int *returnCode) const¶

Returns whether the item is of type Object or not.

Return

true if the item was of the corresponding JSON type, otherwise false

Parameters

returnCode: The error code returned when accessing the item.

bool isNull() const¶

Returns whether the item is of type Null or not.

Return

bool isString() const¶

Returns whether the item is of type String or not.

Return: true if the item was of the corresponding JSON type, otherwise false.

bool isNumber() const¶

Returns whether the item is of type Number or not.

Return: true if the item was of the corresponding JSON type, otherwise false.

bool isBool() const¶

Returns whether the item is of type Bool or not.

Return: true if the item was of the corresponding JSON type, otherwise false.

bool isArray() const¶

Returns whether the item is of type Array or not.

Return: true if the item was of the corresponding JSON type, otherwise false.

bool isObject() const¶

Returns whether the item is of type Object or not.

Return: true if the item was of the corresponding JSON type, otherwise false.

int type(int *returnCode) const¶

Retrieve the JSON type of this item.

Return

The item type constant. See nxLibGetType() for item types.

Parameters

returnCode: The error code returned when accessing the item.

int type() const¶

Retrieve the JSON type of this item.

Return: The item type constant. See nxLibGetType() for item types.

bool exists() const¶

Check whether an item with the corresponding path exists in the tree.

Return: true, if the item exists, false otherwise.

bool exists(int *returnCode) const¶

Check whether an item with the corresponding path exists in the tree.

Return

true, if the item exists, false otherwise.

Parameters

returnCode: The error code returned when accessing the item.

void erase() const¶: Deletes the item or subtree.

void erase(int *returnCode) const¶

Deletes the item or subtree.

Parameters

returnCode: The error code returned when accessing the item.

std::string name() const¶

Retrieves the item’s name.

Note: Calling this function is only allowed when accessing object members by index, otherwise the function will fail.
Return: The item’s name.

std::string name(int *returnCode) const¶

Retrieves the item’s name.

Note

Calling this function is only allowed when accessing object members by index, otherwise the function will

Return

The item’s name.

Parameters

returnCode: The error code returned when accessing the item.

int count() const¶

Retrieves the number of subitems of an Object or Array. Calling the function on scalar nodes will return an error.

Note: Calling this function on a Binary node will retrieve the binary data size in bytes, but it is recommended to use getBinaryDataInfo instead to get and verify all format properties of the binary blob before retrieving it.
Return: The number of subitems.

int count(int *returnCode) const¶

Retrieves the number of subitems of an Object or Array. Calling the function on scalar nodes will return an error.

Note

Calling this function on a Binary node will retrieve the binary data size in bytes, but it is recommended to use getBinaryDataInfo instead to get and verify all format properties of the binary blob before retrieving it.

Return

The number of subitems.

Parameters

returnCode: The error code returned when accessing the item.

void getBinaryDataInfo(int *width, int *height, int *channels, int *bytesPerElement, bool *isFloat, double *timestamp) const¶

Reads the properties of a Binary node. You can omit retrieving any of the properties by setting the corresponding parameter pointer to 0.

Parameters

width: Width of the image.
height: Height of the image.
channels: Number of channels, i.e. elements per pixels.
bytesPerElement: Size of each element.
isFloat: Indicates whether elements are an IEEE float type of the corresponding size.
timestamp: Timestamp when the binary blob was generated.

void getBinaryDataInfo(int *returnCode, int *width, int *height, int *channels, int *bytesPerElement, bool *isFloat, double *timestamp) const¶

Reads the properties of a Binary node. You can omit retrieving any of the properties by setting the corresponding parameter pointer to 0.

Parameters

returnCode: The error code returned when accessing the item.
width: Width of the image.
height: Height of the image.
channels: Number of channels, i.e. elements per pixels.
bytesPerElement: Size of each element.
isFloat: Indicates whether elements are an IEEE float type of the corresponding size.
timestamp: Timestamp when the binary blob was generated.

void getBinaryData(void *bufferPointer, int bufferSize, int *numBytesCopied, double *timestamp) const¶

Retrieves data of a Binary item.

Parameters

bufferPointer: Pointer to a buffer where the binary data will be copied to. The buffer must have been allocated by the caller.
bufferSize: Size of the allocated buffer in bytes.
numBytesCopied: Pointer to an integer, can be 0. If non-zero the value will be set to the number of bytes actually copied to the user’s buffer.
timestamp: Timestamp when the binary blob was generated. This pointer can be set to zero when the time stamp should not be retrieved.

void getBinaryData(int *returnCode, void *bufferPointer, int bufferSize, int *numBytesCopied, double *timestamp) const¶

Retrieves data of a Binary item.

Parameters

returnCode: The error code returned when accessing the item.
bufferPointer: Pointer to a buffer where the binary data will be copied to. The buffer must have been allocated by the caller.
bufferSize: Size of the allocated buffer in bytes.
numBytesCopied: Pointer to an integer, can be 0. If non-zero the value will be set to the number of bytes actually copied to the user’s buffer.
timestamp: Timestamp when the binary blob was generated. This pointer can be set to zero when the time stamp should not be retrieved.

void setBinaryData(void const *bufferPointer, int bufferSize) const¶

Sets data of a Binary item.

Parameters

bufferPointer: Pointer to a buffer where the binary data will be copied from.
bufferSize: Size of the data to be copied in bytes.

void setBinaryData(int *returnCode, void const *bufferPointer, int bufferSize) const¶

Sets data of a Binary item.

Parameters

returnCode: The error code returned when accessing the item.
bufferPointer: Pointer to a buffer where the binary data will be copied from.
bufferSize: Size of the data to be copied in bytes.

template<typename T> void getBinaryData(std::vector<T> &bufferVector, double *timestamp) const¶

Retrieves data of a Binary item.

Note

This function takes a std::vector<T> as buffer.

Template Parameters

T: The element type of the std::vector buffer.

Parameters

bufferVector: A std::vector that should be filled with the binary data.
timestamp: Timestamp when the binary blob was generated. This pointer can be set to zero when the time stamp should not be retrieved.

template<typename T> void setBinaryData(std::vector<T> const &bufferVector) const¶

Sets data of a Binary item.

Note

This function takes a std::vector<T> as buffer.

Template Parameters

T: The element type of the std::vector buffer.

Parameters

bufferVector: The std::vector to take the binary data from.

template<typename T> void setBinaryData(int *returnCode, std::vector<T> const &bufferVector) const¶

Sets data of a Binary item.

Template Parameters

T: The element type of the std::vector.

Parameters

returnCode: The error code returned when accessing the item.
bufferVector: A std::vector from which the binary data should be copied.

template<typename T> void setBinaryData(std::vector<T> const &bufferVector, int width, int height, int channelCount, bool isFloat) const¶

Sets data of a Binary item.

Template Parameters

T: Element type of the std::vector.

Parameters

bufferVector: A std::vector from which the binary data should be copied.
width: The width of the array (consecutive elements in memory).
height: The height of the array (number of rows of width*channelCount elements)
channelCount: Number of channels for a single item.
isFloat: Indicates whether elements are an IEEE float type of the corresponding size.

template<typename T> void setBinaryData(int *returnCode, std::vector<T> const &bufferVector, int width, int height, int channelCount, bool isFloat) const¶

Sets data of a Binary item.

Template Parameters

T: Element type of the std::vector.

Parameters

returnCode: The error code returned when accessing the item.
bufferVector: A std::vector from which the binary data should be copied.
width: The width of the array (consecutive elements in memory).
height: The height of the array (number of rows of width*channelCount elements)
channelCount: Number of channels for a single item.
isFloat: Indicates whether elements are an IEEE float type of the corresponding size.

template<typename T> void setBinaryData(T const *const bufferVector, int width, int height, int channelCount, bool isFloat) const¶

Sets data of a Binary item.

Template Parameters

T: Element type the buffer array.

Parameters

bufferVector: Pointer to a buffer that holds the data to copy from.
width: The width of the array (consecutive elements in memory).
height: The height of the array (number of rows of width*channelCount elements)
channelCount: Number of channels for a single item.
isFloat: Indicates whether elements are an IEEE float type of the corresponding size.

template<typename T> void setBinaryData(int *returnCode, T const *const bufferVector, int width, int height, int channelCount, bool isFloat) const¶

Template Parameters

T: Element type the buffer array.

Parameters

returnCode: The error code returned when accessing the item.
bufferVector: Pointer to a buffer that holds the data to copy from.
width: The width of the array (consecutive elements in memory).
height: The height of the array (number of rows of width*channelCount elements)
channelCount: Number of channels for a single item.
isFloat: Indicates whether elements are an IEEE float type of the corresponding size.

template<int Rows, int Cols, int Opt, int MaxRows, int MaxCols> void set(Eigen::Matrix<double, Rows, Cols, Opt, MaxRows, MaxCols> const &matrix) const¶

Set the item’s value to a binary from a eigen matrix.

Parameters

matrix: The Eigen Matrix to copy from.

template<int Rows, int Cols, int Opt, int MaxRows, int MaxCols> void set(int *returnCode, Eigen::Matrix<double, Rows, Cols, Opt, MaxRows, MaxCols> const &matrix) const¶

Set the item’s value to a binary from a eigen matrix.

Parameters

returnCode: The error code returned when accessing the item.
matrix: The Eigen Matrix to copy from.

template<typename T> void getBinaryData(int *returnCode, std::vector<T> &bufferVector, double *timestamp) const¶

Retrieves data of a Binary item.

Template Parameters

T: Element type of the std::vector buffer.

Parameters

returnCode: The error code returned when accessing the item.
bufferVector: A std::vector that should be filled with the binary data.
timestamp: Timestamp when the binary blob was generated. This pointer can be set to zero when the time stamp should not be retrieved.

void waitForChange() const¶

void waitForChange(int *returnCode) const¶

Waits for any change to the item.

Parameters

returnCode: The error code returned when accessing the item.

void waitForType(int type, bool waitForEqual) const¶

Waits until the item has a specific type.

Parameters

type: The type constant to wait for. See nxLibGetType() for valid types.
waitForEqual: Indicates whether to wait until the item has the indicated type, or whether to wait until the item has a type other than the specified one.

void waitForType(int *returnCode, int type, bool waitForEqual) const¶

Waits until the item has a specific type.

Parameters

returnCode: The error code returned when accessing the time.
type: The type constant to wait for. See nxLibGetType() for valid types.
waitForEqual: Indicates whether to wait until the item has the indicated type, or whether to wait until the item has a type other than the specified one.

void waitForValue(int value, bool waitForEqual) const¶

Parameters

value:
waitForEqual:

void waitForValue(int *returnCode, int value, bool waitForEqual) const¶