The functions in this directory allow running of the Cornell Grasping Dataset,

1. Deep Learning for Detecting Robotic Grasps.
   Ian Lenz, Honglak Lee, Ashutosh Saxena.
   International Journal of Robotics Research (IJRR), 2014.

to reproduce results described in,

2. Affordance Detection of Tool Parts from Geometric Features
   Austin Myers, Ching L. Teo, Cornelia Fermuller, and Yiannis Aloimonos
   International Conference on Robotics and Automation (ICRA), 2015.

For details, please visit the project webpage:
http://www.umiacs.umd.edu/~amyers/part_affordance/

================================================================================
Cornell Grasping Rectangle Comparison
================================================================================

In order to compare this segmentation based method on a dataset which is based
on recognition and detection of rectangles, we treat rectangles as segments.

Following the recognition setting from [1], we resize the training and testing
rectangles to a fixed size. We learn HMP features from the training rectangles,
pool the features over the rectangles, and train linear-SVM classifiers which
can be used on the testing rectangles.

For the detection setting from [1], we sample rectangles of a fixed size from
the images. We report the point metric, where the grasp is considered a success
if the predicted rectangle is within some distance of at least one ground truth
center. The predicted rectangle for an image is the top ranked rectangle among
those sampled. Note that we only sample rectangles from image positions, but not
over rectangle orientation as in [1]. Since the point metric does not consider
grasp orientation, it may overestimate performance for robotic applications [1].
Nevertheless, the improvement over the results reported in [1] indicate the
strength of HMP features for this task.

================================================================================
Setup
================================================================================

After downloading the Cornell Grasping Rectangle Dataset, you will need to
prepare the data for recognition and detection. This will do all the necessary
cropping, resizing, and normal/curvature processing which will be saved to disk.

>> cornell_preprocess('cornell_data_path', 'processed_cornell_data_path', ...
                      'detection_results_path', 'recognition_results_path');

You will need to modify the "config_cornell_*" files to reflect these paths.

config = config_cornell_base('recognition_results_path', ...
                             'processed_cornell_data_path');

================================================================================
Recognition
================================================================================

After preparing the data and updating the "config_cornell_recognition.m" file,
simply run,

>> cornell_recognition();

This will learn HMP features from the training rectangles, pool the features
over the rectangles, and train linear-SVM classifiers which will be evaluated
on the testing rectangles. The accuracy over the testing rectangles will be
reported, where chance is 50%.

================================================================================
Detection
================================================================================

After preparing the data and updating the "config_cornell_detection.m" file,
simply run,

>> cornell_detection();

This will learn HMP features from rectangles sampled from training images,
pool the features over the rectangles, and train linear-SVM classifiers.
To evaluate a test image, we sample rectangles from the image and compute
scores using the trained classifier. If the top ranked rectangle is within
a certain distance from a ground truth positive rectangle, it is considered a
success (point-metric). The detection accuracy over the testing images will be
reported, as well as the chance accuracy for the sampled rectangles.

It is important to note however that there are two parameters which influence
the detection evaluation. Firstly, the distance threshold used to determine whether
the predicted rectangle is close enough to the ground truth. Secondly, where in
the image candidate rectangles are sampled from. Unfortunately, these details
were not available from [1] and the corresponding code releases. However, [1]
references a previous paper for the distance threshold, which reports the
average gripper error corresponding to approximately 21 pixels in this dataset.
In addition, the available code suggests that background masks or cropping are
used in evaluation, and [1] reports chance detection performance of 35.9%.

Therefore, we can determine the distance threshold which yields chance
performance close to (but less than) this value, in order to provide a
conservative comparison. We evaluated over a range of possible thresholds and
sampling regions. We consider the bounding box over the positive rectangles from
an image, plus some amount of padding. If there's no padding, we would
essentially be considering an area smaller than the foreground object that
contains all positive rectangle centroids, with a sensitive distance threshold.
As the amount of padding is increased, detection is run over more and more
background, and the distance threshold increases. The detection results reported
in [2] use the 21 pixel threshold following the reference from [1], with a
padding of 35 pixels to give a conservative estimate of detection performance.
We found the results to be robust to the range of reasonable parameter settings.
