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.

percipio.CameraUtils.SetIpAddress("06:2B:5B:1E:70:D4", "192.168.2.144", "255.255.255.0", "192.168.2.1")

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

information, ret = cam.GetCameraInfo()
print("camera info status is ",ret)
print(f"Camera Info: {information}")
percipio.CameraUtils.SetIpAddress(information, "192.168.2.223", "255.255.255.0", "192.168.2.1")

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.

information, ret = cam.GetCameraInfo()
print("camera info status is ",ret)
print(f"Camera Info: {information}")
percipio.CameraUtils.SetIpToDynamic(information, "192.168.2.223", "255.255.255.0", "192.168.2.1")

CameraFactory Class

CameraFactory is a factory class defined by the 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.

percipio.CameraFactory.GetCameraByCameraInfo(device)

Camera Class

Provides core device control and image acquisition interfaces.

GetCameraInfo()

Obtains camera device information.

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

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.

camera.StartCapture()

StopCapture()

Stops image capture.

camera.StopCapture()

GetFeature()

Retrieves a feature for setting.

Important

The list of features supported for setting by the SDK can be found in {SDK installation path}\Percipio_SDK\doc\feature_list.txt.

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

GetAllFeatures()

Retrieves all features.

cam.GetAllFeatures()

FireSoftwareTrigger()

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

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

GetImageModes()

Retrieves the image formats and resolutions that can be 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)

IsMapDepthToColorEnabled()

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

is_enabled_before, status = camera.IsMapDepthToColorEnabled()
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'}")

SetMapDepthToColorEnabled()

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

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

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

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