NxLibItem¶

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

Subclassed by NxLibConfigItem

Public Types

using WatchCallback = std::function<void(NxLibItem const &value, NxLibWatchHandle handle)>¶

Public Functions

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

Parameters: _path – Path to a node in the NxLib tree. By default (with an empty path), the item references the root node.

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

Copies the JSON value from another NxLibItem.

Parameters: otherItem – The NxLibItem to copy from.

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

inline 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 JSON formatted string.

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

Creates an NxLibItem referencing a subnode of the current item.

Parameters: subItemName – Access a JSON object’s subitem by its name.
Returns: An NxLibItem referring to the subitem.

inline const NxLibItem operator[](int subItemIndex) const¶

Creates an NxLibItem referencing a subnode of the current item.

Parameters: subItemIndex – Access an element of a JSON Array or a JSON Object subitem by its index.
Returns: An NxLibItem referring to the subitem.

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

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

Parameters

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

Returns

An integer indicating the result of the comparison.

Returns

-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<typename T> inline int compare(int *returnCode, T const &value) const¶

Compare the item’s value to a constant of type T.

Template Parameters

T – One of bool, int, double or std::string.

Parameters

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

Returns

An integer indicating the result of the comparison.

Returns

-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<typename T> inline int compare(T const &value) const¶

Compare the item’s value to a constant of type T.

Template Parameters

T – One of bool, int, double, std::string or char const*.

Parameters

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

Returns

An integer indicating the result of the comparison.

Returns

-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<typename T> inline void set(T const &value) const¶

Set the item’s value to a constant.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – The value to set.

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

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

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

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

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

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

inline void setNull(int *returnCode) const¶

Set the item’s value to Null.

Parameters: returnCode – The error code when accessing the item.

inline 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 a sub node is not existing or if it is protected. All matching nodes will be modified. If not a single matching node is found, the function returns NxLibItemTypeNotCompatible. In this case you probably tried to apply the JSON value to the wrong path. This mode 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 specifying false here, the function only succeeds if the structure of the given JSON value matches the structure of the entire subtree such that no sub node with protection “Locked” would have its type or value modified and no sub node with protection “StructureLocked” would have its type modified.

inline 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 a sub node is not existing or if it is protected. All matching nodes will be modified. If not a single matching node is found, the function returns NxLibItemTypeNotCompatible. In this case you probably tried to apply the JSON value to the wrong path. This mode 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 specifying false here, the function only succeeds if the structure of the given JSON value matches the structure of the entire subtree such that no sub node with protection “Locked” would have its type or value modified and no sub node with protection “StructureLocked” would have its type modified.

template<typename T> inline 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.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – T The value to set on the item.
Returns: The current item.

template<typename T> inline 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.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – The value to compare the item’s value with.
Returns: Boolean result of the comparison.

template<typename T> inline 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.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – The value to compare the item’s value with.
Returns: Boolean result of the comparison.

template<typename T> inline 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.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – The value to compare the item’s value with.
Returns: Boolean result of the comparison.

template<typename T> inline 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.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – The value to compare the item’s value with.
Returns: Boolean result of the comparison.

template<typename T> inline 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.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – The value to compare the item’s value with.
Returns: Boolean result of the comparison.

template<typename T> inline 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.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Parameters: value – The value to compare the item’s value with.
Returns: Boolean result of the comparison.

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

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

Template Parameters: T – One of bool, int, double or std::string.
Parameters: returnCode – The error code returned when accessing the item.
Returns: The item value in the type specified as template parameter.

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

Reads the item’s value as an std::string.

Parameters: returnCode – The error code returned when accessing the item.
Returns: The item value as an std::string.

inline int asInt(int *returnCode) const¶

Reads the item’s value as integer.

Parameters: returnCode – The error code returned when accessing the item.
Returns: The item value as int value.

inline double asDouble(int *returnCode) const¶

Reads the item’s value as integer.

Parameters: returnCode – The error code returned when accessing the item.
Returns: The item value as double value.

inline bool asBool(int *returnCode) const¶

Reads the item’s value as boolean.

Parameters: returnCode – The error code returned when accessing the item.
Returns: The item value as boolean value.

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

Try to read this tree item and return its 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.
allowScientificFormat – Specifies whether to allow scientific notation.

Returns

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

