= motmot - overview =

Motmot is a collection of modular packages for the real time
collection and analysis of uncompressed digital images from a variety
of sources. The primary language is Python, but the low-level camera
access library (cam_iface) is cross-platform C, and the saved movie
format also has MATLABŪ bindings.

A primary goal of these libraries and applications is speed. Today's
CPUs and cameras are fast and getting faster. We need a
cross-platform, open source framework to make the best use of the
resources for machine vision tasks. We routinely use these libraries
to process data from cameras recording 100 MB per second.

Where does the name motmot come from? In short, it grew out of a
previous project named "kookaburra", and motmot is a bird related to
the kookaburra (both are related to the kingfisher). See
http://en.wikipedia.org/wiki/Momotidae

= Applications built on motmot packages =

== fview ==

The [wiki:fview] application, part of motmot, makes use of these
components to create a realtime camera viewer program that can record
videos to disk. It includes a convenient plugin mechanism by which
realtime video analysis can be performed. fview runs on Linux, Mac OS
X, and Windows. This application is essentially a GUI frontend for
[wiki:cam_iface] built using the wx toolkit.  You may be interested in
visiting the [source:trunk/fview/screenshots screenshot directory].
Here is a screenshot of fview running on Mac OS X using an iSight
camera:

[[Image(source:/trunk/fview/screenshots/homepage.png)]]

Here is another screenshot of fview and the flytrax realtime image analysis
plugin.

[[Image(source:/trunk/fview/screenshots/plugin-flytrax-linux-639x437.png)]]

== Other software using motmot ==

