First Program¶
This page walks you through your first program with the NxLib API: initializing the library, opening a camera, setting parameters and generating a 3D point cloud. It only shows the basic building blocks; refer to the Basic Operations and Command Execution tutorials for more details.
Initializing the NxLib¶
The NxLib should be initialized before use. This loads the library and starts the camera discovery. Although explicit initialization is optional (the library is also initialized automatically on the first access to the tree), it is useful to make sure that cameras can be detected in the network and be used immediately.
// Initialize the NxLib. This loads the library and starts the camera discovery.
nxLibInitialize();
// Use the API...
// Finalize the NxLib when the application shuts down.
nxLibFinalize();
In C, the error code is returned through a pointer argument instead of an exception.
// Initialize the NxLib. This loads the library and starts the camera
// discovery. The second parameter controls whether the initialization waits
// until the initial camera discovery has finished.
NXLIBERR error;
nxLibInitialize(&error, NXLIBTRUE);
if (error != NxLibOperationSucceeded) {
// Handle the error ...
return 1;
}
// Use the API...
// Finalize the NxLib when the application shuts down.
nxLibFinalize(&error);
# Initialize the NxLib. This loads the library and starts the camera discovery.
with NxLib():
# Use the API ...
# The NxLib is finalized automatically when leaving the with block.
pass
// Initialize the NxLib. This loads the library and starts the camera discovery.
NxLib.Initialize();
// Use the API...
// Finalize the NxLib when the application shuts down.
NxLib.Finalize();
Opening a Camera and Setting Parameters¶
A camera is opened with the Open command. After opening, its parameters are available under the path /Cameras/<SERIAL_NUMBER>/Parameters and can be modified directly.
Replace the <SERIAL_NUMBER> placeholder in the examples below with your camera’s serial number.
// References the JSON tree's root node at path "/".
NxLibItem root;
// References the camera's JSON node at path "/Cameras/<SERIAL_NUMBER>".
NxLibItem camera = root[itmCameras]["<SERIAL_NUMBER>"];
// Execute the Open command to open the camera. The constant cmdOpen specifies the
// command name; the variable name `open` does not matter.
NxLibCommand open(cmdOpen);
open.parameters()[itmCameras] = "<SERIAL_NUMBER>";
open.execute();
// The camera's parameter tree is now available under
// /Cameras/<SERIAL_NUMBER>/Parameters.
// Disable auto-exposure, set exposure to 5 ms.
camera[itmParameters][itmCapture][itmExposure][itmAutomatic] = false;
camera[itmParameters][itmCapture][itmExposure][itmValue] = 5.0;
// Grab images and generate 3D point clouds with the new settings...
// Close the camera again.
NxLibCommand close(cmdClose);
close.parameters()[itmCameras] = "<SERIAL_NUMBER>";
close.execute();
// Set the parameters for the Open command and write the command name to
// /Execute/Command. A separate thread executes the command and clears the
// Command node (sets it to null) when it has finished.
nxLibSetString(&error, "/Execute/Parameters/Cameras", "<SERIAL_NUMBER>");
nxLibSetString(&error, "/Execute/Command", cmdOpen);
// Wait until the command has finished, i.e. the Command node is null again.
nxLibWaitForType(&error, "/Execute/Command", NxLibItemTypeNull, NXLIBTRUE);
// Check whether the command succeeded by looking for the ErrorSymbol node.
NXLIBINT type = nxLibGetType(&error, "/Execute/Result/ErrorSymbol");
if (type != NxLibItemTypeInvalid) {
printf(
"Opening the camera failed: %s\n",
nxLibGetString(&error, "/Execute/Result/ErrorText")
);
return 1;
}
// The camera's parameter tree is now available under
// /Cameras/<SERIAL_NUMBER>/Parameters.
// Disable auto-exposure, set exposure to 5 ms.
nxLibSetBool(
&error,
"/Cameras/<SERIAL_NUMBER>/Parameters/Capture/Exposure/Automatic",
NXLIBFALSE
);
nxLibSetDouble(
&error,
"/Cameras/<SERIAL_NUMBER>/Parameters/Capture/Exposure/Value",
5.0
);
// Grab images and generate 3D point clouds with the new settings ...
// Close the camera again.
nxLibSetString(&error, "/Execute/Parameters/Cameras", "<SERIAL_NUMBER>");
nxLibSetString(&error, "/Execute/Command", cmdClose);
nxLibWaitForType(&error, "/Execute/Command", NxLibItemTypeNull, NXLIBTRUE);
# The Camera context manager executes the Open command on enter and Close on exit.
with Camera.from_serial("<SERIAL_NUMBER>") as camera:
# Disable auto-exposure, set exposure to 5 ms.
camera[ITM_PARAMETERS][ITM_CAPTURE][ITM_EXPOSURE][ITM_AUTOMATIC] = False
camera[ITM_PARAMETERS][ITM_CAPTURE][ITM_EXPOSURE][ITM_VALUE] = 5.0
# Grab images and generate 3D point clouds with the new settings...
pass
// Execute the Open command to open the camera. The constant NxLib.cmdOpen
// specifies the command name.
NxLibCommand open = new NxLibCommand(NxLib.cmdOpen);
open.Parameters()[NxLib.itmCameras].Set("<SERIAL_NUMBER>");
open.Execute();
// The camera's parameter tree is now available under /Cameras/<SERIAL_NUMBER>/Parameters.
// Disable auto-exposure, set exposure to 5 ms.
NxLibItem camera = new NxLibItem()[NxLib.itmCameras]["<SERIAL_NUMBER>"];
camera[NxLib.itmParameters][NxLib.itmCapture][NxLib.itmExposure][NxLib.itmAutomatic].Set(false);
camera[NxLib.itmParameters][NxLib.itmCapture][NxLib.itmExposure][NxLib.itmValue].Set(5.0);
// Grab images and generate 3D point clouds with the new settings...
// Close the camera again.
NxLibCommand close = new NxLibCommand(NxLib.cmdClose);
close.Parameters()[NxLib.itmCameras].Set("<SERIAL_NUMBER>");
close.Execute();
Capturing Images and Computing Point Clouds¶
The typical workflow for acquiring 3D data consists of four commands: Open, Capture, ComputeDisparityMap and ComputePointMap. After the last command, the camera’s PointMap node holds metric x, y and z coordinates in millimeters for each image pixel.
// Open the camera.
NxLibCommand open(cmdOpen);
open.parameters()[itmCameras] = "<SERIAL_NUMBER>";
open.execute();
// Capture an image pair.
NxLibCommand(cmdCapture).execute();
// Compute the disparity map from the image pair. This is the computationally
// most demanding part; all following steps are based on it.
NxLibCommand(cmdComputeDisparityMap).execute();
// Convert the disparity values into metric x, y and z coordinates.
NxLibCommand(cmdComputePointMap).execute();
// The point map is now available in the camera's tree as binary data: three
// float values (x, y and z in millimeters) for each image pixel.
NxLibItem camera = NxLibItem()[itmCameras]["<SERIAL_NUMBER>"];
std::vector<float> pointMap;
camera[itmImages][itmPointMap].getBinaryData(pointMap, nullptr);
// pointMap now contains x, y and z coordinates for each image pixel.
// Open the camera.
nxLibSetString(&error, "/Execute/Parameters/Cameras", "<SERIAL_NUMBER>");
nxLibSetString(&error, "/Execute/Command", cmdOpen);
nxLibWaitForType(&error, "/Execute/Command", NxLibItemTypeNull, NXLIBTRUE);
// Capture an image pair.
nxLibSetString(&error, "/Execute/Command", cmdCapture);
nxLibWaitForType(&error, "/Execute/Command", NxLibItemTypeNull, NXLIBTRUE);
// Compute the disparity map from the image pair. This is the computationally
// most demanding part; all following steps are based on it.
nxLibSetString(&error, "/Execute/Command", cmdComputeDisparityMap);
nxLibWaitForType(&error, "/Execute/Command", NxLibItemTypeNull, NXLIBTRUE);
// Convert the disparity values into metric x, y and z coordinates.
nxLibSetString(&error, "/Execute/Command", cmdComputePointMap);
nxLibWaitForType(&error, "/Execute/Command", NxLibItemTypeNull, NXLIBTRUE);
// The point map is now available in the camera's tree as binary data: three
// float values (x, y and z in millimeters) for each image pixel.
NXLIBINT width, height, channels, bytesPerElement;
nxLibGetBinaryInfo(
&error,
"/Cameras/<SERIAL_NUMBER>/Images/PointMap",
&width,
&height,
&channels,
&bytesPerElement,
NULL,
NULL
);
float* pointMap = malloc(width * height * channels * sizeof(float));
nxLibGetBinary(
&error,
"/Cameras/<SERIAL_NUMBER>/Images/PointMap",
pointMap,
width * height * channels * sizeof(float),
NULL,
NULL
);
// pointMap now contains x, y and z coordinates for each image pixel.
free(pointMap);
# The Camera context manager executes the Open command on enter and Close on
# exit. Capture, ComputeDisparityMap and ComputePointMap are also executed
# through NxLibCommand under the hood.
with Camera.from_serial("<SERIAL_NUMBER>") as camera:
# Capture an image pair.
camera.capture()
# Compute the disparity map from the image pair. This is the computationally
# most demanding part; all following steps are based on it.
camera.compute_disparity_map()
# Convert the disparity values into metric x, y and z coordinates.
camera.compute_point_map()
# The point map is now available in the camera's tree as binary data: three
# float values (x, y and z in millimeters) for each image pixel.
point_map_data = camera.get_point_map()
# point_map_data now contains x, y and z coordinates for each image pixel
# as a numpy array.
// Open the camera.
NxLibCommand open = new NxLibCommand(NxLib.cmdOpen);
open.Parameters()[NxLib.itmCameras].Set("<SERIAL_NUMBER>");
open.Execute();
// Capture an image pair.
NxLibCommand capture = new NxLibCommand(NxLib.cmdCapture);
capture.Execute();
// Compute the disparity map from the image pair. This is the
// computationally most demanding part; all following steps are based on it.
NxLibCommand computeDisparityMap = new NxLibCommand(NxLib.cmdComputeDisparityMap);
computeDisparityMap.Execute();
// Convert the disparity values into metric x, y and z coordinates.
NxLibCommand computePointMap = new NxLibCommand(NxLib.cmdComputePointMap);
computePointMap.Execute();
// The point map is now available in the camera's tree as binary data:
// three float values (x, y and z in millimeters) for each image pixel.
NxLibItem pointMap = new NxLibItem()[NxLib.itmCameras]["<SERIAL_NUMBER>"][NxLib.itmImages][NxLib.itmPointMap];
pointMap.GetBinaryDataFloat(out float[] pointMapData, out int numBytesCopied, out double timestamp);
// pointMapData now contains x, y and z coordinates for each image pixel.
You can find more information on how to control cameras in the guides section.