API Descriptions (C++)

GetVersionString()

Gets VCameraSDK Version.

// Include the header file at the beginning of the code
#include "sdk/version.h"

// Print VCameraSDK version
std::cout << "GetVersionString:" << GetVersionString() << std::endl;

CameraUtils Class

CameraUtils is a static utility class provided by the SDK, dedicated to camera device discovery and network configuration.

Init()

Initializes the underlying camera communication library.

CameraUtils::Init(true);

Important

• Direct connection mode (default, recommended): Call Init(true). This mode is sufficient for regular users. A single camera can only be connected by one process.

• RPC mode (advanced): Call Init(false), which supports multi-process connection. It is not recommended for regular users and should only be used when multiple processes are required. In this mode, copy the files in the VcameraSDK-X.X.X/rpc/ folder to the program directory. For specific usage, contact Percipio technical support.

DiscoverCameras()

Scans for currently available camera devices and returns a list of CameraInfo (including MAC address, current IP, etc.).

CameraUtils::Init();
auto devicelist = CameraUtils::DiscoverCameras();
for (auto& device : devicelist) {
    std::cout << "======Device Information======" << std::endl;
    std::cout << "   " << "serial_number : " << device.serial_number << std::endl;
    std::cout << "   " << "status : " << (int)device.state << std::endl;
    std::cout << "   " << "model : " << device.model << std::endl;
    std::cout << "   " << "vendor : " << device.vendor << std::endl;
    std::cout << "   " << "name : " << device.name << std::endl;
    std::cout << "   " << "firmware_version : " << device.firmware_version << std::endl;
    std::cout << "   " << "network_info.mac : " << device.network_info.mac << std::endl;
    std::cout << "   " << "network_info.ip : " << device.network_info.ip << std::endl;
    std::cout << "   " << "network_info.netmask : " << device.network_info.netmask << std::endl;
    std::cout << "   " << "network_info.gateway : " << device.network_info.gateway << std::endl;
    std::cout << "   " << "network_info.broadcast : " << device.network_info.broadcast << std::endl;
    std::cout << "Interface Information" << std::endl;
    std::cout << "   " << "interface_info.id : " << device.interface_info.id << std::endl;
    std::cout << "   " << "interface_type : " << (int)device.interface_info.interface_type << std::endl;
    std::cout << "   " << "interface_info.name : " << device.interface_info.name << std::endl;
    std::cout << "   " << "interface_info.network_info.broadcast : " << device.interface_info.network_info.broadcast << std::endl;
    std::cout << "   " << "interface_info.network_info.gateway : " << device.interface_info.network_info.gateway << std::endl;
    std::cout << "   " << "interface_info.network_info.ip : " << device.interface_info.network_info.ip << std::endl;
    std::cout << "   " << "interface_info.network_info.mac : " << device.interface_info.network_info.mac << std::endl;
    std::cout << "   " << "interface_info.network_info.netmask : " << device.interface_info.network_info.netmask << std::endl;
    std::cout << "   " << "usb_info.address : " << device.usb_info.address << std::endl;
    std::cout << "   " << "usb_info.bus : " << device.usb_info.bus << std::endl;
 }

SetIpAddress()

Sets the camera’s IP to static. It has two usage methods:

1. First method: Input the camera’s MAC address and the desired IP, netmask, and gateway.

   CameraUtils::Init();
   auto devicelist = CameraUtils::DiscoverCameras();
       CameraApiStatus ret = CameraUtils::SetIpAddress("06:20:FD:B6:D4:95","192.168.6.85","255.255.255.0","192.168.6.1");
       if (ret.IsSuccess()) {
           printf("Set camera static ip success!\n");
       }
       else {
           printf("Set camera static ip failed : %s\n", ret.message().c_str());
       }
   

2. Second method: Input the camera’s CamInfo and the desired IP, netmask, and gateway.

   CameraUtils::Init();
   auto devicelist = CameraUtils::DiscoverCameras();
   for (auto& device : devicelist) {
       if (device.network_info.mac == "06:20:FD:B6:D4:95" && device.interface_info.id == "eth-88-a4-c2-b1-35-e37f06a8c0") {
           CameraApiStatus ret = CameraUtils::SetIpAddress(device, "192.168.6.88", "255.255.255.0", "192.168.6.1");
           if (ret.IsSuccess()) {
               printf("Set camera static ip success!\n");
           }
           else {
               printf("Set camera static ip failed : %s\n", ret.message().c_str());
           }
       }
   }
   

SetIpToDynamic()

Sets the camera IP to dynamic. It has two usage methods:

1. First method: Input the camera’s MAC address.

   CameraUtils::Init();
   auto devicelist = CameraUtils::DiscoverCameras();
       CameraApiStatus ret = CameraUtils:: SetIpToDynamic ("06:20:FD:B6:D4:95");
       if (ret.IsSuccess()) {
           printf("Set camera Dynamic ip success!\n");
       }
       else {
           printf("Set camera Dynamic ip failed : %s\n", ret.message().c_str());
   }
   

2. Second method: Input the camera’s CamInfo.

   CameraUtils::Init();
       auto devicelist = CameraUtils::DiscoverCameras();
       for (auto& device : devicelist) {
           if (device.network_info.mac == "06:20:FD:B6:D4:95" && device.interface_info.id == "eth-88-a4-c2-b1-35-e37f06a8c0") {
               CameraApiStatus ret = CameraUtils::SetIpToDynamic(device);
               if (ret.IsSuccess()) {
                   printf("Set camera static ip success!\n");
               }
               else {
                   printf("Set camera static ip failed : %s\n", ret.message().c_str());
               }
           }
   }
   

