C++ Programmer's Guide#

This section provides information specific to Basler Stereo ace cameras. It doesn't aim to give a comprehensive overview of the pylon C++ API.

If you are new to pylon, Basler recommends making yourself familiar with the pylon C++ API first by reading the Getting Started section of the pylon C++ Programmer's Guide.

C++ Programming Samples#

Prerequisites for Building the Samples#

• Optional: OpenCV library
• Optional: Point Cloud Library (PCL)

Building the Samples#

mkdir -p $HOME/Stereo_ace_samples
cp -r /opt/pylon/share/pylon/Samples/Stereo_ace/C++ $HOME/Stereo_ace_samples
cd $HOME/Stereo_ace_samples
mkdir build
cd build
cmake ..
cmake --build .

mkdir -p $HOME/Stereo_ace_samples
cp -r /opt/pylon/share/pylon/Samples/Stereo_ace/C++ $HOME/Stereo_ace_samples
cd $HOME/Stereo_ace_samples
mkdir build
cd build
cmake ..
cmake --build .

Check the Troubleshooting topic if you experience problems building and running the samples.

Installing the OpenCV Library#

cmake -DOpenCV_DIR="C:\Program Files\OpenCV\build\x64\vc16\lib" ..

sudo apt-get -y install libopencv-dev

cmake -DOPENCV_DIR=$HOME/OpenCV/lib ..

cmake -DOPENCV_DIR=$HOME/OpenCV/lib ..

Installing the Point Cloud Library#

  "configurations": [
    {
      "name": "x64-Debug",
      ...
      "cmakeCommandArgs": "-DPCL_DIR=\"C:\\Program Files\\PCL 1.9.1\\cmake\"",
      ...
    },
    {
      "name": "x64-Release",
      ...
      "cmakeCommandArgs": "-DPCL_DIR=\"C:\\Program Files\\PCL 1.9.1\\cmake\"",
      ...
    }
  ]

cmake -DPCL_DIR="C:\Program Files\PCL 1.14.0\cmake" ..

sudo apt-get -y install libpcl-dev

cmake -DPCL_DIR=$HOME/PCL/cmake ..

cmake -DPCL_DIR=$HOME/PCL/cmake ..

List of Samples#

• FirstSample: Introduction to operating a Stereo ace camera and retrieving 3D data.
• ParametrizeCamera: Illustrates how to access camera parameters.
• DeviceRemovalHandling: Illustrates the handling of device removal.
• OpenDeviceByIpAddress: Demonstrates how to open a Stereo ace camera by one of its IP addresses.
• GrabDepthMap: Illustrates how to grab and interpret depth maps.
• SavePointCloud: Illustrates how to save point clouds to file.
• ShowPointcloud: Illustrates how to visualize the point clouds grabbed with a Stereo ace camera.
• TriggerLowLatency: Demonstrates how latency can be reduced by binning on the camera instead of on the host.
• LeftAndRightIntensity: Demonstrates how to grab left and right intensity image from a Stereo ace camera.

Refer to the sample code in the C++ samples directory for more details.

How to Build Applications#

Using CMake#

The pylon Supplementary Package for Stereo ace includes a Findpylon.cmake module that is used to determine the installation location of pylon and the pylon Supplementary Package for Stereo ace. The find module exports the pylon::pylon CMake target. Pass this target as argument to target_link_libraries, and CMake will take care of setting the include path, library path, etc.

A basic CMakeLists.txt CMake file could look like this:

project (hello)

# Locate the CMake find module for pylon ...
# for Unix systems. All other OS PYLON_ROOT will be empty.
list(APPEND CMAKE_PREFIX_PATH $ENV{PYLON_ROOT})
# for Windows systems. All other OS PYLON_DEV_DIR will be empty.
list(APPEND CMAKE_PREFIX_PATH $ENV{PYLON_DEV_DIR})

find_package(pylon 10.0 REQUIRED)

add_executable(hello helloworld.cpp)
target_link_libraries(hello pylon::pylon)

project (hello)

