Camera Capture

Introduction

These functions are responsible for capturing images from a camera.

VxDiscoverCameraDevice

• Function:

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

def VxDiscoverCameraDevices()

• Function Description:

1. This function retrieves a list of available camera devices and stores the device names in a vector of strings.

• Parameter Description:

1. devList: A vector of strings to store the retrieved device names.

2. Return:

   1. C++: devList.size()

   2. Python: tuple(devList.size(), devList)

• Example:

// declare the vector to save the list of devices
std::vector<std::string> dev_list;
// discover the devices
VxDiscoverCameraDevices(dev_list);

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

VxInitialCameraDevice

• Function:

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

def VxInitialCameraDevice(devIdx)

• Function Description:

1. This function initializes a VxCamera instance by selecting an index from the device list retrieved from VxDiscoverCameraDevice().

2. It returns a shared pointer to the created VxCamera object, enabling shared ownership and automatic memory management.

• Parameter Description:

1. devIdx: An integer specifying the index of the device to be opened in the device list.

2. return a shared pointer to the initialized device, return nullptr = FAIL

• Example:

int devIdx = 0;
// initial the camera to obtain the pointer point to camera device
auto vxcam = VxInitialCameraDevice(devIdx); 

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

VxOpen

• Function:

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

def VxOpen(vxcam)

• Function Description:

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

• Parameter Description:

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

2. return 0 = PASS, return -1 = FAIL.

• Example:

// initial the camera to obtain the pointer point to the camera device
auto vxcam = VxInitialCameraDevice(dev_idx);
// open the camera
VxOpen(vxcam);

# open camera
pyvinzionsdk.VxOpen(vxcam)

VxClose

• Function:

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

def VxClose(vxcam)

• Function Description:

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

• Parameter Description:

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

2. return 0 = PASS, return -1 = FAIL.

• Example:

// close the camera
VxClose(vxcam);

# close the camera
pyvizionsdk.VxClose(vxcam)

VxIsVizionCamera

• Function:

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

def VxIsVizionCamera(vxcam)

• Function Description:

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

• Parameter Description:

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

2. return 0 = PASS, return -1 = FAIL.

• Example:

// check the type of camera
VxIsVizionCamera(vxcam);

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

VxGetDeviceName

• Function:

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

def VxGetDeviceName(vxcam)

• Function Description:

1. This function is used to obtain the device name.

• Parameter Description:

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

2. deviceName: A reference of string variable to store the device name.

3. Return:

   1. C++: 0 = PASS, return -1 = FAIL.

   2. Python: tuple(return_code, deviceName)

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

• Example:

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

# get the device name of camer
result, name = pyvizionsdk.VxGetDeviceName(vxcam)
print("Device name:", name)
print("Return code:", result)

VxGetDeviceInterfaceType

• Function:

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

def VxGetDeviceInterfaceType(vxcam)

• Function Description:

1. This function is used to obtain the type of device interface.

2. The device interface type is set as VX_CAMERA_INTERFACE_TYPE format.

• Parameter Description:

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

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

3. Return:

   1. C++: return 0 = PASS, return -1 = FAIL

   2. Python: tuple(return_code, type)

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

4. VX_CAMERA_INTERFACE_TYPE format:

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

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

• Example:

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

result, tyname = pyvizionsdk.VxGetDeviceInterfaceType(vxcam)
print("Device Interface type name:", tyname)
print("Return code:", result)

VxGetHardwareID

• Function:

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

def VxGetHardwareID(vxcam)

• Function Description:

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

• Parameter Description:

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

2. hwId: A reference of string variable to store the hardware ID.

3. Return:

   1. C++: return 0 = PASS, return -1 = FAIL

   2. Python: tuple(return_code, hwId)

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

• Example:

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

# get the hardware ID of camera
result, hwId = pyvizionsdk.VxGetHardwareID(vxcam)
print("Hardware ID:", hwId)
print("Return code:", result)

VxGetUSBDeviceSpeed

• Function:

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

def VxGetUSBDeviceSpeed(vxcam)

• Function Description:

1. This function is used to obtain the speed of the USB device.

2. The speed is set as VX_USB_DEVICE_SPEED format.

• Parameter Description:

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

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

3. Return:

   1. C++: return 0 = PASS, return -1 = FAIL

   2. Python: tuple(return_code, speed)

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

4. VX_USB_DEVICE_SPEED format:

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
};

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

• Example:

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

result, speed = pyvizionsdk.VxGetUSBDeviceSpeed(vxcam)
print("USB device speed:", speed)
print("Return code:", result)

VxGetFormatList

• Function:

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

def VxGetFormatList(vxcam)

• Function Description:

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

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

• Parameter Description:

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

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

3. Return:

   1. C++: return 0 = PASS, return -1 = FAIL

   2. Python: tuple(return_code, fmtList)

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

4. VxFormat structures:

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

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

5. VX_IMAGE_FORMAT format:

enum class VX_IMAGE_FORMAT {
    NONE = 0,
    YUY2,
    UYVY,
    NV12,
    MJPG,
};

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_MJPG = 4

• Example:

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

# get the list of format
result, format_list = pyvizionsdk.VxGetFormatList(vxcam)
print("Return code:", result)

VxSetFormat

• Function:

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

int VxSetFormat(vxcam, fmt)

• Function Description:

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

• Parameter Description:

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

2. fmt: A VxFormat format to be set. The format must be obtained from the VxGetFormatList().

3. return 0 = PASS, return -1 = FAIL.

• Example:

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

# get format
result, format_list = pyvizionsdk.VxGetFormatList(camera)
# set format
result = pyvizionsdk.VxSetFormat(camera, format_list[0])
print("Set format return code:", result)

VxStartStreaming

• Function:

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

def VxStartStreaming(vxcam)

• Function Description:

1. This function is for starting streaming on the device.

• Parameter Description:

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

2. return 0 = PASS, return -1 = FAIL.

• Example:

// start streaming the camera
VxStartStreaming(vxcam);

# start streaming the camera
pyvizionsdk.VxStartStreaming(vxcam)

VxStopStreaming

• Function:

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

def VxStopStreaming(vxcam)

• Function Description:

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

• Parameter Description:

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

2. return 0 = PASS, return -1 = FAIL.

• Example:

// stop streaming the camera
VxStopStreaming(vxcam);

# stop streaming the camera
pyvizionsdk.VxStopStreaming(vxcam)

VxGetImage

• Function:

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

def VxGetImage(vxcam, timeout, fmt)

• Function Description:

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

• Parameter Description:

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

2. data: A pointer to the buffer that stores the raw image data.

3. dataSize: A pointer to an integer that stores the size of the raw image data.

4. timeout: The timeout value in milliseconds.

5. fmt: A VxFormat format to be set.

• Return Values:

  • 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++

      ※ img is stored in a numpy array

• Example:

// 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);

# 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, 1000, mjpg_format)

VxGetImageFd

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:

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

• Parameter Description:

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

2. dmaBufferFd: A pointer to DMA buffer file descriptor that stores the raw image data.

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

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:

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

• Parameter Description:

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

2. dmaBufferFd: A DMA buffer file descriptor that stores the raw image data.

3. return 0 = PASS, return -1 = FAIL.

• Example:

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