Command Execution¶
Commands perform long-running operations, such as capturing images or computing point clouds. They are executed through the /Execute node:
The command parameters and name are written to the JSON tree below
/Execute.A separate thread inside of the NxLib executes the command.
The command’s result can be read from the JSON tree.
The commands reference lists all available commands with the JSON structure of their parameters and results.
Executing a Command¶
The C++, Python and .NET wrappers provide the NxLibCommand class that simplifies executing a command. It creates a temporary execution slot for each command and deletes it afterwards. When using the C API, commands have to be executed manually by writing directly to the tree.
The
parameters()method of theNxLibCommandclass returns anNxLibItemreferencing the Parameters node at path/Execute/<EXECUTION_SLOT>/Parametersand can be used to write the command’s parameters to the tree.The
execute()method executes the command synchronously.The result can be accessed through the
result()method, which returns anNxLibItemreferencing the Result node at path/Execute/<EXECUTION_SLOT>/Result.
The following example executes the GetPresets command, which returns a list of matching presets in its result. It is used here because it works without a connected camera, keeping the example self-contained. The structure of the command’s parameters and result value is specified in the command reference section.
// Create a temporary execution slot for running the GetPresets command.
NxLibCommand getPresets(cmdGetPresets);
// Fill in the parameters for the command.
getPresets.parameters()[itmTags][0] = "StereoMatching";
// Execute the command. The method blocks until execution has finished. When
// the command fails, this throws an exception.
getPresets.execute();
// The command result is written to the JSON tree. Access the preset data of
// the first matching preset.
NxLibItem presetData = getPresets.result()[itmPresets][0][itmData];
// Destruction of the NxLibCommand object deletes the execution slot and the
// command's results from the tree.
// Write the parameters of the command to the tree.
nxLibSetString(&error, "/Execute/Default/Parameters/Tags/\\0", "StereoMatching");
// Start execution by writing the name of the command to the Command node.
nxLibSetString(&error, "/Execute/Default/Command", cmdGetPresets);
// Wait for the command to finish.
nxLibWaitForType(&error, "/Execute/Default/Command", NxLibItemTypeNull, NXLIBTRUE);
NXLIBINT type = nxLibGetType(&error, "/Execute/Default/Result/ErrorSymbol");
if (type != NxLibItemTypeInvalid) {
// The command returned an error.
return;
}
// The command result is written to the JSON tree. Access the preset data of
// the first matching preset.
NXLIBSTR presetData = nxLibGetJson(
&error,
"/Execute/Default/Result/Presets/\\0/Data",
NXLIBFALSE,
6,
NXLIBFALSE
);
# Create a temporary execution slot for running the GetPresets command.
with NxLibCommand(CMD_GET_PRESETS) as get_presets:
# Fill in the parameters for the command.
get_presets.parameters()[ITM_TAGS][0] = "StereoMatching"
# Execute the command. The method blocks until execution has finished. When
# the command fails, this raises an exception.
get_presets.execute()
# The command result is written to the JSON tree. Access the preset data of
# the first matching preset.
preset_data = get_presets.result()[ITM_PRESETS][0][ITM_DATA]
# Leaving the with block deletes the execution slot and the command's results
# from the tree.
// Create a temporary execution slot for running the GetPresets command.
NxLibCommand getPresets = new NxLibCommand(NxLib.cmdGetPresets);
// Fill in the parameters for the command.
getPresets.Parameters()[NxLib.itmTags][0].Set("StereoMatching");
// Execute the command. The method blocks until execution has finished. When
// the command fails, this throws an exception.
getPresets.Execute();
// The command result is written to the JSON tree. Access the preset data
// of the first matching preset.
NxLibItem presetData = getPresets.Result()[NxLib.itmPresets][0][NxLib.itmData];
Asynchronous Execution¶
Since the NxLib executes commands in an internal thread, you can run them asynchronously.
NxLibCommand getPresets(cmdGetPresets);
getPresets.parameters()[itmTags][0] = "StereoMatching";
// Start execution of the command. The method returns immediately and
// does not wait for the command to finish.
getPresets.executeAsync();
// Do some other work while the command runs...
// Block until execution of the command finishes.
getPresets.wait();
// Check whether the command succeeded. Throws an exception when the
// command failed.
getPresets.assertSuccessful();
// Write the parameters of the command to the tree.
nxLibSetString(&error, "/Execute/Default/Parameters/Tags/\\0", "StereoMatching");
// Start execution by writing the name of the command to the Command node.
nxLibSetString(&error, "/Execute/Default/Command", cmdGetPresets);
// Do some other work while the command runs...
// Wait for the command to finish.
nxLibWaitForType(&error, "/Execute/Default/Command", NxLibItemTypeNull, NXLIBTRUE);
NXLIBINT type = nxLibGetType(&error, "/Execute/Default/Result/ErrorSymbol");
if (type != NxLibItemTypeInvalid) {
// The command returned an error.
return;
}
with NxLibCommand(CMD_GET_PRESETS) as get_presets:
get_presets.parameters()[ITM_TAGS][0] = "StereoMatching"
# Start execution of the command. The method returns immediately and
# does not wait for the command to finish.
get_presets.execute(wait=False)
# Do some other work while the command runs...
# Block until execution of the command finishes.
get_presets.wait()
# Check whether the command succeeded. Raises an exception when the
# command failed.
get_presets.assert_successful()
Handling Errors from Commands¶
When a command fails, errors are reported in the ErrorSymbol and ErrorText nodes.
The NxLibCommand classes in the language wrappers check these nodes automatically and throw an exception on failure. The exception object offers methods to access the error texts.
try {
// The command will fail, because the required parameter Cameras is missing.
NxLibCommand(cmdOpen).execute();
} catch (NxLibException& e) {
if (e.isCommandExecutionFailure()) {
// The command execution failed with an error. Get the error texts from its
// result node.
std::string errorSymbol = e.getCommandErrorSymbol();
std::string errorText = e.getCommandErrorText();
} else {
// There was an error while accessing the JSON tree to set up the command.
// This is handled like errors for any other tree access.
int errorCode = e.getErrorCode();
std::string errorText = e.getErrorText();
std::string itemPath = e.getItemPath();
}
}
// The command will fail, because the required parameter Cameras is missing.
nxLibSetString(&error, "/Execute/Default/Command", cmdOpen);
nxLibWaitForType(&error, "/Execute/Default/Command", NxLibItemTypeNull, NXLIBTRUE);
NXLIBINT type = nxLibGetType(&error, "/Execute/Default/Result/ErrorSymbol");
if (type != NxLibItemTypeInvalid) {
// The command execution failed with an error. Get the error texts from its result
// node.
NXLIBSTR errorSymbol =
nxLibGetString(&error, "/Execute/Default/Result/ErrorSymbol");
NXLIBSTR errorText = nxLibGetString(&error, "/Execute/Default/Result/ErrorText");
}
try:
# The command will fail, because the required parameter Cameras is missing.
with NxLibCommand(CMD_OPEN) as open_cmd:
open_cmd.execute()
except NxLibException as e:
if e.is_command_execution_failure():
# The command execution failed with an error. Get the error texts from its
# result node.
error_symbol = e.get_command_error_symbol()
error_text = e.get_command_error_text()
else:
# There was an error while accessing the JSON tree to set up the
# command. This is handled like errors for any other tree access.
error_code = e.get_error_code()
error_text = e.get_error_text()
item_path = e.get_item_path()
try {
// The command will fail, because the required parameter Cameras is missing.
new NxLibCommand(NxLib.cmdOpen).Execute();
} catch (NxLibException e) {
if (e.IsCommandExecutionFailure()) {
// The command execution failed with an error. Get the error texts from
// its result node.
string errorSymbol = e.GetCommandErrorSymbol();
string errorText = e.GetCommandErrorText();
} else {
// There was an error while accessing the JSON tree to set up the
// command. This is handled like errors for any other tree access.
int errorCode = e.GetErrorCode();
string errorText = e.GetErrorText();
string itemPath = e.GetItemPath();
}
}