Input Handling

class libavg.avg.Contact

Bases: libavg.avg.Publisher

A Contact encapsulates the information of one touch on an input device from the down event to an up event. It exposes some aggregate information about the touch - distance and direction travelled etc. - and supports event handlers that are only called for this single contact.

For compatibility reasons, a mouse device also produces contacts. A mouse contact exists from the press of a button to its release. If multiple buttons are pressed without a complete release (e.g. LEFTDOWN-RIGHTDOWN-LEFTUP-RIGHTUP), the mouse contact exists for the complete sequence.

Messages:

All message parameters are of type CursorEvent. To get these messages, call Publisher.subscribe(). All subscribers are unsubscribed automatically after the up event.

CURSOR_MOTION(cursorevent)

Emitted whenever the contact moves.

CURSOR_UP(cursorevent)

Emitted when the mouse button is released or the touch leaves the surface.

age

Time that has passed since the down event in milliseconds. Read-only.

distancefromstart

Distance of the current position from the initial position in pixels. Read-only.

distancetravelled

The total distance travelled since the initial down event. Read-only.

events

An array containing all events that this contact has generated in the past. Read-only.

id

A numerical id for this contact. This corresponds to the CursorEvent.cursorid field. Contacts for touch events have unique ids, while contacts for mouse events always have the id -1. ids are not reused. Read-only.

motionangle

Angle of the current position from the initial position in radians. Like all angles in libavg, motionangle is 0 on the positive x axis and increases clockwise. Read-only.

motionvec

The difference of the current position and the initial position as a Point2D. Read-only.

connectListener(motionCallback, upCallback) → id

Deprecated since version 1.8: Use the message interface instead.

Registers event handlers that get called when CURSORMOTION and CURSORUP events for this Contact occur. Event handlers can be unregistered using disconnectListener(). They are automatically unregistered after the up event. The id returned is unique for this contact.

disconnectListener(id)

Deprecated since version 1.8: Use the message interface instead.

Unregisters an event handler. The parameter is the id returned in connectListener(). It is an error to call disconnectListener() with an invalid id.

class libavg.avg.CursorEvent

Bases: libavg.avg.Event

Base class for all events which contain a position in the global coordinate system.

contact

The Contact that the event belongs to, if there is one. Read-only.

cursorid

A numerical identifier for the current cursor.

node

The Node that the event occured in. If this is None, the event happened outside of the application window and the cursor was captured by the application. Read-only.

pos

Position in the global coordinate system. Read-only.

source

The type of the device that emitted the event. See Event.source. Read-only.

x

x position in the global coordinate system. Read-only.

y

y position in the global coordinate system. Read-only.

class libavg.avg.Event(type, source[, when])

Bases: Boost.Python.instance

Base class for user input events.

Parameters:

• type (type) – The type of the event. See Event.type.
• source (source) – The source of the event. See Event.source.
• when (Integer) – The time the event occured

inputdevice

The address of the device that emitted the event. Read-only

inputdevicename

The name of the device that emitted the event. Read-only.

source

One of MOUSE, TOUCH, TRACK, CUSTOM or NONE. Read-only

type

One of KEYUP, KEYDOWN, CURSORMOTION, CURSORUP, CURSORDOWN, CURSOROVER or CURSOROUT. Read-only.

when

The time when the event occured in milliseconds since program start. Read-only.

class libavg.avg.InputDevice(name[, eventReceiverNode])

Bases: Boost.Python.instance

Base class for input devices which feed events to the system. Derived classes can be either user-defined or one of the predefined libavg input devices. User-defined InputDevice objects are registered with the system by calling Player.addInputDevice(). After this, the emitted events are processed like any other events.

eventreceivernode

The DivNode that the input device will deliver events to. By default, this is the libavg root node. Useful for restricting events to a part of the total canvas or for sending events directly to an offscreen canvas. Event bubbling starts at this node and proceeds down the tree from there. Read-only.

name

The name of the device. Read-only.

pollEvents() → list

Abstract method which returns a list of pending events. Override this method in your derived input device class. After registering the input device, this method gets called on every frame.

start()

Initializes the input device if needed. By default this is an empty method.

class libavg.avg.KeyEvent

Bases: libavg.avg.Event

Generated when a key is pressed or released.

keycode

The keycode of the key according to US keyboard layout. Read-only.

keystring

A character or word describing the key pressed. Read-only.

modifiers

Any modifier keys pressed, or’ed together. Possible Modifiers are KEYMOD_NONE, KEYMOD_LSHIFT, KEYMOD_RSHIFT, KEYMOD_LCTRL, KEYMOD_RCTRL, KEYMOD_LALT, KEYMOD_RALT, KEYMOD_LMETA, KEYMOD_RMETA, KEYMOD_NUM, KEYMOD_CAPS, KEYMOD_MODE. Read-only.

scancode

The untranslated (hardware-dependent) scancode of the key pressed. Read-only.