CameraFactory Class

CameraFactory is a factory class defined by Percipio SDK, specialized in instantiating and connecting camera devices with different configurations. It provides three static factory methods to create camera instances via serial number, IP address, or pre-configured information.

GetCameraBySerialNumber()

Creates a camera instance by its serial number.

Camera camera = CameraFactory::GetCameraBySerialNumber("207000159118");

GetCameraByIpAddress()

Creates a camera instance by its IP address.

Camera camera = CameraFactory::GetCameraByIpAddress("192.168.6.58");

GetCameraByCameraInfo()

Creates a camera instance by the camera’s information.

Camera camera;
auto devicelist = CameraUtils::DiscoverCameras();
for (auto& list : devicelist) {
    if(list.serial_number == "207000162237")
        camera = CameraFactory::GetCameraByCameraInfo(list);
}

Camera Class

Provides core device control and image acquisition interface.

Note

Camera Object Usage Workflow:

Create Camera object 鈫?Connect() 鈫?Perform other operations 鈫?Disconnect()

GetCameraInfo()

Obtains camera device information.

CameraInfo information;
CameraApiStatus ret = camera.GetCameraInfo(information);
if (ret.IsSuccess()) {
    printf("\033[91mGetCameraInfo success\033[0m\n");
    std::cout << "Device Information" << std::endl;
    std::cout << "   " << "serial_number : " << information.serial_number << std::endl;
    std::cout << "   " << "status : " << (int)information.state << std::endl;
    std::cout << "   " << "model : " << information.model << std::endl;
    std::cout << "   " << "vendor : " << information.vendor << std::endl;
    std::cout << "   " << "name : " << information.name << std::endl;
    std::cout << "   " << "firmware_version : " << information.firmware_version << std::endl;
    std::cout << "   " << "network_info.mac : " << information.network_info.mac << std::endl;
    std::cout << "   " << "network_info.ip : " << information.network_info.ip << std::endl;
    std::cout << "   " << "network_info.netmask : " << information.network_info.netmask << std::endl;
    std::cout << "   " << "network_info.gateway : " << information.network_info.gateway << std::endl;
    std::cout << "   " << "network_info.broadcast : " << information.network_info.broadcast << std::endl;
    std::cout << "Interface Information" << std::endl;
    std::cout << "   " << "interface_info.id : " << information.interface_info.id << std::endl;
    std::cout << "   " << "interface_type : " << (int)information.interface_info.interface_type << std::endl;
    std::cout << "   " << "interface_info.name : " << information.interface_info.name << std::endl;
    std::cout << "   " << "interface_info.network_info.broadcast : " << information.interface_info.network_info.broadcast << std::endl;
    std::cout << "   " << "interface_info.network_info.gateway : " << information.interface_info.network_info.gateway << std::endl;
    std::cout << "   " << "interface_info.network_info.ip : " << information.interface_info.network_info.ip << std::endl;
    std::cout << "   " << "interface_info.network_info.mac : " << information.interface_info.network_info.mac << std::endl;
    std::cout << "   " << "interface_info.network_info.netmask : " << information.interface_info.network_info.netmask << std::endl;
    std::cout << "   " << "usb_info.address : " << information.usb_info.address << std::endl;
    std::cout << "   " << "usb_info.bus : " << information.usb_info.bus << std::endl;
}

Connect()

Connects to the device.

camera.Connect();

Disconnect()

Disconnects from the device.

camera.Disconnect();

EnableReconnectWhenOffline()

Enables unlimited reconnection attempts after the camera goes offline.

Note

Reconnection must be configured before calling Connect().

CameraApiStatus status = camera.EnableReconnectWhenOffline();

EnableReconnectWhenOfflineWithMaxAttempts()

Enables reconnection after the camera goes offline and sets the maximum number of attempts.

CameraApiStatus status = camera.EnableReconnectWhenOfflineWithMaxAttempts(max_try_times);

EnableReconnectWhenOfflineWithTimeoutSeconds()

Enables reconnection after the camera goes offline and sets the timeout.

CameraApiStatus status = camera.EnableReconnectWhenOfflineWithTimeoutSeconds(max_try_time_seconds);

DisableReconnectWhenOffline()

Disables reconnection after the camera goes offline and stops any ongoing reconnection attempts.

CameraApiStatus status = camera.DisableReconnectWhenOffline();

GetCameraState()

Obtains the camera state.

CameraState camerastate;
CameraApiStatus ret = camera.GetCameraState(camerastate);
if (ret.IsSuccess()) {
    printf("\033[96mCameraState %d\033[0m\n", camerastate);
}
else {
    printf("\033[91mGetCameraState failed :%s\033[0m\n", ret.message().c_str());
}

The camera has the following states: 0 corresponds to NotFound, 6 corresponds to Error.

enum class CAMERA_API_EXPORT CameraState : int32_t {
NotFound,
Occupied,
Opened,
Closed,
Capturing,
Offlined,
Error,
};

StartCapture()

Controls the camera to start capturing images.

camera.StartCapture();

StopCapture()

Controls the camera to stop capturing images.

camera.StopCapture();

GetFeature()

Obtains a feature for setting.

Important

The list of features supported by the SDK for configuration is found in VcameraSDK-X.X.X/doc/feature_list/.

Feature feature;
CameraApiStatus ret = camera.GetFeature("AcquisitionMode", feature);
if (!ret.IsSuccess()) {
    printf("\033[91mGetFeature failed :%s\033[0m\n", ret.message().c_str());
}

GetAllFeatures()

Get all features.

