Image

Attributes:

Methods:

Constants:

class Leap.Image

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

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

Note that Image objects can be invalid, which means that they do not contain valid image data. Get valid Image objects from Frame.images(). Test for validity with is_valid.

New in version 2.1.0.

classmethod Image()

Constructs a Image object.

An uninitialized image is considered invalid. Get valid Image objects from a ImageList object obtained from the :py:meth`Frame.images()` method.

New in version 2.1.0.

bytes_per_pixel
Type:int

The number of bytes stored for each pixel in the image data array.

bufferSize = image.bytes_per_pixel * image.width * image.height

Current Leap Motion hardware records one byte of data per pixel. Future devices may store more than this.

New in version 2.2.0.

data
Type:byte_array

The image data.

The image data is a set of 8-bit intensity values. The buffer is width times height bytes long.

image_buffer = image.data

New in version 2.1.0.

data_pointer
Type:pointer

A pointer to the image data buffer.

Use this address to directly access the memory in the data buffer using ctypes or numpy.

The image data is a set of 8-bit intensity values. The buffer is width times height bytes long.

image_buffer_ptr = image.data_pointer
ctype_array_def = ctypes.c_ubyte * image.width * image.height

# as ctypes array
as_ctype_array = ctype_array_def.from_address(int(image_buffer_ptr))
# as numpy array
as_numpy_array = numpy.ctypeslib.as_array(as_ctype_array)

New in version 2.3.1.

distortion

The distortion calibration map for this image.

The calibration map is a 64x64 grid of points. Each point is defined by a pair of 32-bit floating point values. 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.

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 rectify() and :py:meth:`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).

Note, in a future release, there may be two distortion maps per image; one containing the horizontal values and the other containing the vertical values.

New in version 2.1.0.

distortion_pointer
Type:pointer

A pointer to the image distortion buffer.

Use this address to directly access the memory in the distortion buffer using ctypes or numpy.

distortion_buffer = image.distortion_pointer

New in version 2.3.1.

distortion_height

The distortion map height.

Currently fixed at 64.

correctionGridHeight = image.distortion_height

New in version 2.1.0.

distortion_width

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

correctionGridWidth = image.distortion_width

New in version 2.1.0.

format
Type:int

The format identifier describing the information in the image data array.

Current Leap Motion hardware stores data in the INFRARED format. Future devices may use different formats.

New in version 2.2.0.

height
Type:int

The image height.

height = image.height

New in version 2.1.0.

id
Type:int

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

New in version 2.1.0.

is_valid

Reports whether this Image instance contains valid data.

New in version 2.1.0.

ray_offset_x

The horizontal ray offset.

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

raySlopes = Leap.Vector(-3.28, 1.76, 0)
normRay = Leap.Vector(raySlopes.x * image.ray_scale_x + image.ray_offset_x,
                      raySlopes.y * image.ray_scale_y + image.ray_offset_y, 0)

New in version 2.1.0.

ray_offset_y

The vertical ray offset.

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

normSlopes = Leap.Vector(.09, .72, 0)
slope = Leap.Vector((normSlopes.x - image.ray_offset_x)/image.ray_scale_x,
                    (normSlopes.y - image.ray_offset_y)/image.ray_scale_y, 0)

New in version 2.1.0.

ray_scale_x

The horizontal ray scale factor.

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

raySlopes = Leap.Vector(-3.28, 1.76, 0)
normRay = Leap.Vector(raySlopes.x * image.ray_scale_x + image.ray_offset_x,
                      raySlopes.y * image.ray_scale_y + image.ray_offset_y, 0)

New in version 2.1.0.

ray_scale_y

The vertical ray scale factor.

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

normSlopes = Leap.Vector(.09, .72, 0)
slope = Leap.Vector((normSlopes.x - image.ray_offset_x)/image.ray_scale_x,
                    (normSlopes.y - image.ray_offset_y)/image.ray_scale_y, 0)

New in version 2.1.0.

sequence_id

An ordinal id indicating the order in which this image was produced.

lastImage = 0
while (not done):
    leftImage = controller.images[0]
    if(leftImage.sequence_id != lastImage):
        rightImage = controller.images[1]
        lastImage = leftImage.sequence_id
        # Use images...

New in version 2.2.1.

timestamp
Type:long

The timestamp, in microseconds, when image capture began.

New in version 2.2.7.

width
type:int

The image width.

width = image.width

New in version 2.1.0.

rectify(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 [x, y, 0], with the third element always zero. 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 3D Leap Motion coordinate system.

feature = Leap.Vector(127, 68, 0)
feature_slopes = image.rectify(feature)
Parameters:uv (Vector) – A Vector containing the position of a pixel in the image.
Returns:A Vector containing the ray direction (the z-component of the vector is always 0).

New in version 2.1.0.

warp(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, py:meth: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.

horizontal_slope = math.tan(65 * math.pi/180)
vertical_slope = math.tan(15 * math.pi/180)
pixel = image.warp(Leap.Vector(horizontal_slope, vertical_slope, 0))
if(pixel.x >= 0 and pixel.y >= 0 and pixel.x <= image.width and pixel.y <= image.height):
    data_index = math.floor(pixel.y) * image.width + math.floor(pixel.x)
    brightness = image.data[int(data_index)]
Parameters:xy (Vector) – A Vector containing the ray direction.
Returns:A Vector containing the pixel coordinates [x, y, 0] (with z always zero).

New in version 2.1.0.

invalid
Type:Image

An invalid Image object.

New in version 2.1.0.

FORMAT_INFRARED

The data format for 8-bit, infrared Leap Motion sensor images.

The INFRARED format contains a single 8-bit value per pixel. This value represents the brightness recorded for the corresponding sensor location. Pixels are stored in the image data array line by horizontal line. The first element in the data array represents the bottom, left corner of the image.

New in version 2.1.2.