[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

kinetcl(n) 0.1 doc "KineTcl"

Name

kinetcl - KineTcl - API

Table Of Contents

Synopsis

  • package require Tcl 8.5
  • package require kinetcl ?0.1?

Description

Welcome to KineTcl, a binding of the OpenNI framework providing Tcl with access to MS Kinect (tm), and related sensor systems.

API

Global commands

This sections documents the global commands in the ::kinetcl namespace and ensemble.

::kinetcl estart

This command deactivates the event deferal, aka lockout mode. Any OpenNI/kinetcl events which were prevented from entering Tcl's event queue are now moved into it.

The result of the command is the empty string.

::kinetcl estop

This command activates the event deferal, aka lockout mode. Any OpenNI/kinetcl events occuring while this mode is active are prevented from entering Tcl's event queue until the next invokation of ::kinetcl estop.

The result of the command is the empty string.

::kinetcl start

This command activates data processing and generation in all known generator nodes.

The result of the command is the empty string.

::kinetcl stop

This command deactivates data processing and generation in all known generator nodes.

The result of the command is the empty string.

::kinetcl waitUpdate

This command waits for all generator nodes to have new data and then updates them all.

The result of the command is the empty string.

::kinetcl waitAnyUpdate

This command waits for any of the generator nodes to have new data and then updates them all.

The result of the command is the empty string.

::kinetcl waitNoneUpdate

This command updates all generator nodes, without any waiting.

The result of the command is the empty string.

::kinetcl waitOneUpdate node

This command waits for the specified generator node to have new data and then updates all nodes.

The result of the command is the empty string.

::kinetcl errorstate

This command returns the global error state of OpenNI as string.

::kinetcl mirror ?bool?

This command returns the current value of the global mirror flag. If the argument is specified the global mirror flag is set to its value, and all existing nodes supporting mirroring are reconfigured to reflect the new state.

Base

This sections documents the class ::kinetcl base, the (abstract) base class for all OpenNI production nodes.

This class actually inherits from ::kinetcl nodeevents for the management of events generated by OpenNI node instances. See section Node Events.

They may have the following capabilities:

  1. Backlight Compensation

  2. Brightness

  3. Color Temperature

  4. Contrast

  5. Exposure

  6. Focus

  7. Gain

  8. Gamma

  9. Hue

  10. Iris

  11. Lowlight compensation

  12. Pan

  13. Roll

  14. Saturation

  15. Sharpness

  16. Tilt

  17. Zoom

Class API

::kinetcl base new
::kinetcl base create objname

This command creates a new instance of the node base. Note that it is impossible to create such an instance on its own. It can be done only as part of constructing the instance of a concrete class. The API provided by the instance, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

baseInstanceCmd capabilities ?-all?

This method returns the capabilities of the instance, or, if option -all was specified, the set of all possible capabilities.

The result is a list containing the names of the capabilities.

baseInstanceCmd is-capable-of capability

This method checks if the named capability is supported by the instance or not.

The result is a boolean value, true if the capability is supported, and false else.

baseInstanceCmd node-info

This method returns a dictionary containing OpenNI's description of the node. They keys of the dictinary, and the associated values are

type

The OpenNI type of the node, which is either one of

  • invalid

  • device

  • depth

  • image

  • audio

  • ir

  • user

  • recorder

  • player

  • gesture

  • scene

  • hands

  • codec

  • production

  • generator

  • map

  • script

or an integer number. The latter is used for unknown custom types OpenNI has no name for.

vendor

The name of the vendor supplying the library which implements the node.

name

The name OpenNI has given to the node. This is the same as returned by method node-name.

version

The version of the library implementing the node (see also the key vendor) as a 4-element list containing major, minor version number, maintenance id, and build number, in this order.

create

The node's creation detail information.

baseInstanceCmd node-name

This method returns a string holding the OpenNI name of the node.

baseInstanceCmd bind event command

This method associates the given command prefix with the named event and arranges for the execution of the command prefix when the event in question occurs.

The result of the method is an opaque token representing the binding. It can only be used as argument of method unbind, see below, to remove the binding again.

The command prefix is expected to have the following signature:

{*}command event obj details
event The name of the event itself, allowing it to be used as sub-method name. obj The name of the instance generating the event. details A dictionary holding more information about the event. The set of keys and their values depends on the event itself and is described with the event. See the sections named Events, at all the classes supporting one or more events.

Each event supported by a specific node class is explained in the documentation of that class.

baseInstanceCmd unbind token

This method takes a token as returned by method bind (see above), and removes the binding it represents. Afterward the command prefix from bind is not invoked anymore when the event the binding was for occurs.

The result of the method is an empty string.

Generator

This sections documents the class ::kinetcl generator, the (abstract) base class for all OpenNI generator nodes.

This class inherits from ::kinetcl base. See section Base.

They may have the following capabilities:

  1. Alternative Viewpoint

  2. Frame Synchronization

  3. Mirror

Class API

::kinetcl generator new
::kinetcl generator create objname

This command creates a new instance of the generator. Note that it is impossible to create such an instance on its own. It can be done only as part of constructing the instance of a concrete class. The API provided by the instance, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

generatorInstanceCmd start

This method causes the instance to start generating output. It implies the activation of all dependencies as well.

The result of the method is the empty string.

generatorInstanceCmd stop

This method causes the instance to stop generating output.

The result of the method is the empty string.

generatorInstanceCmd active

This method tests if the instance is generating output.

The result of the method is a boolean value, true if the instance is generating output, and false else.

generatorInstanceCmd update

This method causes the instance to update its output to the newest available. If no new output was available the method blocks until this happens.

The result of the method is the empty string.

generatorInstanceCmd hasNew

This method tests if the instance has new output available it could be updated to. I.e. it checks if the method update would block or not.

The result of the method is a boolean value, true if the instance has new data (i.e. update would not block), and false else.

generatorInstanceCmd isNew

This method tests if the instance's current input frame is new, i.e. unchanged since the last call to method update.

The result of the method is a boolean value, true if the instance if the current frame is still new, and false else.

The result of the method is the empty string.

generatorInstanceCmd frame

This method returns the id of the input frame currently handled by the instance.

The result of the method is an integer number.

generatorInstanceCmd time

This method returns the time of the input frame currently handled by the instance, in microseconds.

The result of the method is an integer number.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

active

This event is generated in response to activity changes, i.e. the instance starting and stopping the generation of output.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

newdata

This event is generated in response to the availability of new data, i.e the instance having new output available for the user.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Map Generator

This sections documents the class ::kinetcl map, the (abstract) base class for all OpenNI map generator nodes.

This class inherits from ::kinetcl generator and its superclasses. See section Generator.

They may have the following capabilities:

  1. Anti-Flicker

  2. Cropping

Class API

::kinetcl map new
::kinetcl map create objname

This command creates a new instance of the map generator. Note that it is impossible to create such an instance on its own. It can be done only as part of constructing the instance of a concrete class. The API provided by the instance, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

mapInstanceCmd bytes-per-pixel

This method returns the number of bytes per pixel in the map.

mapInstanceCmd modes

This method returns the map output modes supported by the instance.

The result of the method is a list of modes. Each mode is a 3-element list reporting the x- and y-resolution of the map in pixels, and the associated frame rate in frames per second, in this order. All elements are integer numbers.

mapInstanceCmd mode

This form of the method reports the currently set map output mode.

The result of the method is a 3-element list reporting the x- and y-resolution of the map in pixels, and the associated frame rate in frames per second, in this order. All elements are integer numbers.

mapInstanceCmd mode xres yres fps

This form of the method changes the map output mode to the specified resolution and frame rate. The method throws an error if the combination is not supported by the instance.

The result of the method is an empty string.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

mode

This event is generated in response to mode changes, i.e. reconfiguration of the instance's output mode.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Depth Generator

This sections documents the class ::kinetcl generator, the concrete class for all OpenNI depth generator nodes.

This class inherits from ::kinetcl generator and its superclasses. See section Generator.

A depth generator is a generator providing depth maps, i.e. images where each pixel value describes the distance of the pixel from the sensor.

Class API

::kinetcl depth new
::kinetcl depth create objname

This command creates a new depth generator instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

depthInstanceCmd destroy

This method destroys the depth generator instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

depthInstanceCmd max-depth

This method returns the max depth the node is able to generate. The result is an integer number.

depthInstanceCmd fov

This method returns the field of view the node is able to generate, in radians. The result is a 2-element list containing the horizontal and vertical fields of view, in this order.

depthInstanceCmd meta

This method returns a dictionary holding information about the depth maps produced by the node. The keys found in this dictionary, and the associated values are:

map

The value is a dictionary holding information about the map produced by the node. The keys found in this dictionary, and the associated values are:

format

The pixel format of the depth maps produced by the node. The possible values are:

rgb24

3 bytes/pixel red/green/blue.

yuv422

Lumincance/2-Chroma, chroma in reduced horizontal resolution.

grey8

1 byte/pixel, 256 grey levels.

grey16

2 byte/pixel, 65536 grey levels, depths, or labels.

mjpeg

Motion JPEG compressed image.

The formats yuv422 and mjpeg are not supported by kinetcl.

fps

The frame rate of the node, in frames per second.

fullres

The full resolution of the produced depth maps. The value is a 2-element list containing the horizontal and vertical resolution in pixels, in this order.

offset

The location of the produced depth map within the full depth map. The value is a 2-element list containing the horizontal and vertical position in pixels, in this order. This can differ from {0 0} if and only if cropping is active.

output

The value is a dictionary holding information about the output produced by the node. The keys found in this dictionary, and the associated values are:

frame

The id of the current frame.

new

The isNew flag of the current frame.

size

The size of the frame, in bytes. Together with the resolution of the frame we can compute the number of bytes per pixel in the map.

time

The time-code of the current frame.

res

The current resolution of the produced depth maps. This may be less than the full resolution (see above), if cropping is active. The value is a 2-element list containing the horizontal and vertical resolution in pixels, in this order.

max-depth

The max depth the node is able to generate. An integer number. This is the same value as returned by method max-depth.

Notes:

Depth maps are in pixel format grey16.

depthInstanceCmd map

This method returns a crimp image of type grey16 where the value of each pixel represents the distance of the pixel from the sensor, in millimeters.

depthInstanceCmd projective2world point...

This method converts one or more 3D points from sensor coordinates to real world coordinates.

The result of the method is a list holding the conversion results. Each point in both arguments and result is a 3-element list containing the point's X-, Y-, and Z-coordinates, in this order.

depthInstanceCmd world2projective point...

This method converts one or more 3D points from real world coordinates to sensor coordinates.

The result of the method is a list holding the conversion results. Each point in both arguments and result is a 3-element list containing the point's X-, Y-, and Z-coordinates, in this order.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

depthfov

This event is generated in response to depthfov changes, i.e. reconfiguration of the device's field of view.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Image Generator

This sections documents the class ::kinetcl image, the concrete class for all OpenNI image generator nodes.

This class inherits from ::kinetcl map and its superclasses. See section Map Generator.

An image generator is a map generator providing plain images, where each pixel value describes the color (or luminance) of the pixel.

Class API

::kinetcl image new
::kinetcl image create objname

This command creates a new image generator instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

imageInstanceCmd destroy

This method destroys the image generator instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

imageInstanceCmd formats

This method returns a list of the pixel formats supported by the node.

For the list of possible pixel formats see below, under method meta.

imageInstanceCmd format ?format?

This method returns the name of the currently active pixel format. If the argument format is present the node is reconfigured to report the images in the specified format.

For the list of possible pixel formats see below, under method meta.

imageInstanceCmd meta

This method returns a dictionary holding information about the image maps produced by the node. The keys found in this dictionary, and the associated values are:

map

The value is a dictionary holding information about the map produced by the node. The keys found in this dictionary, and the associated values are:

format

The pixel format of the depth maps produced by the node. The possible values are:

rgb24

3 bytes/pixel red/green/blue.

yuv422

Lumincance/2-Chroma, chroma in reduced horizontal resolution.

grey8

1 byte/pixel, 256 grey levels.

grey16

2 byte/pixel, 65536 grey levels, depths, or labels.

mjpeg

Motion JPEG compressed image.

The formats yuv422 and mjpeg are not supported by kinetcl.

fps

The frame rate of the node, in frames per second.

fullres

The full resolution of the produced depth maps. The value is a 2-element list containing the horizontal and vertical resolution in pixels, in this order.

offset

The location of the produced depth map within the full depth map. The value is a 2-element list containing the horizontal and vertical position in pixels, in this order. This can differ from {0 0} if and only if cropping is active.

output

The value is a dictionary holding information about the output produced by the node. The keys found in this dictionary, and the associated values are:

frame

The id of the current frame.

new

The isNew flag of the current frame.

size

The size of the frame, in bytes. Together with the resolution of the frame we can compute the number of bytes per pixel in the map.

time

The time-code of the current frame.

res

The current resolution of the produced depth maps. This may be less than the full resolution (see above), if cropping is active. The value is a 2-element list containing the horizontal and vertical resolution in pixels, in this order.

Notes:

Image maps are usually in pixel format rgb24.

imageInstanceCmd map

This method returns a crimp image containing the current image map. The crimp type of the image depends on the currently active pixel format:

rgb24

--> rgb

grey8

--> grey8

grey16

--> grey16

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

pixelformat

This event is generated in response to changes of the pixel format used for the images generated by the instance.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

IR Generator

This sections documents the class ::kinetcl ir, the concrete class for all OpenNI IR image generator nodes.

This class inherits from ::kinetcl map and its superclasses. See section Map Generator.

An IR image generator is a map generator providing infrared images.

Class API

::kinetcl ir new
::kinetcl ir create objname

This command creates a new ir image generator instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

irIstanceCmd destroy

This method destroys the ir image generator instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

Gesture Generator

This sections documents the class ::kinetcl gesture, the concrete class for all OpenNI gesture generator nodes.

This class inherits from ::kinetcl generator and its superclasses. See section Generator.

A genestur generator identifies and tracks gestures performed by the users within the field of view of the sensor.

Class API

::kinetcl gesture new
::kinetcl gesture create objname

This command creates a new gesture generator instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

gestureInstanceCmd destroy

This method destroys the gesture generator instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

gestureInstanceCmd add-gesture gesture ?box?

This method activates the gesture, i.e. causes the instance to start looking for it in the input.

The box describes the area where to look for it, in real-world coordinates. It is a 2-element list of 3-element lists of x-, y-, and z-coordinates. The 1st 3D coordinate describes the left-bottom-near corner of the box, whereas the 2nd describes the right-top-far corner.

If not specified the box encompasses the whole field of view.

The result of the method is the empty string.

gestureInstanceCmd remove-gesture gesture

This method deactivates the gesture, i.e. causes the instance to stop looking for it in the input.

The result of the method is the empty string.

gestureInstanceCmd is-gesture gesture

This method tests if the named gesture is supported by the instance.

The result is a boolean value, true if the gesture is supported, and false else.

gestureInstanceCmd gesture-has-progress gesture

This method tests if the named gesture supports progess reporting during recognition.

The result is a boolean value, true if the gesture supports progress reporting, and false else.

gestureInstanceCmd all-gestures

This method returns a list containing the names of all gestures supported by the instance.

gestureInstanceCmd active-gestures

This method returns a list containing the names of all gestures that are currently active.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

gesture-recognized

This event is generated in response to the recognition of named a gesture.

The detail dictionary of this event contains:

gesture

The name of the gesture which was recognized

id_position

The position where the gesture was recognized. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

end_position

The position of the hand at the end of the gesture. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

gesture-progress

This event is generated in response to the system's progress in recognizing a gesture.

The detail dictionary of this event contains:

gesture

The name of the gesture whose recognition is in progress.

position

The current position of the hand performing the gesture. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

percent

The percentage of the gesture already performed.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

gesture

This event is generated in response to the (de)activation of the recognition of named gestures.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

gesture-stage-complete

This event is generated in response to the completion of stages in a gesture's recognition.

The detail dictionary of this event contains:

gesture

The name of the gesture whose recognition is in progress.

position

The current position of the hand performing the gesture. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

gesture-stage-ready-for-next

This event is generated in response to the system's readiness to enter the next stage in the recognition of a gesture.

The detail dictionary of this event contains:

gesture

The name of the gesture whose recognition is in progress.

position

The current position of the hand performing the gesture. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Scene Analyzer

This sections documents the class ::kinetcl scene, the concrete class for all OpenNI scene analyzer nodes.

This class inherits from ::kinetcl map and its superclasses. See section Map Generator.

A scene analyzer segments a scene, identifying the floor and other connected areas (i.e. users) in the view of the sensor.

Class API

::kinetcl scene

This command creates a new scene analyzer instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

sceneInstanceCmd destroy

This method destroys the scene analyzer instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

sceneInstanceCmd meta

This method returns a dictionary holding information about the scene segmentation produced by the node. The keys found in this dictionary, and the associated values are:

map

The value is a dictionary holding information about the map produced by the node. The keys found in this dictionary, and the associated values are:

format

The pixel format of the depth maps produced by the node. The possible values are:

rgb24

3 bytes/pixel red/green/blue.

yuv422

Lumincance/2-Chroma, chroma in reduced horizontal resolution.

grey8

1 byte/pixel, 256 grey levels.

grey16

2 byte/pixel, 65536 grey levels, depths, or labels.

mjpeg

Motion JPEG compressed image.

The formats yuv422 and mjpeg are not supported by kinetcl.

fps

The frame rate of the node, in frames per second.

fullres

The full resolution of the produced depth maps. The value is a 2-element list containing the horizontal and vertical resolution in pixels, in this order.

offset

The location of the produced depth map within the full depth map. The value is a 2-element list containing the horizontal and vertical position in pixels, in this order. This can differ from {0 0} if and only if cropping is active.

output

The value is a dictionary holding information about the output produced by the node. The keys found in this dictionary, and the associated values are:

frame

The id of the current frame.

new

The isNew flag of the current frame.

size

The size of the frame, in bytes. Together with the resolution of the frame we can compute the number of bytes per pixel in the map.

time

The time-code of the current frame.

res

The current resolution of the produced depth maps. This may be less than the full resolution (see above), if cropping is active. The value is a 2-element list containing the horizontal and vertical resolution in pixels, in this order.

Notes:

Scene segmentations are in pixel format grey16.

sceneInstanceCmd map

This method returns a crimp image of type grey16 containing the current scene segmentation. Each pixel is labeled with the id of the user it belongs to, or 0 if it is background.

sceneInstanceCmd floor

This method returns a dictionary describing the floor, as a combination of a point on the floor, plus the normal vector to specify orientation. The two keys in the dictionary are

point

A point on the floor, in real world coordinates. The value is a 3-element list containing the x-, y-, and z-coordinates, in this order.

normal

The normal vector describing the orientation. The value is a 3-element list containing the real world x-, y-, and z-coordinates, in this order.

User Generator

This sections documents the class ::kinetcl user, the concrete class for all OpenNI user generator nodes.

This class inherits from ::kinetcl generator and its superclasses. See section Generator.

A user generator identifies and tracks users within the field of view of the sensor.

They may have the following capabilities:

  1. Pose Detection

  2. Hand Touching FOV Edge

  3. Skeleton/Joint Tracking

Class API

::kinetcl user new
::kinetcl user create objname

This command creates a new user generator instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

userInstanceCmd destroy

This method destroys the user generator instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

userInstanceCmd count

This method returns the number of users currently tracked by the user generator instance.

userInstanceCmd users

This method returns a list containing the ids of the users currently tracked by the user generator instance.

userInstanceCmd centerof id

This method returns the center location for the user specified by its id, as a 3-element list, i.e. vector, of floating point coordinates. The coordinates are specified in the order of X, Y, and Z.

The method will throw an error if the user id is not valid.

userInstanceCmd pixelsof id

This method returns a crimp image of type grey16 where all pixels representing the user are set to the user's id, and everything else set to 0.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

user-enter

This event is generated in response to a user re-entering the scene.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

user-exit

This event is generated in response to a user existing the scene.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

user-new

This event is generated in response to the recognition of a new user.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

user-lost

This event is generated in response to the loss of a user (after exiting the scene).

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Hands Generator

This sections documents the class ::kinetcl hands, the concrete class for all OpenNI hand generator nodes.

This class inherits from ::kinetcl generator and its superclasses. See section Generator.

A hand generator identifies and tracks the hands of the users within the field of view of the sensor.

Class API

::kinetcl hands new
::kinetcl hands create objname

This command creates a new hands generator instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

handsInstanceCmd destroy

This method destroys the hands generator instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

instanceCmd set-smoothing factor

This method sets the smoothing factor for hand tracking, a floating point value between 0 and 1. The former disables smoothing, the latter implies infinite smoothing.

The result of the method is an empty string.

instanceCmd start-tracking point

This method activates the tracking of a hand at the point. The point must be a 3-element list containing the X, Y, and Z coordinates, in this order.

The result of the method is an empty string.

instanceCmd stop-tracking id

This method stops tracking of the hand specified by the id.

The result of the method is an empty string.

instanceCmd stop-tracking-all

This method stops the tracking of all hands known to the node.

The result of the method is an empty string.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

hand-create

This event is generated in response to the creation of a new tracked hand.

The detail dictionary of this event contains:

hand

The id of the tracked hand.

position

The position of the hand. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

time

A timestamp.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

hand-update

This event is generated in response to the movement of an existing tracked hand.

The detail dictionary of this event contains:

hand

The id of the tracked hand.

position

The position of the hand. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

time

A timestamp.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

hand-destroy

This event is generated in response to the removal of a hand from tracking.

The detail dictionary of this event contains:

hand

The id of the lost hand.

time

A timestamp.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Audio Generator

This sections documents the class ::kinetcl audio, the concrete class for all OpenNI audio generator nodes.

This class inherits from ::kinetcl generator and its superclasses. See section Generator.

An audio generator provides access to the stream of sound data from the sensor.

Class API

::kinetcl audio new
::kinetcl audio create objname

This command creates a new audio generator instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

audioInstanceCmd destroy

This method destroys the audio generator instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

Recorder Node

This sections documents the class ::kinetcl recorder, the concrete class for all OpenNI recorder nodes.

This class inherits from ::kinetcl base. See section Base.

A recorder watches the stream of sensor information in the system and serializes it to a file. A player node may in the future read this information and replay it.

Class API

::kinetcl recorder new
::kinetcl recorder create objname

This command creates a new recorder instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

recorderInstanceCmd destroy

This method destroys the recorder instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

Player Node

This sections documents the class ::kinetcl player, the concrete class for all OpenNI player nodes.

This class inherits from ::kinetcl base. See section Base.

A player read a stream of sensor information from a file and injects it into the system, faking the existence of a sensor.

Class API

::kinetcl player new
::kinetcl player create objname

This command creates a new player instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

playerInstanceCmd destroy

This method destroys the player instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

playerInstanceCmd speed speed

This method sets the speed of playback as a ratio of the time passed in the recording. I.e. a speed of 1 implies playback at the same frame/rate as recorded, whereas a speed < 1 causes slow-motion, and a speed > 1 fast-forward.

The result of the method is the empty string.

playerInstanceCmd speed

This method returns the speed of playback, as a ratio of the time passed in the recording.

The result of the method is a floating point number.

playerInstanceCmd repeat bool

This method activates or deactivates repeating mode. If repeating is activated (bool is true) the player will automatically rewind to the beginning of the recording when reaching the end, and continue playing.

The result of the method is the empty string.

playerInstanceCmd eof

This method tests if the player has reached the end of the recording, or not. Note that this is never true when the player is in repeating mode, however "eof" events are still triggered.

The result of the method is boolean value, true if the player is at the end of the recording, and false else.

playerInstanceCmd format

This method returns the name of the format supported by the player instance.

playerInstanceCmd next

This method causes the player to explicitly advance to the next frame.

The result of the method is the empty string.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

eof

This event is generated in response to the player reaching the end of the recording (even when it loops).

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Script Node

This sections documents the class ::kinetcl script, the concrete class for all OpenNI recorder nodes.

This class inherits from ::kinetcl base. See section Base.

A script node can run scripts (sic!), and manages the life-time of all nodes created by such.

Class API

::kinetcl script new
::kinetcl script create objname

This command creates a new script instance and returns the fully qualified name of the instance command. The API provided by that command, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

scriptInstanceCmd destroy

This method destroys the script instance and releases all associated resources, including the instance command. Note that resources used by multiple instances are released only when the last instance using them is destroyed.

The result of the method is the empty string.

Capabilities

This sections documents the various capabilities a production node may have. The main classes will all refer to the sub-sections found here.

Alternative Viewpoint

Should an instance support alternate viewpoints the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name alternative-viewpoint.

instanceCmd supports-view node

This method tests if the instance is able to use the viewpoint of the the other production node. This argument is the object command of another kinetcl instance.

The result is a boolean value, true if the viewpoint of node is supported, and false else.

instanceCmd set-view node

This method sets the instance's viewpoint to the view of the other production node. This argument is the object command of another kinetcl instance.

The result of the method is an empty string. An error is thrown if the node's viewpoint is not supported.

instanceCmd reset-view

This method sets the instance's viewpoint back to its own viewpoint.

The result of the method is an empty string.

instanceCmd using-view node

This method tests if the instance is currently using the viewpoint of the other production node. This argument is the object command of another kinetcl instance.

The result is a boolean value, true if the viewpoint of node is in use, and false else.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

viewpoint

This event is generated in response to viewpoint changes, i.e. when the instance takes or drops the viewpoint of another node.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Anti-Flicker

Should an instance support anti-flicker behaviour the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name antiflicker.

instanceCmd frequency

In this form the method returns the current anti-flicker settings.

The result is either the string off, or the powerline frequency the node is synchronized to.

instanceCmd crop frequency

In this form the method changes the anit-flicker settings. The allowed values for frequency are 50, 60, and off. The latter disables the anti-flicker system.

The result is an empty string.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

frequency

This event is generated in response to reconfiguration of the instance's powerline frequency setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Cropping

Should an instance support cropping the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name cropping.

instanceCmd crop

In this form the method returns the current crop settings.

The result is a list of 4-elements containing the x- and y-offset of the crop rectangle, and its horizontal and vertical dimensions, in this order.

instanceCmd crop x y w h

In this form the method sets the crop rectangle to the specified x- and y-offset of the crop rectangle, and its horizontal and vertical dimensions

The result is an empty string.

instanceCmd uncrop

This method deactivates any croppping set on the instance.

The result of the method is an empty string.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

cropping

This event is generated in response to reconfiguration of the instance's crop region.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Frame Synchronization

Should an instance support frame synchronization the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name framesync.

instanceCmd can-sync-with node

This method tests if the instance is able to synchronize its generation of frames with the the other production node. This argument is the object command of another kinetcl instance.

The result is a boolean value, true if the viewpoint of node is supported, and false else.

instanceCmd start-sync-with node

This method causes the instance's to synchronize its frame generation with the other production node. This argument is the object command of another kinetcl instance.

The result of the method is an empty string. An error is thrown if the instance is not able to synchronize with node.

instanceCmd stop-sync-with node

This method causes the instance's to decouple its frame generation from the other production node. This argument is the object command of another kinetcl instance.

The result of the method is an empty string.

instanceCmd synced-with node

This method tests if the instance is currently synchronized to the other production node. This argument is the object command of another kinetcl instance.

The result is a boolean value, true if the instance is synchronized to node, and false else.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

framesync

This event is generated in response to frame synchronization changes, i.e. when the instance starts or stops synchronization with another node.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Hand Touching FOV Edge

Should an instance support the events for hands touching the edge of the field of view the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name hand-touching-fov-edge.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

fov-edge

This event is generated in response to hands coming into contact with the edge of the field of view (a box).

The detail dictionary of this event contains:

hand

The numerical id of the hand the event was generated for.

position

The position of the hand when it touched the edge. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

times

The timestamp is a floating point value in seconds.

direction

The direction is one of

  1. illegal

  2. left

  3. right

  4. up

  5. down

  6. forward

  7. backward

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Mirror

Should an instance support mirroring the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name mirror.

instanceCmd mirror

In this form the method returns the current state of the instance's mirror flag.

The result is a boolean value, true if the instance generates mirrored frames, and false else.

instanceCmd mirror bool

In this form the method (un)sets the instance's mirror flag.

The result is an empty string.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

mirror

This event is generated in response to reconfiguration of the instance's mirror flag.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Pose Detection

Should an instance support pose detection the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name user-pose-detection.

instanceCmd poses

This method returns a list containing the names of the supported user poses.

instanceCmd is-supported pose

This method tests if the named user pose is supported by the instance.

The result is a boolean value, true if the pose is supported, and false else.

instanceCmd start-detection user pose

This method activates the detection of the named pose for the specified user.

The result of the method is an empty string.

instanceCmd stop-detection user pose

This method deactivates the detection of the named pose for the specified user.

The result of the method is an empty string.

instanceCmd stop-all-detection user

This method deactivates the detection of any poses for the specified user.

The result of the method is an empty string.

instanceCmd status user pose

This method queries the status of the detection of the named pose for the specified user.

The result of the method is 3-element string containing, in the named order

  1. The state of the user with respect to the pose, one of in, out, or undefined

  2. The status of the detection progress.

    The possible stati are

    1. ok

    2. no-user

    3. top-fov

    4. side-fov

    5. error

    6. no-tracking

  3. A timestamp telling us when the user entered the pose, if it is in the pose. If the user is out of the pose 0 is returned here.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

pose-enter

This event is generated in response to a user entering a pose.

The detail dictionary of this event contains:

pose

The name of the pose the event was generated for.

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

pose-exit

This event is generated in response to a user exiting a pose.

The detail dictionary of this event contains:

pose

The name of the pose the event was generated for.

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

pose-progress

This event is generated in response to the system's progress in the detection of a pose for a user.

The detail dictionary of this event contains:

pose

The name of the pose the event was generated for.

user

The numerical id of the user the event was generated for.

status

The status of the pose detection engine.

The possible stati are

  1. ok

  2. no-user

  3. top-fov

  4. side-fov

  5. error

  6. no-tracking

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Skeleton/Joint Tracking

Should an instance support skeleton and joint tracking the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name user-skeleton.

instanceCmd need-pose

This method tests if the skeleton tracking requires the user to enter a pose for calibration.

The result is a boolean value, true if entering a pose is required, and false else. NOTE: XXX. The C API to query the name of the required pose looks to be borken, or underspecified. Research required.

instanceCmd is-profile-available profile

This method tests if the skeleton tracking supports the named profile.

The result is a boolean value, true if the profile is supported, and false else.

The accepted profile names are

  1. none

  2. all

  3. upper

  4. lower

  5. heads-hands

instanceCmd set-profile profile

This method activates the named profile. This will result in joints getting activated or deactivated, as per the profile.

The accepted profile names are described above, at is-profile-available.

The result of the method is an empty string.

instanceCmd set-smoothing factor

This method sets the skeleton smoothing factor, a floating point value.

The result of the method is an empty string.

instanceCmd start-tracking id

This method activates the tracking of the skeleton for the user specified by the id.

The result of the method is an empty string.

instanceCmd stop-tracking id

This method stops tracking of the skeleton for the user specified by the id.

The result of the method is an empty string.

instanceCmd reset-tracking id

This method discards the calibration of the skeleton for the user specified by the id.

The result of the method is an empty string.

instanceCmd is-tracking id

This method tests if the skeleton for the user id is currently tracked.

The result is a boolean value, true if tracking is active, and false else.

instanceCmd is-calibrated id

This method tests if the skeleton for the user id is calibrated.

The result is a boolean value, true if the skeleton is calbrated, and false else.

instanceCmd is-calibrating id

This method tests if calibration of the skeleton for the user id is currently in progress.

The result is a boolean value, true if calibration is in progress, and false else.

instanceCmd request-calibration id force

This method requests calibration of the skeleton for the user specified by the id.

The result of the method is an empty string.

If the boolean flag force is set any previous calibration data is discarded.

instanceCmd abort-calibration id

This method stops a calibration in progress, for the user specified by the id.

The result of the method is an empty string.

instanceCmd save-calibration-file id path

This method saves the calibration data for the skeleton of the user specified by the id into the file path. The format of the calibration data is not documented.

The result of the method is an empty string.

instanceCmd load-calibration-file id path

This method loads the calibration data for the skeleton of the user specified by the id from the file path. The format of the calibration data is not documented.

The result of the method is an empty string.

instanceCmd save-calibration id slot

This method saves the calibration data for the skeleton of the user specified by the id into the in-memory storage identified by the slot number.

The result of the method is an empty string.

instanceCmd load-calibration-slot id slot

This method loads the calibration data for the skeleton of the user specified by the id from the in-memory storage identified by the slot number.

The result of the method is an empty string.

instanceCmd clear-calibration-slot slot

This method clears the in-memory calibration data storage identified by the slot number.

The result of the method is an empty string.

instanceCmd is-calibration-slot slot

This method tests if the in-memory storage identified by the slot number contains skeleton calibration data.

The result is a boolean value, true if the slot is occupied, and false else.

instanceCmd is-joint-available joint

This method tests if the skeleton tracking supports the named joint.

The result is a boolean value, true if the joint is supported, and false else.

The accepted joint names are

  1. head

  2. neck

  3. torso

  4. waist

  5. left-collar

  6. left-shoulder

  7. left-elbow

  8. left-wrist

  9. left-hand

  10. left-fingertip

  11. right-collar

  12. right-shoulder

  13. right-elbow

  14. right-wrist

  15. right-hand

  16. right-fingertip

  17. left-hip

  18. left-knee

  19. left-ankle

  20. left-foot

  21. right-hip

  22. right-knee

  23. right-ankle

  24. right-foot

instanceCmd is-joint-active joint

This method tests if the the named joint is actively tracked.

The result is a boolean value, true if the joint is active, and false else.

The accepted joint names are described above, at is-joint-available.

instanceCmd set-joint-active joint active

This method (de)activates the named joint.

The accepted joint names are described above, at is-joint-available.

The result of the method is an empty string.

instanceCmd active-joints

This method returns a list containig the names of all currently active joints.

The possible joint names are described above, at is-joint-available.

instanceCmd get-joint user joint

This method retrieves position and orientation data for the user specified by id and the named joint.

The accepted joint names are described above, at is-joint-available.

The result of the command is a 2-element list containing, in the order specified:

position

A 2-element list containing, in the order specified:

confidence

A floating point value representing the system's confidence in the position information.

coordinates

A 3-element list of floating point values representing the x-, y-, and z-position of the joint.

orientation

A 2-element list containing, in the order specified:

confidence

A floating point value representing the system's confidence in the orientation information.

rotation

A 9-element list of floating point values representating the rotation matrix for the joint.

instanceCmd get-skeleton user

This method retrieves the position and orientation data for all joints of the user specified by id. In other words, the whole skeleton, as available and active.

The result of the method is a dictionary mapping joint names to position and orientation, given in the format returned by method get-joint.

Joints which are either not available or not actively tracked will not be found in the dictionary.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

joint

This event is generated in response to joint changes, i.e. the (de)activation of specific joints.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

calibration-start

This event is generated in response to the start of skeleton calibration for a user.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

calibration-complete

This event is generated in response to the completion of skeleton calibration for a user.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

status

The status of the calibration engine.

The possible stati are

  1. ok

  2. no-user

  3. arm

  4. leg

  5. head

  6. torso

  7. top-fov

  8. side-fov

  9. pose

  10. manual-abort

  11. manual-reset

  12. timeout

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

calibration-progress

This event is generated in response to the system's progress in the calibration of the skeleton for a user.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

status

The status of the calibration engine.

The possible stati are

  1. ok

  2. no-user

  3. arm

  4. leg

  5. head

  6. torso

  7. top-fov

  8. side-fov

  9. pose

  10. manual-abort

  11. manual-reset

  12. timeout

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Backlight Compensation

Should an instance support the backlight-compensation setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name backlight-compensation.

instanceCmd backlight-compensation

In this form the method returns the current state of the instance's backlight-compensation setting.

The result is an integer.

instanceCmd backlight-compensation value

In this form the method changes the instance's backlight-compensation setting to the specified value.

The result is an empty string.

instanceCmd backlight-compensation-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

backlight-compensation

This event is generated in response to backlight-compensation changes, i.e. reconfiguration of the instance's backlight-compensation setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Brightness

Should an instance support the brightness setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name brightness.

instanceCmd brightness

In this form the method returns the current state of the instance's brightness setting.

The result is an integer.

instanceCmd brightness value

In this form the method changes the instance's brightness setting to the specified value.

The result is an empty string.

instanceCmd brightness-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

brightness

This event is generated in response to brightness changes, i.e. reconfiguration of the instance's brightness setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Color Temperature

Should an instance support the color-temperature setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name color-temperature.

instanceCmd color-temperature

In this form the method returns the current state of the instance's color-temperature setting.

The result is an integer.

instanceCmd color-temperature value

In this form the method changes the instance's color-temperature setting to the specified value.

The result is an empty string.

instanceCmd color-temperature-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

color-temperature

This event is generated in response to color-temperature changes, i.e. reconfiguration of the instance's color-temperature setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Contrast

Should an instance support the contrast setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name contrast.

instanceCmd contrast

In this form the method returns the current state of the instance's contrast setting.

The result is an integer.

instanceCmd contrast value

In this form the method changes the instance's contrast setting to the specified value.

The result is an empty string.

instanceCmd contrast-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

contrast

This event is generated in response to contrast changes, i.e. reconfiguration of the instance's contrast setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Exposure

Should an instance support the exposure setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name exposure.

instanceCmd exposure

In this form the method returns the current state of the instance's exposure setting.

The result is an integer.

instanceCmd exposure value

In this form the method changes the instance's exposure setting to the specified value.

The result is an empty string.

instanceCmd exposure-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

exposure

This event is generated in response to exposure changes, i.e. reconfiguration of the instance's exposure setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Focus

Should an instance support the focus setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name focus.

instanceCmd focus

In this form the method returns the current state of the instance's focus setting.

The result is an integer.

instanceCmd focus value

In this form the method changes the instance's focus setting to the specified value.

The result is an empty string.

instanceCmd focus-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

focus

This event is generated in response to focus changes, i.e. reconfiguration of the instance's focus setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Gain

Should an instance support the gain setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name gain.

instanceCmd gain

In this form the method returns the current state of the instance's gain setting.

The result is an integer.

instanceCmd gain value

In this form the method changes the instance's gain setting to the specified value.

The result is an empty string.

instanceCmd gain-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

gain

This event is generated in response to gain changes, i.e. reconfiguration of the instance's gain setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Gamma

Should an instance support the gamma setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name gamma.

instanceCmd gamma

In this form the method returns the current state of the instance's gamma setting.

The result is an integer.

instanceCmd gamma value

In this form the method changes the instance's gamma setting to the specified value.

The result is an empty string.

instanceCmd gamma-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

gamma

This event is generated in response to gamma changes, i.e. reconfiguration of the instance's gamma setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Hue

Should an instance support the hue setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name hue.

instanceCmd hue

In this form the method returns the current state of the instance's hue setting.

The result is an integer.

instanceCmd hue value

In this form the method changes the instance's hue setting to the specified value.

The result is an empty string.

instanceCmd hue-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

hue

This event is generated in response to hue changes, i.e. reconfiguration of the instance's hue setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Iris

Should an instance support the iris setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name iris.

instanceCmd iris

In this form the method returns the current state of the instance's iris setting.

The result is an integer.

instanceCmd iris value

In this form the method changes the instance's iris setting to the specified value.

The result is an empty string.

instanceCmd iris-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

iris

This event is generated in response to iris changes, i.e. reconfiguration of the instance's iris setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Lowlight compensation

Should an instance support the lowlight-compensation setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name lowlight-compensation.

instanceCmd lowlight-compensation

In this form the method returns the current state of the instance's lowlight-compensation setting.

The result is an integer.

instanceCmd lowlight-compensation value

In this form the method changes the instance's lowlight-compensation setting to the specified value.

The result is an empty string.

instanceCmd lowlight-compensation-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

lowlight-compensation

This event is generated in response to lowlight-compensation changes, i.e. reconfiguration of the instance's lowlight-compensation setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Pan

Should an instance support the pan setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name pan.

instanceCmd pan

In this form the method returns the current state of the instance's pan setting.

The result is an integer.

instanceCmd pan value

In this form the method changes the instance's pan setting to the specified value.

The result is an empty string.

instanceCmd pan-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

pan

This event is generated in response to pan changes, i.e. reconfiguration of the instance's pan setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Roll

Should an instance support the roll setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name roll.

instanceCmd roll

In this form the method returns the current state of the instance's roll setting.

The result is an integer.

instanceCmd roll value

In this form the method changes the instance's roll setting to the specified value.

The result is an empty string.

instanceCmd roll-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

roll

This event is generated in response to roll changes, i.e. reconfiguration of the instance's roll setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Saturation

Should an instance support the saturation setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name saturation.

instanceCmd saturation

In this form the method returns the current state of the instance's saturation setting.

The result is an integer.

instanceCmd saturation value

In this form the method changes the instance's saturation setting to the specified value.

The result is an empty string.

instanceCmd saturation-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

saturation

This event is generated in response to saturation changes, i.e. reconfiguration of the instance's saturation setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Sharpness

Should an instance support the sharpness setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name sharpness.

instanceCmd sharpness

In this form the method returns the current state of the instance's sharpness setting.

The result is an integer.

instanceCmd sharpness value

In this form the method changes the instance's sharpness setting to the specified value.

The result is an empty string.

instanceCmd sharpness-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

sharpness

This event is generated in response to sharpness changes, i.e. reconfiguration of the instance's sharpness setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Tilt

Should an instance support the tilt setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name tilt.

instanceCmd tilt

In this form the method returns the current state of the instance's tilt setting.

The result is an integer.

instanceCmd tilt value

In this form the method changes the instance's tilt setting to the specified value.

The result is an empty string.

instanceCmd tilt-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

tilt

This event is generated in response to tilt changes, i.e. reconfiguration of the instance's tilt setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Zoom

Should an instance support the zoom setting the following methods become available. This support can checked by invoking the inherited method is-capable-of for the capability name zoom.

instanceCmd zoom

In this form the method returns the current state of the instance's zoom setting.

The result is an integer.

instanceCmd zoom value

In this form the method changes the instance's zoom setting to the specified value.

The result is an empty string.

instanceCmd zoom-range

This method returns a dictionary describing the allowed domain of values for the capability. The keys and associated values are:

min

The value is an integer number, the minimal value the setting is allowed to have.

max

The value is an integer number, the maximal value the setting is allowed to have.

default

The value is an integer number, the default value the setting will have after node construction.

step

The value is an integer number, the difference between two legal values of the setting. The difference between min and max is a multiple of this value.

auto

A boolean value. If true the setting supports automatic adjustment during operation of the node, otherwise not.

This capability supports the events below. These names can be used as the event argument of method bind defined by base class ::kinetcl::base.

zoom

This event is generated in response to zoom changes, i.e. reconfiguration of the instance's zoom setting.

The detail dictionary of this event is empty.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Event Base

This sections documents the class ::kinetcl ventbase, a base class supplying general event management facilities.

This class has no superclasses, i.e it inherit nothing.

It itself is used by the classes ::kinetcl nodeevents (described in section Node Events) and ::kinetcl joints (described in section Joint Events.

Class API

::kinetcl eventbase new
::kinetcl eventbase create objname

This command creates a new instance of the class, either automatically named (new), or explicitly (create). The API provided by the instance, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

instanceCmd bind event cmdprefix

This method binds the command prefix cmdprefix to the specified event and returns an opaque token for the binding.

The system ensures that everybody with an interest in the event (i.e. having to know if there are bindings or not) is notified and can take action.

The result of the method is an opaque token.

The command prefix is expected to have the following signature:

{*}$cmdprefix event instance details
event The name of the event which triggered the command. First argument, thus allowing it to be used as a sub-command or method of an ensemble or object instance. instance The object instance generating the event. details Event specific data with more information about the event.
instanceCmd unbind token

This method removes the event binding represented by the opaque token, a result of a call to method bind above.

The system ensures that everybody with an interest in the event (i.e. having to know if there are bindings or not) is notified and can take action.

The result of the method is an empty string.

instanceCmd generate event details

This method generates the named event, ensuring that all bindings are called and supplied with the given details. The structure of said details depends on the event in question.

instanceCmd bound

This is an abstract method which can be overridden by derived classes. As is it does nothing.

It is invoked when the instance becomes known as having bindings for any event.

The result of the method is ignored.

instanceCmd unbound

This is an abstract method which can be overridden by derived classes. As is it does nothing.

It is invoked when the instance becomes known as having no bindings anymore, for no events.

The result of the method is ignored.

instanceCmd event-bound event

This is an abstract method which can be overridden by derived classes. As is it does nothing.

It is invoked when the named event becomes known as having bindings.

The result of the method is ignored.

instanceCmd event-unbound event

This is an abstract method which can be overridden by derived classes. As is it does nothing.

It is invoked when the named event becomes known as having no bindings anymore.

The result of the method is ignored.

instanceCmd Register events

This is a method for use by derived classes. It takes a list of event names and arranges for notification when bindings to the instance and these events come into existence or are removed.

This information is used to drive the invokations of the abstract methods above, i.e. bound, unbound, event-bound, and event-unbound.

The result of the method is an empty string.

Node Events

This sections documents the class ::kinetcl nodeevents, a base class supplying the event management for all OpenNI production nodes dervided from class ::kinetcl base described in section Base.

This class inherits from ::kinetcl eventbase for the overall management of events. See section Event Base.

Class API

::kinetcl nodeevents new
::kinetcl nodeevents create objname

This command creates a new instance of the class, either automatically named (new), or explicitly (create). The API provided by the instance, i.e. the set of available methods and their semantics is described in the next subsection.

Instance API

instanceCmd SetupEventsOf node

This method introspects the C-level OpenNI instance node and registers all callbacks it exposes (via a method pair set-callback-*, unset-callback-*) as events the instance is able to generate.

It further remembers the mapping from event names to the node instances generating them.

The result of the method is an empty string.

Joint Events

This sections documents the class ::kinetcl joints, a class providing proper event based tracking of user skeletons.

This class inherits from ::kinetcl eventbase for the overall management of the events it generates. See section Event Base.

Instances of the class rely on a (possibly external) instance of class ::kinetcl user (See section User Generator) and its events for the basic aquisition and tracking of users.

Class API

::kinetcl joints new ?user?
::kinetcl joints create objname ?user?

This command creates a new instance of the class, either automatically named (new), or explicitly (create). The API provided by the instance, i.e. the set of available methods and their semantics is described in the next subsection.

If the argument user is specified then it must be an instance of class ::kinetcl user. See section User Generator for details. In the future we may relax these restriction to require only API cmopatibility.

If no such instance is specified the new instance will itself create such an instance.

This user generator is used to get the basic events for tracking users and skeletons the instance will then transform into more suitable form and events.

Note that any instance methods invoked and not known to the class (see below for the known API) are delegated to the user generator for handling, making the instance look like an extended user generator.

Instance API

instanceCmd threshold

In this form the method returns the value of the confidence threshold used to distinguish between good and ignorable joint locations. The default is 0.5.

instanceCmd threshold value

In this form the method configures the instance to use the new value of the confidence threshold used to distinguish between good and ignorable joint locations. This value must be a floating point number in the range 0..1.

instanceCmd get-generator

The method returns the instance command of the user generator provinding the raw information about users and skeletons. This is either the generator specified at instance construction time, or the internally created generator.

instanceCmd get-joint user joint

This method returns the location of the named joint for the specified user (id).

This information comes out of an internal cache maintained by the instance, to avoid having to go to the underlying user generator.

The result of the method is a 3D location in world coordinates.

instanceCmd get-skeleton user

This method returns the location of all joints currently known for the specified user (id).

This information comes out of an internal cache maintained by the instance, to avoid having to go to the underlying user generator.

The result of the method is a dictionary mapping joint names to 3D locations in world coordinates.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

user-create

This event is generated in response to the appearance of new users in the scene.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

user-move

This event is generated in response to the user moving in the scene.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

user-destroy

This event is generated in response to the disappearance of users from the scene.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

joint-create

This event is generated in response to the appearance of a user's joint (confident position).

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

joint

The name of the joint the event was generated for.

position

The current position of the joint. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

joint-move

This event is generated in response to the user's joint's movement in the scene.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

joint

The name of the joint the event was generated for.

position

The current position of the joint. This is a 3-element list of floating point values containing the real world x-, y-, and z-coordinates of the position, in this order.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

joint-destroy

This event is generated in response to the disappearance of a user's joint (non-confident position).

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

joint

The name of the joint the event was generated for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Stance Events

This sections documents the class ::kinetcl stance, a class for the recognition of stances, also known as poses or body gestures. Events are generated whenever a user enters or leaves a stance.

This was in general inspired by the concept of FAAST body gestures mentioned at http://fivedots.coe.psu.ac.th/~ad/jg/nui1610/index.html.

This class inherits from ::kinetcl eventbase for the overall management of the events it generates. See section Event Base.

Instances of the class rely on an external instance of class ::kinetcl joints (See section Joint Events) and its events for the tracking of users and their skeleton joints.

Multiple instances can trivially share the same joint tracker instance, given that the communication from tracker to recognizer is by events and bindings.

Class API

::kinetcl stance new joints
::kinetcl stance create objname joints

This command creates a new instance of the class, either automatically named (new), or explicitly (create). The API provided by the instance, i.e. the set of available methods and their semantics is described in the next subsection.

The joints argument must be a joint tracking object which is API compatible to instances of class ::kinetcl joints.

This tracker is monitored for the creation, movement and destruction of users, in response to which the referenced user and its joints are run through the stance recognizer.

Instance API

instanceCmd add name script

This method defines a new stance to be recognized by the instance, identified by name. The script is the recognizer for the stance and is invoked whenever a user moved, as this may have caused her to either enter or exit the stance.

The context and commands available to this script are explained in detail in section Stance Recognition Language.

The script has to return a boolean value, true if the stance is recognized, and false otherwise.

Events are send whenever this information changes (per-user).

Note that a user can be in multiple stances at the same time.

The result of the method is the empty string.

instanceCmd remove name

This method removes the named stance from the instance, stopping its future recognition.

The result of the method is the empty string.

instanceCmd measure name script

This method extends the gesture recognition language used by the instance with a named measure(ment), a cacheable piece of information about a user's skeleton.

The value of the measure is computed once, per user, by invoking the script. The result of the script is the value of the measurement.

The context and commands available to this script are explained in detail in section Stance Recognition Language.

The set of predefined measures is explained in section Predefined Measurements.

The result of the method is the empty string.

Events

This class supports the events below. These names can be used as the event argument of method bind defined by our super-class ::kinetcl::base.

stance-enter

This event is generated in response to a user entering a recognized stance.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

stance

The name of the stance the event is for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

stance-exit

This event is generated in response to a user leaving a recognized stance.

The detail dictionary of this event contains:

user

The numerical id of the user the event was generated for.

stance

The name of the stance the event is for.

Note that events are not told the actual state of the instance. If this information is required then it is the receiver's responsibility to query the state using the appropriate query methods.

Stance Recognition Language

All stance recognition and measurement scripts are executed within a namespace which provides the commands below:

Math

All of Tcl's builtin math functions and operators.

Measurements

All named measurements of the instance running the script, as commands taking no arguments and returning the value of the measurement.

Skeleton
head
neck
torso
waist
left-collar
left-shoulder
left-elbow
left-wrist
left-hand
left-fingertip
left-hip
left-knee
left-ankle
left-foot
right-collar
right-shoulder
right-elbow
right-wrist
right-hand
right-fingertip
right-hip
right-knee
right-ankle
right-foot

These commands return the location of the named joint in world coordinates, for the user the script is invoked for. If the joint is not defined for that user, the script is aborted, and the gesture's enter/exit state is not changed.

Distances
distance jointa jointb
distance_side jointa jointb
distance_height jointa jointb
distance_depth jointa jointb

In this form the commands take the names of two joints, determine their locations and then compute the euclidean distance between them, or the distance along the named axes.

For the names of the possible joints see the command names above.

The result of the commands is a floating point value, the computed distance.

distance segment
distance_side segment
distance_height segment
distance_depth segment

In this form the commands take the names of a single segment and compute it length, either the full euclidean distance between its joints, or the length along the named axes.

The following segments are known:

left-lower-arm

left-hand -- left-elbow

left-upper-arm

left-elbow -- left-shoulder

left-lower-leg

left-foot -- left-knee

left-upper-leg

left-knee -- left-hip

right-lower-arm

right-hand -- right-elbow

right-upper-arm

right-elbow -- right-shoulder

right-lower-leg

right-foot -- right-knee

right-upper-leg

right-knee -- right-hip

Undirected Axis Alignment
horizontal_side jointa jointb
vertical jointa jointb
horizontal_depth jointa jointb
horizontal_side segment
vertical segment
horizontal_depth segment

The commands take the names of two joints or of one segment (which maps to two joints), determine their locations and then check if these locations are aligned with the primary axes of the coordinate system.

The result of the commands is a boolean value, true if the relationship holds, and false otherwise.

Directed Axis Alignment
horizontal_right jointa jointb
horizontal_left jointa jointb
vertical_up jointa jointb
vertical_down jointa jointb
horizontal_backward jointa jointb
horizontal_forward jointa jointb
horizontal_right segment
horizontal_left segment
vertical_up segment
vertical_down segment
horizontal_backward segment
horizontal_forward segment

The commands take the names of two joints or of one segment (which maps to two joints), determine their locations and then check if these locations are aligned with the primary axes of the coordinate system, and in the described relationship.

The result of the commands is a boolean value, true if the relationship holds, and false otherwise.

General Spatial Relationships
right jointa jointb
left jointa jointb
above jointa jointb
below jointa jointb
before jointa jointb
behind jointa jointb
right segment
left segment
above segment
below segment
before segment
behind segment

The commands take the names of two joints or of one segment (which maps to two joints), determine their locations and then check if these locations are in the described relationship.

The result of the commands is a boolean value, true if the relationship holds, and false otherwise.

Unit Conversion
mm x
cm x
inch x

These command convert floating point values from various units to millimeters. The result of the commands are the conversion results.

Predefined Measurements

All instances of ::kinetcl stance know the following measurements:

left-neck-length

The distance from left soulder to neck.

left-upper-arm-length

The distance from left shoulder to left elbow.

left-lower-arm-length

The distance from left hand to left elbow.

right-neck-length

The distance from right soulder to neck.

right-upper-arm-length

The distance from right shoulder to right elbox.

right-lower-arm-length

The distance from right hand to right elbow.

neck-length

The minimum of both neck lengths above.

upper-arm-length

The minimum of both upper arm lengths above.

lower-arm-length

The minimum of both lower arm lengths above.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the KineTcl Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.

Keywords

3D vision, Kinect, OpenNI, PrimeSense, computer vision, tracking, volume sensor

Category

3rd party library binding