unicode

Unicode index of the character. Takes into account the current keyboard layout and any modifiers pressed. This attribute is only filled in the KEYDOWN event. Read-only.

class libavg.avg.MouseEvent(type, leftButtonState, middleButtonState, rightButtonState, pos, button[, speed, when])

Bases: libavg.avg.CursorEvent

Generated when a mouse-related event occurs.

button

The button that caused the event. Read-only.

cursorid

Always -1 for mouse events, but can be used to handle mouse and tracking events in one handler. Read-only.

leftbuttonstate

True if the left mouse button is currently pressed. Read-only.

middlebuttonstate

True if the middle mouse button is currently pressed. Read-only.

rightbuttonstate

True if the right mouse button is currently pressed. Read-only.

source

Always MOUSE. Read-only

speed

Current speed of the mouse in pixels per millisecond as a Point2D. Read-only.

class libavg.avg.TouchEvent(id, type, pos, source[, speed])

Bases: libavg.avg.CursorEvent

Generated when a touch or other tracking event occurs. Touch events happen only when a multi-touch sensitive surface or other camera tracker is active.

area

Size of the blob found in pixels. Read-only.

center

Position as Point2D, with sub-pixel accuracy. Used for calibration. Read-only.

cursorid

An identifier for the current touch. A single touch will generate a down, zero or more motion and a single up event in its lifetime, all with the same cursorid.

eccentricity

handorientation

The angle of the hand relative to the finger. handorientation is only defined for events with source`=:py:const:`TOUCH. If the tracker has detected a hovering hand attached to the finger, this is the actual hand-finger angle. If no hand was detected, the angle is approximated using the position of the touch on the surface. handorientation ranges from -pi to pi, with 0 being the positive x axis. Angles increase in a clockwise fashion.

For CURSORUP events, the angle is always approximated.

majoraxis

Major axis of an ellipse that is similar to the blob. Read-only.

minoraxis

Minor axis of an ellipse that is similar to the blob. Read-only.

orientation

Angle of the blob in radians. For hovering hands, this is roughly the direction of the hand, modulo 180 degrees. Read-only.

source

source can be either TRACK or TOUCH. In most cases, actual touches will generate TOUCH events. When used with a DI device, the internal tracker also generates TRACK events for hands above the surface. When used with an FTIR device, the internal tracker generates TRACK events for the actual touches. Read-only.

speed

Current speed of the touch in pixels per millisecond as a Point2D. Read-only.

getContour() → list

Returns the contour of the blob as a list of points if supported by the tracker being used.

getRelatedEvents() → events

Only for DI devices and the internal tracker: Returns a python tuple containing the events ‘related’ to this one. For TOUCH events (fingers), the tuple contains one element: the corresponding TRACK event (hand). For TRACK events, the tuple contains all TOUCH events that belong to the same hand.

class libavg.avg.Tracker

Bases: Boost.Python.instance

A class that uses a camera to track moving objects and delivers the movements as avg events. Create a tracker by using Player.enableMultitouch() with AVG_MULTITOUCH_DRIVER=TRACKER. The properties of this class are explained under https://www.libavg.de/wiki/ProgrammersGuide/Tracker.

abortCalibration()

Aborts coordinate calibration session and restores the previous coordinate transformer.

endCalibration()

Ends coordinate calibration session and activates the coordinate transformer generated.

getDisplayROIPos()

getDisplayROISize()

getImage(imageid) → Bitmap

Returns one of the intermediate images necessary for tracking. These images are only available if setDebugImages was called before with appropriate parameters. Possible imageid values are IMG_CAMERA, IMG_DISTORTED, IMG_NOHISTORY, IMG_HISTOGRAM, IMG_FINGERS or IMG_HIGHPASS.

getParam(element) → value

Returns a tracker configuration parameter.

resetHistory()

Throws away the current history image and generates a new one from the next second of images.

saveConfig()

Saves the current tracker configuration to the default config file.

setDebugImages(img, finger)

Controls whether debug images of intermediate tracking results and detected finger positions are generated and exported to python. Generating the debug images takes a moderate amount of time, so it is turned off by default.

Parameters:

• img – Whether to generate intermediate result images.
• finger – Whether to generate the IMG_FINGERS result image.

setParam(element, value)

Sets one of the tracker configuration parameters.

startCalibration(displayextents) → TrackerCalibrator

Starts coordinate calibration session. The returned TrackerCalibrator exists until endCalibration() or abortCalibration() is called.

Parameters:displayextents – The width and height of the display area.

class libavg.avg.TrackerCalibrator

Bases: Boost.Python.instance

Generates a mapping of display points to camera points using a set of reference points. Python code should display reference points that the user must touch to establish a mapping. Created by Tracker.startCalibration().

getDisplayPoint() → Point2D

nextPoint() → bool

Advances to the next point. Returns False and ends calibration if all points have been set.

setCamPoint(pos)