API Descriptions (C#)

GetVersionString()

Gets the VCameraSDK version.

string versionString = UCV.CameraApi.Interop.Version.GetVersionString();
Console.WriteLine($"GetVersionString: {versionString}");

CameraUtils Class

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

Init()

Initializes the SDK communication library.

CameraUtils.Init(true);

Important

• Direct connection mode (default and recommended): Call Init(true). This mode is suitable for most users. Each camera can be connected by only one process at a time in this mode.

• RPC mode (advanced): Call Init(false). This mode supports multi-process connections. It is intended only for scenarios that require multi-process access and is not recommended for most users. To use this mode, copy the files in VcameraSDK-X.X.X/rpc/ to the program directory. For detailed usage instructions, contact Percipio Technical Support.

Note: This method must be called before any other operation.

DiscoverCameras()

Scans for and discovers all available Percipio cameras.

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.

string mac = "06:20:FD:B6:D4:95";
string ip = "192.168.6.119";
string mask = "255.255.255.0";
string gateway = "192.168.6.1";
status = CameraUtils.SetIpAddress(mac, ip, mask, gateway);
if (status != CameraApiStatus.Success) {
    Console.WriteLine($"Force Device IP failed :{ status}");
    return;
}
else
{
    Console.WriteLine($"Force Device IP success :{status}");
    return;
}

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

var camInfos = CameraUtils.DiscoverCameras();
foreach (var camInfo in camInfos)
{
    Console.WriteLine($"Found camera: {camInfo.ModelName}, SN: {camInfo.Sn}, IP: {camInfo.NetworkInfo.Ip}");
    if(camInfo.Sn == "207000159118")
    {
        status = CameraUtils.SetIpAddress(camInfo,"192.168.6.119","255.255.255.0","192.168.6.1");
        if (status != CameraApiStatus.Success)
        {
            Console.WriteLine($"Force Device IP failed :{status}");
            return;
        }else
        {
            Console.WriteLine($"Force Device IP success :{status}");
            return;
        }
    }
}

SetDeviceDhcp()

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.

string mac = "06:20:FD:B6:D4:95";
status = CameraUtils.SetIpToDynamic(mac);
if (status != CameraApiStatus.Success) {
    Console.WriteLine($"Force Device IP failed :{ status}");
    return;
}else
{
    Console.WriteLine($"Force Device IP success :{status}");
    return;
}

Second method: pass the camera CamInfo.

var camInfos = CameraUtils.DiscoverCameras();
foreach (var camInfo in camInfos)
{
    Console.WriteLine($"Found camera: {camInfo.ModelName}, SN: {camInfo.Sn}, IP: {camInfo.NetworkInfo.Ip}");
    if(camInfo.Sn == "207000159118")
    {
        status = CameraUtils.SetIpToDynamic(camInfo);
        if (status != CameraApiStatus.Success)
        {
            Console.WriteLine($"Force Device IP failed :{status}");
            return;
        } else
        {
            Console.WriteLine($"Force Device IP success :{status}");
            return;
        }
    }
}

CameraCapture Class

CameraCapture 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.

CameraCapture.GetCameraBySerialNumber("207000159205");

GetCameraByIpAddress()

This API gets a camera object by camera IP address.

CameraCapture.GetCameraByIpAddress("192.168.6.50");

GetCameraByDeviceInfo()

This API gets a camera object by camera information.

var camInfos = CameraUtils.DiscoverCameras();
CameraCapture cc = null;
foreach (var camInfo in camInfos)
{
    Console.WriteLine($"Found camera: {camInfo.ModelName}, SN: {camInfo.Sn}, IP: {camInfo.NetworkInfo.Ip}");
    if (camInfo.Sn == "207000159118")
    {
        cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
    }
}

Connect()

Connects to the device.

cc.Connect();

Disconnect()

Disconnects from the device.

cc.Disconnect();

GetCameraState()

Gets the current camera state. This API should be called after the camera is connected.

cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
cc.Connect();
CameraState camerastatus;
cc.GetCameraState(out camerastatus);
Console.WriteLine($"CameraState : {camerastatus}");

GetCameraInfo()

Gets detailed information about the camera device.

var camInfos = CameraUtils.DiscoverCameras();
CameraCapture cc = null;
foreach (var camInfo in camInfos)
{
    cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
    CameraApiStatus connectStatus = cc.Connect();
    if (connectStatus != CameraApiStatus.Success)
    {
        Console.WriteLine($"Connect the camera {camInfo.Sn} Failure: {connectStatus}");
        continue;
    }
    CameraInfo detailedInfo;
    CameraApiStatus infoStatus = cc.GetCameraInfo(out detailedInfo);
    if (infoStatus == CameraApiStatus.Success)
    {
        Console.WriteLine("\n====== Camera details ======");
        Console.WriteLine($"   Model number: {detailedInfo.ModelName}");
        Console.WriteLine($"   Serial Number: {detailedInfo.Sn}");
        Console.WriteLine($"   IP address: {detailedInfo.NetworkInfo.Ip}");
        Console.WriteLine($"   Name: {detailedInfo.Name}");
        Console.WriteLine($"   VendorName: {detailedInfo.VendorName}");
        Console.WriteLine($"   FirmwareVersion: {detailedInfo.FirmwareVersion}");
        Console.WriteLine($"   State: {detailedInfo.State}");
        Console.WriteLine($"   Mac: {detailedInfo.NetworkInfo.Mac}");
        Console.WriteLine($"   Netmask: {detailedInfo.NetworkInfo.Netmask}");
        Console.WriteLine($"   Gateway: {detailedInfo.NetworkInfo.Gateway}");
        Console.WriteLine($"   InterfaceType: {detailedInfo.InterfaceInfo.InterfaceType}");
        Console.WriteLine($"   InterfaceName: {detailedInfo.InterfaceInfo.Name}");
    }
    else
    {
        Console.WriteLine($"Get the camera {camInfo.Sn} Details failed: {infoStatus}");
    }
    cc.Disconnect();
}
if (camInfos.Count == 0)
{
    Console.WriteLine("No camera found!");
    return;
}

StartCapture()

Starts image acquisition on the camera.

cc.StartCapture();

StopCapture()

Stops image acquisition on the camera.

cc.StopCapture();

GetFeature()

Gets a feature to be configured.

Important

For the list of configurable SDK features, see VcameraSDK-X.X.X/doc/feature_list/.

CameraFeature feature;
CameraApiStatus status=cc.GetFeature("Left/ExposureTime", out feature);
Console.WriteLine($"GetFeature Left/ExposureTime Status: {status}");

GetAllFeatures()

Gets all features.

cc.GetAllFeatures();

FireSoftwareTrigger()

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

cc.FireSoftwareTrigger();

IsSupportGenicam()

Checks whether the camera complies with the GenICam standard. If the return value is True, the camera is GenICam compliant.

CameraApiStatus ret = CameraApiStatus.Success;
cc = CameraCapture.GetCameraByDeviceInfo(camInfo);
ret = cc.Connect();
if(ret == CameraApiStatus.Success)
{
    bool isSupport = cc.IsSupportGenicam(out status);
    if (status == CameraApiStatus.Success)
    {
        if (isSupport)
        {
            Console.WriteLine("Support GenICam");
        }
        else
        {
            Console.WriteLine("Not Support GenICam");
        }
    }
    else
    {
        Console.WriteLine($" IsSupportGenicam API call : {status}");
    }
}

GetImageModes()

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

List<ImageMode> image_modes = cc.GetImageModes(SensorType.Right, out status);
if (status != CameraApiStatus.Success)
{
        Console.WriteLine($"GetImageModes failed : {status}");
}
else
{
    foreach (var mode in image_modes)
    {
            Console.WriteLine($"ImageModePixelFormat : {mode.RawPixelFormat} , ImageModeWidth : {mode.Width} , ImageModeHeight : {mode.Height}");
        }
}

GetCurrentImageMode()

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

var currentMode = cc.GetCurrentImageMode(SensorType.Left, out status);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"Current ImageModePixelFormat : {currentMode.RawPixelFormat} , ImageModeWidth : {currentMode.Width} , ImageModeHeight : {currentMode.Height}");
}
else
{
    Console.WriteLine($"GetCurrentImageMode API call : {status}");
}

