Introduction

This document describes the design and usage of the Darwin framework for machine learning and computer vision research and development. It includes an overview of the various components of the framework, installation instructions, and tutorial. The document assumes that you are familiar with either the Linux or Windows (Microsoft Visual Studio) C/C++ development environments and have a basic understanding of Machine Learning, e.g., as presented in a number of excellent texts:

Richard O. Duda and Peter E. Hart and David G. Stork, "Pattern Classification", 2000.
Christopher M. Bishop, "Pattern Recognition and Machine Learning", 2007.
Trevor Hastie and Robert Tibshirani and Jerome Friedman, "The Elements of Statistical Learning: Data Mining, Inference, and Prediction", 2009.
Daphne Koller and Nir Friedman, "Probabilistic Graphical Models: Principles and Techniques", 2009.
Kevin Murphy, "Machine Learning: A Probabilistic Approach", 2012.

For computer vision the following texts are recommended:

Richard Szeliski, "Computer Vision: Algorithms and Applications", 2010.
Simon Prince, "Computer Vision: Models, Learning, and Inference", 2012.
Gary Bradski and Adrian Kaehler, "Learning OpenCV", 2008.

The Darwin framework is designed to make it easy for researchers to share code that makes use of the Darwin libraries. The basic structure is shown in the figure below where Darwin applications and projects link against the Darwin libraries, which in turn link against a small set of external (third-party) libraries. Individual projects may include full-blown machine learning applications or reference code to replicate results from scientific publications. Individual projects may also link against other external libraries. The Darwin libraries are outlined in more detail below (see Darwin Libraries).

A number of researchers have contributed to the Darwin project. They are listed here.

Darwin Libraries

The following (clickable) diagram shows the dependencies between Darwin libraries. Dashed external libraries are optional. However, some functionality may not be available without these libraries.

The drwnBase library provides a number of core utility classes such as command line processing, code profiling, and message logging that are used throughout the rest of the library. All applications that use the Darwin framework must include drwnBase.h and link against this library.

The drwnIO library provides input/output functionality such as data storage in uncompressed or compressed format (provided by zlib). Applications using the i/o library should include the drwnIO.h header file.

The drwnML library provides basic machine learning capability for optimization, classification, regression and modeling probability distributions. Applications using the machine learning library should include the drwnML.h header file.

The drwnPGM library provides infrastructure for inference and learning in probabilistic graphical models. Applications using the PGM library should include the drwnPGM.h header file.

The drwnVision library provided high-level computer vision routines. It requires OpenCV (http://code.opencv.org). Client code using the computer vision library should include the drwnVision.h header file. This library is optional.

Applications and Projects

The Darwin framework includes many pre-developed applications for and projects for common machine learning and computer vision problems. For example, one of the projects provides mex interfaces for accessing many components of the library from Matlab; other projects integrate various components of the library through small utility applications and Python scripts. See Applications and Project Descriptions for details.

There is also a short tutorial that you should read if you are new to the library.

Downloading and Installing

Darwin has minimal dependencies on external libraries. Small libraries such as RapidXML and RapidJSON are included in the distribution, but larger libraries, such as Eigen and OpenCV, need to be installed separately. Darwin source code is hosted at http://github.com/sgould/drwn/. The following links provide detailed download and install instructions for Windows, Linux and Mac OS X.

The latest stable release can be downloaded from this link.

Previous stable releases, pre-compiled Windows and Matlab mex binaries, and change logs are also available.

Please report bugs via the issue tracker https://github.com/sgould/drwn/issues or email to steph.nosp@m.en.g.nosp@m.ould@.nosp@m.anu..nosp@m.edu.a.nosp@m.u and include a small example (code and data) that will trigger the bug.

Helper Videos

Miscellaneous Documentation

External Documentation

Eigen matrix library (http://eigen.tuxfamily.org)
C++ STL (http://www.sgi.com/tech/stl)
OpenCV (http://code.opencv.org)
RapidXML (http://rapidxml.sourceforge.net/)
RapidJSON (http://github.com/miloyip/rapidjson/)
GitHub and source control (http://github.com)
Python (http://www.python.org/)

License

Darwin is distributed under the BSD license. This means that it is free for both academic and commercial use. Note, however, that some projects may use third-party components that may have more stringent restrictions (e.g., academic use only or that certain works be cited in scientific publications).

Note

If you would like to cite Darwin in your scientific work please use the following reference (and include the specific software version number):

Stephen Gould, "DARWIN: A Framework for Machine Learning and Computer Vision Research and Development",
Journal of Machine Learning Research (JMLR), 13(Dec):3533−3537, 2012.

Copyright (c) 2007-2015, Stephen Gould
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.
    * Neither the name of the software's copyright holders nor the
      names of its contributors may be used to endorse or promote
      products derived from this software without specific prior
      written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.