Camera Capture

Introduction

These functions are responsible for capturing images from a camera.

VxDiscoverCameraDevice

Function:

C++

int VxDiscoverCameraDevices(std::vector<std::string>& devList)

Python

def VxDiscoverCameraDevices()

C#

int VxDiscoverCameraDevices(StringVector devList)

Function Description:

• This Function retrieves a list of available camera devices and stores the device names in a vector of wide strings.
• C# : The caller must create a StringVector instance before calling this function.

Parameter Description:

• devList : A vector of wide strings to store the retrieved devices.
• Return:
  • The number of camera devices detected

Example:

C++

// declare the vector to save the list of devices
std::vector<std::string> dev_list;
// discover the devices
int deviceCount = VxDiscoverCameraDevices(dev_list);
std::cout << "Found " << deviceCount << " camera(s):" << std::endl;

// print dev_list
for (size_t i = 0; i < devList.size(); i++) {
      std::cout << "[" << i << "] " << devList[i] << std::endl;
}

Python

# discover the devices
result, camera_list = pyvinzionsdk.VxDiscoverCameraDevices()
print("Return code:", result)
print("Discovered cameras:", camera_list)

# print camera_list
for camera in camera_list:
    print(camera)

C#

// discover the devices
StringVector devList = new StringVector();
int cam_num = CSVizionSDK.VxDiscoverCameraDevices(devList);
Console.WriteLine($"Devices: {cam_num}");

// print devList
for (int i = 0; i < devList.Count; i++)
{
    Console.WriteLine($"[{i}] {devList[i]}");
}

VxInitialCameraDevice

Function:

C++

std::shared_ptr<VxCamera> VxInitialCameraDevice(int devIdx)

Python

def VxInitialCameraDevice(devIdx)

C#

VxCamera VxInitialCameraDevice(int devIdx)

Function Description:

• This function initializes a VxCamera instance by selecting an index from the device list retrieved from VxDiscoverCameraDevice().
• It returns a shared pointer to the created VxCamera object, enabling shared ownership and automatic memory management.
• C# : The returned VxCamera object can be used directly in C# without manually managing memory.

Parameter Description:

• devIdx : An integer specifying the index of the device to be opened in the device list.
• return a shared pointer to the initialized device, return nullptr = FAIL

Example:

C++

// initial the camera of index 0
std::shared_ptr<VxCamera> vxcam = VxInitialCameraDevice(0);

Python

# initial the camera of index 0
vxcam = pyvizionsdk.VxInitialCameraDevice(0)

C#

// initial the camera of index 0
VxCamera vxcam = CSVizionSDK.VxInitialCameraDevice(0);

VxOpen

Function:

C++

int VxOpen(std::shared_ptr<VxCamera> vxcam)

Python

def VxOpen(vxcam)

C#

int VxOpen(VxCamera vxcam)

Function Description:

• This function is used to open a device obtained by calling VxInitialCameraDevice().

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• return 0 = PASS, return -1 = FAIL.

Example:

C++

// open the camera
VxOpen(vxcam)

Python

# open camera
pyvizionsdk.VxOpen(vxcam)

C#

// open camera
CSVizionSDK.VxOpen(vxcam)

VxClose

Function:

C++

int VxClose(std::shared_ptr<VxCamera> vxcam)

Python

def VxClose(vxcam)

C#

int VxClose(VxCamera vxcam)

Function Description:

• This function is used to close a device obtained by calling VxInitialCameraDevice().

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• return 0 = PASS, return -1 = FAIL.

Example:

C++

// close the camera
VxClose(vxcam);

Python

# close the camera
pyvizionsdk.VxClose(vxcam)

C#

// close the camera
CSVizionSDK.VxClose(vxcam)

VxIsVizionCamera

Function:

C++

int VxIsVizionCamera(std::shared_ptr<VxCamera> vxcam)

Python

def VxIsVizionCamera(vxcam)

C#

int VxIsVizionCamera(VxCamera vxcam)

Function Description:

• Verify whether the VxCamera device is TechNexion UVC or MIPI product or not.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• return 0 = PASS, return -1 = FAIL.

Example:

C++

// check the type of camera
int ret = VxIsVizionCamera(vxcam);

Python

