The LeapImage class represents a single greyscale image from one of the the Leap Motion cameras. More...

Inherits NSObject.

Instance Methods
(BOOL)	- equals:
	Compare LeapImage object equality. More...

(int32_t)	- id
	The image ID. More...

(LeapVector *)	- rectify:
	Provides the corrected camera ray intercepting the specified point on the image. More...

(int64_t)	- sequenceId
	The image sequence ID. More...

(LeapVector *)	- warp:
	Provides the point in the image corresponding to a ray projecting from the camera. More...

Class Methods
(LeapImage *)	+ invalid
	Returns an invalid Image object. More...

Properties
int	bytesPerPixel
	The number of bytes per pixel. More...

const unsigned char *	data
	A pointer to the image data. More...

const float *	distortion
	A pointer to the distortion calibration map. More...

int	distortionHeight
	The distortion map height. More...

int	distortionWidth
	The stride of the distortion map. More...

LeapImageFormatType	format
	The image format. More...

int	height
	The image height. More...

BOOL	isValid
	Reports whether this LeapImage instance contains valid data. More...

float	rayOffsetX
	The horizontal ray offset. More...

float	rayOffsetY
	The vertical ray offset. More...

float	rayScaleX
	The horizontal ray scale factor. More...

float	rayScaleY
	The vertical ray scale factor. More...

int64_t	timestamp
	Returns a timestamp indicating when this frame began being captured on the device. More...

int	width
	The image width. More...

Detailed Description

The LeapImage class represents a single greyscale image from one of the the Leap Motion cameras.

In addition to image data, the LeapImage object provides a distortion map for correcting lens distortion.

Note that LeapImage objects can be invalid, which means that they do not contain valid image data. Get valid LeapImage objects from [LeapFrame frames:]. Test for validity with the LeapImage.isValid.

Since: 2.1.5

Method Documentation

- (BOOL) equals: (const LeapImage *) other

Compare LeapImage object equality.

Two LeapImage objects are equal if and only if both objects represent the exact same image and both LeapImage objects are valid.

Since: 2.1.5

- (int32_t) id

The image ID.

Images with ID of 0 are from the left camera; those with an ID of 1 are from the right camera (with the device in its standard operating position with the green LED facing the operator).

Since: 2.1.5

+ (LeapImage *) invalid

Returns an invalid Image object.

You can use the instance returned by this function in comparisons testing whether a given Image instance is valid or invalid. (You can also use the LeapImage.isValid property.)

Returns: The invalid LeapImage instance.

Since: 2.1.5

- (LeapVector *) rectify: (LeapVector *) uv

Provides the corrected camera ray intercepting the specified point on the image.

Given a point on the image, rectify: corrects for camera distortion and returns the true direction from the camera to the source of that image point within the Leap Motion field of view.

This direction vector has an x and y component with the third element always zero: i.e. [x, y, 0]. Note that this vector uses the 2D camera coordinate system where the x-axis parallels the longer (typically horizontal) dimension and the y-axis parallels the shorter (vertical) dimension. The camera coordinate system does not correlate to the Leap Motion 3D coordinate system.

LeapVector *feature = [[LeapVector alloc] initWithX:127 y:68 z:0];

LeapVector *slopes = [image rectify:feature];

Parameters

uv	A LeapVector containing the position of a pixel in the image.

Returns: A LeapVector containing the ray direction (the z-component of the vector is always 0).

Since: 2.1.5

- (int64_t) sequenceId

The image sequence ID.

long lastImage = 0;
while(!done){
    LeapImage *leftImage = [controller.images objectAtIndex:0];
    if(leftImage.sequenceId != lastImage){
        LeapImage *rightImage = [controller.images objectAtIndex:1];
        lastImage = leftImage.sequenceId;
        // Use images...
    }
}

Since: 2.2.1

- (LeapVector *) warp: (LeapVector *) xy

Provides the point in the image corresponding to a ray projecting from the camera.

Given a ray projected from the camera in the specified direction, warp: corrects for camera distortion and returns the corresponding pixel coordinates in the image.

The ray direction is specified in relationship to the camera. The first vector element corresponds to the "horizontal" view angle; the second corresponds to the "vertical" view angle.

float horizontal_slope = tan(65 * LEAP_DEG_TO_RAD);
float vertical_slope = tan(15 * LEAP_DEG_TO_RAD);
LeapVector *pixel = [image warp:[[LeapVector alloc] initWithX:horizontal_slope y: vertical_slope z:0]];
if(pixel.x >= 0 && pixel.y >= 0 && pixel.x <= image.width && pixel.y <= image.height){
    int data_index = floor(pixel.y) * image.width + floor(pixel.x);
    unsigned char brightness = image.data[data_index];
}

Parameters

xy	A LeapVector containing the ray direction.

Returns: A LeapVector containing the pixel coordinates [x, y, 0] (with z always zero).

Since: 2.1.5

Property Documentation

- (int) bytesPerPixel

readnonatomicassign

The number of bytes per pixel.

int bufferSize = image.bytesPerPixel * image.width * image.height;

Since: 2.2.0

- (const unsigned char*) data

readnonatomicassign

A pointer to the image data.

The image data is a set of 8-bit intensity values. The size of the buffer is image.width * image.height bytes.

