NxLibItem

See the nx_version.py section on the Examples page for a short demonstration of how this class can be used to access the NxLib tree.

class nxlib.item.NxLibItem(path=None)

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

Parameters

path (str, optional) – The item’s path. If None is given, the item will reference the root of the tree. Defaults to None.

__eq__(value)

The == comparison operator.

Parameters

value (int, str, bool or double) – The value to compare the item’s value against.

Returns

True if item’s value is eqaul to given value, False otherwise.

Return type

bool

__ge__(value)

The >= comparison operator.

Parameters

value (int, str, bool or double) – The value to compare the item’s value against.

Returns

True if item’s value is greater or eqaul to given value, False otherwise.

Return type

bool

__gt__(value)

The > comparison operator.

Parameters

value (int, str, bool or double) – The value to compare the item’s value against.

Returns

True if item’s value is greater than given value, False otherwise.

Return type

bool

__le__(value)

The <= comparison operator.

Parameters

value (int, str, bool or double) – The value to compare the item’s value against.

Returns

True if item’s value is less or eqaul to given value, False otherwise.

Return type

bool

__lshift__(other)

The << operator.

Sets a new value for the item, where other is either a JSON formatted string whose value is taken or another NxLibItem whose JSON string is taken.

Parameters

other (str or NxLibItem) – A JSON formatted string or another NxLibItem.

Raises

NxLibException – If other is neither a string nor an NxLibItem.

__lt__(value)

The < comparison operator.

Parameters

value (int, str, bool or double) – The value to compare the item’s value against.

Returns

True if item’s value is less than given value, False otherwise.

Return type

bool

__ne__(value)

The != comparison operator.

Parameters

value (int, str, bool or double) – The value to compare the item’s value against.

Returns

True if item’s value is not eqaul to given value, False otherwise.

Return type

bool

__setitem__(path, value)

The = operator. Set the item’s value at the given path to the given value.

Parameters

  • path (str) – The path of the item to be set.

  • value (int, str, bool or double) – The value to be set.

as_bool()

Returns the item value as bool.

Raises

NxLibException – With NxLib Error NxLibItemTypeNotCompatible if item is not a bool.

Returns

The item value.

Return type

bool

as_double()

Returns the item value as double.

Raises

NxLibException – With NxLib Error NxLibItemTypeNotCompatible if item is not a double.

Returns

The item value.

Return type

double

as_int()

Returns the item value as int.

Raises

NxLibException – With NxLib Error NxLibItemTypeNotCompatible if item is not an int.

Returns

The item value.

Return type

int

as_json(pretty_print=1, number_precision=18, scientific_number_format=0)

Retrieves an item value or an entire subtree in JSON representation.

Parameters

  • pretty_print (int, optional) – Specifies whether to use pretty printing. Int is treated as bool. Defaults to 1.

  • number_precision (int, optional) – The floating point precision of the returned numbers. Defaults to 2.

  • scientific_number_format (int, optional) – Specifies whether to use scientific notation for all numbers. Int is treated as bool. Defaults to 0.

Returns

A JSON string representing the item value or subtree.

Return type

JSON string

as_json_meta(num_levels=1, pretty_print=1, number_precision=18, scientific_number_format=0)

Retrieves an item value or an entire subtree in JSON representation including item metadata (protection, extended type, internal flags).

Parameters

  • num_levels (int, optional) – The depth of the returned subtree. Nodes in lower levels will be omitted. Defaults to 1.

  • pretty_print (int, optional) – Specifies whether to use pretty printing. Int is treated as bool. Defaults to 1.

  • number_precision (int, optional) – The floating point precision of the returned numbers. Defaults to 2.

  • scientific_number_format (int, optional) – Specifies whether to use scientific notation for all numbers. Int is treated as bool. Defaults to 0.

Returns

A JSON string representing the item value or subtree including each item’s metadata.

Return type

JSON string

as_string()

Returns the item value as string.

Raises

NxLibException – With NxLib Error NxLibItemTypeNotCompatible if item is not a string.

Returns

The item value.

Return type

str

count()

Retrieves the number of subitems of an Object or the number of elements of an item. In case of a Binary item its data size in bytes is returned.

Returns

The number of subitems.

Return type

int

erase()

Erases the item from the tree.

exists()
Returns

True if item exists, False otherwise.

Return type

bool

get_binary_data()

Retrieves data of a Binary item.

Returns

A byte buffer containing the binary data.

Return type

Object

get_binary_data_info()

Retrieves meta data of a Binary item.

Returns

tuple containing

  • width (int): The width of the array (consecutive elements in memory).

  • height (int): The height of the array (number of rows of width * channel_count elements)

  • channel_count (int): Number of channels for a single item.

  • bytes_per_element (int): Size in bytes of a single channel value of an item.

  • is_float (bool): Specifies whether the element data type is a floating point type.

  • timestamp (str): The current timestamp of the binary blob queried.