std::vector<percipio::Feature> features;
status = camera.GetAllFeatures(features);

FireSoftwareTrigger()

Sends a software trigger signal to a camera operating in software trigger mode.

CameraApiStatus status = camera.FireSoftwareTrigger();
std::cout << "FireSoftwareTrigger status= " << status.message() << std::endl;

GetImageModes()

Obtains the image formats and resolutions that is set for a specified sensor.

std::vector<ImageMode> image_mode;
CameraApiStatus ret = camera.GetImageModes(SensorType::Depth, image_mode);

if (!ret.IsSuccess()) {
    printf("\033[91mGetImageModes failed :%s\033[0m\n", ret.message().c_str());
}
else {
    for (auto& mode : image_mode) {
        printf("ImageModePixelFormat : %d , ImageModeWidth :%d ,ImageModeHeight :%d\n ", mode.pixel_format , mode.width, mode.height);
    }
}

GetCurrentImageMode()

Obtains the current image format and resolution of a specified sensor.

ImageMode image_mode;
camera.GetCurrentImageMode(SensorType::Depth, image_mode);
printf("CurrentImageModePixelFormat : %d , ImageModeWidth :%d ,ImageModeHeight :%d\n ", image_mode.pixel_format , image_mode.width, image_mode.height);

SetImageMode()

Sets the image format and resolution for a specified sensor.

ImageMode image_mode;
image_mode.pixel_format = RawPixelFormat::Coord3D_C16;
image_mode.width = 320;
image_mode.height = 240;
CameraApiStatus ret = camera.SetImageMode(SensorType::Depth, image_mode);
printf("\033[91mSetImageMode1 :%s\033[0m\n", ret.message().c_str());

HasSensor()

Determines whether the camera has a specified sensor.

bool has_sensor;
CameraApiStatus ret = camera.HasSensor(SensorType::Right, has_sensor);
if (!ret.IsSuccess()) {
    printf("\033[91mHasSensor Call  failed :%s\033[0m\n", ret.message().c_str());
}
else {
    printf("HasSensor : %s\n", has_sensor ? "true" : "false");
}

IsSensorEnabled()

Determines whether a specified sensor of the camera is enabled.

bool is_enable;
ret = camera.IsSensorEnabled(SensorType::Color, is_enable);
if (!ret.IsSuccess()) {
    printf("\033[91mIsSensorEnabledCallfailed:%s\033[0m\n", ret.message().c_str());
}
else {
    printf("IsSensorEnabled:%s\n", is_enable ? "true" : "false");
}

SetSensorEnabled()

Enables/disables image output for a specified sensor.

CameraApiStatus ret = camera.SetSensorEnabled(SensorType::Left, true);
if (!ret.IsSuccess()) {
    printf("\033[91mSetSensorEnabled Call  failed :%s\033[0m\n", ret.message().c_str());
}

SetUndistortionEnabled()

Applies/removes distortion correction for images from a specified sensor.

CameraApiStatus ret = camera.SetUndistortionEnabled(SensorType::Left, true);
printf("\033[91mSetUndistortionEnabled:%s\033[0m\n", ret.message().c_str());

IsMapDepthToTextureEnabled()

Used to query whether depth-to-color image mapping (depth and color alignment) is enabled.

bool isEnabled = false;
status = camera.IsMapDepthToTextureEnabled(isEnabled);
if (!status.IsSuccess()) {
    std::cout << "Failed to check depth-to-color mapping status: " << status.message() << std::endl;
    return -1;
}
std::cout << "Current depth-to-color mapping status: " << (isEnabled ? "Enabled" : "Disabled") << std::endl;

SetMapDepthToTextureEnabled()

Enables or disables depth-to-color image mapping (alignment between depth and color images).

Note

This interface is mutually exclusive with SetMapTextureToDepthEnabled(). Select the appropriate alignment mode as needed.

status = camera.SetMapDepthToTextureEnabled(true);
if (!status.IsSuccess()) {
  std::cout << "enable MapDepthToTexture err " << status.message() << std::endl;
  return -1;
}

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/cpp/example/ImageRegistration.cpp.

IsMapTextureToDepthEnabled()

Used to query whether texture-to-depth image mapping (color-to-depth alignment) is enabled.

bool isEnabled = false;
status = camera.IsMapTextureToDepthEnabled(isEnabled);
if (!status.IsSuccess()) {
    std::cout << "Failed to check texture-to-depth mapping status: " << status.message() << std::endl;
    return -1;
}
std::cout << "Current texture-to-depth mapping status: " << (isEnabled ? "Enabled" : "Disabled") << std::endl;

SetMapTextureToDepthEnabled()

Enables or disables texture-to-depth image mapping (color-to-depth alignment).

Note

This interface is mutually exclusive with SetMapDepthToTextureEnabled(). Select the appropriate alignment mode as needed.

status = camera.SetMapTextureToDepthEnabled(true);
if (!status.IsSuccess()) {
  std::cout << "enable MapTextureToDepth err " << status.message() << std::endl;
  return -1;
}

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/cpp/example/ImageRegistration.cpp.

SaveFeaturesToFile()

Saves the camera configuration to a JSON file.

Note

The saving behavior varies by camera type:

• Non-GenICam cameras: Only parameters modified after the camera connection are saved. Parameters saved before the connection are not recorded.

• GenICam cameras: All parameters are saved as much as possible. For the specific saved parameter list, refer to doc/feature_save_gige2_1.txt under the installation path.

Example: Save the camera configuration to the D:/tmp/1.json file.

std::string file_path_save = u8"D:/tmp/1.json";
status = camera.SaveFeaturesToFile(file_path_save);

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/cpp/example/SaveFeaturesToFile.cpp.

