kinetcl_install_guide - KineTcl - The Installer's Guide
Welcome to KineTcl, a binding of the OpenNI framework providing Tcl with access to MS Kinect (tm), and related sensor systems.
The audience of this document is anyone wishing to build the packages, for either themselves, or others.
For a developer intending to extend or modify the packages we additionally provide
Please read KineTcl - How To Get The Sources first, if that was not done already. Here we assume that the sources are already available in a directory of your choice.
Before KineTcl can be build and used a number of requisites must be installed. These are:
The scripting language Tcl. For details see Tcl.
The critcl package (C embedding) for Tcl. For details see CriTcl.
The crimp package (image processing) for Tcl. For details see Crimp.
The OpenNI framework. For details see OpenNI.
The PrimeSense NITE algorithm package for the OpenNI framework. For details see NITE.
An OpenNI sensor library for your Sensor device. For details see Sensors.
The kettle application (Build tool) for Tcl. For details see Kettle.
This list assumes that the machine where KineTcl is to be installed is essentially clean. Of course, if parts of the dependencies listed below are already installed the associated steps can be skipped. It is still recommended to read their sections though, to validate that the dependencies they talk about are indeed installed.
As we are building a Tcl package that should be pretty much obvious that a working Tcl installation is needed, and I will not belabor the point.
Out of the many use whatever you are comfortable with, as long as it provides Tcl 8.5, or higher, and Tk 8.5 or higher.
This may a Tcl installation provided by your operating system distribution, from a distribution-independent vendor, or built by yurself.
Myself, I used ActiveState's ActiveTcl 8.5 distribution during development of the binding, as I am most familiar with it.
(Disclosure: I, Andreas Kupries, work for ActiveState, maintaining ActiveTcl and TclDevKit for them).
This distribution can be found at http://www.activestate.com/activetcl. Retrieve the archive of ActiveTcl 8.5 for your platform and install it as directed by ActiveState.
Assuming that ActiveTcl got installed I usually run the command
teacup update
to install all packages ActiveState provides, and the kitchensink, as the distribution itself usually contains only the ost important set of packages. This ensures that the dependencies for CriTcl, Crimp, and KineTcl are all present, and more.
If that is not your liking you have to read the sections for CriTcl, Crimp, and KineTcl to determine the exact set of packages required, and install only these using
teacup install $packagename
Both teacup commands above assume that ActiveState's TEApot repository at http://teapot.activestate.com is in the list of repositories accessible to teacup. This is automatically ensured for the ActiveTcl distribution. Others may have to run
teacup archive add http://teapot.activestate.com
to make this happen.
For those wishing to build Tcl/Tk on their own, their sources can be found at
To build both Crimp, and KineTcl the tool critcl is required.
Both Crimp's and KineTcl's build systems accept it either as an application found in the PATH, or as a Tcl package available to the tclsh used to run their build & installation processes.
While Crimp just requires version 3 or higher KineTcl itself must have version 3.1 or higher. Either is found in CriTcl's github repository.
This github repository can be found at http://andreas-kupries.github.com/critcl.
The relevant repository branch is master. Do not try to use other branches, these usually contain features, experiments or bugfixes in progress, and as such are not stable.
Please make sure to use at least commit [fe814d4977], or later.
At the above url is also an explanation on how to build and install CriTcl, including a list of its dependencies.
Its instructions will not be repeated here. If there are problems with their directions please file a bug against the critcl project, and not KineTcl.
To build and use KineTcl the image processing package crimp is required.
This package must be available to the tclsh used to run KineTcl's build & installation process, and the tclsh used to run scripts requiring KineTcl.
KineTcl must have access to revision [795374375f] of Crimp fossil reository, or later. Earlier revisions do not provide all the operations used by KineTcl.
This fossil repository can be found at http://chiselapp.com/user/andreas_kupries/repository/crimp/home.
The relevant repository branch is trunk.
Note: While the ActiveState TEApot repository provides all crimp packages for installation, this is not enough for building KineTcl, only running it later. The header files required to build KineTcl are not provided by the packages in the TEApot. This is why Crimp's sources have to be retrieved from its fossil repository and build locally.
Crimp has a build and installation guide much like this one for KineTcl, which can be found at the above site and explains how to retrieve its sources and build the package, which dependencies are required, etc. The direct link to this guide is http://chiselapp.com/user/andreas_kupries/repository/crimp/doc/tip/embedded/www/doc/files/crimp_installer.html
Its instructions will not be repeated here. If there are problems with their directions please file a bug against the crimp project, and not KineTcl.
KineTcl is, despite its name, not a direct binding to the Kinect itself. It actually is a binding to the more general OpenNI framework (version 1). This framework provides a set of generic APIs for sensors, processing algorithms, and applications into which anything following these APIs can be plugged into.
PrimeSense, the maker of the 3D sensor found in the Kinect is a main member of the OpenNI organization managing the framework and provides plugins for its sensor and various analysis algorithms.
The OpenNI binaries must be installed to build and use KineTcl.
These binaries can be found at http://www.openni.org/Downloads/OpenNIModules.aspx
References to the sources of the frameork, should you wish to build them by yourself, can be found at http://www.openni.org/Downloads.aspx. When doing so please follow their instructions on building the package. If there are problems with their directions please file a bug against the OpenNI project, and not KineTcl.
Development was done against the binaries of OpenNI version 1.5.2.23. After downloading the binaries were installed by unpacking the tarball and then running the provided installation script. I.e.:
bunzip2 < openni-bin-dev-linux-x64-v1.5.2.23.tar.bz2 | tar xf - cd OpenNI-Bin-Dev-Linux-x64-v1.5.2.23 # !Edit the headers to work around the bug mentioned below. sudo ./install.sh # Note the sudo above, this script installs binaries into # root owned directories.
Note that version 1.5.2.23 has a bug in its headers. To work around this bug the provided header files have to be modified, before installing them.
Open the header file "XnModuleInterface.h" in the editor of your choice and look for the declaration of
typedef struct XnModuleExportedProductionNodeInterface {
...
} XnModuleExportedProductionNodeInterface;
Rewrite the end of this declaration to
typedef struct XnModuleExportedProductionNodeInterface {
...
} ;
This removes a conflict between this declaration and its forward declaration in the header file "XnTypes.h".
OpenNI (the organization) recommends to install the PrimeSense NITE binaries, which provide various higher-level analysis algorithms.
For KineTcl we not only recommend but demand installation. It is the algorithms in NITE which provide user detection and skeleton tracking, i.e. all the interesting higher-level features we want.
These binaries can be found at http://www.openni.org/Downloads/OpenNIModules.aspx
In contrast to the OpenNI framework itself NITE seems to be closed-source, and no references to a source repository are available.
During development NITE version 1.5.2.21 was installed. After downloading the binaries were installed by unpacking the tarball and then running the provided installation script. I.e.:
bunzip2 < nite-bin-linux-x64-v1.5.2.21.tar.bz2 | tar xf - cd NITE-Bin-Dev-Linux-x64-v1.5.2.21 sudo ./install.sh # Note the sudo above, this script installs binaries into # root owned directories.
When actually using a Kinect the OpenNI framework alone is not enough.
We have to install the drivers for our sensor device as well.
Please note that the Sensor driver binaries available at http://www.openni.org/Downloads.aspx are only generic to devices using PrimeSense's sensor and are not adapted to specific devices like MS Kinect. Do not install these, but whatever is available for your specific device.
For MS Kinect the sources of the specific sensor driver are found at https://github.com/avin2/SensorKinect.
This repository also contain prebuilt binaries for various platforms, which were used during development of the binding. Should you wish to build the sensor driver by yourself, please follow their instructions on building the package. If there are problems with their directions please file a bug against the SensorKinect project, and not KineTcl.
Development was done against the binaries of SensorKinect version 5.1.0.25. After downloading the binaries were installed by unpacking the tarball and then running the provided installation script. I.e.:
bunzip2 < SensorKinect091-Bin-Linux64-v5.1.0.25.tar.bz2 | tar xf - cd SensorKinect091-Bin-Linux64-v5.1.0.25 sudo ./install.sh # Note the sudo above, this script installs binaries into # root owned directories.
On a specific note, one of the files installed is "Install/55-primesense-usb.rules" which is placed into "/etc/udev/rules.d".
This file contains the udev rules which enable access to the usb sensor devices by non-root users.
To build KineTcl the tool kettle is required.
KineTcl's build system requires it as an application found in the PATH.
KineTcl requires version 1 or higher.
The fossil repository providing releases of this tool (and its associated package) can be found at http://core.tcl.tk/akupries/kettle.
A mirror of the repository can be found at https://chiselapp.com/user/andreas_kupries/repository/Kettle.
Use of either releases or of the head of the main branch is recommended. Usage of branches is strongly discouraged as these are used to work on experimental features and bugfixes of the tool. As such their stability is not guaranteed.
At the above url is also an explanation on how to build and install Kettle, including a list of its dependencies.
Its instructions will not be repeated here. If there are problems with their directions please file a bug against the Kettle project, and not KineTcl.
This section describes the actions required to install KineTcl on Unix systems (Linux, BSD, and related, including OS X). If you have to install KineTcl on a Windows machine see section Build & Installation (Windows) instead.
To install KineTcl simply run
/path/to/tclsh8.5 /path/to/kinetcl/build.tcl install
where "/path/to/tclsh8.5" is the tclsh of your Tcl installation, and "/path/to/kinetcl" the location of the KineTcl sources on your system.
This builds all packages and then places them in a directory where the tclsh8.5 will find them.
The build system provides a small GUI for those not comfortable with the command line. This GUI is accessible by invoking "build.tcl" without any arguments.
To get help about the methods of "build.tcl", and their complete syntax, invoke "build.tcl" with argument help, i.e., like
/path/to/tclsh8.5 /path/to/kinetcl/build.tcl help
This section describes the actions required to install KineTcl on Windows(tm) systems. If you have to install KineTcl on a Unix machine (Linux, BSD, and related, including OS X) see section Build & Installation (Unix) instead.
To install KineTcl simply run
/path/to/tclsh8.5 /path/to/kettle -f /path/to/kinetcl/build.tcl install
where "/path/to/tclsh8.5" is the tclsh of your Tcl installation, "/path/to/kettle" is the installed kettle application, and "/path/to/kinetcl" the location of the KineTcl sources on your system.
This builds all packages and then places them in a directory where the tclsh8.5 will find them.
The above is written without assuming any associations from extensions (like ".tcl") to executables responsible for the file with that extension. Actually, given that "build.tcl" is technically a "kettle"-script, which in turn is a ".tcl"-script I am not sure if Windows is able to handle such a chain of interpreters. The command given above simply spells out the entire chain.
The build system provides a small GUI for those not comfortable with the command line. This GUI is accessible by invoking "build.tcl" without any arguments from the command line.
To get help about the methods of "build.tcl", and their complete syntax, invoke "build.tcl" with argument help, i.e., like
/path/to/tclsh8.5 /path/to/kettle -f /path/to/kinetcl/build.tcl help
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.
3rd party library binding
Copyright © 2012 Andreas Kupries
Copyright © 2012 Documentation, Andreas Kupries