API Descriptions (Python)

GetVersionString()

Gets VCameraSDK Version.

version = GetVersionString()
print('version = ', version)

CameraUtils Class

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

Init()

Initializes the camera system environment.

percipio.CameraUtils.Init(True)

Note: Must be called before any other operations.

DiscoverCameras()

Scans and discovers all available cameras.

percipio.CameraUtils.DiscoverCameras()

SetIpAddress()

Sets the camera’s static IP. There are two methods to use this interface.

First method: pass the camera’s MAC address and the IP, netmask, and gateway to be set.
Second method: pass the camera’s Camera_info and the IP, netmask, and gateway to be set.

Complete example code is found at: VcameraSDK-X.X.X/python/samples/SetIpAddress.py.

SetIpToDynamic()

Sets the camera’s IP to dynamic. There are two methods to use this interface.

First method: pass the camera’s MAC address.

percipio.CameraUtils.SetIpToDynamic("06:26:CD:26:6C:38")

Second method: pass the camera’s camera_info.

for item in cameras:
    if item.serial_number == '207000159544':
        status = percipio.CameraUtils.SetIpToDynamic(item)
        if not status:
            print("Failed to set ip address: ", status.message())
            return
        else:
            print('Set IP address success :)')

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

Obtains a camera object by its serial number.

percipio.CameraFactory.GetCameraBySerialNumber('207000161660')

GetCameraByIpAddress()

Obtains a camera object by its IP address.

percipio.CameraFactory.GetCameraByIpAddress('192.168.2.201')

GetCameraByCameraInfo()

Creates a camera instance using the camera’s information.

for info in cameras:
    if info.serial_number == '207000159544':
        cam = percipio.CameraFactory.GetCameraByCameraInfo(info)
        if cam is None:
            print("Failed to create camera instance")
            return

        print("Camera created successfully")

Camera Class

Provides core device control and image acquisition interfaces.

GetCameraInfo()

Obtains camera device information.

Complete example code is found at: VcameraSDK-X.X.X/python/samples/DumpDeviceInfo.py.

devicelist = percipio.CameraUtils.DiscoverCameras()
if not devicelist:
   print("no device found")
   return -1
for device in devicelist:
   # Get camera object via camera information
   camera = percipio.CameraFactory.GetCameraByCameraInfo(device)
   # Connect camera
   status = camera.Connect()
   if not status.IsSuccess():
      print(f"Camera Connect error: {status.message()}")
      return -1
   # Get camera information
   camera_info = camera.GetCameraInfo()
   print(f"Camera Info: {camera_info}")

Camera information includes the following fields:

interface_info: InterfaceInfo - Interface information
network_info: NetworkInfo - Network information
usb_info: UsbInfo - USB information
serial_number: str - Serial number
name: str - Camera name
model: str - Model
vendor: str - Vendor Name
firmware_version: str - Firmware version
state: CameraState - Camera state

Connect()

Connects the camera.

cam.Connect('')

Disconnect()

Disconnects the camera.

cam.Disconnect()

EnableReconnectWhenOffline()

Enables unlimited reconnection attempts after the camera goes offline.

Note

Reconnection must be configured before calling Connect().

status = camera.EnableReconnectWhenOffline()

EnableReconnectWhenOfflineWithMaxAttempts()

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

status = camera.EnableReconnectWhenOfflineWithMaxAttempts(max_try_times)

EnableReconnectWhenOfflineWithTimeoutSeconds()

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

status = camera.EnableReconnectWhenOfflineWithTimeoutSeconds(max_try_time_seconds)

DisableReconnectWhenOffline()

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

status = camera.DisableReconnectWhenOffline()

GetCameraState()

Retrieves the camera state.

status = cam.GetCameraState()
print("the status is: ", status)

The camera has 7 states: NotFound, Occupied, Opened, Closed, Capturing, Offlined, Error.

StartCapture()

Starts image capture.

cam.StartCapture()

StopCapture()

Stops image capture.

cam.StopCapture()

GetFeature()

Retrieves a feature for setting.

Important

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

acq_mode, status = cam.GetFeature('AcquisitionMode')
if not status:
    print("Failed to get AcquisitionMode: ", status.message())
    return

GetAllFeatures()

Retrieves all features.

cam.GetAllFeatures()

FireSoftwareTrigger()

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

Complete example code is found at: VcameraSDK-X.X.X/python/samples/SoftTrigger.py.

status = cam.FireSoftwareTrigger()
if not status:
print("Failed to fire a software trigger:", status.message())

GetImageModes()

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

modelist, mode = cam.GetImageModes(percipio.SensorType.COLOR)
print("support ", modelist)

GetCurrentImageMode()

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

modelist, mode = cam.GetCurrentImageMode(percipio.SensorType.COLOR)
print("support ", modelist)

SetImageMode()

Sets the image format and resolution for a specified sensor.