LoadFeaturesFromFile()

Loads a configuration from a JSON file and applies it to the camera.

Note

The following optional parameters are available since V25.1.7:

• restore_sensor_enable_state: Whether to overwrite the sensor enable state parameters when loading, default value is true.

• restore_acquisition_and_trigger: Whether to overwrite the acquisition and trigger mode parameters (continuous mode, software trigger mode) when loading, default value is true.

If you do not want to modify the current sensor enable state, acquisition state, or trigger mode when loading a configuration, set the corresponding parameter to false.

Example: Load the camera configuration from the D:/tmp/1.json file.

std::string file_path_load = u8"D:/tmp/1.json";
std::string error_message;
status = camera.LoadFeaturesFromFile(file_path_load, error_message);

If you do not want to modify the current sensor enable state, acquisition state, or trigger mode when loading a camera configuration, set restore_sensor_enable_state and restore_acquisition_and_trigger to false.

std::string file_path_load = u8"D:/tmp/1.json";
std::string error_message;
status = camera.LoadFeaturesFromFile(file_path_load, error_message, false, false);

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/cpp/example/LoadFeaturesFromFile.cpp.

SaveFeaturesToStorage()

Saves the camera configuration to the camera’s internal storage.

Note

• This interface applies only to non-GenICam cameras.

• For GenICam cameras, use the UserSetManager class interface.

bool save_to_storage = true;
if (save_to_storage) {
    status = camera.SaveFeaturesToStorage();
}

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/cpp/example/SaveFeaturesToStorage.cpp.

LoadFeaturesFromStorage()

Loads a configuration from the camera’s internal storage.

Note

• This interface applies only to non-GenICam cameras.

• For GenICam cameras, use the UserSetManager class interface.

Note

The following optional parameters are available since V25.1.7:

• restore_sensor_enable_state: Whether to overwrite the sensor enable state related parameters when loading, default value is true.

• restore_acquisition_and_trigger: Whether to overwrite the acquisition and trigger mode related parameters (continuous mode, software trigger mode), default value is true.

If you do not want to modify the current sensor enable state, acquisition state, or trigger mode when loading a configuration, set the corresponding parameter to false.

status = camera.StopCapture();
std::string error_message;
status = camera.LoadFeaturesFromStorage(error_message);

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/cpp/example/LoadFeaturesFromStorage.cpp.

RegisterFrameSetCallback()

Registers an image callback function.

camera.RegisterFrameSetCallback([](const FrameSet& frameset){
    cout << "FrameSetCallback" << endl;
    Image image = frameset.GetImage(SensorType::Depth);
    if(image.IsValid()){
        cout << "Image: width:" << image.width() << " " << "height:" << image.height() << endl;
        cout << "Image: frame index:" << image.frame_index() << endl;
        cout << "Image: timestamp:" << image.time_stamp() << endl;
        cout << "Image: sensor:" << image.sensor() << endl;
        cout << "Image: sensor type:" <<(int)image.pixel_format() << endl;
        cout << "Image: scale_unit:" << image.scale_unit() << endl;
        cout << "Image: distortion:";for(float f : image.calib_info().distortion.data) cout << f << " "; cout << endl;
        cout << "Image: intrinsic:";for(float f : image.calib_info().intrinsic.data) cout << f << " "; cout << endl;
        cout << "Image: extrinsic:";for(float f : image.calib_info().extrinsic.data) cout << f << " "; cout << endl;
    }
});

RegisterCameraEventCallback()

Registers a camera event callback function.

camera.RegisterCameraEventCallback(
    [](CameraEventCode event_code, int error_code) {
        switch (event_code) {
        case CameraEventCode::Offlined:
            printf("\033[93mWaiting for reconnecting ... ...\033[0m\n");
            break;
        case CameraEventCode::Started:
            printf("\033[93mCamera Started ... ...\033[0m\n");
            break;
        case CameraEventCode::Opened:
            printf("\033[93mCamera Opened ... ...\033[0m\n");
            break;
        case CameraEventCode::Stopped:
            printf("\033[93mCamera Stopped ... ...\033[0m\n");
            break;
        case CameraEventCode::Closed:
            printf("\033[93mCamera Closed ... ...\033[0m\n");
            break;
        case CameraEventCode::Error:
            printf("\033[93mCamera Error ... ...\033[0m\n");
            break;
        }
    }
);

GetFactoryCalibInfo()

Gets the factory calibration information for the specified sensor.

CalibInfo calib_info;
status = camera.GetFactoryCalibInfo(sensor_type, calib_info);

GetRectificationRotation()

Gets the stereo rectification rotation matrix for the specified sensor.

Important

Prerequisite: Only call this interface when you need to implement stereo rectification yourself. If SetUndistortionEnabled() is already enabled, the SDK has already used the rotation parameters internally, and there is no need to call this interface.

Applicable scope: Applies only to the left and right IR sensors.

CameraRotation rotation;
status = camera.GetRectificationRotation(sensor_type, rotation);

GetRectifiedIntrinsic()

Gets the rectified intrinsic parameters for the specified sensor.

Important

Prerequisite: Only call this interface when you need to implement stereo rectification yourself. If SetUndistortionEnabled() is already enabled, the images returned by the SDK already come with the rectified intrinsic parameters, and there is no need to call this interface.

Applicable scope: Applies only to the left and right IR sensors.

CameraIntrinsic intrinsic;
status = camera.GetRectifiedIntrinsic(sensor_type, intrinsic);

GetRectifiedExtrinsic()