# check the type of camera
result = pyvizionsdk.VxIsVizionCamera(vxcam)

C#

// check the type of camera
int ret = CSVizionSDK.VxIsVizionCamera(vxcam)

VxGetDeviceName

Function:

C++

int VxGetDeviceName(std::shared_ptr<VxCamera> vxcam, std::string& deviceName)

Python

def VxGetDeviceName(vxcam)

C#

int VxGetDeviceName(VxCamera vxcam, ref string deviceName)

Function Description:

• This function is used to obtain the device name.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• deviceName : A reference of string variable to store the device name.
• Return:
  • C++ / C# : return 0 = PASS, return -1 = FAIL.
  • Python : tuple(return_code, deviceName)

    return_code : return 0 = PASS, return -1 = FAIL

Example:

C++

std::string deviceName;
// get the device name of camera
VxGetDeviceName(vxcam, deviceName);

Python

# get the device name of camera
result, name = pyvizionsdk.VxGetDeviceName(vxcam)

C#

// get the device name of camera
string deviceName = "";
CSVizionSDK.VxGetDeviceName(vxcam, ref deviceName);

VxGetDeviceInterfaceType

Function:

C++

int VxGetDeviceInterfaceType(std::shared_ptr<VxCamera> vxcam, VX_CAMERA_INTERFACE_TYPE& type);

Python

def VxGetDeviceInterfaceType(vxcam)

C#

int VxGetDeviceInterfaceType(VxCamera vxcam, out VX_CAMERA_INTERFACE_TYPE type)

Function Description:

• This function is used to obtain the type of device interface.
• The device interface type is set as VX_CAMERA_INTERFACE_TYPE format.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().

• type : A VX_CAMERA_INTERFACE_TYPE format variable, which is used to store the interface type.

• Return:

  • C++ / C# : return 0 = PASS, return -1 = FAIL
  • Python : tuple(return_code, type)

    return_code : return 0 = PASS, return -1 = FAIL

• VX_CAMERA_INTERFACE_TYPE format:

  C++

  enum class VX_CAMERA_INTERFACE_TYPE {
      INTERFACE_USB = 0,
      INTERFACE_MIPI_CSI2,
      INTERFACE_ETHERNET,
  }

  Python

  class VX_CAMERA_INTERFACE_TYPE(Enum):
      INTERFACE_USB = 0
      INTERFACE_MIPI_CSI2 = 1
      INTERFACE_ETHERNET = 2

  C#

  public enum VX_CAMERA_INTERFACE_TYPE{
      INTERFACE_USB,
      INTERFACE_MIPI_CSI2,
      INTERFACE_ETHERNET,
  }

Example:

C++

VX_CAMERA_INTERFACE_TYPE type;
// get the device interface type of camera
VxGetDeviceInterfaceType(vxcam, type);

Python

result, tyname = pyvizionsdk.VxGetDeviceInterfaceType(vxcam)

C#

VX_CAMERA_INTERFACE_TYPE type;
// get the device interface type of camera
CSVizionSDK.VxGetDeviceInterfaceType(vxcam, out type);

VxGetHardwareID

Function:

C++

int VxGetHardwareID(std::shared_ptr<VxCamera> vxcam, std::string& hwId)

Python

def VxGetHardwareID(vxcam)

C#

int VxGetHardwareID(VxCamer vxcam, ref string hwId)

Function Description:

• This function is used to obtain the hardware ID of the device.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• hwId : A reference of string variable to store the hardware ID.
• Return:
  • C++ / C# : return 0 = PASS, return -1 = FAIL
  • Python : tuple(return_code, hwId)

    return_code : return 0 = PASS, return -1 = FAIL

Example:

C++

std::string hwId;
// get the hardware ID of camera
VxGetHardwareID(vxcam, hwId);

Python

# get the hardware ID of camera
result, hwId = pyvizionsdk.VxGetHardwareID(vxcam)

C#

string hwId = "";
// get the hardware ID of camera
CSVizionSDK.VxGetHardwareID(vxcam, ref hwId);

VxGetUSBDeviceSpeed

Function:

C++

int VxGetUSBDeviceSpeed(std::shared_ptr<VxCamera> vxcam, VX_USB_DEVICE_SPEED& speed)