is_array()
Returns

True if item is an array, False otherwise.

Return type

bool

is_bool()
Returns

True if item is a bool, False otherwise.

Return type

bool

is_double()
Returns

True if item is a double, False otherwise.

Return type

bool

is_int()
Returns

True if item is an integer, False otherwise.

Return type

bool

is_null()
Returns

True if item is null, False otherwise.

Return type

bool

is_number()
Returns

True if item is a number (int or double), False otherwise.

Return type

bool

is_object()
Returns

True if item is an object, False otherwise.

Return type

bool

is_string()
Returns

True if item is a string, False otherwise.

Return type

bool

make_unique_item(item_name=None)

Creates a new item with a unique name.

Parameters

item_name (str, optional) – The parent path of the new item to create. Defaults to None.

Returns

The name of the generated item.

Return type

str

name()
Returns

The item name.

Return type

str

set_binary_data(buffer, buffer_size_or_width=0, height=0, channel_count=0, bytes_per_element=0, is_float=0)

Sets data of a Binary item with either an OpenCV matrix or another array object (e.g. Numpy array). In the first case, this function calls set_binary_data_from_cv(). In the second case it sets the data formatted if channel_count is non-zero and uses buffer_size_or_width as width, otherwise it sets the data unformatted and uses buffer_size_or_width as buffer size.

Parameters

  • buffer (Object) – Either a OpenCV matrix or another array object (e.g. a Numpy array).

  • buffer_size_or_width (int, optional) – Either the buffer size or the array width. Defaults to 0.

  • height (int, optional) – [description]. The array height to 0.

  • channel_count (int) – Number of channels for a single item. Defaults to 0.

  • bytes_per_element (int, optional) – Size in bytes of a single channel value of an item. Defaults to 0.

  • is_float (int, optional) – Specifies whether the element data type is a floating point type. Defaults to 0.

set_binary_data_from_cv(mat)

Sets data of a Binary item with an OpenCV matrix.

Parameters

mat (OpenCV matrix) – The matrix containing the data to set the item content to.

Raises

NxLibException – With NxLib Error NxLibItemTypeNotCompatible if mat is not an ndarray.

set_bool(value)

Sets an item to the given boolean value.

Parameters

value (bool) – Boolean value to be set.

set_double(value)

Sets an item to the given double value.

Parameters

value (double) – Float value to be set.

set_int(value)

Sets an item to the given int value.

Parameters

value (int) – Integer value to be set.

set_json(value, only_writable_nodes=False)

Sets an item to the given JSON value. The value might itself be an entire tree structure which will be placed under the specified node.

Parameters

  • value (JSON string) – The JSON string representing the value or subtree to write.

  • only_writable_nodes (bool, optional) – 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 as_json(). 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. Defaults to False.

set_null()

Sets an item to the value Null.

set_string(value)

Sets an item to the given string value.

Parameters

value (string) – String value to be set.

type()

Retrieves the item type of a tree item.

Returns

The type identifier of the basic type of the item. See constants for constants named NXLIB_ITEM_TYPE_*

Return type

int

wait_for_bool_value(value, wait_for_equal)

Wait for specific boolean value of the item. When the condition to wait for is already satisfied initially, the function returns immediately.

Parameters

  • value (bool) – The value to wait for.

  • wait_for_equal (bool) – If True, the function waits until the item has the specified type, otherwise it waits until the item has a different type than the one specified.

wait_for_change()

Wait for any change of the item, i.e. a change of value or item type.

wait_for_double_value(value, wait_for_equal)

Wait for specific double value the item. When the condition to wait for is already satisfied initially, the function returns immediately.

Parameters

  • value (double) – The value to wait for.

  • wait_for_equal (bool) – If True, the function waits until the item has the specified type, otherwise it waits until the item has a different type than the one specified.

wait_for_int_value(value, wait_for_equal)

Wait for specific integer value of the item. When the condition to wait for is already satisfied initially, the function returns immediately.

Parameters

  • value (int) – The value to wait for.

  • wait_for_equal (bool) – If True, the function waits until the item has the specified type, otherwise it waits until the item has a different type than the one specified.

wait_for_string_value(value, wait_for_equal)

Wait for specific string value of the item. When the condition to wait for is already satisfied initially, the function returns immediately.

Parameters

  • value (str) – The value to wait for.

  • wait_for_equal (bool) – If True, the function waits until the item has the specified type, otherwise it waits until the item has a different type than the one specified.

wait_for_type(awaited_type, wait_for_equal)

Wait for a type change of the item. When the condition to wait for is already satisfied initially, the function returns immediately.

Parameters

  • awaited_type (item_type) – The item type to wait for.

  • wait_for_equal (bool) – If True, the function waits until the item has the specified type, otherwise it waits until the item has a different type than the one specified.