Gets the rectified extrinsic parameters for the specified sensor.

Important

Prerequisite: Only call this interface when you need to implement stereo rectification yourself. If SetUndistortionEnabled() is already enabled, the images returned by the SDK already come with the rectified extrinsic parameters, and there is no need to call this interface.

Applicable scope: Applies only to the right IR sensor.

CameraExtrinsic extrinsic;
status = camera.GetRectifiedExtrinsic(sensor_type, extrinsic);

SetParallelEnabled()

Enables or disables multi-core CPU acceleration for image-processing functions.

Note

When disabled, the CPU usage of image-processing operations such as undistortion is reduced, but the processing time may increase. If real-time requirements cannot be met, it is recommended to use image processing libraries such as OpenCV for undistortion and other operations.

status = ImageProc::SetParallelEnabled(true);

UserSetManager Class

GetAllUserSets()

Obtains all UserSets of the camera.

vector<UserSet> usersetall;
UserSetManager& usersetmanager = camera.GetUserSetManager();
CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
for (auto usersets : usersetall) {
    std::cout << usersets.sid << "   " << usersets.name << std::endl;
}

Where,

• sid: Unique identifier, cannot be changed, content is Default0-7, UserSet0-7.

• name: The name of the UserSet

SaveToUserSet()

Saves the UserSet. This interface has two usage methods.

1. First method: Save using the UserSet name

   vector<UserSet> usersetall;
   UserSetManager& usersetmanager = camera.GetUserSetManager();
   CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
   ret = usersetmanager.SaveToUserSet("123");
       if (ret.IsSuccess()) {
           printf("\033[92mSaveToUserSet success\033[0m\n");
       }
   

2. Second method: Save using the UserSet object

   vector<UserSet> usersetall;
   UserSetManager& usersetmanager = camera.GetUserSetManager();
   CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
   if (ret.IsSuccess()) {
       for (auto usersets : usersetall) {
           std::cout << usersets.name << "   " << usersets.sid << std::endl;
           if (usersets.name == "789") {
               ret = usersetmanager.SaveToUserSet(usersets);
               if(ret.IsSuccess()){
                   printf("\033[92mSaveToUserSet %s(sid: %s) success\033[0m\n", usersets.name.c_str(), usersets.sid.c_str());
               }
           }
       }
   }
   

SaveToUserSetWithNewName()

Renames the UserSet and perform the save action. The first parameter is the old name, the second parameter is the new name.

vector<UserSet> usersetall;
UserSetManager& usersetmanager = camera.GetUserSetManager();
CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
ret = usersetmanager.SaveToUserSetWithNewName("123","Peace");
if (ret.IsSuccess()) {
    printf("\033[92mSaveToUserSetWithNewName success\033[0m\n");
}
else {
    printf("\033[91mSaveToUserSetWithNewName failed : %s\033[0m\n", ret.message().c_str());
}

LoadUserSet()

Loads the desired UserSet. Passes the name of the UserSet to load when calling, As illustrated in the code:

vector<UserSet> usersetall;
UserSetManager& usersetmanager = camera.GetUserSetManager();
CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
ret = usersetmanager.LoadUserSet("standard_ObstacleAvoidance");
if (ret.IsSuccess()) {
  printf("\033[92mLoadUserSet success\033[0m\n");
 }
 else {
     printf("\033[91mLoadUserSet failed : %s\033[0m\n", ret.message().c_str());
 }

CurrentUserSet()

Reads the name of the currently used UserSet.

vector<UserSet> usersetall;
UserSetManager& usersetmanager = camera.GetUserSetManager();
CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
std::string CurrentUserSetName;
ret = usersetmanager.CurrentUserSet(CurrentUserSetName);
if (ret.IsSuccess()) {
    printf("\033[95mCurrentUserSet : %s\033[0m\n", CurrentUserSetName.c_str());
}

GetPowerOnUserSet()

Reads the name of the default UserSet when the camera powers on.

vector<UserSet> usersetall;
UserSetManager& usersetmanager = camera.GetUserSetManager();
CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
std::string PowerOnUserSetName;
ret = usersetmanager.GetPowerOnUserSet(PowerOnUserSetName);
if (ret.IsSuccess()) {
    printf("\033[95mPowerOnUserSet : %s\033[0m\n", PowerOnUserSetName.c_str());
}

SetPowerOnUserSet()

Sets the UserSet for when the camera powers on. Pass the name of the UserSet when calling.

vector<UserSet> usersetall;
UserSetManager& usersetmanager = camera.GetUserSetManager();
CameraApiStatus ret = usersetmanager.GetAllUserSets(usersetall);
ret = usersetmanager.SetPowerOnUserSet("HelloWorld");
if (ret.IsSuccess()) {
    printf("\033[92mSetPowerOnUserSet success\033[0m\n");
}
else {
    printf("\033[91mSetPowerOnUserSet failed : %s\033[0m\n",ret.message().c_str());
}

ImageProc Class

DepthImageToPointCloud()

Converts the input depth image into point cloud data.

CameraApiStatus status;
PointCloud point_cloud = ImageProc::DepthImageToPointCloud(image, &status);
// Among them, invalid points are represented by "nan".
std::vector<PointXYZ> points = pcOut.GetPoints();

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/cpp/example/DepthImageToPointCloud.cpp.

PointCloudToDepthImage()

Parameters: point cloud, depth intrinsics, target width, target height, depth scale factor (optional, default is 1)

Returns: depth image

TransformPointCloud()

Parameters: point cloud, extrinsic matrix, whether to use the inverse transform (optional, default is false)

Returns: the transformed point cloud object