Python

def VxGetUSBDeviceSpeed(vxcam)

C#

int VxGetUSBDeviceSpeed(VxCamera vxcam, out VX_USB_DEVICE_SPEED speed)

Function Description:

• This function is used to obtain the speed of the USB device.
• The speed is set as VX_USB_DEVICE_SPEED format.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().

• speed : A reference of VX_USB_DEVICE_SPEED format variable to store the speed.

• Return:

  • C++ / C# : return 0 = PASS, return -1 = FAIL
  • Python : tuple(return_code, speed)

    return_code : return 0 = PASS, return -1 = FAIL

• VX_USB_DEVICE_SPEED format:

  C++

  enum class VX_USB_DEVICE_SPEED {
      USB_DEVICE_SPEED_LOW,
      USB_DEVICE_SPEED_FULL,
      USB_DEVICE_SPEED_HIGH,
      USB_DEVICE_SPEED_SUPER,
      USB_DEVICE_SPEED_SUPER_PLUS,
      USB_DEVICE_SPEED_UNKNOWN
  }

  Python

  class VX_USB_DEVICE_SPEED(Enum):
      USB_DEVICE_SPEED_LOW = 0
      USB_DEVICE_SPEED_FULL = 1
      USB_DEVICE_SPEED_HIGH = 2
      USB_DEVICE_SPEED_SUPER = 3
      USB_DEVICE_SPEED_SUPER_PLUS = 4
      USB_DEVICE_SPEED_UNKNOWN = 5

  C#

  public enum VX_USB_DEVICE_SPEED {
      USB_DEVICE_SPEED_LOW,
      USB_DEVICE_SPEED_FULL,
      USB_DEVICE_SPEED_HIGH,
      USB_DEVICE_SPEED_SUPER,
      USB_DEVICE_SPEED_SUPER_PLUS,
      USB_DEVICE_SPEED_UNKNOWN
  }

Example:

C++

VX_USB_DEVICE_SPEED speed;
// get the hardware ID of camera
VxGetUSBDeviceSpeed(vxcam, speed);

Python

result, speed = pyvizionsdk.VxGetUSBDeviceSpeed(vxcam)

C#

VX_USB_DEVICE_SPEED speed;
// get the hardware ID of camera
CSVizionSDK.VxGetUSBDeviceSpeed(vxcam, out speed);

VxGetFormatList

Function:

C++

int VxGetFormatList(std::shared_ptr<VxCamera> vxcam, std::vector<VxFormat>& fmtList)

Python

def VxGetFormatList(vxcam)

C#

int VxGetFormatList(VxCamera vxcam, VxFormatVector fmtList)

Function Description:

• This function is used to obtain the list of formats from the VxCamera device.
  info

  To retrieve the available formats of a VxCamera device, first create a vector of VxFormat structures, and then call VxGetFormatList function passing in the VxCamera object and the vector as parameters.

• C# : The caller must create a VxFormatVector instance before calling this function.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().

• fmtList : A vector of VxFormat structures. The function will populate this vector with the available formats.

• Return:

  • C++ / C# : return 0 = PASS, return -1 = FAIL
  • Python : tuple(return_code, fmtList)

    return_code : return 0 = PASS, return -1 = FAIL

• VxFormat structures:

C++

struct VxFormat {
    uint8_t mediatypeIdx;
    uint16_t width;
    uint16_t height;
    uint16_t framerate;
    VX_IMAGE_FORMAT format;
}

Python

class VxFormat:
  def __init__(self, width, height, framerate, format):
      self.width = width
      self.height = height
      self.framerate = framerate
      self.format = format

C#

public struct VxFormat {
    public byte mediatypeIdx;
    public ushort width;
    public ushort height;
    public ushort framerate;
    public VX_IMAGE_FORMAT format;
}

• VX_IMAGE_FORMAT format:

C++

enum class VX_IMAGE_FORMAT {
    NONE = 0,
    YUY2,
    UYVY,
    NV12,
    MJPG,
    BGRA,
    BGRX,
    BGR,
    RGB16,
    RGB,
}

Python