const unsigned char* image_buffer = image.data;

Where convenient, you can wrap the image data in an NSData object:

NSData * asNSData = [[NSData alloc] initWithBytesNoCopy:(void *)image.data
                length:image.width * image.height
                deallocator:^void (void * bytes, NSUInteger length) {}];
                //No need to deallocate

Since: 2.1.5

- (const float*) distortion

readnonatomicassign

A pointer to the distortion calibration map.

The calibration map is a 64x64 grid of points. Each point is defined by a pair of 32-bit floating point values. Thus the size of the buffer is (image.distortionWidth * 2) * image.distortionHeight * 4 bytes. Currently the size is not dynamic and evaluates to: 64 * 2 * 64 * 4 = 32768 bytes. A future device or change in the API, however, could result in a different size for the calibration map. You should always use the image.distortionWidth and image.distortionHeight properties to calculate the buffer size.

Each point in the map represents a ray projected into the camera. The value of a grid point defines the pixel in the image data containing the brightness value produced by the light entering along the corresponding ray. By interpolating between grid data points, you can find the brightness value for any projected ray. Grid values that fall outside the range [0..1] do not correspond to a value in the image data and those points should be ignored.

const float* distortion_buffer = image.distortion;

The calibration map can be used to render an undistorted image as well as to find the true angle from the camera to a feature in the raw image. The distortion map itself is designed to be used with GLSL shader programs. In other contexts, it may be more convenient to use the [LeapImage rectify:] and [LeapImage warp:] functions.

Distortion is caused by the lens geometry as well as imperfections in the lens and sensor window. The calibration map is created by the calibration process run for each device at the factory (and which can be rerun by the user).

Since: 2.1.5

- (int) distortionHeight

readnonatomicassign

The distortion map height.

Currently fixed at 64.

int correctionGridHeight = image.distortionHeight;

Since: 2.1.5

- (int) distortionWidth

readnonatomicassign

The stride of the distortion map.

Since each point on the 64x64 element distortion map has two values in the buffer, the stride is 2 times the size of the grid. (Stride is currently fixed at 2 * 64 = 128).

int correctionGridWidth = image.distortionWidth;

Since: 2.1.5

- (LeapImageFormatType) format

readnonatomicassign

The image format.

if(image.format == LEAP_IMAGE_FORMAT_TYPE_INFRARED){
    NSString *openGL_format = @"GL_RED";
    NSString *openGL_type = @"GL_UNSIGNED_BYTE";
}

Since: 2.2.0

- (int) height

readnonatomicassign

The image height.

int height = image.height;

Since: 2.1.5

- (BOOL) isValid

readnonatomicassign

Reports whether this LeapImage instance contains valid data.

Returns: true, if and only if the image is valid.

Since: 2.1.5

- (float) rayOffsetX

readnonatomicassign

The horizontal ray offset.

Used to convert between normalized coordinates in the range [0..1] and the ray slope range [-4..4].

LeapVector *raySlopes = [[LeapVector alloc] initWithX:-3.28 y:1.76 z:0];
LeapVector *normRay =
    [[LeapVector alloc] initWithX:raySlopes.x * image.rayScaleX + image.rayOffsetX
                                y:raySlopes.y * image.rayScaleY + image.rayOffsetY
                                z:0];

Since: 2.1.5

- (float) rayOffsetY

readnonatomicassign

The vertical ray offset.

Used to convert between normalized coordinates in the range [0..1] and the ray slope range [-4..4].

LeapVector *normSlopes = [[LeapVector alloc] initWithX:.09 y:.72 z:0];
LeapVector *slope =
    [[LeapVector alloc] initWithX:(normSlopes.x - image.rayOffsetX)/image.rayScaleX
                                y:(normSlopes.y - image.rayOffsetY)/image.rayScaleY
                                z:0];

Since: 2.1.5

- (float) rayScaleX

readnonatomicassign

The horizontal ray scale factor.

Used to convert between normalized coordinates in the range [0..1] and the ray slope range [-4..4].

LeapVector *raySlopes = [[LeapVector alloc] initWithX:-3.28 y:1.76 z:0];
LeapVector *normRay =
    [[LeapVector alloc] initWithX:raySlopes.x * image.rayScaleX + image.rayOffsetX
                                y:raySlopes.y * image.rayScaleY + image.rayOffsetY
                                z:0];

Since: 2.1.5

- (float) rayScaleY

readnonatomicassign

The vertical ray scale factor.

Used to convert between normalized coordinates in the range [0..1] and the ray slope range [-4..4].

LeapVector *normSlopes = [[LeapVector alloc] initWithX:.09 y:.72 z:0];
LeapVector *slope =
    [[LeapVector alloc] initWithX:(normSlopes.x - image.rayOffsetX)/image.rayScaleX
                                y:(normSlopes.y - image.rayOffsetY)/image.rayScaleY
                                z:0];

Since: 2.1.5

- (int64_t) timestamp

readnonatomicassign

Returns a timestamp indicating when this frame began being captured on the device.

Since: 2.2.7

- (int) width

readnonatomicassign

The image width.

int width = image.width;

Since: 2.1.5

LeapImage¶

Instance Methods

Class Methods

Properties

Detailed Description

Method Documentation

Property Documentation