Ensenso::NxLib¶

class Ensenso.NxLib¶

This class wraps the functions provided by the NxLibImport class.

C# strings that are taken by or returned from these functions are UTF-8 encoded.

Public Types

enum DebugLevel¶

Specifies how much debug information should be logged. The higher, the more information.

Values:

nxdInherit¶: Inherits the debug level of the parent block. When the block does not have a parent, this will correspond to the debug level nxdInfo.

nxdInfo¶: Outputs only basic information like command executions.

nxdDebug¶: Outputs more information about substeps of commands or helper threads.

nxdTrace¶: Full logging including all API calls and parameter values.

Public Static Functions

static void Initialize (out int result, bool waitForInitialCameraRefresh)¶

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.

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().

All initialization methods will eventually fully populate the camera list, also including full link information. The initialization methods only allow the user to access the tree at earlier points in time if his application does not need guarantees on the completeness of the listing. NxView for example uses the fastest “direct access” initialization to present the user with a preliminary camera listing as fast as possible, and then the listing is completed while the user already has time to choose from existing cached cameras.

Throws NxLibDllNotFoundException.

Param result: The return code of the operation.
Param waitForInitialCameraRefresh: Whether to wait for all cameras to be enumerated or to be returned immediately.

static void Finalize (out int result)¶

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.

After closing the library with Finalize(), it will no longer be automatically initialized when you attempt to access the tree. You can call Initialize to explicitly initialize the library again.

Pay attention to not confuse this function with C# Object.Finalize method.

Param result: The return code of the operation.

static void OpenTcpPort (int portNumber, out int openedPort)¶

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

Throws NxLibException.

Param portNumber: The port to be opened. Specify 0 here to automatically choose a port in the range 24000 to 25000.
Param openedPort: Number of the opened port.

static void OpenTcpPort (out int result, int portNumber, out int openedPort)

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

Param result: The return code of the operation.
Param portNumber: The port to be opened. Specify 0 here to automatically choose a port in the range 24000 to 25000.
Param openedPort: Number of the opened port.

static void CloseTcpPort ()¶

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

Throws NxLibException.

static void CloseTcpPort (out int result)

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

Param result: The return code of the operation.

static void Erase (out int result, string itemPath)¶

Erases an item or subtree.

Param result: The return code of the operation.
Param itemPath: The path of the item or subtree to erase.

static void SetNull (out int result, string itemPath)¶

Sets an item to the value Null.

Param result: The return code of the operation.
Param itemPath: The path of the item to set to the value Null. When specifying a subtree, the entire subtree will be replaced by a single Null value.

static void SetJson (out int result, string itemPath, string value, bool onlyWriteableNodes)¶

Sets an item to the given JSON value.

The value itself might be an entire tree structure which will be placed under the specified node.

Param result: The return code of the operation.
Param itemPath: The path of the item to set. When specifying a subtree, the entire subtree will be replaced by the specified value.
Param value: The JSON string representing the value or subtree to write.
Param onlyWriteableNodes: 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 GetJson(). 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 NxLib.ItemTypeNotCompatible. 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.

static void SetInt (out int result, string itemPath, int value)¶

Sets an item to the specified integer value.

The resulting item will be of type Number.

Param result: The return code of the operation.
Param itemPath: The path of the item to set. When specifying a subtree, the entire subtree will be replaced by the specified value.
Param value: The value to set.

static void SetDouble (out int result, string itemPath, double value)¶

Sets an item to the specified floating point value.

The resulting item will be of type Number.

Param result: The return code of the operation.
Param itemPath: The path of the item to set. When specifying a subtree, the entire subtree will be replaced by the specified value.
Param value: The value to set.

static void SetBool (out int result, string itemPath, bool value)¶

Sets an item to the specified boolean value.

The resulting item will be of type Boolean.

Param result: The return code of the operation.
Param itemPath: The path of the item to set. When specifying a subtree, the entire subtree will be replaced by the specified value.
Param value: The value to set.

static void SetString (out int result, string itemPath, string value)¶

Sets an item to the specified string.

The resulting item will be of type String.

Param result: The return code of the operation.
Param itemPath: The path of the item to set. When specifying a subtree, the entire subtree will be replaced by the specified value.
Param value: The value to set.

static void SetBinary<T> (out int result, string itemPath, T[] buffer)¶

Sets data of a Binary item and updates the timestamp of the node to the current UTC time.

The data format must be identical to the current format of the binary node. The current format can be queried using GetBinaryInfo().

Tparam T: Type of the Binary item.
Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param buffer: A memory buffer, where the new item content should be read from.

static void SetBinaryFormatted<T> (out int result, string itemPath, T[] buffer, int width, int height, int channelCount, int bytesPerElement, bool isFloat)¶

Sets data of a Binary item and updates the timestamp of the node to the current UTC time.

The current data format of the binary node can be changed with this function.

Tparam T: Type of the Binary item.
Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param buffer: A memory buffer, where the new item content should be read from.
Param width: The width of the array (consecutive elements in memory).
Param height: The height of the array (number of rows of width * channelCount elements).
Param channelCount: Number of channels for a single item.
Param bytesPerElement: Size in bytes of a single channel value of an item.
Param isFloat: Specifies whether the element data type is a floating point type.