class VX_IMAGE_FORMAT(Enum):
    VX_IMAGE_FORMAT_NONE = 0
    VX_IMAGE_FORMAT_YUY2 = 1
    VX_IMAGE_FORMAT_UYVY = 2
    VX_IMAGE_FORMAT_NV12 = 3
    VX_IMAGE_FORMAT_BGRA = 4
    VX_IMAGE_FORMAT_BGRX = 5
    VX_IMAGE_FORMAT_BGR  = 6
    VX_IMAGE_FORMAT_RGB16 = 7
    VX_IMAGE_FORMAT_RGB  = 8

C#

public enum VX_IMAGE_FORMAT {
    NONE,
    YUY2,
    UYVY,
    NV12,
    MJPG,
    BGRA,
    BGRX,
    BGR,
    RGB16,
    RGB,
}

Example:

C++

std::vector<VxFormat> fmt_list;
// get the list of formats from the camera
VxGetFormatList(vxcam, fmt_list);

Python

# get the list of format
result, format_list = pyvizionsdk.VxGetFormatList(vxcam)

C#

VxFormatVector fmtList = new VxFormatVector();
// get the list of formats from the camera
CSVizionSDK.VxGetFormatList(vxcam, fmtList);

VxSetFormat

Function:

C++

int VxSetFormat(std::shared_ptr<VxCamera> vxcam, VxFormat fmt)

Python

def VxSetFormat(vxcam, fmt)

C#

int VxSetFormat(VxCamera vxcam, VxFormat fmt)

Function Description:

• This function is used to set the specified format to the VxCamera device.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• fmt : A VxFormat format to be set. The format must be obtained from the VxGetFormatList().
• return 0 = PASS, return -1 = FAIL.

Example:

C++

// get format list
std::vector<VxFormat> fmt_list;
VxGetFormatList(vxcam, fmt_list);
// set the format
VxSetFormat(vxcam, fmt_list[0]);

Python

# get format
result, format_list = pyvizionsdk.VxGetFormatList(vxcam)
# set format
result = pyvizionsdk.VxSetFormat(vxcam, format_list[0])

C#

// get format list
VxFormatVector fmtList = new VxFormatVector();
CSVizionSDK.VxGetFormatList(vxcam, fmtList);
// set the format
CSVizionSDK.VxSetFormat(vxcam, fmtList[0]);

VxStartStreaming

Function:

C++

int VxStartStreaming(std::shared_ptr<VxCamera> vxcam)

Python

def VxStartStreaming(vxcam)

C#

int VxStartStreaming(VxCamera vxcam)

Function Description:

• This function is for starting streaming on the device.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• return 0 = PASS, return -1 = FAIL.

Example:

C++

// start streaming the camera
VxStartStreaming(vxcam);

Python

# start streaming the camera
pyvizionsdk.VxStartStreaming(vxcam)

C#

// start streaming the camera
CSVizionSDK.VxStartStreaming(vxcam);

VxStopStreaming

Function:

C++

int VxStopStreaming(std::shared_ptr<VxCamera> vxcam)

Python

def VxStopStreaming(vxcam)

C#

int VxStopStreaming(VxCamera vxcam)

Function Description:

• This function is for stopping streaming on the VxCamera device.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• return 0 = PASS, return -1 = FAIL.

Example:

C++

// stop streaming the camera
VxStopStreaming(vxcam);

Python

# stop streaming the camera
pyvizionsdk.VxStopStreaming(vxcam)

C#

// stop streaming the camera
CSVizionSDK.VxStopStreaming(vxcam);

VxGetImage

Function:

C++

VX_CAPTURE_RESULT VxGetImage(std::shared_ptr<VxCamera> vxcam,
                                uint8_t* data,
                                int* dataSize,
                                uint16_t timeout)

Python

def VxGetImage(vxcam, timeout, fmt)

C#

VX_CAPTURE_RESULT VxGetImage(VxCamera vxcam,
                             byte[] data,
                             out int dataSize,
                             ushort timeout)

Function Description:

• This function is used to capture the image from the VxCamera device.

info

For developers seeking to handle raw data, the vizionsdk-opencv repository provides examples such as saveImg and captureImg, which demonstrate the integration of OpenCV with UYVY and MJPG formats.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• data : A pointer to the buffer that stores the raw image data.
• dataSize : A pointer to an integer that stores the size of the raw image data.
• timeout : The timeout value in milliseconds.
• fmt : A VxFormat format to be set.

