INuiSensor::NuiCameraElevationSetAngle Method

Article
09/12/2013

Kinect for Windows 1.5, 1.6, 1.7, 1.8

Sets the elevation (tilt angle) whose range is [+/-27] degrees.

Syntax

public:
HRESULT NuiCameraElevationSetAngle(
         LONG lAngleDegrees
)

Parameters

lAngleDegrees
Type: LONG
[in] The elevation angle relative to gravity, in degrees. A value of zero indicates that the sensor array points horizontally. Positive values indicate that the sensor array points above the horizon, and negative values indicate that the sensor array points below the horizon. Valid angles are in the range [NUI_CAMERA_ELEVATION_MINIMUM, NUI_CAMERA_ELEVATION_MAXIMUM].

Return Value

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

Error	Description
ERROR_RETRY	The time interval between subsequent calls to NuiCameraElevationSetAngle was too short.
ERROR_TOO_MANY_CMDS	Too many calls to NuiCameraElevationSetAngle were issued in a short time interval.
E_NUI_DEVICE_NOT_READY	Kinect has not been initialized.

Remarks

Important

You should tilt the Kinect as few times as possible, to minimize wear on the sensor and to minimize tilting time. The tilt motor is not designed for constant or repetitive movement, and attempts to use it that way can cause degradation of motor function. To reduce wear, your application should change the elevation angle no more than once per second. In addition, you must allow at least 20 seconds of rest after 15 consecutive changes. If your application exceeds these limits, the tilt motor may experience a lock period during which attempting to set the elevation angle will result in an error code.

You can tilt the field of view using the tilt motor in the sensor. The motor allows an additional [+/-27] degrees, which effectively doubles the volume that the field of view could surround.

The tilt is relative to gravity rather than relative to the sensor base. An elevation angle of zero indicates that the Kinect is pointing perpendicular to gravity.

The angle is subject to the physical limitations of the sensor. If the sensor base is resting on a tilted surface, the middle of the sensor's tilt range will not correspond to an elevation angle of zero, and the sensor may not be physically capable of reaching the outer limits of the range allowed by the API.

If the sensor is moved so that the base is at a different angle relative to gravity, or if the sensor is tilted manually, the angle reported by the API will change, even if the elevation angle has not been changed programmatically.

For more information, see Interaction Space.

Requirements

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

Share via