INuiSensor::NuiImageGetColorPixelCoordinatesFromDepthPixelAtResolution Method

Article
09/12/2013

Kinect for Windows 1.5, 1.6, 1.7, 1.8

Gets the pixel coordinates in color space that correspond to the specified pixel coordinates in depth space, using the specified depth resolution.

Syntax

public:
HRESULT NuiImageGetColorPixelCoordinatesFromDepthPixelAtResolution(
         NUI_IMAGE_RESOLUTION eColorResolution,
         NUI_IMAGE_RESOLUTION eDepthResolution,
         const NUI_IMAGE_VIEW_AREA *pcViewArea,
         LONG lDepthX,
         LONG lDepthY,
         USHORT usDepthValue,
         LONG *plColorX,
         LONG *plColorY
)

Parameters

eColorResolution
Type: NUI_IMAGE_RESOLUTION
[in] The resolution of the color image, as a NUI_IMAGE_RESOLUTION enumeration constant.
eDepthResolution
Type: NUI_IMAGE_RESOLUTION
[in] The resolution of the depth image, as a NUI_IMAGE_RESOLUTION enumeration constant.
pcViewArea
Type: NUI_IMAGE_VIEW_AREA
[in] The optional zoom and pan settings of the color image, as a pointer to a NUI_IMAGE_VIEW_AREA structure. To ensure that the settings are valid, use the ViewArea member of the NUI_IMAGE_FRAME that you are registering pixels against. Do not instantiate and populate this structure manually.
lDepthX
Type: LONG
[in] The x-coordinate in depth image space.
lDepthY
Type: LONG
[in] The y-coordinate in depth image space.
usDepthValue
Type: USHORT
[in] The depth value in depth image space. This value is in the range [NUI_IMAGE_DEPTH_MINIMUM, NUI_IMAGE_DEPTH_MAXIMUM]
plColorX
Type: LONG
Pointer to a LONG value that receives the x-coordinate of the pixel in color image space. This pointer must be non-NULL when you call this function. If this method does not return S_OK, this data is invalid. This value can be outside of the bounds of the color image.
plColorY
Type: LONG
Pointer to a LONG value that receives the y-coordinate of the pixel in color image space. This pointer must be non-NULL when you call this function. If this method does not return S_OK, this data is invalid. This value can be outside of the bounds of the color image.

Return Value

Type: HRESULT
Returns S_OK if successful; otherwise, returns one of the failure codes in the following table.

Error	Description
E_INVALIDARG	An invalid resolution was specified or does not correspond to the cColorCoordinates or cDepthCoordinates parameters.
E_NUI_DEVICE_NOT_READY	The device has not been initialized. Refer to NuiInitialize.
E_OUTOFMEMORY	The allocation failed.
E_POINTER	The value of plColorX or plColorY parameter is NULL.

Remarks

Because depth image data and color image data come from separate sensors, pixels in the two images may not always line up exactly. The two sensors may have different fields of view, or may not be aimed precisely in the same direction. This means that a point near the edge of the depth image may correspond to a pixel just beyond the edge of the color image, or vice versa.

This function accepts coordinates outside the bounds of the depth image. It may return pixels outside the color image. This means that you can use data from the two images in combination, even when the two images do not line up completely. You must verify that the coordinates that are returned lie within the color image before using the coordinates to reference pixels in that color image.

The depth image coordinates you specify are not required to be within the bounds of the depth frame image, but they should not be too far outside the depth frame image bounds. If the coordinates are far outside the depth frame image, they are unlikely to map to coordinates inside the bounds of the color image. This function will then return color image coordinates that are unlikely to be useful.

For more information, see Data Streams.

Requirements

Header: Declared in NuiSensor.h; however, include NuiApi.h in your project.

Share via