Return Values:

• C++ / C#:

  • VX_SUCCESS = 0
  • VX_TIMEOUT = -1
  • VX_CAM_OCCUPIED = -2
  • VX_OTHER_ERROR = -3
  • VX_BUFFER_CORRUPTED = -4

• Python:

  • tuple(return_code, img)

    return_code : return value same as C++/C#
    img is stored in a numpy array

Example:

C++

// get format list
std::vector<VxFormat> fmt_list;
VxGetFormatList(cam, fmt_list);
// get mjpg format
VxFormat mjpg_fmt;
for (auto fmt : fmt_list) {
    // find MJPG format
    if (fmt.format == VX_IMAGE_FORMAT::MJPG) {
        mjpg_fmt = fmt;
    }
}

// set the MJPG format
VxSetFormat(cam, mjpg_fmt);
// start streaming
VxStartStreaming(cam);

// get the MJPG format image
uint8_t* raw_data = new uint8_t[3840 * 2160 * 2];
int raw_size = 0;
VxGetImage(cam, raw_data, &raw_size, 2500);

Python

# get format
result, format_list = pyvizionsdk.VxGetFormatList(camera)
mjpg_format = None
for format in format_list:
    # get mjpg format
    if format.format == VX_IMAGE_FORMAT.VX_IMAGE_FORMAT_MJPG:
        mjpg_format = format

# set format
result = pyvizionsdk.VxSetFormat(camera, mjpg_format)
# start streaming
result = pyvizionsdk.VxStartStreaming(camera)

# get the MJPG format image
result, image = pyvizionsdk.VxGetImage(camera, 2500, mjpg_format)

C#

// get format list
VxFormatVector fmtList = new VxFormatVector();
CSVizionSDK.VxGetFormatList(vxcam, fmtList);
// get mjpg format
VxFormat mjpgFormat = new VxFormat();
foreach (VxFormat fmt in fmtList)
{
    if (fmt.format == VX_IMAGE_FORMAT.MJPG)
    {
        mjpgFormat = fmt;
    }
}

// set the MJPG format
CSVizionSDK.VxSetFormat(cam, mjpgFormat);
// start streaming
CSVizionSDK.VxStartStreaming(cam);

// get the MJPG format image
int dataSize;
byte[] buffer = new byte[mjpgFormat.width * mjpgFormat.height * 2];
VX_CAPTURE_RESULT result = CSVizionSDK.VxGetImage(cam, buffer, out dataSize, 2500);

VxGetImageFd

warning

This function is only supported in C++ and works only when the image buffer is allocated using a DMA buffer.

Function:

VX_CAPTURE_RESULT VxGetImageFd(std::shared_ptr<VxCamera> vxcam,
                                                int* dmaBufferFd,
                                                uint16_t timeout)

Function Description:

• This function is used to capture the image from the device and store it in a DMA buffer.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• dmaBufferFd : A pointer to DMA buffer file descriptor that stores the raw image data.
• timeout : The timeout value in milliseconds.

Return Values:

• VX_SUCCESS = 0
• VX_TIMEOUT = -1
• VX_CAM_OCCUPIED = -2
• VX_OTHER_ERROR = -3
• VX_BUFFER_CORRUPTED = -4

Example:

int dmaBufferFd;
uint16_t timeout;
// get the image to DMA buffer
VxGetImageFd(vxcam, dmaBufferFd, timeout);

VxReleaseImageFd

warning

This function is only supported in C++ and works only when the image buffer is allocated using a DMA buffer.

Function:

int VxReleaseImageFd(std::shared_ptr<VxCamera> vxcam, int dmaBufferFd)

Function Description:

• This function is used to release the image stored in a DMA buffer.

Parameter Description:

• vxcam : A pointer shared ownership of a camera obtained from VxInitialCameraDevice().
• dmaBufferFd : A DMA buffer file descriptor that stores the raw image data.
• return 0 = PASS, return -1 = FAIL.

Example:

int dmaBufferFd;
// release the image from the DMA buffer
VxReleaseImageFd(vxcam, dmaBufferFd);