Example Code

This section shows snippets of code that perform basic camera management tasks. This section also describes the buildable example code projects included in the Emergent SDK (eSDK).

See eSDK Code Examples for information about how to build and run the example code projects.

Example code snippets

The following example code snippets help you to start using the Emergent eSDK. It covers camera initialization, parameter configuration, triggering modes, frame acquisition, and cleanup. These examples align with the structure and function of EVT_BenchmarkHS.cpp, the primary eSDK example for high-speed image capture, ensuring compatibility with performance-focused applications.

The examples perform the following camera management tasks:

• Initial setup and device enumeration
• Configure basic camera parameters
• Configure trigger modes
• Acquire and buffer frames
• Close cameras and cleanup
• Handle errors

Initial setup and device enumeration

To begin, include the necessary headers and initialize variables. Here, the EVT_ListDevices function finds available cameras, and EVT_CameraOpen opens the first compatible camera found.

#include <EmergentCameraAPIs.h>
#include <emergentframe.h>

int main() {
    CEmergentCamera camera;
    struct GigEVisionDeviceInfo deviceInfo[MAX_CAMERAS];
    unsigned int count;

    // List devices
    EVT_ListDevices(deviceInfo, &MAX_CAMERAS, &count);
    if (count == 0) {
        printf("No cameras found. Exiting...\n");
        return -1;
    }

    // Open the first camera
    if (EVT_CameraOpen(&camera, &deviceInfo[0]) != EVT_SUCCESS) {
        printf("Failed to open camera.\n");
        return -1;
    }

    printf("Camera opened successfully.\n");
    EVT_CameraClose(&camera);
    return 0;
}

‍

Configure basic camera parameters

To set essential camera attributes like exposure, gain, and frame rate, first check the allowable limits using EVT_CameraGetUInt32ParamMin and EVT_CameraGetUInt32ParamMax, then set the values within that range using EVT_CameraSetUInt32Param.

unsigned int exposure = 1000; // Desired exposure time in microseconds
unsigned int frame_rate = 30; // Desired frame rate in frames per second
unsigned int min_value, max_value;

// Check and set exposure within limits
EVT_CameraGetUInt32ParamMin(&camera, "Exposure", &min_value);
EVT_CameraGetUInt32ParamMax(&camera, "Exposure", &max_value);
if (exposure < min_value || exposure > max_value) {
    exposure = min_value; // Set to minimum if outside range (adjust as needed)
}
EVT_CameraSetUInt32Param(&camera, "Exposure", exposure);

// Check and set frame rate within limits
EVT_CameraGetUInt32ParamMin(&camera, "FrameRate", &min_value);
EVT_CameraGetUInt32ParamMax(&camera, "FrameRate", &max_value);
if (frame_rate < min_value || frame_rate > max_value) {
    frame_rate = min_value; // Set to minimum if outside range (adjust as needed)
}
EVT_CameraSetUInt32Param(&camera, "FrameRate", frame_rate);

‍

Configure trigger modes

This example demonstrates configuring different trigger modes. Use EVT_CameraSetEnumParam to control the acquisition mode and trigger source.

// Internal trigger (continuous mode)
EVT_CameraSetEnumParam(&camera, "AcquisitionMode", "Continuous");
EVT_CameraSetEnumParam(&camera, "TriggerMode", "Off");

// Software trigger mode
EVT_CameraSetEnumParam(&camera, "AcquisitionMode", "MultiFrame");
EVT_CameraSetEnumParam(&camera, "TriggerMode", "On");
EVT_CameraSetEnumParam(&camera, "TriggerSource", "Software");

// To initiate capture in software trigger mode:
EVT_CameraExecuteCommand(&camera, "TriggerSoftware");

// For hardware trigger setup, specify GPIO (general-purpose input/output) settings:
EVT_CameraSetEnumParam(&camera, "TriggerSource", "Hardware");
EVT_CameraSetEnumParam(&camera, "GPI_Start_Exp_Mode", "GPI_4"); // Example GPIO input

