API Descriptions (Python)

GetVersionString()

Gets the VCameraSDK version.

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

CameraUtils Class

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

Init()

Initializes the underlying camera communication library.

vcam.CameraUtils.Init(True)

DiscoverCameras()

Scans for and discovers all available Percipio cameras.

vcam.CameraUtils.DiscoverCameras()

SetIpAddress()

This API sets a static IP address for the camera. It can be used in two ways.

First method: pass the camera MAC address together with the IP address, netmask, and gateway to be set.
Second method: pass the camera_info together with the IP address, netmask, and gateway to be set.

For a complete example, see VcameraSDK-X.X.X/python/samples/SetIpAddress.py.

SetIpToDynamic()

This API sets the camera to use a dynamic IP address. It can be used in two ways.

First method: pass the camera MAC address.

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

Second method: pass the camera_info.

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

CameraFactory Class

CameraFactory is designed to instantiate and connect camera devices with different configurations. It provides three static factory methods to create camera instances by serial number, IP address, or preconfigured camera information.

GetCameraBySerialNumber()

This API gets a camera object by camera serial number.

vcam.CameraFactory.GetCameraBySerialNumber('207000161660')

GetCameraByIpAddress()

This API gets a camera object by camera IP address.

vcam.CameraFactory.GetCameraByIpAddress ('192.168.2.201')

GetCameraByCameraInfo()

This API creates a camera instance from camera information.

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

        print("Camera created successfully")

Camera Class

Provides the core device control and image acquisition interfaces.

GetCameraInfo()

Gets information about the camera device.

For a complete example, see VcameraSDK-X.X.X/python/samples/DumpDeviceInfo.py.

devicelist = vcam.CameraUtils.DiscoverCameras()
if not devicelist:
   print("no device found")
   return -1
for device in devicelist:
   # Get a camera object from camera information
   camera = vcam.CameraFactory.GetCameraByCameraInfo(device)
   # Connect to the 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
firmware_version: str - firmware version
state: CameraState - camera state

Connect()

Connects to the device.

cam.Connect()

Disconnect()

Disconnects from the device.

cam.Disconnect()

GetCameraState()

Gets the current camera state after the camera has been connected successfully.

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

StartCapture()

Starts image acquisition on the camera.

cam.StartCapture()

StopCapture()

Stops image acquisition on the camera.

cam.StopCapture()

GetFeature()

Gets a feature to be configured.

Important

For the list of configurable SDK features, see 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()

Gets all features.

cam.GetAllFeatures()

FireSoftwareTrigger()

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

For a complete example, see VcameraSDK-X.X.X/python/samples/SoftTrigger.py.

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

GetImageModes()

Gets the image formats and resolutions supported by the specified sensor.

modelist, mode = cam.GetImageModes(vcam.SensorType.Texture)
print("support ",modelist)

GetCurrentImageMode()

Gets the current image format and resolution of the specified sensor.

modelist, mode = cam.GetCurrentImageMode(vcam.SensorType.Texture)
print("support ",modelist)

SetImageMode()

Sets the image format and resolution of the specified sensor.

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

HasSensor()

Checks whether the camera has the specified sensor.

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

IsSensorEnabled()

Checks whether the specified sensor of the camera is enabled.

isenabled = cam.IsSensorEnabled(vcam.SensorType.Depth)
print("depth is enable ",isenabled)

SetSensorEnabled()

Enables or disables image output for the specified sensor.

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

SetUndistortionEnabled()

Enables or disables distortion correction for the specified sensor image.

# cam.SetUndistortionEnabled(vcam.SensorType.Texture, False)
cam.SetUndistortionEnabled(vcam.SensorType.Texture,True)

IsMapDepthToTextureEnabled()

Checks whether mapping from the depth image to the color image 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 mapping from the depth image to the color image.

For a complete example, see VcameraSDK-X.X.X/python/samples/DepthToTextureRegistration.py.

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

SaveFeaturesToFile/LoadFeaturesFromFile()

