LeapScreen Class Reference
Inherits from | NSObject |
Declared in | LeapObjectiveC.h |
Overview
The LeapScreen class represents a computer monitor screen.
The LeapScreen class reports characteristics describing the position and
orientation of the monitor screen within the Leap coordinate system. These
characteristics include the bottom-left corner position of the screen,
direction vectors for the horizontal and vertical axes of the screen, and
the screen’s normal vector. The screen must be properly registered with the
Screen Locator for the Leap to report these characteristics accurately.
The LeapScreen class also reports the size of the screen in pixels, using
information obtained from the operating system. (Run the Screen Locator
from the Leap Application Settings dialog, on the Screen page.)
Get an array containing the available LeapScreen objects from a connected
LeapController object:
NSArray *screens = [controller locatedScreens];
You can get the point of intersection between the screen and a ray
projected from a LeapPointable object using the LeapScreen
intersect:normalize:clampRatio function.
Likewise, you can get the distance to the closest point on the screen to a point in space
using the LeapScreen distanceToPoint: function. Again, the screen location
must be registered with the Screen Locator for these functions to
return accurate values.
Note that LeapScreen objects can be invalid, which means that they do not contain
valid screen coordinate data and do not correspond to a physical entity.
Test for validity with the LeapScreen isValid: function.
Tasks
-
– id
A unique identifier for this screen based on the screen
information in the configuration. A default screen with ID, 0,
always exists and contains default characteristics, even if no screens
have been located. -
– intersect:normalize:clampRatio:
Returns the intersection between this screen and a ray projecting from a
Pointable object. -
– intersect:direction:normalize:clampRatio:
Returns the intersection between this screen and a ray projecting from
the specified position along the specified direction. -
– project:normalize:clampRatio:
Returns the projection from the specified position onto this screen.
-
– horizontalAxis
A LeapVector representing the horizontal axis of this LeapScreen within the
Leap coordinate system. -
– verticalAxis
A LeapVector representing the vertical axis of this LeapScreen within the
Leap coordinate system. -
– bottomLeftCorner
A LeapVector representing the bottom left corner of this LeapScreen within the
Leap coordinate system. -
– normal
A LeapVector normal to the plane in which this LeapScreen lies.
-
– widthPixels
The horizontal resolution of this screen, in pixels.
-
– heightPixels
The vertical resolution of this screen, in pixels.
-
– distanceToPoint:
The shortest distance from the specified point to the plane in which this
LeapScreen lies. -
– isValid
Reports whether this is a valid LeapScreen object.
-
– equals:
Compare LeapScreen object equality.
Two LeapScreen objects are equal if and only if both objects represent the
exact same screens and both LeapScreen objects are valid. -
+ invalid
Returns an invalid LeapScreen object.
Class Methods
invalid
Returns an invalid LeapScreen object.
+ (LeapScreen *)invalid
Return Value
The invalid LeapScreen instance.
Discussion
Returns an invalid LeapScreen object.
You can use the instance returned by this function in comparisons testing
whether a given LeapScreen instance is valid or invalid. (You can also use the
LeapScreen isValid function.)
Declared In
LeapObjectiveC.h
Instance Methods
bottomLeftCorner
A LeapVector representing the bottom left corner of this LeapScreen within the
Leap coordinate system.
- (LeapVector *)bottomLeftCorner
Return Value
A LeapVector containing the coordinates of the bottom-left corner
of this LeapScreen.
Discussion
A LeapVector representing the bottom left corner of this LeapScreen within the
Leap coordinate system.
The point represented by this vector defines the origin of the screen
in the Leap coordinate system.
Together, horizontalAxis, verticalAxis, and bottomLeftCorner
describe the physical position, size and orientation of this LeapScreen.
Declared In
LeapObjectiveC.h
distanceToPoint:
The shortest distance from the specified point to the plane in which this
LeapScreen lies.
- (float)distanceToPoint:(const LeapVector *)point
Parameters
- point
The point of interest.
Return Value
The length of the perpendicular line segment extending from
the plane this LeapScreen lies in to the specified point.
Discussion
The shortest distance from the specified point to the plane in which this
LeapScreen lies.
if ([frame.pointables count] > 0) {
LeapPointable *pointable = [[frame pointables] objectAtIndex:0];
NSArray *screens = [controller locatedScreens];
LeapScreen *screen = [screens closestScreenHit:pointable];
float normalDistance = [screen distanceToPoint:pointable.tipPosition];
NSLog(@"Normal distance: %f", normalDistance);
}
Declared In
LeapObjectiveC.h
equals:
Compare LeapScreen object equality.
Two LeapScreen objects are equal if and only if both objects represent the
exact same screens and both LeapScreen objects are valid.
- (BOOL)equals:(const LeapScreen *)other
Parameters
- other
The LeapScreen object to compare.
Discussion
Compare LeapScreen object equality.
Two LeapScreen objects are equal if and only if both objects represent the
exact same screens and both LeapScreen objects are valid.
Declared In
LeapObjectiveC.h
heightPixels
The vertical resolution of this screen, in pixels.
- (int)heightPixels
Return Value
The height of this LeapScreen in pixels.
Discussion
The vertical resolution of this screen, in pixels.
Declared In
LeapObjectiveC.h
horizontalAxis
A LeapVector representing the horizontal axis of this LeapScreen within the
Leap coordinate system.
- (LeapVector *)horizontalAxis
Return Value
A LeapVector representing the bottom, horizontal edge of this LeapScreen.
Discussion
A LeapVector representing the horizontal axis of this LeapScreen within the
Leap coordinate system.
The magnitude of this vector estimates the physical width of this LeapScreen
in millimeters. The direction of this vector is parallel to the bottom
edge of the screen and points toward the right edge of the screen.
Together, horizontalAxis, verticalAxis, and bottomLeftCorner
describe the physical position, size and orientation of this LeapScreen.
Declared In
LeapObjectiveC.h
id
A unique identifier for this screen based on the screen
information in the configuration. A default screen with ID, 0,
always exists and contains default characteristics, even if no screens
have been located.
- (int32_t)id
Discussion
A unique identifier for this screen based on the screen
information in the configuration. A default screen with ID, 0,
always exists and contains default characteristics, even if no screens
have been located.
Declared In
LeapObjectiveC.h
intersect:direction:normalize:clampRatio:
Returns the intersection between this screen and a ray projecting from
the specified position along the specified direction.
- (LeapVector *)intersect:(const LeapVector *)position direction:(const LeapVector *)direction normalize:(BOOL)normalize clampRatio:(float)clampRatio
Parameters
- position
The position from which to check for screen intersection.
- direction
The direction in which to check for screen intersection.
- normalize
If true, return normalized coordinates representing
the intersection point as a percentage of the screen’s width and height.
If false, return Leap coordinates (millimeters from the Leap origin,
which is located at the center of the top surface of the Leap device).
If true and the clampRatio parameter is set to 1.0, coordinates will be
of the form (0..1, 0..1, 0). Setting the clampRatio to a different value
changes the range for normalized coordinates. For example, a clampRatio
of 5.0 changes the range of values to be of the form (-2..3, -2..3, 0).
- clampRatio
Adjusts the clamping border around this screen.
By default this ratio is 1.0, and the border corresponds to the actual
boundaries of the screen. Setting clampRatio to 0.5 would reduce the
interaction area. Likewise, setting the ratio to 2.0 would increase the
interaction area, adding 50% around each edge of the physical monitor.
Intersection points outside the interaction area are repositioned to
the closest point on the clamping border before the vector is returned.
Return Value
A Vector containing the coordinates of the intersection between
this screen and a ray projecting from the specified position in the
specified direction.
Discussion
Returns the intersection between this screen and a ray projecting from
the specified position along the specified direction.
Set the normalize parameter to true to request the intersection point in
normalized screen coordinates. Normalized screen coordinates are usually
values between 0 and 1, where 0 represents the screen’s origin at the
bottom-left corner and 1 represents the opposite edge (either top or
right). When you request normalized coordinates, the z-component of the
returned vector is zero. Multiply a normalized coordinate by the values
returned by [LeapScreen widthPixels] or [LeapScreen heightPixels] to calculate
the screen position in pixels (remembering that many other computer
graphics coordinate systems place the origin in the top-left corner).
Set the normalize parameter to false to request the intersection point
in Leap coordinates (millimeters from the Leap origin).
If the specified ray points outside the screen’s border (but still
intersects the plane in which the screen lies), the returned intersection
point is clamped to the nearest point on the edge of the screen.
You can use the clampRatio parameter to contract or expand the area in
which you can point. For example, if you set the clampRatio parameter to
0.5, then the positions reported for intersection points outside the
central 50% of the screen are moved to the border of this smaller area.
If, on the other hand, you expanded the area by setting clampRatio to
a value such as 3.0, then you could point well outside screen’s physical
boundary before the intersection points would be clamped. The positions
for any points clamped would also be placed on this larger outer border.
The positions reported for any intersection points inside the clamping
border are unaffected by clamping.
If the specified ray does not point toward the plane of the screen
(i.e. it is pointing parallel to or away from the screen), then the
components of the returned vector are all set to NaN (not-a-number).
Declared In
LeapObjectiveC.h
intersect:normalize:clampRatio:
Returns the intersection between this screen and a ray projecting from a
Pointable object.
- (LeapVector *)intersect:(LeapPointable *)pointable normalize:(BOOL)normalize clampRatio:(float)clampRatio
Parameters
- pointable
The LeapPointable object to check for screen intersection.
- normalize
If true, return normalized coordinates representing
the intersection point as a percentage of the screen’s width and height.
If false, return Leap coordinates (millimeters from the Leap origin,
which is located at the center of the top surface of the Leap device).
If true and the clampRatio parameter is set to 1.0, coordinates will be
of the form (0..1, 0..1, 0). Setting the clampRatio to a different value
changes the range for normalized coordinates. For example, a clampRatio
of 5.0 changes the range of values to be of the form (-2..3, -2..3, 0).
- clampRatio
Adjusts the clamping border around this screen.
By default this ratio is 1.0, and the border corresponds to the actual
boundaries of the screen. Setting clampRatio to 0.5 would reduce the
interaction area. Likewise, setting the ratio to 2.0 would increase the
interaction area, adding 50% around each edge of the physical monitor.
Intersection points outside the interaction area are repositioned to
the closest point on the clamping border before the vector is returned.
Return Value
A LeapVector containing the coordinates of the intersection between
this screen and a ray projecting from the specified Pointable object.
Discussion
Returns the intersection between this screen and a ray projecting from a
Pointable object.
The projected ray emanates from the [LeapPointable tipPosition] along the
pointable’s direction vector.
if ([frame.pointables count] > 0) {
LeapPointable *pointable = [frame.pointables objectAtIndex:0];
NSArray *screens = controller.calibratedScreens;
LeapScreen *screen = [screens closestScreenHit:pointable];
LeapVector *normalizedCoordinates = [screen intersect:pointable normalize:YES clampRatio:2.0];
int xPixel = normalizedCoordinates.x * screen.widthPixels;
int yPixel = screen.heightPixels - normalizedCoordinates.y * screen.heightPixels;
NSLog(@"Normalized coordinates: (%d, %d)", xPixel, yPixel);
}
Set the normalize parameter to true to request the intersection point in
normalized screen coordinates. Normalized screen coordinates are usually
values between 0 and 1, where 0 represents the screen’s origin at the
bottom-left corner and 1 represents the opposite edge (either top or
right). When you request normalized coordinates, the z-component of the
returned vector is zero. Multiply a normalized coordinate by the values
returned by [LeapScreen widthPixels] or [LeapScreen heightPixels] to calculate
the screen position in pixels (remembering that many other computer
graphics coordinate systems place the origin in the top-left corner).
Set the normalize parameter to false to request the intersection point
in Leap coordinates (millimeters from the Leap origin).
If the LeapPointable object points outside the screen’s border (but still
intersects the plane in which the screen lies), the returned intersection
point is clamped to the nearest point on the edge of the screen.
You can use the clampRatio parameter to contract or expand the area in
which you can point. For example, if you set the clampRatio parameter to
0.5, then the positions reported for intersection points outside the
central 50% of the screen are moved to the border of this smaller area.
If, on the other hand, you expanded the area by setting clampRatio to
a value such as 3.0, then you could point well outside screen’s physical
boundary before the intersection points would be clamped. The positions
for any points clamped would also be placed on this larger outer border.
The positions reported for any intersection points inside the clamping
border are unaffected by clamping.
If the LeapPointable object does not point toward the plane of the screen
(i.e. it is pointing parallel to or away from the screen), then the
components of the returned vector are all set to NaN (not-a-number).
To get the physical distance from the tip of a pointable object to the
screen intersection point, set the normalize parameter to NO to get the
intersection coordinates in terms of the Leap coordinate system and then
calculate the distance between the two points:
if ([frame.pointables count] > 0) {
LeapPointable *pointable = [frame.pointables objectAtIndex:0];
NSArray *screens = controller.calibratedScreens;
LeapScreen *screen = [screens closestScreenHit:pointable];
LeapVector *leapCoordinates = [screen intersect:pointable normalize:NO clampRatio:0.0];
LeapVector *tipToScreen = [leapCoordinates minus:pointable.tipPosition];
float pointingDistance = tipToScreen.magnitude;
NSLog(@"Distance: %f", pointingDistance);
}
Declared In
LeapObjectiveC.h
isValid
Reports whether this is a valid LeapScreen object.
- (BOOL)isValid
Return Value
YES, if this LeapScreen object contains valid data.
Discussion
Reports whether this is a valid LeapScreen object.
Important: A valid LeapScreen object does not necessarily contain
up-to-date screen location information. Location information is only
accurate until the Leap device or the monitor are moved. In addition, the
primary screen always contains default location information even if the
user has never run the screen location utility. This default location
information will not return accurate results.
Declared In
LeapObjectiveC.h
normal
A LeapVector normal to the plane in which this LeapScreen lies.
- (LeapVector *)normal
Return Value
A LeapVector representing this LeapScreen’s normal vector.
Discussion
A LeapVector normal to the plane in which this LeapScreen lies.
The normal vector is a unit direction vector orthogonal to the screen's
surface plane. It points toward a viewer positioned for typical use of
the monitor.
Declared In
LeapObjectiveC.h
project:normalize:clampRatio:
Returns the projection from the specified position onto this screen.
- (LeapVector *)project:(LeapVector *)position normalize:(BOOL)normalize clampRatio:(float)clampRatio
Parameters
- position
The position from which to project onto this screen.
- normalize
If true, return normalized coordinates representing
the projection point as a percentage of the screen’s width and height.
If false, return Leap coordinates (millimeters from the Leap origin,
which is located at the center of the top surface of the Leap device).
If true and the clampRatio parameter is set to 1.0, coordinates will be
of the form (0..1, 0..1, 0). Setting the clampRatio to a different value
changes the range for normalized coordinates. For example, a clampRatio
of 5.0 changes the range of values to be of the form (-2..3, -2..3, 0).
- clampRatio
Adjusts the clamping border around this screen.
By default this ratio is 1.0, and the border corresponds to the actual
boundaries of the screen. Setting clampRatio to 0.5 would reduce the
interaction area. Likewise, setting the ratio to 2.0 would increase the
interaction area, adding 50% around each edge of the physical monitor.
Projection points outside the interaction area are repositioned to
the closest point on the clamping border before the vector is returned.
Return Value
A Vector containing the coordinates of the projection between
this screen and a ray projecting from the specified position onto the
screen along its normal vector.
Discussion
Returns the projection from the specified position onto this screen.
if ([frame.pointables count] > 0) {
LeapPointable *pointable = [[frame pointables] objectAtIndex:0];
NSArray *screens = controller.calibratedScreens;
LeapScreen *screen = [screens closestScreen:pointable.tipPosition];
LeapVector *leapCoordinates = [screen project:pointable.tipPosition normalize:NO clampRatio:1.0];
NSLog(@"Leap coordinates: (%f, %f, %f)", leapCoordinates.x, leapCoordinates.y, leapCoordinates.z);
}
Set the normalize parameter to true to request the projection point in
normalized screen coordinates. Normalized screen coordinates are usually
values between 0 and 1, where 0 represents the screen’s origin at the
bottom-left corner and 1 represents the opposite edge (either top or
right). When you request normalized coordinates, the z-component of the
returned vector is zero. Multiply a normalized coordinate by the values
returned by [LeapScreen widthPixels] or [LeapScreen heightPixels] to calculate
the screen position in pixels (remembering that many other computer
graphics coordinate systems place the origin in the top-left corner).
Set the normalize parameter to false to request the projection point
in Leap coordinates (millimeters from the Leap origin).
If the specified point projects outside the screen’s border, the returned
projection point is clamped to the nearest point on the edge of the screen.
You can use the clampRatio parameter to contract or expand the area in
which you can point. For example, if you set the clampRatio parameter to
0.5, then the positions reported for projection points outside the
central 50% of the screen are moved to the border of this smaller area.
If, on the other hand, you expanded the area by setting clampRatio to
a value such as 3.0, then you could point well outside screen’s physical
boundary before the projection points would be clamped. The positions
for any points clamped would also be placed on this larger outer border.
The positions reported for any projection points inside the clamping
border are unaffected by clamping.
Declared In
LeapObjectiveC.h
verticalAxis
A LeapVector representing the vertical axis of this LeapScreen within the
Leap coordinate system.
- (LeapVector *)verticalAxis
Return Value
A LeapVector representing the left, vertical edge of this LeapScreen.
Discussion
A LeapVector representing the vertical axis of this LeapScreen within the
Leap coordinate system.
The magnitude of this vector estimates the physical height of this LeapScreen
in millimeters. The direction of this vector is parallel to the left
edge of the screen and points toward the top edge of the screen.
Together, horizontalAxis, verticalAxis, and bottomLeftCorner
describe the physical position, size and orientation of this screen.
Declared In
LeapObjectiveC.h