image_mode = percipio.ImageMode()
image_mode.pixel_format = percipio.RawPixelFormat.CSIBayer12GBRG
image_mode.width = 2560
image_mode.height = 1920
cam.SetImageMode(percipio.SensorType.COLOR, image_mode)
modelist, mode = cam.GetCurrentImageMode(percipio.SensorType.COLOR)
print("support ", modelist)

HasSensor()

Checks if the camera has a specified sensor.

has_color,status = cam.HasSensor(percipio.SensorType.COLOR)
if has_color:
     status = cam.SetSensorEnabled(percipio.SensorType.COLOR, True)
     if not status:
         print("Failed to enable color sensor: ", status.message())
         cam.Disconnect()
         return

The camera supports the following sensor types:

DEPTH = “Depth”
LEFT = “Left”
RIGHT = “Right”
COLOR = “Color”

IsSensorEnabled()

Checks if a specified sensor of the camera is enabled.

isenabled = cam.IsSensorEnabled(percipio.SensorType.DEPTH)
print("depth is enable ", isenabled)

SetSensorEnabled()

Enables or disables image output for a specified sensor.

status = cam.SetSensorEnabled(percipio.SensorType.DEPTH, True)
if not status:
   print("Failed to enable depth sensor: ", status.message())

SetUndistortionEnabled()

Enables or disables distortion correction for images from a specified sensor.

#cam.SetUndistortionEnabled(percipio.SensorType.COLOR, False)
cam.SetUndistortionEnabled(percipio.SensorType.COLOR, True)

IsMapDepthToTextureEnabled()

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

is_enabled_before, status = camera.IsMapDepthToTextureEnabled()
if not status.IsSuccess():
    print(f"Failed to check mapping status: {status.message()}")
    return

print(f"Before setting: {'Enabled' if is_enabled_before else 'Disabled'}")

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.

For the complete sample code, see VcameraSDK-X.X.X/python/samples/ImageRegistration.py.

status = cam.SetMapDepthToTextureEnabled(True)
if not status:
    print(f"enable depth to color mapping err: {status.message()}")
    return -1

IsMapTextureToDepthEnabled()

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

is_enabled, status = camera.IsMapTextureToDepthEnabled()
if not status.IsSuccess():
    print(f"Failed to check texture-to-depth mapping status: {status.message()}")
    return
print(f"Current texture-to-depth mapping status: {'Enabled' if is_enabled else 'Disabled'}")

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 = cam.SetMapTextureToDepthEnabled(True)
if not status:
    print(f"enable texture to depth mapping err: {status.message()}")
    return -1

For the complete sample code, see VcameraSDK-X.X.X/python/samples/ImageRegistration.py.

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 1.json file.

file_path_save = "1.json"
status = camera.SaveFeaturesToFile(file_path_save)

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/python/samples/SaveFeaturesToFile.py.

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 1.json file.

file_path_load = "1.json"
status, error_message = camera.LoadFeaturesFromFile(file_path_load)

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.

file_path_load = "1.json"
status, error_message = camera.LoadFeaturesFromFile(file_path_load, False, False)

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/python/samples/LoadFeaturesFromFile.py.

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.

Save Configuration to Internal Storage:

status = camera.SaveFeaturesToStorage()
if status.IsSuccess():
    print("Successfully saved features to storage")
else:
    print(f"Fail to save features to storage: {status.message()}")

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/python/samples/SaveFeaturesToStorage.py.

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.

Example: Load a configuration from the camera’s internal storage.

status, error_message = camera.LoadFeaturesFromStorage()
if status.IsSuccess():
    print("Successfully loaded features from storage")