These APIs are used to save camera settings to a JSON file and load settings from a JSON file and apply them to the camera.

Note

Save behavior differs by camera type:

Gige_2_0 cameras: only parameters modified after the camera is connected are saved. Parameters already stored before connection are not recorded.
Gige_2_1 cameras: as many parameters as possible are saved. For the exact list, refer to doc/feature_save_gige2_1.txt under the installation path.

Save settings to a file:

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

Load settings from a file:

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

For detailed usage, see the sample programs:

VcameraSDK-X.X.X/python/samples/SaveFeaturesToFile.py
VcameraSDK-X.X.X/python/samples/LoadFeaturesFromFile.py

SaveFeaturesToStorage/LoadFeaturesFromStorage()

These APIs are used to save settings to the camera’s internal storage and load settings from the internal storage.

Note

This API is available only for Gige_2_0 cameras.
For Gige_2_1 cameras, use the UserSetManager Class API.

Save settings 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()}")

Load settings from 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}")

For detailed usage, see the sample programs:

VcameraSDK-X.X.X/python/samples/SaveFeaturesToStorage.py
VcameraSDK-X.X.X/python/samples/LoadFeaturesFromStorage.py

RegisterFrameSetCallback()

Image callback function.

cam.RegisterFrameSetCallback(frame_callback)

RegisterFeaturesChangedCallback()

RegisterFeaturesChangedCallback(callback: Callable[[list[Feature]], None]) -> None Registers a callback function for feature changes.

RegisterCameraEventCallback()

RegisterCameraEventCallback(callback: Callable[[CameraEventCode, int], None]) -> None Registers a callback function for camera events.

Camera event codes include:

Closed # closed
Opened # opened
Started # started
Stopped # stopped
Offlined # offline
Error # error

UserSetManager Class

GetAllUserSets()

This API gets all UserSet parameters from the camera.

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

SaveToUserSet()

Saves the current settings to a UserSet.

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

SaveToUserSetWithNewName()

This API renames a UserSet and saves it.

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

LoadUserSet()

This API loads the required UserSet. Pass the name of the UserSet to load, as shown below:

index_str = input("\nSelect a user set 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()

This API reads the name of the currently active UserSet.

name, status = user_set_mgr.CurrentUserSet()
print("Current user set: ", name)

GetPowerOnUserSet()

This API reads the name of the default UserSet used when the camera powers on.

name, status = user_set_mgr.GetPowerOnUserSet()
print("GetPowerOnUserSet user set: ", name)

SetPowerOnUserSet()

This API sets the UserSet used when the camera powers on. Pass the name of the UserSet when calling it.

user_set_mgr.SetPowerOnUserSet(usets[2].name)
name, status = user_set_mgr.GetPowerOnUserSet()
print("GetPowerOnUserSet user set: ", name)

CameraApiStatusCode (API Status Codes)

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,

CameraFeature Class

Basic Information Methods

IsValid()

Checks whether the feature is valid.

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

GetName()

Gets the feature name.

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

GetAccessMode()

Gets the access mode of the camera feature.

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

GetType()

Gets the camera feature type.

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

Value Operation Methods

GetValue()

Gets the current value of the feature.

Integer feature

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

Floating-point feature

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

Enum 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 feature value.

Integer feature

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

Floating-point feature

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

Enum feature

acq_mode, status = cam.GetFeature('DeviceTimeSyncMode')
print("before DeviceTimeSyncMode is ",acq_mode.GetValue())
status = acq_mode.SetValue(1)
print("DeviceTimeSyncMode Static 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(0)
print("DepthSgbmLRC Static is : ", status.message())
print("after DepthSgbmLRC is ",acq_mode.GetValue())

Range Query Methods

GetIntRange()

Gets the value range of an integer feature.

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

GetFloatRange()

Gets the value range of a floating-point feature.

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

Enum Item Methods

GetEnumItems()

Gets all enum items of an enum feature.

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