SetImageMode()

Sets the image format and resolution of the specified sensor.

List<ImageMode> image_modes = cc.GetImageModes(SensorType.Texture, out status);
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"GetImageModes failed : {status}");
}
else
{
    foreach (var mode in image_modes)
    {
        Console.WriteLine($"ImageModePixelFormat : {mode.RawPixelFormat} , ImageModeWidth : {mode.Width} , ImageModeHeight : {mode.Height}");
    }
}
status = cc.SetImageMode(SensorType.Texture, image_modes[1]);
if(status == CameraApiStatus.Success)
{
    Console.WriteLine($"SetImageMode : {status}");
}
else
{
    Console.WriteLine($"SetImageMode : {status}");
}

HasSensor()

Checks whether the camera has the specified sensor.

bool hasSensor = cc.HasSensor(SensorType.Right);
if (hasSensor) {
    Console.WriteLine($"This camera has Right");
}
else
{
    Console.WriteLine($"This camera does not have Right");
}

IsSensorEnabled()

Checks whether the specified sensor of the camera is enabled.

bool enabled;
status = cc.IsSensorEnabled(SensorType.Right, out enabled);
if (status == CameraApiStatus.Success) {
    Console.WriteLine($"Depth is {(enabled ? "Enabled": "Disabled")}");
}
else
{
    Console.WriteLine($"IsSensorEnabled API call : {status}");

}