# Locate the CMake find module for pylon ...
# for Unix system. All other OS PYLON_ROOT will be empty
list(APPEND CMAKE_PREFIX_PATH $ENV{PYLON_ROOT})
# for Windows system. All other OS PYLON_DEV_DIR will be empty
list(APPEND CMAKE_PREFIX_PATH $ENV{PYLON_DEV_DIR})

find_package(pylon 10.0 REQUIRED)

add_executable(hello helloworld.cpp)
target_link_libraries(hello pylon::pylon)

project (hello)

# Locate the CMake find module for pylon ...
# for Unix system. All other OS PYLON_ROOT will be empty
list(APPEND CMAKE_PREFIX_PATH $ENV{PYLON_ROOT})
# for Windows system. All other OS PYLON_DEV_DIR will be empty
list(APPEND CMAKE_PREFIX_PATH $ENV{PYLON_DEV_DIR})

find_package(pylon 10.0 REQUIRED)

add_executable(hello helloworld.cpp)
target_link_libraries(hello pylon::pylon)

Instant Camera Class for Stereo ace#

pylon provides different types of classes for accessing camera devices. Apart from low-level IPylon devices, there are the so-called Instant Camera classes that provide a convenient high-level API for cameras.

The Pylon::CInstantCamera class provides generic access to all Basler cameras.

For Stereo ace cameras, the pylon Supplementary Package for Stereo ace includes the Pylon::CStereoAceInstantCamera class. Basler recommends using this class for Basler Stereo ace cameras as it provides convenient parameter access and Stereo ace-specific features.

If you use the CBaslerUniversalInstantCamera class instead of the CStereoAceInstantCamera class, you can still set and get all camera parameters provided by the Stereo ace camera. If there is no accessor object provided by the CBaslerUniversalInstantCamera class, use the so-called generic parameter access for accessing parameters by their names as explained in the Generic Parameter Access section of the pylon C++ Programmer's Guide.

示例：

using namespace Pylon;
GenApi::INodeMap& nodemap = camera.GetNodeMap();
CIntegerParameter depthSeg(nodemap, "BslDepthSeg" );
std::cout << "Segmentation: " << depthSeg.GetValue() << std::endl;

Opening and Accessing Stereo ace Cameras#

It takes three steps to create and open a Stereo ace camera object:

1. Create a camera object for the camera you want to access.
   Usually, you should create an instance of the Pylon::CStereoAceInstantCamera class.
2. Register a Stereo ace-specific configuration event handler if required (see the DeviceRemovalHandling.cpp sample for details).
3. Call the Open() method to establish a connection to the camera device.

The following example illustrates these steps:

#include <pylon/PylonIncludes.h>
#include <pylon/StereoAceInstantCamera.h>
using namespace Pylon;

// ...

// Before using any pylon methods, the pylon runtime must be initialized.
PylonInitialize();

try {
    // 1: Create a camera object for the first available Stereo ace camera.
    CUniversalInstantInterface instantInterface(
        CInterfaceInfo().SetDeviceClass(Pylon::BaslerGenTlStaDeviceClass));
    CStereoAceInstantCamera camera(instantInterface.CreateFirstDevice());

    // 2. Register a default configuration if available (see samples).
    // camera.RegisterConfiguration(...);

    // 3. Open the camera, i.e., establish a connection to the camera device.
    camera.Open();

    // Use the camera.
    std::cout << "Connected to camera "
        << camera.GetDeviceInfo().GetFriendlyName() << std::endl;
    // ...

    // Close the connection.
    camera.Close();
} catch (const GenICam::GenericException& e) {
    std::cerr << "Exception occurred: " << std::endl
        << e.GetDescription() << std::endl;
}

// Releases all pylon resources.
PylonTerminate();

In case of errors, exceptions inheriting from GenICam::GenericException are thrown.

Typical error conditions:

• No Stereo ace camera found: The CreateFirstDevice() function throws an exception.
• Camera can't be opened, e.g., because it is already opened by another application: The Open() method throws an exception.

The following subsections provide more detailed information about how to create and open a camera object.