MapTextureImageToDepth()

Parameters: texture image (distortion allowed), target depth image (used to obtain the size and calibration parameters)

Returns: the aligned texture image with the same size as the depth image

MapGrayImageToDepth()

Parameters: gray image (GRAY8 or GRAY16, distortion allowed), target depth image (used to obtain the size and calibration parameters)

Returns: the aligned gray image with the same size as the depth image

MapDepthImageToTexture()

Parameters: depth image (DEPTH16, distortion allowed), texture image (used to obtain the size and calibration parameters)

Returns: the aligned depth image with the same size as the texture image

UndistortImage()

Parameters: image (GRAY8 / GRAY16 / RGB24 / DEPTH16), new intrinsics (optional, default is the same as the input)

Returns: the undistorted image

CameraApiStatusCode

Success,
Failure,
ArrayInfoInvalid,
ArrayInvalid,
CalibrationInfoInvalid,
CameraInvalid,
ComponentInvalid,
DeviceInvalid,
DeviceError,
DeviceIdle,
DeviceBusy,
DeviceLost,
DeviceInterfaceInvalid,
DeviceInterfaceTypeError,
DeviceInfoInvalid,
FeatureInvalid,
FeatureInfoInvalid,
FeatureTypeError,
FrameInvalid,
FrameMetadataInvalid,
FrameBufferInvalid,
FrameBufferConsumerInvalid,
FrameSetInvalid,
FrameSetStreamInvalid,
FrameSetConsumerInvalid,
TriggerModeError,
NotExist,
NotImplemented,
NotPermitted,
NotSupported,
OutOfMemory,
OutOfIndexRange,
OutOfValueRange,
ParameterInvalid,
StructureInfoInvalid,
StructureInvalid,
Timeout,
ValueInvalid,
ValueTypeError,
ValueInfoInvalid,
NullCameraHandle,
UserSetIsFull,

Set/Read Camera Features

The names of the features supported by the SDK and their corresponding data types are listed in the doc/feature_list/ directory of the SDK:

doc/
└── 📁 feature_list/
    ├── 📄 feature_list.txt                # Summary of known feature names and corresponding data types (for reference only, subject to the features actually supported by the camera)
    ├── 📄 feature_save_gige2_0.txt
    └── 📄 feature_save_gige2_1.txt

Query Features Supported by the Current Camera

After the camera is connected, call Camera::GetAllFeatures() to query all features actually supported by the current camera, and use GetName, GetType, and GetAccessMode to obtain the feature name, data type, and access mode. The following example prints the query results line by line.

The complete code of this example is located in VcameraSDK-X.X.X/cpp/example/DumpAllFeatures.cpp. Before calling this interface, complete SDK initialization, discover the camera, create a camera instance, and call Connect() to connect the camera.

std::vector<vcamera::Feature> features;
CameraApiStatus status = camera.GetAllFeatures(features);
if (status.IsSuccess()) {
    for (auto& feature : features) {
        AccessMode access_mode;
        status = feature.GetAccessMode(access_mode);
        if (!status.IsSuccess()) {
            continue;
        }

        std::cout << feature.GetName() << ": "
                  << GetFeatureTypeString(feature.GetType()) << ", "
                  << GetAccessModeString(access_mode) << std::endl;
    }
}

Note

GetFeatureTypeString and GetAccessModeString are helper functions defined in VcameraSDK-X.X.X/cpp/example/utils.h. They convert data types and access modes into readable strings and are not part of the public SDK API.

The output displays the feature name, data type, and access mode in sequence. For example:

AcquisitionMode: Enumeration, ReadWrite

isValid()

Checks whether the camera supports this feature.

Feature feature;
CameraApiStatus ret = camera.GetFeature("DepthRangeMax", feature);
bool isValid = ret.IsSuccess();
if isValid {
    printf("\033[92m Feature is valid and available\033[0m\n");
}
else {
    printf("\033[91m Error: %s (code: %d)\033[0m\n", ret.message().c_str(), (int)ret.code());
}

GetName()

Gets feature name.

Feature feature;
CameraApiStatus ret = camera.GetFeature("LightController0/LightBrightness", feature);
cout << feature.GetName() << endl;

GetAccessMode()

Gets feature access permission.

Feature feature;
CameraApiStatus ret = camera.GetFeature("DepthRangeMax", feature);
AccessMode access_mode;
ret = feature.GetAccessMode(access_mode);
if (ret.IsSuccess()) {
    printf("\033[92mDepthRangeMax AccessMode :%d\033[0m\n", access_mode);
 }

In VCameraSDK, feature access permissions have the following four types:

• 0: Indicates the camera does not support this feature or the current state does not support it (e.g., exposure time is not supported when AEC is enabled).

• 1: Indicates the feature is read-only for this camera.

• 2: Indicates the feature is write-only for this camera.

• 3: Indicates the feature is readable and writable for this camera.

GetType()

Feature feature;
camera.GetFeature("Depth/PixelFormat", feature);
FeatureType type = feature.GetType();
printf("\033[91mFeatureType is %d  \033[0m\n", type);

In VCameraSDK, feature types have the following eight types:

enum class CAMERA_API_EXPORT FeatureType : int32_t {
        Undefined,
        Bool,
        Int64,
        Float64,
        Enumeration,
        String,
        ByteArray,
        Dictionary,
};

Int64 Features

Get Feature Value

