NxLib API

This module wraps the C-functions provided by the NxLib library (shared library on Linux or DLL on Windows) with ctypes. All functions provided by the API are further wrapped by the following classes:

• nxlib.item.NxLibItem

• nxlib.exception.NxLibException

• nxlib.context.NxLib

• nxlib.context.NxLibRemote

• nxlib.log.NxLog

Note

If you only use the above classes you do not need to call any function from nxlib.api yourself.

nxlib.api.close_tcp_port()

Disconnects all connected NxLibRemote instances and closes the opened TCP port, if any.

Raises

nxlib.NxLibError – If the currently loaded NxLib library is a remote NxLib.

nxlib.api.connect(hostname, port)

Remote NxLib specific function that opens a connection to the remote NxLib with the given hostname and port.

Parameters

• hostname (str) – The hostname of the remote NxLib to connect to.

• port (int) – The port of the remote NxLib to connect to.

Raises

nxlib.NxLibError – If the currently loaded NxLib library is not a remote NxLib.

nxlib.api.disconnect()

Remote NxLib specific function that closes the connection to the remote NxLib.

Raises

nxlib.NxLibError – If the currently loaded NxLib library is not a remote NxLib.

nxlib.api.finalize()

Explicitly closes the library, terminating all internal threads and freeing allocated memory. It is important to explicitly call finalize() before unloading the NxLib library when your process is not terminating afterwards, because Windows doesn’t allow to cleanly exit threads during DLL unload.

Raises

nxlib.NxLibError – If the currently loaded NxLib library is a remote NxLib.

nxlib.api.get_debug_buffer(destination_buffer, buffer_size, clear_read)

Copy n=buffer_size bytes of the NxLib debug buffer into the given destination buffer and clear the debug buffer if desired.

Parameters

• destination_buffer (Object) – The byte buffer the debug buffer’s content gets written to.

• buffer_size (int) – The buffer size.

• clear_read (bool) – If True, the buffer will be cleared after reading.

Raises

NxLibException – If the wrapped NxLib function returned with an error.

Returns

tuple containing

• bytes_read (int): The number of bytes read from the debug buffer.

• bytes_remaining (int): The number of bytes remaining in the debug buffer.

• overflow (bool): True if the debug buffer overflowed before it was read. False otherwise.

nxlib.api.initialize(wait_for_initial_camera_refresh=True, path=None)

Explicitly initializes the library and starts to enumerate the connected cameras. When omitting this function call, the library is initialized on first access to the tree.

Note

After finalize() was called, the library will no longer be initialized automatically when you access the tree. You can reinitialize it by explicitly calling initialize().

Parameters

wait_for_initial_camera_refresh (bool, optional) – Specifies whether to wait for all cameras to be enumerated or to return immediately. Defaults to True.

Raises

nxlib.NxLibError – If the currently loaded NxLib library is a remote NxLib.

nxlib.api.is_current_lib_remote()

Checks whether the currently loaded NxLib library is a remote NxLib.

Returns

True if the currently loaded NxLib library is a remote NxLib. False otherwise.

Return type

bool

nxlib.api.load_lib(path=None)

Loads the default or given NxLib.

Parameters

path (str, optional) – Filepath to the shared library. Defaults to None.

Raises

nxlib.NxLibError – If the shared library could not be loaded.

nxlib.api.load_remote_lib(path=None)

Loads the default or given remote NxLib.

Parameters

path (str, optional) – Filepath to the shared remote library. Defaults to None.

Raises

nxlib.NxLibError – If the shared remote library could not be loaded.

nxlib.api.open_tcp_port(port_number=0, opened_port=0)

Opens a TCP port on which a remote NxLib can connect to the current NxLib instance.

Parameters

• port_number (int, optional) – The port to be opened. Specify 0 here to automatically choose a port in the range 24000 to 25000. Defaults to 0.

• opened_port (int, optional) – The variable receiving the opened port number. Defaults to 0.

Raises

nxlib.NxLibError – If the currently loaded NxLib library is a remote NxLib.

nxlib.api.translate_error_code(error_code)

Returns the corresponding error text for the given NxLib error code.

Parameters

error_code (int) – The error code.

Returns

The corresponding error text.

Return type

str