Notice: MediaWiki has been updated. Report any rough edges to marcan@marcan.st

Difference between revisions of "Python Wrapper"

From OpenKinect
Jump to: navigation, search
(Current Status)
m (Added dependencies for compiling)
 
(7 intermediate revisions by 5 users not shown)
Line 3: Line 3:
 
== About ==
 
== About ==
  
The Python wrapper is written in Cython [https://github.com/OpenKinect/libfreenect/tree/master/wrappers/python/ Ctypes].  This is the Cython-based libfreenect Python wrappers.  This provides async (e.g., using callbacks) and sync (e.g., simple function calls) interfaces to libfreenect.  The majority of the runloop is abstracted so that later upstream modifications will have minimal impact on your code; however, you are free to implement your own runloop and access all available functionality.  The interface is designed to mimic the C library except where 1.) It is impractical or 2.) It would be "Un-Pythonic" to do so.  See "Differences with C Library" for specific instances of this.  The exposed interface supports both asynchronous (e.g., callback) and synchronous (e.g., call and block) functions which is enabled by the [[C_Sync_Wrapper]].
+
The [https://github.com/OpenKinect/libfreenect/tree/master/wrappers/python/ Python wrapper] is written in [http://cython.org/index.html Cython] Ctypes.  This is the Cython-based libfreenect Python wrappers.  This provides async (e.g., using callbacks) and sync (e.g., simple function calls) interfaces to libfreenect.  The majority of the runloop is abstracted so that later upstream modifications will have minimal impact on your code; however, you are free to implement your own runloop and access all available functionality.  The interface is designed to mimic the C library except where 1.) It is impractical or 2.) It would be "Un-Pythonic" to do so.  See "Differences with C Library" for specific instances of this.  The exposed interface supports both asynchronous (e.g., callback) and synchronous (e.g., call and block) functions which is enabled by the [[C_Sync_Wrapper]].
  
We have been through several iterations of these wrappers in Pure C, Ctypes, and Cython.  Cython is by far the easiest to maintain (as the main lib changes regularly) while maintaining C-like speed.  It does require Cython to install the C code; however, this is available for all supported platforms.  If this becomes a burden we can easily include the generated C code in the repo.  The other dependencies are the same for pure C python extensions.
+
We have been through several iterations of these wrappers in Pure C, [http://docs.python.org/library/ctypes.html Ctypes], and Cython.  Cython is by far the easiest to maintain (as the main lib changes regularly) while maintaining C-like speed.  It does require Cython to install the C code; however, this is available for all supported platforms.  If this becomes a burden we can easily include the generated C code in the repo.  The other dependencies are the same for pure C python extensions.
  
 
A variety of demos are provided using all available kinect features with examples for Matplotlib and OpenCV display.
 
A variety of demos are provided using all available kinect features with examples for Matplotlib and OpenCV display.
 +
 +
''The wrappers don't work for windows out of the box.  Note about that process can be found [[Python_Wrapper_Windows|here]].
  
 
== Who is involved ==
 
== Who is involved ==
Line 15: Line 17:
 
However ([[User:Brandyn|Brandyn]]) and ([[User:amiller|amiller]]) are trying to organize things for Python.
 
However ([[User:Brandyn|Brandyn]]) and ([[User:amiller|amiller]]) are trying to organize things for Python.
  
== Current Status ==
 
 
== Current Status ==
 
== Current Status ==
 
{| border="1" cellpadding="10"
 
{| border="1" cellpadding="10"
Line 52: Line 53:
  
 
== Differences with C Library ==
 
== Differences with C Library ==
=== Things that are intentially different to be more Pythonic ===
+
=== Things that are intentionally different to be more Pythonic ===
 
==== init/open_device ====
 
==== init/open_device ====
 
Different calling style (returns the new value as opposed to using a double pointer).
 
Different calling style (returns the new value as opposed to using a double pointer).
Line 80: Line 81:
 
An abstraction that takes in depth, rgb, and body callbacks.  The body is called in the 'freenect_process_events' loop. Depth and RGB callbacks are given numpy arrays of the returned data.
 
An abstraction that takes in depth, rgb, and body callbacks.  The body is called in the 'freenect_process_events' loop. Depth and RGB callbacks are given numpy arrays of the returned data.
 
==== Integration with the c_sync wrapper ====
 
==== Integration with the c_sync wrapper ====
Provides sync_get_depth (get the depth without needed a callback) and sync_get_rgb (same for rgb)
+
Provides sync_get_depth (get the depth without needed a callback) and sync_get_video (same for video)
 +
 
 
==== Kill exception ====
 
==== Kill exception ====
 
Stops the runloop from within the body
 
Stops the runloop from within the body
  
 
== How to compile ==
 
== How to compile ==
 +
===Dependencies===
 +
*Cython
 +
*python-dev
 +
*python-numpy
 
=== Global Install ===
 
=== Global Install ===
 
sudo python setup.py install
 
sudo python setup.py install
Line 92: Line 98:
 
==Example Python Scripts==
 
==Example Python Scripts==
  
([[User:amiller|amiller]])  has a few Python demo scripts at https://github.com/amiller/pykinect
+
([[User:amiller|amiller]])  has a few Python demo scripts at https://github.com/amiller/libfreenect-goodies
  
 
== TODO ==
 
== TODO ==
 +
=== Currently being worked on ===
 +
* Do numpy conversion code in Cython cdef
 +
* Add XYZ synchronous point cloud output
 +
* Make the dev, ctx, and state structs non-opaque
  
 
[[Category:Wrappers]]
 
[[Category:Wrappers]]

Latest revision as of 05:58, 13 June 2011

"Python API, Documents and Stuff"

About

The Python wrapper is written in Cython Ctypes. This is the Cython-based libfreenect Python wrappers. This provides async (e.g., using callbacks) and sync (e.g., simple function calls) interfaces to libfreenect. The majority of the runloop is abstracted so that later upstream modifications will have minimal impact on your code; however, you are free to implement your own runloop and access all available functionality. The interface is designed to mimic the C library except where 1.) It is impractical or 2.) It would be "Un-Pythonic" to do so. See "Differences with C Library" for specific instances of this. The exposed interface supports both asynchronous (e.g., callback) and synchronous (e.g., call and block) functions which is enabled by the C_Sync_Wrapper.

We have been through several iterations of these wrappers in Pure C, Ctypes, and Cython. Cython is by far the easiest to maintain (as the main lib changes regularly) while maintaining C-like speed. It does require Cython to install the C code; however, this is available for all supported platforms. If this becomes a burden we can easily include the generated C code in the repo. The other dependencies are the same for pure C python extensions.

A variety of demos are provided using all available kinect features with examples for Matplotlib and OpenCV display.

The wrappers don't work for windows out of the box. Note about that process can be found here.

Who is involved

Search for Python in People

However (Brandyn) and (amiller) are trying to organize things for Python.

Current Status

Feature Supported? Notes
Connect to Kinect Yes
Control LED Yes
Control motor Yes
Get accelerometer data Yes Both with the C style interface and a helper function
RGB data callback Yes
Depth data callback Yes
Synchronous depth/rgb Yes Using c_sync wrapper

Differences with C Library

Things that are intentionally different to be more Pythonic

init/open_device

Different calling style (returns the new value as opposed to using a double pointer).

In C:

 freenect_init(&ctx, 0)

Becomes:

 ctx = init()

Names

Everything is in the freenect module. Since all freenect functions are of the form freenect_blah, we use freenect.blah to refer to them. This is also true for the synchronous calls. The reason for this is Python has good module level namespace support and the function name's differ by 1 character. This also goes for enumerated constants that have the FREENECT_ prefix.

Things not implemented (though could be added)

get/set user

Not implemented

Dev/Ctx/State

Opaque classes wrapping void *'s (you can't access struct elements). This will be fixed later but for now it makes tracking the core library easier as the internals of the struct are not considered. Later this can be updated in a backwards compatible way that allows for viewing the actual struct values (ideally when the API stabilizes).

Log functionality and callback

Not implemented

Additional Features

get_accel

A helper function that simplifies the accelerometer handling

runloop

An abstraction that takes in depth, rgb, and body callbacks. The body is called in the 'freenect_process_events' loop. Depth and RGB callbacks are given numpy arrays of the returned data.

Integration with the c_sync wrapper

Provides sync_get_depth (get the depth without needed a callback) and sync_get_video (same for video)

Kill exception

Stops the runloop from within the body

How to compile

Dependencies

  • Cython
  • python-dev
  • python-numpy

Global Install

sudo python setup.py install

Local Install

python setup.py build_ext --inplace

Example Python Scripts

(amiller) has a few Python demo scripts at https://github.com/amiller/libfreenect-goodies

TODO

Currently being worked on

  • Do numpy conversion code in Cython cdef
  • Add XYZ synchronous point cloud output
  • Make the dev, ctx, and state structs non-opaque