[[Image(http://mosca.caltech.edu/mtrax/screenshots/mtrax-screenshot-tiny.jpg)]] Mtrax

 * [http://dickinson.caltech.edu/Research/Mtrax Mtrax] is multiple fly
   tracking software to enable quantitative analysis of fly
   behavior. From recorded videos, it tracks flies using a
   background/foreground model to track positions and orientations of
   individual flies over time. Identies of flies are maintained for
   long durations, with special care given to events such as close
   contact between flies and rapid movements. Mtrax is free,
   open-source software.

 * [http://dickinson.caltech.edu/Research/MultiTrack Flydra] is a
   realtime tracking system for performing marker-less tracking of
   moving image features, such as flying insects or birds. This
   multi-camera system uses, at its core, the motmot packages running
   simultaneously on multiple computers connected to multiple cameras
   to enable high spatial and temporal resolution in a large tracking
   volume with standard commercial components.

 * '''flytrax''' (screenshot above) is a simple realtime tracking
   system to track moving image features (a walking fly) using a
   simple but fast background-subtraction algorithm. Flytrax is freely
   available, open-source software distributed as part of the motmot
   package and functions as a plugin for [wiki:fview].

= subpackages contained within motmot =

|| '''package''' || '''description''' || '''svn''' ||
||  (entire package ) || (All of motmot) || [http://code.astraw.com/motmot/trunk svn] ||
|| [wiki:cam_iface] ||       camera interface C API and Python wrapper || ||
|| [wiki:pycamiface] ||      Python wrapper of cam_iface || ||
|| !FastImage ||             Pyrex based wrapper of Intel's Integrated Performance Primitives (IPP) Library || [http://code.astraw.com/motmot/trunk/FastImage#egg=motmot.FastImage-dev svn] ||
|| !FlyMovieFormat ||       Code for manipulating .fmf movies. Includes Python (read/write) and MATLABŪ (read-only) || [http://code.astraw.com/motmot/trunk/FlyMovieFormat#egg=motmot.FlyMovieFormat-dev svn] ||
|| flytrax ||               fview plugin for tracking 2D points in realtime and saving data and small images || [http://code.astraw.com/motmot/trunk/flytrax#egg=motmot.flytrax-dev svn] ||
|| [wiki:fview] ||          extensible GUI to use cam_iface || [http://code.astraw.com/motmot/trunk/fview#egg=motmot.fview-dev svn] ||
|| fview_PLUGIN_TEMPLATE || blank fview plugin to use as template for new plugins ||
|| fview_c_callback ||      example fview plugin that calls pure C code ||
|| fview_live_histogram ||  example fview plugin that calls pure Python code ||
|| imops ||                 Python extension module to manipulate image codings || [http://code.astraw.com/motmot/trunk/imops#egg=motmot.imops-dev svn] ||
|| motmot_utils ||          Facilitate versioning and configuring of motmot packages || [http://code.astraw.com/motmot/trunk/motmot_utils#egg=motmot.utils-dev svn] ||
|| posix_sched ||           Python extension module to boost priority in POSIX systems ||
|| [http://code.astraw.com/projects/motmot/wiki/pygarrayimage pygarrayimage] ||         transfer Python objects supporting the array interface to OpenGL textures || [http://code.astraw.com/motmot/trunk/pygarrayimage#egg=pygarrayimage-dev svn] ||
|| [http://code.astraw.com/projects/motmot/wiki/pygxinput pygxinput] ||         use XInput devices with pyglet || [http://code.astraw.com/motmot/trunk/pygxinput#egg=pygxinput-dev svn] ||
|| realtime_image_analysis || Implements background subtraction and 2D feature extraction using !FastImage || [http://code.astraw.com/motmot/trunk/realtime_image_analysis#egg=motmot.realtime_image_analysis-dev svn] ||
|| [wiki:wxglvideo] ||             wxPython OpenGL interface for videos || [http://code.astraw.com/motmot/trunk/wxglvideo#egg=motmot.wxglvideo-dev svn] ||
|| wxvalidatedtext || validated integer/float text entry field for wxPython || [http://code.astraw.com/motmot/trunk/wxvalidatedtext#egg=motmot.wxvalidatedtext-dev svn] ||
|| wxvideo ||               wxPython interface for videos || [http://code.astraw.com/motmot/trunk/wxvideo#egg=motmot.wxvideo-dev svn] ||
|| wxwrap ||                wrapper to allow use of multiple wxPython versions ||
|| trackem ||               multiple point realtime tracker || [http://code.astraw.com/motmot/trunk/trackem#egg=motmot.trackem-dev svn] ||

= Download and install =

'''Subversion repository:''' Our source code is kept in the svn repository. https://code.astraw.com/motmot/trunk/ (On Windows, you may be interested in [http://tortoisesvn.tigris.org/ Tortoise SVN].)

== Ubuntu packages ==

Pre-compiled packages for most of motmot are available at
http://debs.astraw.com For example, if you're running Ubuntu 8.04
(Hardy), add the following line to {{{/etc/apt/sources.list}}}:

{{{
deb http://debs.astraw.com/ hardy/
}}}

Here are step-by-step instructions using the GUI:

 1. Start Synaptic (System->Administration->Synaptic Package Manager).

 2. Open the "Software Sources" dialog (Settings->Repositories). In
    the "Ubuntu Software" Tab, make sure the "universe" repository is
    enabled.

 3. Go to the "Third-Party Software" Tab. Click "Add..." and then type
    "{{{deb http://debs.astraw.com/ hardy/}}}".

 4. Now, back in the main Synaptic window, click the "Reload"
    button. You should get an error about a bad GPG signature at this
    point.

 5. Add Andrew Straw's repository signing keyring to get rid of this
    error by clicking the "Search" button and typing "astraw-keyring" in
    the Search field. Then click the "Search" button.

 6. In the small empty square next to "astraw-keyring", click once and
    select "Mark for installation". Accept the warning and click the
    "Apply" button. After the installation is finished you will not get
    more GPG signature errors.

 7. Click the "Reload" button again to get the repository information
    once more and verify with the newly installed keyring.

 8. Now, install the python-motmot-fview package by following steps 5
    and 6 again for "python-motmot-fview" instead of "astraw-keyring".

 9. If you are using a firewire camera, add your user to the "disk"
    group. Open a terminal window (Applications->Accessories->Terminal),
    type "sudo adduser <your_user_name_here> disk" and then enter your
    password when prompted. If you did this, you will need to log out and
    log in again for the new group membership to take effect.

10. Start fview (Applications->Sound & Video->fview).

== Mac OS X ==

motmot is known to work on Intel Mac OS X (10.4) computers. Until
installers available, the installation must be done from the source
code.

== Microsoft Windows ==

motmot is known to work on Microsoft Windows XP. Until installers
available, the installation must be done from the source code.

== License ==

See the {{{LICENSE.txt}}} file within each subpackage. In general,
this code is released under a BSD-like license.

= Mailing list =

To stay up to date, ask questions, and share information,
[http://code.astraw.com/cgi-bin/mailman/listinfo/motmot join the motmot email list]. The
[http://code.astraw.com/pipermail/motmot/ archives] are also online.

= Related Software =

== Similar open source libraries ==

See the [http://artoolkit.sourceforge.net/ Augmented Reality Toolkit],
http://muonics.net/, [http://unicap-imaging.org/ unicap],
[http://opencvlibrary.sourceforge.net/ OpenCV], and
[http://code.google.com/p/libcam/ libcam] for lots of interesting and
fun stuff.

== GenICam(TM) and GigEVision(TM) ==

Another project with similar goals to motmot/camiface is GenICam(TM)
http://www.genicam.com/ . Primary differences between camiface and
GenICam(TM) include the following: 1) camiface has been developed by a
single individual to support a limited number of camera features from
a limited number of cameras and is necessarily narrower in scope than
an API meant to encompass every available feature on every available
camera. 2) camiface operates using existing drivers rather than
creating a new implementation of the driver layer.

One implementation of GenICam(TM) appears to be Basler's
Pylon. http://www.baslerweb.com/beitraege/beitrag_en_53074.html

For a description of GigEVision(TM) see
http://www.machinevisiononline.org/public/articles/index.cfm?cat=167

For an discussion of these libraries from an open source perspective, see
[http://sourceforge.net/mailarchive/forum.php?thread_name=1180629301.16081.147.camel%40mn65-eggplant.htc.honeywell.com&forum_name=libdc1394-devel this thread on the libdc1394-devel mailing list].

== Similar closed source libraries/applications ==

 * [http://www.ioindustries.com/software.htm Streams 5] by IO Industries
 * [http://www.norpix.com/ StreamPix] and [http://www.norpix.com/products/api.php the Hermes API] by Norpix
 * The MATLAB [http://www.mathworks.com/products/imaq/ Image Acquisition Toolbox].

== Scientific papers which used the motmot suite of tools ==

John A. Bender and Michael H. Dickinson (2006)
[http://jeb.biologists.org/cgi/content/full/209/16/3170 Visual
stimulation of saccades in magnetically tethered Drosophila]. Journal
of Experimental Biology.

John A. Bender and Michael H. Dickinson (2006)
[http://jeb.biologists.org/cgi/content/full/209/23/4597 A comparison
of visual and haltere-mediated feedback in the control of body
saccades in Drosophila melanogaster]. Journal of Experimental Biology.

Seth A. Budick, Michael B. Reiser, and Michael H. Dickinson (2007) [http://jeb.biologists.org/cgi/content/full/210/23/4092 The role of visual and mechanosensory cues in structuring forward flight in Drosophila melanogaster]. Journal of Experimental Biology.