.TH CLUTTER-SEGMENTATION "JUNE 2011" 

.SH NAME

clutter-segmentation - a ROS package for recognizing objects in cluttered scenes

.SH SOURCES

    $ git clone indefero@code.in.tum.de:clutter-segmentation.git

.SH INSTALLATION 

The clutseg package is built on top of ROS packages tod_training and
tod_detecting in the object_recognition stack. It has been developed and
tested on ROS Diamondback running on a Ubuntu 10.10 Maverick Meerkat.

Use the install.bash script in the repository. It installs system dependencies
and required ROS stacks via aptitude, checks out other ROS stacks, creates the
overlays, and compiles the clutter-segmentation packages.

    $ ./install.bash <CLUTSEG_PATH>

Hit 's' for skip when being asked for what action to take on repository
clutter-segmentation. The environment variable CLUTSEG_PATH is important, it is
referenced by scripts and software tests. 

    $ cd $CLUTSEG_PATH

    $ source setup.bash

If you want to have convenient access to the scripts:

    $ export PATH=$CLUTSEG_PATH/clutter-segmentation/scripts/script-bin:$PATH

.SH RUNNING TESTS 

There are plenty of tests available that test for functionality and regression
in package clutseg and its - often experimental - dependencies. Some of these
tests require Gigabytes of test data that have not been included in the
repository. Some smaller test data has been included, and other tests do not
require any test data to run. You can compile the tests (standard for ROS
packages) via

    make tests

and run them by calling

    make test

You can also run single tests via

   bin/utest --gtest_filter=test_extractor.*

or another example

   bin/utest --gtest_filter=test_conn_comp.largest_connected_component

for running a single test only.

.SH LEARNING MODELS FROM TOD_* RAW DATA 

TOD comes with some example raw data that can be used for populating a modelbase.
There are also test images available. The general approach to generate a modelbase
and use it for recognition is described in two tutorials:

    http://www.ros.org/wiki/tod_training/Tutorials
    http://www.ros.org/wiki/tod_detecting/Tutorials.


The tutorial http://www.ros.org/wiki/tod_training/Tutorials/BaseCreation
explains how to create a training base. According to this tutorial, the
training objects are assumed to have a fiducial marker rigidly attached to
them.  This might create problems when we try to use existing databases with
images that actually do not contain any fiducial marker. The tutorial also
expects ROS bags that contain synchronized messages of certain types.
Unfortunately, it seems that it's only the topic names listed but not the data
types. Inspecting the sample data using rosbag info show the different kinds of
data that might have to be included in training data:

    camera_info   sensor_msgs/CameraInfo 
    image         sensor_msgs/Image      
    image_mono    sensor_msgs/Image      
    points2       sensor_msgs/PointCloud2
    tf            tf/tfMessage 


There are some ROS bags available that can be used for training purposes.

    $ wget http://vault.willowgarage.com/wgdata1/vol1/tod_kinect_bags/training/fat_free_milk.bag
    $ wget http://vault.willowgarage.com/wgdata1/vol1/tod_kinect_bags/training/fat_free_milk.tf.bag
    $ ...
    
Get some configuration data for training, edit config.txt to specify all available bags.

    $ wget http://vault.willowgarage.com/wgdata1/vol1/tod_kinect_bags/training/fiducial.yml
    $ wget http://vault.willowgarage.com/wgdata1/vol1/tod_kinect_bags/training/config.yaml
    $ wget http://vault.willowgarage.com/wgdata1/vol1/tod_kinect_bags/training/config.txt
    $ wget http://vault.willowgarage.com/wgdata1/vol1/tod_kinect_bags/training/features.config.yaml
    $ wget http://vault.willowgarage.com/wgdata1/vol1/tod_kinect_bags/training/README

Extract the bag file using 

    $ rosrun tod_training dump_all.py bags base

and generate the training data base using
  
    # these two configuration files are required for training 
    $ cp bags/fiducial.yml base/
    $ cp bags/config.yaml base/
    $ cp bags/features.config.yaml base/
    $ cd base
    $ rosrun tod_training train_all.sh
    $ cp bags/config.txt base/config.txt

.SH RESOURCES

    * C++, http://www.cplusplus.com/reference
    * Lib-C, http://www.gnu.org/s/hello/manual/libc
    * OpenCV, http://opencv.willowgarage.com/documentation/cpp
    * Boost, http://www.boost.org/doc/libs
    * ROS, http://www.ros.org/wiki
    * SQLite, http://www.sqlite.org/c3ref/intro.html
    * SQL, http://www.w3schools.com/sql