‍

Acquire and buffer frames

To acquire frames, allocate buffers with EVT_AllocateFrameBuffer, then queue frames using EVT_CameraQueueFrame. Retrieve frames with EVT_CameraGetFrame and requeue them to maintain continuous capture.

CEmergentFrame frame;
frame.size_x = width;          // Set frame width
frame.size_y = height;         // Set frame height
frame.pixel_type = GVSP_PIX_MONO8; // Define pixel format

// Allocate frame buffer
EVT_AllocateFrameBuffer(&camera, &frame, EVT_FRAME_BUFFER_ZERO_COPY);

// Queue the frame
EVT_CameraQueueFrame(&camera, &frame);

// Retrieve and process frames
if (EVT_CameraGetFrame(&camera, &frame, 100) == EVT_SUCCESS) {
    // Process frame data from frame.imagePtr
}

// Release memory for the frame
EVT_ReleaseFrameBuffer(&camera, &frame);

‍

Close cameras and cleanup

To clean up, close the camera and release resources.

EVT_CameraCloseStream(&camera);
EVT_CameraClose(&camera);
printf("Camera closed.\n");

‍

Handle errors

Each API function returns an error code (e.g., EVT_SUCCESS, EVT_ERROR_DEVICE_NOT_CONNECTED). Check each return value and handle errors accordingly. This helps in diagnosing connection issues or incorrect parameter settings.

EVT_ERROR status = EVT_CameraOpen(&camera, &deviceInfo[0]);
if (status != EVT_SUCCESS) {
    printf("Error opening camera: %d\n", status);
    return -1;
}

‍

Example code projects

Example code for managing Emergent Vision Technologies cameras is available as buildable example projects in the C:\Program Files\EVT\eSDK\Examples directory on Windows or /opt/EVT/eSDK/Examples on Linux. Each project demonstrates specific functions and camera features covered in this document, providing a practical resource for software developers.

For developers new to the eSDK, we recommend starting with EVT_BenchmarkHS or EVT_BenchmarkHS.NET to understand basic camera configuration and performance features.

You can open, compile, and run all example projects in Visual Studio on Windows or with the provided makefiles and g++ on Linux. Below, the examples are listed by priority and use case:

• EVT_BenchmarkHS – C++ example for benchmarking your camera at maximum resolution and frame rate. Recommended for developers starting with Emergent camera applications.
• EVT_BenchmarkHS.NET – C# example for benchmarking your camera at maximum resolution and frame rate. Recommended for developers using .NET.
• EVT_BenchmarkHS_GpuDirect – Advanced C++ benchmarking program designed to leverage NVIDIA GPU Direct technology for high-speed, low-latency data transfers directly between the NIC and the GPU. Requires a compatible NVIDIA GPU, NIC, and the CUDA toolkit.
• EVT_AcquisitionControl – Demonstrates acquisition control features, including starting and stopping streams.
• EVT_AnalogControl – Exercises analog control features, such as gain and offset adjustments.
• EVT_DeviceInformation – Displays camera and device information.
• EVT_GPIO – Shows various triggering methods through GPIO control.
• EVT_ImageFormatControl – Demonstrates pixel format options and file-saving functionality for captured images.
• EVT_Mcast/EVT_Mcast_Master – Shows multicast setup and usage as the master.
• EVT_Mcast/EVT_Mcast_Slave – Shows multicast setup and usage as the slave.
• EVT_PTP – Demonstrates Precision Time Protocol (PTP) for time synchronization.
• EVT_Py – Python-based interface to configure cameras, acquire images, and perform basic processing tasks within Python. Requires Python 3.10 or above and specific dependencies (Pillow, cffi, numba).
• EVT_VI – Basic LabVIEW interface for controlling and capturing images from Emergent cameras. Requires LabVIEW with Vision Development and Emergent eSDK.