Image grabbing#

The image retrieval process starts within the camera. The device reads out the image data collected from the sensor and transfers it via GigE Vision to the host. This process is called acquisition. The acquisition can go on for a given number of frames or it can continue indefinitely until manually stopped. When images are received by the host, they’re collected in a queue managed by the ItalaApi internal acquisition engine. At this point, the user is able to grab images by calling DEV_GetNextImage . This function pops the first available image (if any) from the queue and delivers it to the client code.

Warning

The client code is responsible for the image instance lifetime. The client code must release the grabbed image when it’s no longer required, so that its memory can be reused for grabbing.

//...

// Start the acquisition process on the camera
error = DEV_StartAcquisition(hDevice);
H_IMAGE hImage = NULL;
bool isIncomplete = false;
for (size_t i = 0; i < 100; i++)
{
    ///Ask for an available image with a maximum timeout of 500ms
    error = DEV_GetNextImage(hDevice, 500, &hImage);

    //If the image is incomplete due to errors, print some info and skip it.
    error = IMG_IsIncomplete(hImage, &isIncomplete);
    if(isIncomplete){
        // Report some info if the image is partially filled.
        printf("Incomplete image.\n");
        size_t filled = 0;
        size_t payloadSize = 0;
        error = IMG_GetBytesFilled(hImage, &filled);
        error = IMG_GetPayloadSize(hImage, &payloadSize);
        printf("\tIncomplete image received.\n");
        printf("\tBytes filled: %zu/%zu\n", filled, payloadSize);
    }

    error = IMG_Dispose(hImage);
    hImage = NULL;
}
error = DEV_StopAcquisition(hDevice);

//...

The image instance is received and accessed via its handle H_IMAGE. It contains all the necessary informations to be displayed or processed via third party tools, e.g. its width, height, format, size and data pointer.

Warning

The created device instances are automatically configured to use the filter driver and packet resend functionalities for a more reliable and efficient acquisition. Make sure the filter driver component is enabled on the NIC the device is connected to. Both functionalities can be found and disabled on the DataStream nodemap provided thought the H_DEVICE handle.