Feature feature;
Value value;
CameraApiStatus ret = camera.GetFeature("DeviceStreamChannelSelector", feature);
ret = feature.GetValue(value);
if (ret.IsSuccess()) {
  printf("\033[92mGetValue success : %lld\033[0m\n", (int64_t)value);

Check Feature Type

Feature feature;
Value value;
CameraApiStatus ret = camera.GetFeature("DeviceStreamChannelSelector", feature);
feature.GetValue(value);
if (value.IsInt64()) {
    printf("\033[92mValueType is true\033[0m\n");
}
else {
    printf("\033[91mValueType is wrong. ValueType:%d\033[0m\n", value.GetType());
}

Get Feature Range

Feature feature;
CameraApiStatus ret = camera.GetFeature("LightController0/LightBrightness", feature);
Int64Range range;
ret = feature.GetRange(range);
if (ret.IsSuccess()) {
    printf("\033[92mGetRange success : [%lld ,%lld], step : %lld\033[0m\n", range.minValue, range.maxValue, range.step);
                }

Set Feature Value

Feature feature;
CameraApiStatus ret = camera.GetFeature("LightController0/LightBrightness", feature);
ret = feature.SetValue(Value((int64_t)10));
if (ret.IsSuccess()) {
    printf("\033[92mSetValue success\033[0m\n");
}
else {
    printf("\033[91mSetValue call failed : %s\033[0m\n", ret.message().c_str());
}

Complete Code Example

Feature feature;
AccessMode access_mode;
Int64Range range;
Value value;
CameraApiStatus ret = camera.GetFeature("LightController0/LightBrightness", feature);
ret = feature.GetAccessMode(access_mode);
printf("\033[95mDepthRangeMax AccessMode:%d\033[0m\n", access_mode);
ret = feature.GetValue(value);
printf("\033[95mValueType:%d\033[0m\n",value.GetType());
ret = feature.GetRange(range);
printf("\033[95mCurretnValue : %lld , Range : [%lld ,%lld] , Step : %lld\033[0m\n", (int64_t)value, range.minValue, range.maxValue, range.step);
ret = feature.SetValue(Value((int64_t)80));
//ret = feature.SetValue(Value(range.minValue));
//ret = feature.SetValue(Value(range.maxValue));

Boolean Features

Get Feature Value

Feature feature;
CameraApiStatus ret = camera.GetFeature("Texture/ExposureAuto", feature);
Value value;
ret = feature.GetValue(value);
if (ret.IsSuccess()) {
printf("\033[92mGetValue success : %s\033[0m\n", value?"true":"false");
}

Check Feature Type

Feature feature;
CameraApiStatus ret = camera.GetFeature("Texture/ExposureAuto", feature);
Value value;
feature.GetValue(value);
if (value.IsBool()) {
        printf("\033[92mValueType is Bool\033[0m\n");
    }
    else {
        printf("\033[91mValueType is not Bool\033[0m\n");
}

Set Feature Value

Feature feature;
CameraApiStatus ret = camera.GetFeature("Texture/ExposureAuto", feature);
Value value;
    ret = feature.SetValue(Value(false));
    if (ret.IsSuccess()) {
        printf("\033[92mSetValue success\033[0m\n");
    }
    else {
        printf("\033[91mSetValue call failed : %s\033[0m\n", ret.message().c_str());
}

Complete Code Example

Feature feature;
AccessMode access_mode;
Value value;
CameraApiStatus ret = camera.GetFeature("Texture/ExposureAuto", feature);
ret = feature.GetAccessMode(access_mode);
printf("\033[95mTexture/ExposureAuto AccessMode:%d\033[0m\n", access_mode);
ret = feature.GetValue(value);
printf("\033[95mValueType:%d\033[0m\n", value.GetType());
printf("\033[95mCurretnValue : %s\033[0m\n", value?"true":"false");
ret = feature.SetValue(Value(true));

Float64 Features

Get Feature Value

Feature feature;
CameraApiStatus ret = camera.GetFeature("DepthScaleUnit", feature);
Value value;
ret = feature.GetValue(value);
if (ret.IsSuccess()) {
    printf("\033[92mGetValue success : %f\033[0m\n", (double)value);
}

Check Feature Type

Feature feature;
CameraApiStatus ret = camera.GetFeature("DepthScaleUnit", feature);
Value value;
feature.GetValue(value);
if (value.IsDouble()) {
    printf("\033[92mValueType is float\033[0m\n");
}
else {
    printf("\033[91mValueType is not float\033[0m\n");
}

Get Feature Range

Feature feature;
CameraApiStatus ret = camera.GetFeature("DepthScaleUnit", feature);
Float64Range range;
ret = feature.GetRange(range);
if (ret.IsSuccess()) {
    printf("\033[92mGetRange success : [%f , %f]\033[0m\n", range.minValue, range.maxValue);
}

Set Feature Value

Feature feature;
CameraApiStatus ret = camera.GetFeature("DepthScaleUnit", feature);
Value value;
ret = feature.SetValue(Value((double)(0.25)));
if (ret.IsSuccess()) {
    printf("\033[92mSetValue success\033[0m\n");
}
else {
    printf("\033[91mSetValue call failed : %s\033[0m\n", ret.message().c_str());
}

Complete Code Example

Feature feature;
AccessMode access_mode;
Float64Range range;
Value value;
CameraApiStatus ret = camera.GetFeature("DepthScaleUnit", feature);
ret = feature.GetAccessMode(access_mode);
printf("\033[95mDepthScaleUnit AccessMode:%d\033[0m\n", access_mode);
ret = feature.GetValue(value);
printf("\033[95mValueType:%d\033[0m\n", value.GetType());
ret = feature.GetRange(range);
printf("\033[95mCurretnValue : %f , Range : [%f ,%f] , Step : %f\033[0m\n", (double)value, range.minValue, range.maxValue, range.step);
ret = feature.SetValue(Value((double)0.25));
//ret = feature.SetValue(Value(range.minValue));
//ret = feature.SetValue(Value(range.minValue));

Enumeration Features

Get Feature Value

Feature feature;
CameraApiStatus ret = camera.GetFeature("Texture/BinningHorizontal", feature);
Value value;
ret = feature.GetValue(value);
if (ret.IsSuccess()) {
    printf("\033[92mGetValue success : %d\033[0m\n", (int64_t)value);
}

Check Feature Type

Feature feature;
CameraApiStatus ret = camera.GetFeature("DeviceTimeSyncMode", feature);
Value value;
feature.GetValue(value);
if (value.IsInt64()) {
    printf("\033[92mValueType is Enum\033[0m\n");
}
else {
    printf("\033[91mValueType is not Enum\033[0m\n");
}

Get Enum List

Feature feature;
CameraApiStatus ret = camera.GetFeature("DeviceTimeSyncMode", feature);
std::vector<EnumItem> enum_list;
ret = feature.GetEnumItems(enum_list);
if (ret.IsSuccess()) {
    printf("\033[92mGetEnumItems success\033[0m\n");
    for (auto& list : enum_list) {
        printf("Name : %s ,Value :%d\n", list.name.c_str(), list.value);
    }
}

Set Feature Value

Feature feature;
CameraApiStatus ret = camera.GetFeature("DeviceTimeSyncMode", feature);
std::vector<EnumItem> enum_list;
feature.GetEnumItems(enum_list);
ret = feature.SetValue(Value(enum_list[1].value));
if (ret.IsSuccess()) {
    printf("\033[92mSetValue success\033[0m\n");
}
else {
    printf("\033[91mSetValue Call  failed :%s\033[0m\n", ret.message().c_str());
}

Complete Code Example

Feature feature;
AccessMode access_mode;
Value value;
CameraApiStatus ret = camera.GetFeature("DeviceTimeSyncMode", feature);
ret = feature.GetAccessMode(access_mode);
printf("\033[95mDeviceTimeSyncMode AccessMode:%d\033[0m\n", access_mode);
ret = feature.GetValue(value);
printf("\033[95mValueType:%d\033[0m\n", value.GetType());
printf("\033[95mCurretnValue : %d\033[0m\n", (int64_t)value);
std::vector<EnumItem> enum_list;
ret = feature.GetEnumItems(enum_list);
if (ret.IsSuccess()) {
    printf("\033[92mGetEnumItems success\033[0m\n");
    for (auto& list : enum_list) {
        printf("Name : %s ,Value :%d\n", list.name.c_str(), list.value);
        //Set
        ret = feature.SetValue(Value(list.value));
        if (ret.IsSuccess()) {
            printf("\033[92mSetValue success\033[0m\n");
        }
        else {
            printf("\033[91mSetValue Call  failed :%s\033[0m\n", ret.message().c_str());
        }
    }
}

ByteArray Features

Get Feature Value

Feature feature;
CameraApiStatus status = camera.GetFeature("Left/HDRControl", feature);
vcamera::Value value;
status = feature.GetValue(value);
if (value.IsArray()) {
    auto values = value.GetArray();
    std::cout << "HDR value array size: " << values.size() << std::endl;
    for (size_t i = 0; i < values.size(); ++i) {
        std::cout << "HDR[" << i << "]: " << GetValueString(values[i])
                  << std::endl;
    }
} else {
    std::cout << "HDR value: " << GetValueString(value) << std::endl;
}

Check Feature Type

Feature feature;
Value value;
CameraApiStatus ret = camera.GetFeature("Left/HDRControl", feature);
feature.GetValue(value);
if (value.IsArray()) {
    printf("\033[92mValueType is Array\033[0m\n");
} else {
    printf("\033[91mValueType is wrong. ValueType:%d\033[0m\n", static_cast<int>(value.GetType()));
}

Set Feature Value

const char feature_name[] = "Left/HDRControl";
Feature feature;
if (!camera.GetFeature(feature_name, feature).IsSuccess()) {
    ColorPrintf::print(ColorPrintf::Color::Red, "Get feature failed\n");
    return -1;
}
std::vector<vcamera::Value> hdr_vals{vcamera::Value((int32_t)0), vcamera::Value((int32_t)1)};
vcamera::Value hdr_value(hdr_vals);
if (!feature.SetValue(hdr_value).IsSuccess()) {
    ColorPrintf::print(ColorPrintf::Color::Red, "Set value failed\n");
    return -1;
}

Complete Code Example

const char feature_name[] = "Left/HDRControl";
Feature feature;
CameraApiStatus status = camera.GetFeature(feature_name, feature);
ColorPrintf::print(ColorPrintf::Color::Default, "Feature type %s\n",
                   GetFeatureTypeString(feature.GetType()).c_str());
// Set HDR control, the value should be in range {0, 1, 2}
vcamera::Value hdr_val1((int32_t)0);
vcamera::Value hdr_val2((int32_t)1);
std::vector<vcamera::Value> hdr_vals{hdr_val1, hdr_val2};
vcamera::Value hdr_value(hdr_vals);
status = feature.SetValue(hdr_value);
vcamera::Value value;
status = feature.GetValue(value);
if (value.IsArray()) {
    auto values = value.GetArray();
    std::cout << "Array size: " << values.size() << std::endl;
    for (int i = 0; i < values.size(); ++i) {
        std::cout << "Value[" << i << "]: " << GetValueString(values[i]) << ", type="  << (int)values[i].GetType() << std::endl;
    }
}