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_ATTRIBUTE_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_ATTRIBUTE_LEVELS = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x0,   VX_PYRAMID_ATTRIBUTE_SCALE = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x1,   VX_PYRAMID_ATTRIBUTE_WIDTH = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x2,   VX_PYRAMID_ATTRIBUTE_HEIGHT = ((( VX_ID_KHRONOS ) << 20) | ( VX_TYPE_PYRAMID << 8)) + 0x3,   VX_PYRAMID_ATTRIBUTE_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

enum vx_pyramid_attribute_e

The pyramid object attributes.

Enumerator
VX_PYRAMID_ATTRIBUTE_LEVELS	The number of levels of the pyramid. Use a vx_size parameter.
VX_PYRAMID_ATTRIBUTE_SCALE	The scale factor between each level of the pyramid. Use a vx_float32 parameter.
VX_PYRAMID_ATTRIBUTE_WIDTH	The width of the 0th image in pixels. Use a vx_uint32 parameter.
VX_PYRAMID_ATTRIBUTE_HEIGHT	The height of the 0th image in pixels. Use a vx_uint32 parameter.
VX_PYRAMID_ATTRIBUTE_FORMAT	The vx_df_image_e format of the image. Use a vx_df_image parameter.

Definition at line 934 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. In OpenVX 1.0, the 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 to the sub-image. 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_context context = vxCreateContext();
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. In OpenVX 1.0, the 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 vxAccessImagePatch 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.

Return values

0	Indicates that the index or the object is invalid.