SetSensorEnabled()

Enables or disables image output for the specified sensor.

status = cc.SetSensorEnabled(SensorType.Depth, true);
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"SetSensorEnabled API call : {status}");
}
else
{
    Console.WriteLine($"SetSensorEnabled {status}");
}

SetUndistortionEnabled()

Enables or disables distortion correction for the specified sensor image.

cc.SetUndistortionEnabled(SensorType.Texture, true);

IsMapDepthToTextureEnabled()

Checks whether mapping from the depth image to the color image is enabled.

bool en = false;
cc.IsMapDepthToTextureEnabled(out en);
Console.WriteLine($"IsMapDepthToTextureEnabled: {en}");

SetMapDepthToTextureEnabled()

Enables or disables mapping from the depth image to the color image.

status = cc.SetMapDepthToTextureEnabled(true);
if (status != CameraApiStatus.Success)
{
    Console.WriteLine($"Failed to enable MapDepthToTexture: {status}");
    return;
}

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:

string filePath = "1.json";
status = cc.SaveFeaturesToFile(filePath);

Load settings from a file:

string error_message = "";
// We strongly recommend to use path only including ASCII characters.
string file_path_load = "1.json";
status = cc.LoadFeaturesFromFile(file_path_load, ref error_message);

For detailed usage, see the sample programs:

• VcameraSDK-X.X.X/csharp/net48/example/SaveFeaturesToFile/Program.cs

• VcameraSDK-X.X.X/csharp/net48/example/LoadFeaturesFromFile/Program.cs

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 = cc.SaveFeaturesToStorage();

Load settings from internal storage:

string error_message = "";
status = cc.LoadFeaturesFromStorage(ref error_message);

For detailed usage, see the sample programs:

• VcameraSDK-X.X.X/csharp/net48/example/SaveFeaturesToStorage/Program.cs

• VcameraSDK-X.X.X/csharp/net48/example/LoadFeaturesFromStorage/Program.cs

RegisterFrameSetCallback()

Image callback function.

RegisterCameraEventCallback()

Camera event callback function.

RegisterFeaturesChangedCallback()

Registers a callback function for feature changes.

UserSetManager Class

GetAllUserSets()

This API gets all UserSet parameters from the camera.

var userSetMgr = cc.GetUserSetManager();
var userSets = new List<UserSet>();
status = userSetMgr.GetAllUserSets(userSets);
Console.WriteLine("Available User Sets:");
for (int i = 0; i < userSets.Count; i++)
{
    Console.WriteLine($"  [{i}] {userSets[i].Name}");
}

SaveToUserSet()

Saves all current camera parameter settings to the specified user set or an empty user set.

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.SaveToUserSet("Default");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine("Save success");
}
else
{
    Console.WriteLine($"SaveToUserSet API call : {status}");
}

SaveToUserSetWithNewName()

Saves an existing configuration set under a new name, effectively renaming the configuration set.

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.SaveToUserSetWithNewName("Default", "MyCustomConfig");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"SaveToUserSetWithNewName : {status}");
}

LoadUserSet()

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

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.LoadUserSet("Standard");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"LoadUserSet : {status}");
}
else
{
    Console.WriteLine($"LoadUserSet API call : {status}");
}

CurrentUserSet()

This API reads the name of the currently active UserSet.

var userSetMgr = cc.GetUserSetManager();
string currentUserSet;
status = userSetMgr.CurrentUserSet(out currentUserSet);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"Get CurrentUserSet {status} , currentuserset is {currentUserSet}");
}
else
{
    Console.WriteLine($"CurrentUserSet API call : {status}");
}

GetPowerOnUserSet()

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

var userSetMgr = cc.GetUserSetManager();
string powerOnUserSet;
status = userSetMgr.GetPowerOnUserSet(out powerOnUserSet);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"GetPowerOnUserSet : {status} ,name is {powerOnUserSet}");
}
else
{
    Console.WriteLine($"GetPowerOnUserSet API call : {status}");
}

SetPowerOnUserSet()

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

var userSetMgr = cc.GetUserSetManager();
status = userSetMgr.SetPowerOnUserSet("Standard");
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"SetPowerOnUserSet : {status}");
}
else
{
    Console.WriteLine($"SetPowerOnUserSet API call : {status}");
}

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 camera supports this feature.