inline std::string asJsonMeta(int *returnCode, int numLevels = -1, bool prettyPrint = false, int numberPrecision = 18, bool allowScientificFormat = 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.

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.
allowScientificFormat – Specifies whether to allow scientific notation.

Returns

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

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

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

Parameters

prettyPrint – Specify true here to format the resulting string with line breaks and tabs.
numberPrecision – The floating point precision of the returned numbers.
allowScientificFormat – Specifies whether to allow scientific notation.

Returns

The item value as JSON string if the item exists.

inline std::string asJsonMeta(int numLevels = -1, bool prettyPrint = false, int numberPrecision = 18, bool allowScientificFormat = 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.

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.
allowScientificFormat – Specifies whether to allow scientific notation.

Returns

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

template<typename T> inline T as() const¶

Reads the item’s value in a specified format.

When using the specialization for char const* please refer to the C-API string type description for information about usage restrictions applying to the returned pointer.

Template Parameters: T – One of bool, int, double, std::string or char const*.
Returns: The item value in the specified format.

inline std::string asString() const¶

Reads the item’s value as an std::string.

Returns: The item value as an std::string.

inline int asInt() const¶

Reads the item’s value in an integer format.

Returns: The item value as int value.

inline double asDouble() const¶

Reads the item’s value in double format.

Returns: The item value as double value.

inline bool asBool() const¶

Reads the item’s value in bool format.

Returns: The item value as boolean value.

inline bool isNull(int *returnCode) const¶

Returns whether the item is of type Null or not.

Parameters: returnCode – The error code returned when accessing the item.
Returns: true if the item was of the corresponding JSON type, otherwise false

inline bool isString(int *returnCode) const¶

Returns whether the item is of type String or not.

Parameters: returnCode – The error code returned when accessing the item.
Returns: true if the item was of the corresponding JSON type, otherwise false

inline bool isNumber(int *returnCode) const¶

Returns whether the item is of type Number or not.

Parameters: returnCode – The error code returned when accessing the item.
Returns: true if the item was of the corresponding JSON type, otherwise false

inline bool isBool(int *returnCode) const¶

Returns whether the item is of type Bool or not.

Parameters: returnCode – The error code returned when accessing the item.
Returns: true if the item was of the corresponding JSON type, otherwise false

inline bool isArray(int *returnCode) const¶

Returns whether the item is of type Array or not.

Parameters: returnCode – The error code returned when accessing the item.
Returns: true if the item was of the corresponding JSON type, otherwise false

inline bool isObject(int *returnCode) const¶

Returns whether the item is of type Object or not.

Parameters: returnCode – The error code returned when accessing the item.
Returns: true if the item was of the corresponding JSON type, otherwise false

inline bool isNull() const¶

Returns whether the item is of type Null or not.

Returns

inline bool isString() const¶

Returns whether the item is of type String or not.

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

inline bool isNumber() const¶

Returns whether the item is of type Number or not.

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

inline bool isBool() const¶

Returns whether the item is of type Bool or not.

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

inline bool isArray() const¶

Returns whether the item is of type Array or not.

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

inline bool isObject() const¶

Returns whether the item is of type Object or not.

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

inline int type(int *returnCode) const¶

Retrieve the JSON type of this item.

Parameters: returnCode – The error code returned when accessing the item.
Returns: The item type constant. See nxLibGetType() for item types.

inline int type() const¶

Retrieve the JSON type of this item.

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

inline bool exists() const¶

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

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

inline bool exists(int *returnCode) const¶

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

Parameters: returnCode – The error code returned when accessing the item.
Returns: true, if the item exists, false otherwise.

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

inline void erase(int *returnCode) const¶

Deletes the item or subtree.

Parameters: returnCode – The error code returned when accessing the item.

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

Returns: The item’s name.

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

Retrieves the item’s name.

Parameters: returnCode – The error code returned when accessing the item.
Returns: The item’s name.

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

Returns: The number of subitems.

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

Parameters: returnCode – The error code returned when accessing the item.
Returns: The number of subitems.

inline 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 nullptr.

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 – The timestamp when the binary blob was generated. This pointer can be set to nullptr when the timestamp should not be retrieved. The returned value should only be relied upon if the function returns NxLibOperationSucceeded.

inline 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 nullptr.

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 – The timestamp when the binary blob was generated. This pointer can be set to nullptr when the timestamp should not be retrieved. The returned value should only be relied upon if the function returns NxLibOperationSucceeded.

inline 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 nullptr. If non-zero the value will be set to the number of bytes actually copied to the user’s buffer.
timestamp – The timestamp when the binary blob was generated. This pointer can be set to nullptr when the timestamp should not be retrieved. The returned value should only be relied upon if the function returns NxLibOperationSucceeded.

inline 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 nullptr. If non-zero the value will be set to the number of bytes actually copied to the user’s buffer.
timestamp – The timestamp when the binary blob was generated. This pointer can be set to nullptr when the timestamp should not be retrieved. The returned value should only be relied upon if the function returns NxLibOperationSucceeded.

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

inline 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> inline void getBinaryData(std::vector<T> &bufferVector, double *timestamp) const¶

Retrieves data of a Binary item.

Note

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

Template Parameters

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

Parameters

bufferVector – An std::vector that should be filled with the binary data.
timestamp – The timestamp when the binary blob was generated. This pointer can be set to nullptr when the timestamp should not be retrieved. The returned value should only be relied upon if the function returns NxLibOperationSucceeded.

template<typename T> inline 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> inline 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 – An std::vector from which the binary data should be copied.

template<typename T> inline 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> inline 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 – An 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> inline 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> inline 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> inline 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> inline 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> inline 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 – An std::vector that should be filled with the binary data.
timestamp – The timestamp when the binary blob was generated. This pointer can be set to nullptr when the timestamp should not be retrieved. The returned value should only be relied upon if the function returns NxLibOperationSucceeded.

inline void waitForChange() const¶: Waits for any change to the item.

inline void waitForChange(int *returnCode) const¶

Waits for any change to the item.

Parameters: returnCode – The error code returned when accessing the item.

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

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

inline void waitForValue(int value, bool waitForEqual) const¶