Creating a Camera Object for the First Available Stereo ace Camera#

Use the Pylon::CTlFactory::CreateFirstDevice() method to create a camera object for the first available Stereo ace camera. Always specify the pylon device class identifier for Stereo ace cameras to prevent CreateFirstDevice() from creating a camera object for a different type of camera:

CUniversalInstantInterface instantInterface(
    CInterfaceInfo().SetDeviceClass(Pylon::BaslerGenTlStaDeviceClass));
CStereoAceInstantCamera camera(instantInterface.CreateFirstDevice());

If no Stereo ace camera is found, check the camera's and your network adapter's IP configuration settings. Refer to the Network Configuration topic in the Basler Product Documentation for more information about setting up your network.

Creating a Camera Object for a Specific Stereo ace Camera#

If you want to open a specific Stereo ace camera, you can specify other properties in addition to the device class.

To open a specific Stereo ace camera by its serial number, use the following lines:

CUniversalInstantInterface instantInterface(
    CInterfaceInfo().SetDeviceClass(Pylon::BaslerGenTlStaDeviceClass));
CStereoAceInstantCamera camera(instantInterface.CreateFirstDevice(
    CDeviceInfo().SetSerialNumber("40410842")));

To open a Stereo ace camera by user-defined name, use the following lines:

CUniversalInstantInterface instantInterface(
    CInterfaceInfo().SetDeviceClass(Pylon::BaslerGenTlStaDeviceClass));
CStereoAceInstantCamera camera(instantInterface.CreateFirstDevice(
    CDeviceInfo().SetUserDefinedName("MyCamera")));

camera.DeviceUserID.SetValue("MyStereoAce");

If the desired Stereo ace camera isn't found, check whether you're using the right values for the properties and check your camera's and your network adapter's IP configuration settings. Refer to the Network Configuration topic in the Basler Product Documentation for more information about setting up your network.

Enumerating Stereo ace Cameras#

The following code snippet illustrates how to retrieve a list of all connected Stereo ace cameras. For each element of the list, the camera is opened and some camera parameter values are printed.

#include <pylon/PylonIncludes.h>
#include <pylon/StereoAceInstantCamera.h>
#include <ostream>
using namespace Pylon;

// ....

// Before using any pylon methods, the pylon runtime must be initialized.
PylonInitialize();

// ....

