The OpenVX Specification  2b213f9
Object: Pyramid

## Detailed Description

Defines the Image Pyramid Object Interface.

A Pyramid object in OpenVX represents a collection of related images. Typically, these images are created by either downscaling or upscaling a base image, contained in level zero of the pyramid. Successive levels of the pyramid increase or decrease in size by a factor given by the VX_PYRAMID_SCALE attribute. For instance, in a pyramid with 3 levels and VX_SCALE_PYRAMID_HALF, the level one image is one-half the width and one-half the height of the level zero image, and the level two image is one-quarter the width and one quarter the height of the level zero image. When downscaling or upscaling results in a non-integral number of pixels at any level, fractional pixels always get rounded up to the nearest integer. (E.g., a 3-level image pyramid beginning with level zero having a width of 9 and a scaling of VX_SCALE_PYRAMID_HALF results in the level one image with a width of $$5 = \mathbf{ceil}(9*0.5)$$ and a level two image with a width of $$3 = \mathbf{ceil}(5*0.5)$$. Position $$(r_N,c_N)$$ at level $$N$$ corresponds to position $$(r_{N-1}/\mathbf{scale}, c_{N-1}/\mathbf{scale})$$ at level $$N-1$$.

## Macros

#define VX_SCALE_PYRAMID_HALF   (0.5f)
Use to indicate a half-scale pyramid.

#define VX_SCALE_PYRAMID_ORB   ((vx_float32)0.8408964f)
Use to indicate a ORB scaled pyramid whose scaling factor is $$\frac{1}{\root 4 \of {2}}$$.

## Typedefs

typedef struct _vx_pyramid * vx_pyramid
The Image Pyramid object. A set of scaled images.

## Enumerations

enum  vx_pyramid_attribute_e {
VX_PYRAMID_LEVELS = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x0,
VX_PYRAMID_SCALE = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x1,
VX_PYRAMID_WIDTH = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x2,
VX_PYRAMID_HEIGHT = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x3,
VX_PYRAMID_FORMAT = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x4
}
The pyramid object attributes. More...

## Functions

vx_pyramid VX_API_CALL vxCreatePyramid (vx_context context, vx_size levels, vx_float32 scale, vx_uint32 width, vx_uint32 height, vx_df_image format)
Creates a reference to a pyramid object of the supplied number of levels. More...

vx_pyramid VX_API_CALL vxCreateVirtualPyramid (vx_graph graph, vx_size levels, vx_float32 scale, vx_uint32 width, vx_uint32 height, vx_df_image format)
Creates a reference to a virtual pyramid object of the supplied number of levels. More...

vx_image VX_API_CALL vxGetPyramidLevel (vx_pyramid pyr, vx_uint32 index)
Retrieves a level of the pyramid as a vx_image, which can be used elsewhere in OpenVX. A call to vxReleaseImage is necessary to release an image for each call of vxGetPyramidLevel. More...

vx_status VX_API_CALL vxQueryPyramid (vx_pyramid pyr, vx_enum attribute, void *ptr, vx_size size)
Queries an attribute from an image pyramid. More...

vx_status VX_API_CALL vxReleasePyramid (vx_pyramid *pyr)
Releases a reference to a pyramid object. The object may not be garbage collected until its total reference count is zero. More...

## Enumeration Type Documentation

The pyramid object attributes.

Enumerator
VX_PYRAMID_LEVELS

The number of levels of the pyramid. Read-only. Use a vx_size parameter.

VX_PYRAMID_SCALE

The scale factor between each level of the pyramid. Read-only. Use a vx_float32 parameter.

VX_PYRAMID_WIDTH

The width of the 0th image in pixels. Read-only. Use a vx_uint32 parameter.

VX_PYRAMID_HEIGHT

The height of the 0th image in pixels. Read-only. Use a vx_uint32 parameter.

VX_PYRAMID_FORMAT

The vx_df_image_e format of the image. Read-only. Use a vx_df_image parameter.

Definition at line 1045 of file vx_types.h.

## Function Documentation

 vx_pyramid VX_API_CALL vxCreatePyramid ( vx_context context, vx_size levels, vx_float32 scale, vx_uint32 width, vx_uint32 height, vx_df_image format )

Creates a reference to a pyramid object of the supplied number of levels.

Parameters
 [in] context The reference to the overall context. [in] levels The number of levels desired. This is required to be a non-zero value. [in] scale Used to indicate the scale between pyramid levels. This is required to be a non-zero positive value. Only permissible values are VX_SCALE_PYRAMID_HALF or VX_SCALE_PYRAMID_ORB. [in] width The width of the 0th level image in pixels. [in] height The height of the 0th level image in pixels. [in] format The format of all images in the pyramid. NV12, NV21, IYUV, UYVY and YUYV formats are not supported.
Returns
A pyramid reference vx_pyramid containing the sub-images. Any possible errors preventing a successful creation should be checked using vxGetStatus.
 vx_pyramid VX_API_CALL vxCreateVirtualPyramid ( vx_graph graph, vx_size levels, vx_float32 scale, vx_uint32 width, vx_uint32 height, vx_df_image format )

Creates a reference to a virtual pyramid object of the supplied number of levels.

Virtual Pyramids can be used to connect Nodes together when the contents of the pyramids will not be accessed by the user of the API. All of the following constructions are valid:

vx_graph graph = vxCreateGraph(context);
vx_pyramid virt[] = {
vxCreateVirtualPyramid(graph, 4, VX_SCALE_PYRAMID_HALF, 0, 0, VX_DF_IMAGE_VIRT), // no dimension and format specified for level 0
vxCreateVirtualPyramid(graph, 4, VX_SCALE_PYRAMID_HALF, 640, 480, VX_DF_IMAGE_VIRT), // no format specified.
vxCreateVirtualPyramid(graph, 4, VX_SCALE_PYRAMID_HALF, 640, 480, VX_DF_IMAGE_U8), // no access
};
Parameters
 [in] graph The reference to the parent graph. [in] levels The number of levels desired. This is required to be a non-zero value. [in] scale Used to indicate the scale between pyramid levels. This is required to be a non-zero positive value. Only permissible values are VX_SCALE_PYRAMID_HALF or VX_SCALE_PYRAMID_ORB. [in] width The width of the 0th level image in pixels. This may be set to zero to indicate to the interface that the value is unspecified. [in] height The height of the 0th level image in pixels. This may be set to zero to indicate to the interface that the value is unspecified. [in] format The format of all images in the pyramid. This may be set to VX_DF_IMAGE_VIRT to indicate that the format is unspecified.
Returns
A pyramid reference vx_pyramid. Any possible errors preventing a successful creation should be checked using vxGetStatus.
Note
Images extracted with vxGetPyramidLevel behave as Virtual Images and cause vxMapImagePatch to return errors.
 vx_status VX_API_CALL vxReleasePyramid ( vx_pyramid * pyr )

Releases a reference to a pyramid object. The object may not be garbage collected until its total reference count is zero.

Parameters
 [in] pyr The pointer to the pyramid to release.
Returns
A vx_status_e enumeration.
Return values
 VX_SUCCESS No errors. VX_ERROR_INVALID_REFERENCE If pyr is not a vx_pyramid.
Postcondition
After returning from this function the reference is zeroed.
 vx_status VX_API_CALL vxQueryPyramid ( vx_pyramid pyr, vx_enum attribute, void * ptr, vx_size size )

Queries an attribute from an image pyramid.

Parameters
 [in] pyr The pyramid to query. [in] attribute The attribute for which to query. Use a vx_pyramid_attribute_e enumeration. [out] ptr The location at which to store the resulting value. [in] size The size in bytes of the container to which ptr points.
Returns
A vx_status_e enumeration.
 vx_image VX_API_CALL vxGetPyramidLevel ( vx_pyramid pyr, vx_uint32 index )

Retrieves a level of the pyramid as a vx_image, which can be used elsewhere in OpenVX. A call to vxReleaseImage is necessary to release an image for each call of vxGetPyramidLevel.

Parameters
 [in] pyr The pyramid object. [in] index The index of the level, such that index is less than levels.
Returns
A vx_image reference. Any possible errors preventing a successful creation should be checked using vxGetStatus.
Return values
 0 Indicates that the index or the object is invalid.