CameraFeature feature;
status = cc.GetFeature("DepthScaleUnit", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");

FullName

Gets the full name of the feature.

CameraFeature feature;
status = cc.GetFeature("Left/ExposureTime", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");
string fullName = feature.FullName;
Console.WriteLine($"{fullName}");

FeatureType

Gets the feature type.

CameraFeature feature;
status = cc.GetFeature("Left/ExposureTime", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");
FeatureType type = feature.FeatureType;
Console.WriteLine($"FeatureType is {type}");

GetAccessMode()

Gets the access mode of the camera feature.

CameraFeature feature;
status = cc.GetFeature("DepthScaleUnit", out feature);
bool isValid = feature.IsValid();
Console.WriteLine($"Feature is {(isValid ? "Valid" : "Invalid")}");
CameraFeatureAccessMode access_mode;
status = feature.GetAccessMode(out access_mode);
if (status == CameraApiStatus.Success)
{
    Console.WriteLine($"AccessMode is {access_mode}");
}

Value Operation Methods

GetValue()

Gets the current value of the feature.

1. Integer feature

   CameraFeature feat;
   cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat);
   CameraValue currentValue;
   feat.GetValue(out currentValue);
   Console.WriteLine($"DepthSgbmTextureFilterValueOffset Current value: {currentValue.SingleValue}");
   

2. Floating-point feature

   CameraFeature feat;
   cc.GetFeature("Left/ExposureTime", out feat);
   CameraValue currentValue;
   feat.GetValue(out currentValue);
   Console.WriteLine($"Left/ExposureTime Current value: {currentValue.SingleValue}");
   

3. Enum feature

   CameraFeature feature;
   cc.GetFeature("DeviceLinkHeartbeatMode", out feature);
   CameraValue currentValue;
   feature.GetValue(out currentValue);
   Console.WriteLine($"DeviceLinkHeartbeatMode Current value: {currentValue.SingleValue}");
   

4. Boolean feature

   CameraFeature feat;
   cc.GetFeature("Texture/BalanceWhiteAuto", out feat);
   feat.SetValue(new CameraValue(CameraValueType.Int64, 31));
   CameraValue currentValue;
   feat.GetValue(out currentValue);
   Console.WriteLine($"Texture/BalanceWhiteAuto Current value: {currentValue.SingleValue}");
   

SetValue()

Sets the value of the feature.

1. Integer feature

   CameraFeature feat;
   cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat);
   status = feat.SetValue(50);
   Console.WriteLine($"SetValue: {status}");
   

2. Floating-point feature

   CameraFeature feat;
   cc.GetFeature("Left/ExposureTime", out feat);
   status = feat.SetValue(31);
   Console.WriteLine($"SetValue: {status}");
   

3. Enum feature

   CameraFeature feat;
   cc.GetFeature("TriggerSource", out feat);
   status = feat.SetValue(0);
   Console.WriteLine($"SetValue: {status}");
   

4. Boolean feature

   CameraFeature feat;
   cc.GetFeature("IRUndistortion", out feat);
   status = feat.SetValue(true);
   Console.WriteLine($"SetValue: {status}");
   

Range Query Methods

GetRange()

Gets the value range of an integer or floating-point feature.

1. Integer feature

   CameraFeature feat;
   status = cc.GetFeature("DepthSgbmTextureFilterValueOffset", out feat);
   Int64Range range;
   CameraApiStatus ret = feat.GetRange(out range);
   if (ret == CameraApiStatus.Success)
   {
       Console.WriteLine($"GetRange success : [{range.Min}, {range.Max}], Step: {range.Step}");
   }
   

2. Floating-point feature

   CameraFeature feat;
   status = cc.GetFeature("Left/ExposureTime", out feat);
   Float64Range range;
   CameraApiStatus ret = feat.GetRange(out range);
   if (ret == CameraApiStatus.Success)
   {
       Console.WriteLine($"GetRange success : [{range.Min}, {range.Max}], Step: {range.Step}");
   }
   

Enum Methods

GetEnumItems()

Gets all enum items of an enum feature.

CameraFeature feature;
status = cc.GetFeature("DeviceTimeSyncMode", out feature);
if(status == CameraApiStatus.Success)
{
    List<EnumItem> enum_list = new List<EnumItem>();
    status = feature.GetEnumItems(enum_list);
    if (status == CameraApiStatus.Success)
    {
        foreach (var item in enum_list)
        {
            Console.WriteLine($"Name: {item.Name}, Value: {item.Value}");
        }
    }
    else
    {
        Console.WriteLine($"GetEnumItems failed: {status}");
    }
}
else
{
    Console.WriteLine($"GetFeature {status}");
}