// Enumerate all Stereo ace cameras.
CTlFactory& TlFactory = CTlFactory::GetInstance();
DeviceInfoList_t lstDevices;
DeviceInfoList_t filter;
filter.push_back(CDeviceInfo().SetDeviceClass(BaslerGenTlStaDeviceClass));
TlFactory.EnumerateDevices(lstDevices, filter);
if (!lstDevices.empty()) {
    DeviceInfoList_t::const_iterator it;
    for (it = lstDevices.begin(); it != lstDevices.end(); ++it) {
        std::cout << it->GetFullName();

        // Open camera, i.e., establish a connection to the camera device.
        CStereoAceInstantCamera camera(CTlFactory::GetInstance().CreateDevice(*it));
        // Optionally register configuration(s) here.
        camera.Open();

        // Print out some information.
        std::cout << "Connected to camera "
            << camera.GetDeviceInfo().GetFriendlyName() << std::endl;
        std::cout << "IP Address: "
            << camera.GevCurrentIPAddress.GetValue() << std::endl;
        std::cout << "User-defined name: "
            << camera.DeviceUserID.GetValue() << std::endl;
        std::cout << "Serial Number: "
            << camera.DeviceSerialNumber.GetValue() << std::endl;
}  // The connection will be closed automatically when leaving the scope here.
else {
    std::cerr << "No devices found!" << std::endl;
}

Registering Camera Configuration Handlers#

pylon Instant Camera classes allow you to register configuration event handler objects that can be used to apply camera settings on certain events, for example when the Open() method is called.

The following example illustrates how to register a configuration event handler that applies additional settings:

class MyConfigurationHandler : public StereoAceConfigurationEventHandler
{
public:
    // Sets exposure time to minimum possible value.
    void OnOpened(CStereoAceInstantCamera& camera) override
    {
        camera.ExposureTime.SetToMinimum();
    }
};

// ....

// Then, register configuration event handlers.
camera.RegisterConfiguration(
      new MyConfigurationHandler,
      RegistrationMode_Append, Cleanup_Delete);

// ....

camera.Open(); // Configurations will be applied.

Refer to the Instant Camera Event Handler Basics section of the pylon C++ Programmer's Guide for more information about pylon camera event handler classes.

If you don't want to apply your desired settings by providing a configuration event handler, you can set the parameters you want to change at any time after calling the CStereoAceInstantCamera::Open() method.

Refer to the Parametrize Camera section for information about how to set and get camera parameter values.

Connecting to a Camera#

After creating a camera object and registering a configuration event handler, the connection to the camera is established by calling the CStereoAceInstantCamera::Open() method.

The connection is kept alive until the CStereoAceInstantCamera::Close() method is called. The destructor of CStereoAceInstantCamera automatically calls Close() if it hasn't been called explicitly.

The camera closes the connection if it doesn't periodically receive heartbeat requests from the camera. Missing heartbeat requests occur if the application crashes or is interrupted by a debugger. Refer to the Debugging Applications and Controlling the GigE Vision Heartbeat section for more details.

Parametrize Camera#

Refer to the Accessing Parameters section of the pylon C++ Programmer's Guide to get familiar with how to access camera parameters using the pylon API.

The pylon C++ samples Parametrize_NativeParameterAccess and Parametrize_GenericParameterAccess illustrate typical methods for accessing camera parameters using pylon.

The following code sample illustrates how to set and get frequently-used Stereo ace-specific camera parameters using the CStereoAceInstantCamera class.

// Include files to use the pylon API
#include <pylon/PylonIncludes.h>
#include <pylon/StereoAceInstantCamera.h>

// Namespaces for using the pylon API and the Stereo ace camera parameters
using namespace Pylon;
using namespace StereoAceCameraParams_Params;


// Set the exposure time of the camera.
camera.ExposureTime.SetValue(5000); // us

// Set the gain.
camera.Gain.SetValue(0.0);

// Set the illumination mode (e.g., AlwaysActive, AlternateActive, Off).
camera.BslIlluminationMode.SetValue(BslIlluminationMode_AlwaysActive);

// Set the illumination strength (0.0 ... 1.0).
camera.BslIlluminationStrength.SetValue(1.0);

// Set the minimum and maximum depth for the working area.
camera.BslDepthMinDepth.SetValue(200); // mm
camera.BslDepthMaxDepth.SetValue(2000); // mm

// Enable or disable binning.
camera.BslBinningHorizontal.SetValue(BslBinningHorizontal_Binning2);
camera.BslBinningVertical.SetValue(BslBinningVertical_Binning2);

// Set the depth quality.
camera.BslDepthQuality.SetValue(BslDepthQuality_High);

// Print out current parameter values.
std::cout << "Exposure Time            : "
    << camera.ExposureTime.GetValue() << std::endl;
std::cout << "Gain                     : "
    << camera.Gain.GetValue() << std::endl;
std::cout << "Illumination Mode        : "
    << camera.BslIlluminationMode.GetValue() << std::endl;
std::cout << "Illumination Strength    : "
    << camera.BslIlluminationStrength.GetValue() << std::endl;
std::cout << "Min Depth                : "
    << camera.BslDepthMinDepth.GetValue() << std::endl;
std::cout << "Max Depth                : "
    << camera.BslDepthMaxDepth.GetValue() << std::endl;
std::cout << "Binning Horizontal       : "
    << camera.BslBinningHorizontal.GetValue() << std::endl;
std::cout << "Binning Vertical         : "
    << camera.BslBinningVertical.GetValue() << std::endl;
std::cout << "Depth Quality            : "
    << camera.BslDepthQuality.GetValue() << std::endl;

The Stereo Camera Viewer provides a Documentation pane. When you select a camera parameter in the Features pane, the Documentation pane displays information about the parameter selected as well as C++ and C# code snippets that illustrate how to get and set the value of that camera parameter.

Acquiring Data#

Refer to the Grabbing Images section of the pylon C++ Programmer's Guide to get familiar with how to acquire data using the pylon API.

pylon represents grabbed images as data structures called GrabResults. GrabResults acquired by a Stereo ace camera contain multiple components. By default, each GrabResult stores an intensity image, a disparity map, and additional information.

// Enable disparity maps by enabling the Disparity component and setting the
// appropriate pixel format.
camera.ComponentSelector.SetValue(ComponentSelector_Disparity);
camera.ComponentEnable.SetValue(true);

Refer to the Component Selector and Pixel Format topics of the Basler Product Documentation for more details.

Grab Loop#

pylon supports different approaches for setting up a grab loop and provides different strategies for handling memory buffers.

Refer to the Grabbing Images section of the pylon C++ Programmer's Guide for more details.

The following code snippet illustrates a typical grab loop using the CStereoAceInstantCamera class:

#include <pylon/PylonIncludes.h>
#include <pylon/StereoAceInstantCamera.h>

using namespace Pylon;
using namespace StereoAceCameraParams_Params;


PylonInitialize();

CUniversalInstantInterface instantInterface(
    CInterfaceInfo().SetDeviceClass(Pylon::BaslerGenTlStaDeviceClass));
CStereoAceInstantCamera camera(instantInterface.CreateFirstDevice());
camera.Open();

size_t nBuffersGrabbed = 0;

// This smart pointer will receive the grab result data.
CGrabResultPtr ptrGrabResult;

camera.StartGrabbing();

while (camera.IsGrabbing() && nBuffersGrabbed < 10) {
    // Wait for an image and then retrieve it. A timeout of 1000 ms is used.
    camera.RetrieveResult(1000, ptrGrabResult, TimeoutHandling_ThrowException);

    // Data grabbed successfully?
    if (ptrGrabResult->GrabSucceeded()) {
        nBuffersGrabbed++;
        // Access the data.
        // ...existing code...
    } else {
        // Error handling
        std::cerr << "Grab error occurred: "
            << ptrGrabResult->GetErrorDescription() << std::endl;
    }
}
// Clean-up
camera.StopGrabbing();
camera.Close();

Accessing Components#

To access the individual components of a GrabResult, you can use the Pylon::CPylonDataContainer and Pylon::CPylonDataComponent classes. A container can hold one or more components. You can use the container to query for the number of components and to retrieve a specific component. Each component in the container holds the actual data, e.g., the depth values, as well as its metadata.

Use the Pylon::CGrabResultData::GetDataContainer() method to get access to a GrabResult's CPylonDataContainer. Use the Pylon::CPylonDataContainer::GetDataComponent() method to access a component by specifying the index of the component.

Check each component's type by using the CPylonDataComponent::GetComponentType() method.

Refer to the Multi-Component Grab Results section in the "Advanced Topics" chapter of the pylon C++ Programmer's Guide for more information about how pylon provides access to GrabResults containing multiple components.

示例：

if (ptrGrabResult->GrabSucceeded()) {

    auto componentIdxIntensity = -1;
    auto componentIdxDisparity = -1;
    for (int idx = 0; idx < (int) ptrGrabResult->GetDataComponentCount(); ++idx)
    {
        const auto componentType =
            ptrGrabResult->GetDataComponent(idx).GetComponentType();
        switch (componentType) {
        case EComponentType::ComponentType_Intensity:
            componentIdxIntensity = idx;
            break;
        case EComponentType::ComponentType_Disparity:
            componentIdxDisparity = idx;
            break;
        default:
            // ignore component
            break;
        }
    }

    const auto intensityComponent =
        ptrGrabResult->GetDataComponent(componentIdxIntensity);

    const auto disparityComponent =
        ptrGrabResult->GetDataComponent(componentIdxDisparity);

} else {
    std::cerr << "Grab error: " << ptrGrabResult->GetErrorCode() << " "
              << ptrGrabResult->GetErrorDescription() << std::endl;
}