else:
    print(f"Fail to load features from storage: {status.message()}\n{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.

status, error_message = camera.LoadFeaturesFromStorage(False, False)

For detailed usage instructions, see the sample program VcameraSDK-X.X.X/python/samples/LoadFeaturesFromStorage.py.

RegisterFrameSetCallback()

Registers an image callback function.

cam.RegisterFrameSetCallback(frame_callback)

RegisterFeaturesChangedCallback()

Registers a callback function for feature changes.

RegisterFeaturesChangedCallback(callback: Callable[[list[Feature]], None]) -> None

RegisterCameraEventCallback()

Registers a camera event callback function.

RegisterCameraEventCallback(callback: Callable[[CameraEventCode, int], None]) -> None

Camera event codes include:

Closed
Opened
Started
Stopped
Offlined
Error

GetFactoryCalibInfo()

Gets the factory calibration information for the specified sensor.

calib_info, status = camera.GetFactoryCalibInfo(sensor_type)

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.

rotation, status = camera.GetRectificationRotation(sensor_type)

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.

intrinsic, status = camera.GetRectifiedIntrinsic(sensor_type)

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.

extrinsic, status = camera.GetRectifiedExtrinsic(sensor_type)

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 = vcam.ImageProc.SetParallelEnabled(True)

UserSetManager Class

GetAllUserSets()

Retrieves all UserSets of the camera.

usets, status = user_set_mgr.GetAllUserSets()
print("Available Usersets:")

SaveToUserset()

Saves the current camera’s parameter settings to the specified Userset.

status = user_set_mgr.SaveToUserset("123")
if status:
    print("Save success")
else:
    print("Save fail")

SaveToUsersetWithNewName()

Renames an existing Userset.

status = user_set_mgr.SaveToUsersetWithNewName('123', '456')
if status:
    print("rename success")
else:
    print("rename fail")

LoadUserset()

Loads the desired Userset.

index_str = input("\nSelect a userset index: ")
index = int(index_str)

if index < len(usets):
    print(f"You selected: {usets[index].name}")
    status = user_set_mgr.LoadUserset(usets[index].name)
    if status:
       print("Load success")
    else:
       print("Load fail")
else:
    print("Invalid index.")

CurrentUserset()

Reads the name of the currently used Userset.

name, status = user_set_mgr.CurrentUserset()
print("Current userset: ", name)

GetPowerOnUserset()

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

name, status = user_set_mgr.GetPowerOnUserset()
print("GetPowerOnUserset userset: ", name)

SetPowerOnUserset()

Sets the Userset when the camera powers on.

user_set_mgr.SetPowerOnUserset(usets[2].name)
name, status = user_set_mgr.GetPowerOnUserset()
print("GetPowerOnUserset userset: ", name)

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,

Camera Feature Class

Basic Information Methods

IsValid()

Determines whether the camera supports this feature.

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.IsValid())

GetName()

Gets feature name.

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.GetName())

GetAccessMode()

Retrieves the camera feature permission.

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.GetAccessMode())

In VCameraSDK, features have the following four access modes:

NotAvailable
Readable
Writable
ReadWritable

GetType()

Retrieves the feature type.

acq_mode, status = cam.GetFeature('AcquisitionMode')
print(acq_mode.GetType())

In VCameraSDK, features have the following eight types:

Undefined
Bool
Int64
Float64
Enumeration
String
ByteArray
Dictionary

Value Operation Methods

GetValue()

Retrieves the current value of a feature.

Integer feature

acq_mode, status = cam.GetFeature('CaptureTimeStatistic')
print("capture time is ", acq_mode.GetValue())

Float feature

acq_mode, status = cam.GetFeature('DepthScaleUnit')
print("DepthScaleUnit is ", acq_mode.GetValue())

Enumeration feature

acq_mode, status = cam.GetFeature('DeviceTimeSyncMode')
print("DeviceTimeSyncMode is ", acq_mode.GetValue())

Boolean feature

acq_mode, status = cam.GetFeature('IRUndistortion')
print("IRUndistortion is ", acq_mode.GetValue())

SetValue()

Sets the value of a feature.

Integer feature

acq_mode, status = cam.GetFeature('DepthSgbmImageNumber')
print("before DepthSgbmImageNumber is ", acq_mode.GetValue())
status = acq_mode.SetValue(percipio.Value(1, percipio.INT32))
print("DepthSgbmImageNumber Status is: ", status.message())
print("after DepthSgbmImageNumber is ", acq_mode.GetValue())

Float feature

acq_mode, status = cam.GetFeature('DepthScaleUnit')
status = acq_mode.SetValue(percipio.Value(2, percipio.FLOAT64))
print("DepthScaleUnit is set to: ", status.message())
print("DepthScaleUnit is ", acq_mode.GetValue())

Enumeration feature

acq_mode, status = cam.GetFeature('DeviceTimeSyncMode')
print("before DeviceTimeSyncMode is ", acq_mode.GetValue())
status = acq_mode.SetValue(percipio.Value(1, percipio.INT32))
print("DeviceTimeSyncMode Status is: ", status.message())
print("after DeviceTimeSyncMode is ", acq_mode.GetValue())

Boolean feature

acq_mode, status = cam.GetFeature('DepthSgbmLRC')
print("before DepthSgbmLRC is ", acq_mode.GetValue())
status = acq_mode.SetValue(percipio.Value(0, percipio.BOOL))
print("DepthSgbmLRC Status is: ", status.message())
print("after DepthSgbmLRC is ", acq_mode.GetValue())

Range Query Methods

GetIntRange()

Retrieves the value range of an integer feature.

acq_mode, status = cam.GetFeature('DepthSgbmImageNumber')
print("DepthSgbmImageNumber range is ", acq_mode.GetIntRange())

Applies to: Integer feature

GetFloatRange()

Retrieves the value range of a float feature.

acq_mode, status = cam.GetFeature('DepthScaleUnit')
print("DepthScaleUnit range is ", acq_mode.GetFloatRange())

Applies to: Float feature

Enumeration Item Methods

GetEnumItems()

Retrieves all enumeration items of an enumeration feature.

acq_mode, status = cam.GetFeature('DeviceTimeSyncMode')
modes, status = acq_mode.GetEnumItems()
for mod in modes:
    print(mod.name)
    print(mod.value)
    print("============================")

Applies to: Enumeration feature