Image Data Object

This tutorial demonstrates VisionWorks image data object usage.

One of the main data object in VisionWorks is vx_image. It is used to hold images, masks, and motion fields.

An image object is described by its size and format, which are also referred to as image metadata.

vx_image image = vxCreateImage(context,
                               640 /*width*/, 480 /*height*/,
                               VX_DF_IMAGE_RGB);

An image object has an attribute mechanism, which allows it to query information about the image. Some attributes can be overwritten by the application.

vx_uint32 width, height;
vxQueryImage(image, VX_IMAGE_ATTRIBUTE_WIDTH, &width, sizeof(width));
vxQueryImage(image, VX_IMAGE_ATTRIBUTE_HEIGHT, &height, sizeof(height));

vx_enum color_space = VX_COLOR_SPACE_BT601_525;
vxSetImageAttribute(image, VX_IMAGE_ATTRIBUTE_SPACE, &color_space, sizeof(color_space));

An image object is opaque and does not provide direct access to its own data. Application can map a rectangular sub-region of the image object for access. It is performed via the vxAccessImagePatch method, which accepts the intended usage of mapped memory (read only, write only, read and write) as an additional parameter. The method returns a mapped pointer and vx_imagepatch_addressing_t structure, which describes the layout of the mapped memory.

vx_rectangle_t rect = {
    0u, 0u,
    width, height
};

void* ptr = NULL; // must be NULL to access in MAP mode
vx_imagepatch_addressing_t addr;
vxAccessImagePatch(image, &rect, 0, &addr, &ptr, VX_WRITE_ONLY);

The vx_imagepatch_addressing_t structure holds full information about mapped patch memory layout : dimensions, steps in pixels, strides in bytes, and scales for sub-samples planes. Application must use this information to iterate pixel data.

vx_uint8* row_start_ptr = (vx_uint8*)ptr;
for (vx_uint32 y = 0; y < addr.dim_y; y += addr.step_y)
{
    vx_uint8* row_ptr = row_start_ptr;
    for (vx_uint32 x = 0; x < addr.dim_x; x += addr.step_x)
    {
        vx_uint8 R, G, B;
        randomColor(R, G, B);

        row_ptr[0] = R;
        row_ptr[1] = G;
        row_ptr[2] = B;

        row_ptr += addr.stride_x; // be careful, if the pixel size is more than one byte (stride_x in bytes)
    }

    row_start_ptr += addr.stride_y; // be careful, if the pixel size is more than one byte (stride_y in bytes)
}

After the application finishes manipulation with the mapped patch, it must unmap the image object using vxCommitImagePatch.

vxCommitImagePatch(image, &rect, 0, &addr, ptr);

After all operations on the image object are finished and the object is not needed by the application, the image must be released. The vxReleaseImage method decrements the reference counter of the image object, and when the counter is equal to zero, the object is destroyed.

Note

The VisionWorks framework may hold internal references to the image object (for example, if it was used in graph), so the vxReleaseImage may not destroy the image immediately.

vxReleaseImage(&image);

Other data objects in VisionWorks use the similar attributes mechanism, access/commit methods, and have the same release behavior.