static string GetJson (out int result, string itemPath, bool prettyPrint, int numberPrecision, bool allowScientificFormat)¶

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

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param prettyPrint: Whether to format the JSON string with line breaks and tabs.
Param numberPrecision: The accuracy of numbers.
Param allowScientificFormat: Whether to allow scientific notation.
Return: A string formatted as Json.

static string GetJsonMeta (out int result, string itemPath, int numLevels, bool prettyPrint, int numberPrecision, bool allowScientificFormat)¶

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.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param numLevels: The depth of the returned subtree. Nodes in lower levels will be omitted.
Param prettyPrint: Whether to format the JSON string with line breaks and tabs.
Param numberPrecision: The accuracy of numbers.
Param allowScientificFormat: Whether to allow scientific notation.
Return: A string formatted as Json with meta information.

static int GetInt (out int result, string itemPath)¶

Retrieves the value of an integer item.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Return: The integer value of the item.

static double GetDouble (out int result, string itemPath)¶

Retrieves the value of a double item.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Return: The double value of the item.

static bool GetBool (out int result, string itemPath)¶

Retrieves the value of a boolean item.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Return: The boolean value of the item.

static string GetString (out int result, string itemPath)¶

Retrieves the value of a string item.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Return: The string value of the item.

static void GetBinary<T> (out int result, string itemPath, out T[] destinationBuffer, out int numBytesCopied, out double timestamp)¶

Retrieves data of a binary item.

Tparam T: Type of the items in the destinationBuffer.
Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param destinationBuffer: A memory buffer, where the item content should be copied.
Param numBytesCopied: The out parameter will be set to the number of bytes actually copied to the user’s buffer. The value can be 0.
Param timestamp: The timestamp of the binary blob copied to the buffer.

static void GetBinaryByte (out int result, string itemPath, out byte[] destinationBuffer, out int bytesCopied, out double timestamp)¶

Retrieves data of a binary item.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param destinationBuffer: A byte array, where the item content should be copied.
Param bytesCopied: The out parameter will be set to the number of bytes actually copied to the user’s buffer. The value can be 0.
Param timestamp: The timestamp of the binary blob copied to the buffer.

static void GetBinaryShort (out int result, string itemPath, out short[] destinationBuffer, out int bytesCopied, out double timestamp)¶

Retrieves data of a binary item.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param destinationBuffer: A short array, where the item content should be copied.
Param bytesCopied: The out parameter will be set to the number of bytes actually copied to the user’s buffer. The value can be 0.
Param timestamp: The timestamp of the binary blob copied to the buffer.

static void GetBinaryFloat (out int result, string itemPath, out float[] destinationBuffer, out int bytesCopied, out double timestamp)¶

Retrieves data of a binary item.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param destinationBuffer: A float array, where the item content should be copied.
Param bytesCopied: The out parameter will be set to the number of bytes actually copied to the user’s buffer. The value can be 0.
Param timestamp: The timestamp of the binary blob copied to the buffer.

static int GetType (out int result, string itemPath)¶

Retrieves the item type of a tree item.

Param result

The return code of the operation.

Param itemPath

The path of the item to access.

Return

The enum value of the item type.

NxLib.ItemTypeInvalid An error occurred, refer to the result parameter for further information.
NxLib.ItemTypeNull The item is of type Null.
NxLib.ItemTypeNumber The item is a number. This can be an integer or floating point value.
NxLib.ItemTypeString The item is a string.
NxLib.ItemTypeBool The item is a boolean value.
NxLib.ItemTypeArray The item is an array. The number of array elements can be queried with GetCount(). The array can be empty.
NxLib.ItemTypeObject The item is an object. The number of children can be queried with GetCount(). The object can be empty.

static int GetCount (out int result, string itemPath)¶

Retrieves the number of subitems of an object or the number of elements of an array item.

In case of a binary item its data size in bytes is returned.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Return: The amount of subitems.

static string GetName (out int result, string itemPath)¶

Retrieves string of an item.

This function is intended to be used to enumerate subitems of an Object. The subitems can be accessed by the index notation, then the corresponding names can be queried with GetName().

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Return: The name of the item.

static void GetBinaryInfo (out int result, string itemPath, out int width, out int height, out int channelCount, out int bytesPerElement, out bool isFloat, out double timestamp)¶

Retrieves meta data of a binary item.

The entire size of the binary blob is width * height * channelCount * bytesPerElement. A 24bit RGB image of VGA resolution would have width == 640, height == 480, channelCount == 3, bytesPerElement == 1 and isFloat == NXLIBFALSE.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.
Param width: The width of the array (consecutive elements in memory).
Param height: The height of the array (number of rows of width*channelCount elements).
Param channelCount: Number of channels for a single item.
Param bytesPerElement: Size in bytes of a single value of an item.
Param isFloat: Whether the element data type is a floating point type.
Param timestamp: The current timestamp of the binary blob queried.

static void WaitForChange (out int result, string itemPath)¶

Waits for any change to the specified item, i.e. a change of value or item type.

Param result: The return code of the operation.
Param itemPath: The path of the item to access.

static void WaitForType (out int result, string itemPath, int itemType, bool waitForEqual)¶

Waits for a type change to the specified item.