The OpenVX Specification  a73e458
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 [R00125]. (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$$.

## Modules

The pyramid object attributes.
The pyramid object attributes.

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

## 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 [R01122]. 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 [R01135]. More...

vx_image VX_API_CALL vxGetPyramidLevel (vx_pyramid pyr, vx_uint32 index)
Retrieves a level of the pyramid as a vx_image [R01160], which can be used elsewhere in OpenVX. A call to vxReleaseImage is necessary to release an image for each call of vxGetPyramidLevel [R01161]. 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 [R01153]. More...

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

## ◆ vxCreatePyramid()

 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 [R01122].

Parameters
 [in] context The reference to the overall context [R01123]. [in] levels The number of levels desired [R01124]. This is required to be a non-zero value [R01125]. [in] scale Used to indicate the scale between pyramid levels [R01126]. This is required to be a non-zero positive value [R01127]. VX_SCALE_PYRAMID_HALF and VX_SCALE_PYRAMID_ORB must be supported [R01128]. [in] width The width of the 0th level image in pixels [R01129]. [in] height The height of the 0th level image in pixels [R01130]. [in] format The format of all images in the pyramid [R01131]. NV12, NV21, IYUV, UYVY and YUYV formats are not supported [R01132].
Returns
A pyramid reference vx_pyramid containing the sub-images [R01133]. Any possible errors preventing a successful creation should be checked using vxGetStatus [R01134].

## ◆ vxCreateVirtualPyramid()

 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 [R01135].

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 [R01136]. [in] levels The number of levels desired [R01137]. This is required to be a non-zero value [R01138]. [in] scale Used to indicate the scale between pyramid levels. This is required to be a non-zero positive value [R01139]. VX_SCALE_PYRAMID_HALF and VX_SCALE_PYRAMID_ORB must be supported [R01140]. [in] width The width of the 0th level image in pixels [R01141]. This may be set to zero to indicate to the interface that the value is unspecified [R01142]. [in] height The height of the 0th level image in pixels [R01143]. This may be set to zero to indicate to the interface that the value is unspecified [R01144]. [in] format The format of all images in the pyramid [R01145]. This may be set to VX_DF_IMAGE_VIRT to indicate that the format is unspecified [R01146].
Returns
A pyramid reference vx_pyramid [R01147]. Any possible errors preventing a successful creation should be checked using vxGetStatus [R01148].
Note
Images extracted with vxGetPyramidLevel behave as Virtual Images and cause vxMapImagePatch to return errors [R01149].

## ◆ vxReleasePyramid()

 vx_status VX_API_CALL vxReleasePyramid ( vx_pyramid * pyr )

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

Parameters
 [in] pyr The pointer to the pyramid to release [R01151].
Returns
A The vx_status Constants value.
Return values
 VX_SUCCESS No errors; any other value indicates failure [R01152]. VX_ERROR_INVALID_REFERENCE pyr is not a valid vx_pyramid reference.
Postcondition
After returning from this function the reference is zeroed.

## ◆ vxQueryPyramid()

 vx_status VX_API_CALL vxQueryPyramid ( vx_pyramid pyr, vx_enum attribute, void * ptr, vx_size size )

Queries an attribute from an image pyramid [R01153].

Parameters
 [in] pyr The pyramid to query [R01154]. [in] attribute The attribute for which to query [R01155]. Use a The pyramid object attributes. value [R01156]. [out] ptr The location at which to store the resulting value [R01157]. [in] size The size in bytes of the container to which ptr points [R01158].
Returns
A The vx_status Constants value.
Return values
 VX_SUCCESS No errors; any other value indicates failure [R01159]. VX_ERROR_INVALID_REFERENCE pyr is not a valid vx_pyramid reference.

## ◆ vxGetPyramidLevel()

 vx_image VX_API_CALL vxGetPyramidLevel ( vx_pyramid pyr, vx_uint32 index )

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

Parameters
 [in] pyr The pyramid object [R01162]. [in] index The index of the level, such that index is less than levels [R01163].
Returns
A vx_image reference [R01164]. Any possible errors preventing a successful function completion should be checked using vxGetStatus [R01165].