per_primer_release

ReadMe.txt

-Copyright (C) 2009-2010 Institut de Robòtica i Informàtica Industrial, CSIC-UPC.
+Copyright (C) 2014 Institut de Robòtica i Informàtica Industrial, CSIC-UPC.
 Author aramisa (aramisa@iri.upc.edu)
 All rights reserved.
 
-This file is part of FINDDD descriptor library
-FINDDD descriptor library is free software: you can redistribute it and/or modify
-it under the terms of the GNU Lesser General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-at your option) any later version.
+This file is part of FINDDD descriptor library. 
+FINDDD descriptor library is free software: you can redistribute it
+and/or modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation, either version 3
+of the License, or at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -17,3 +17,69 @@ You should have received a copy of the GNU Lesser General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>
 
 
+INSTALLATION
+------------
+This library is built using CMake. To compile it, create a sub-folder
+called build in the project root directory, and run "cmake .." followed 
+by "make" within it.
+
+FINDDD requires the PCL library (www.pointclouds.org) and the Boost 
+libraries (www.boost.org) for the "make_shared" function.
+
+
+USAGE
+-----
+To compute FINDDD descriptors for a structured point cloud, compile
+and run the "bin/finddd_descriptor" command with appropriate
+parameters:
+
+finddd_descriptor -pcd <file_path> -centroids_file <centroids_path> 
+                  -descfile <output_descfile_path> [-use_soft_voting <bool>] 
+                  [-sample_each <step>] [-normalize_desc] [-desc_patch_radius 
+                  <radius>] [-num_spatial_bins <num_bins_per_side>] [-positions_file 
+                  <positions_file_path>] [-keep_nan] [-pca_file <file_path>] 
+                  [-pca_nkeep <num ev to keep>] [-ascii]
+
+Parameters:
+  -pcd <filename>              Input pcd file path. Mandatory.
+  -centroids_file <filename>   Input centroid file path. Mandatory.
+  -descfile <filename>         Output descriptor file path. Mandatory.
+  -use_soft_voting <bool>      Disable soft-voting. 
+  -sample_each <num_pix>       Density of descriptor sampling if positions_file is 
+                               not specified. Defaults to 6 pixels. 
+  -normalize_desc <norm>       0=none 1=L1 2=L2 3=sqrt+L2.
+  -desc_patch_radius <num_pix> Radius of the local patch. Defaults to 21 pixels.
+  -num_spatial_bins <num_bins> Number of spatial bins per side (sqrt of 
+                               total spatial bins). Defaults to 4.
+  -positions_file <filename>   Input locations file path.
+  -pca_file <filename>         PCA matrix filename. Should include mean vector .
+                               followed by the PCA matrix in space-separated ascii.
+                               See example file in "examples/pca_matrix_o13_d43.txt".
+  -pca_nkeep <num_ev_to_keep>  Number of eigenvectors to keep (output dimension).
+  -ascii                       Save descriptors in ASCII format.
+
+
+EXAMPLES
+--------
+In the "examples" directory you will find the following files:
+$> run_example.sh           Set of example executions to demonstrate functionality
+                           of the program.
+$> display_finddd.py        Python tool to visualize a set of FINDDD descriptors.
+$> example.png              Example RGB-D image, image part.
+$> example.pcd              Example RGB-D image, depth part.
+$> xyz_centers13.txt        Example file with 13 angular bin centroids.
+$> 50positions.txt          Fifty random image locations to compute descriptors in.
+$> pca_matrix_o13_d43.txt   Example file with PCA matrix to project the descriptors.
+
+
+CITATION
+--------
+If you use this code in your work, please cite:
+A. Ramisa, G. Alenya, F. Moreno-Noguer and C. Torras; "FINDDD: A fast 3D descriptor 
+to characterize textiles for robot manipulation", IROS 2013.
+
+
+CHANGELOG
+---------
+Version 1.0: Initial release.
+

doc/main.dox

@@ -2,6 +2,50 @@
 
   \section Introduction 
 
+  This package contains an implementation of the Fast Integral Normal
+  3D %Descriptor (FINDDD), originally designed to be used for clothing
+  manipulation tasks. Most current depth sensors provide 2.5D range
+  images in which depth values are assigned to a rectangular 2D
+  array. Taking advantage of this structured information, it can be
+  about two orders of magnitude faster than other approaches, while
+  showing similar performance in several tasks involving deformable
+  object recognition. 
+
+  \image html "images/pasos_metode.png" 
+  \image latex "images/pasos_metode.png"
+
+  Given a 2D patch surrounding a point and its associated depth
+  values, the descriptor for that point is built based on the
+  cumulative distances between their normals and a discrete set of
+  normal directions. This processing is made very efficient using
+  integral images, even allowing to densely compute descriptors for
+  every point in the image in a few seconds.
+  
+
+  If you use this code, please cite: Ramisa et al. FINDDD: \b A \b fast \b 3D \b descriptor \b to \b characterize \b textiles \b for \b robot \b manipulation. IROS, 2013.
+
+  \verbatim
+ @inproceedings{ramisa2013finddd,
+  title={FINDDD: A fast 3D descriptor to characterize textiles for robot manipulation},
+  author={Ramisa, Arnau and Alenya, Guillem and Moreno-Noguer, Francesc and Torras, Carme},
+  booktitle={Intelligent Robots and Systems (IROS), 2013 IEEE/RSJ International Conferenceon},
+  pages={824--830},
+  year={2013},
+  organization={IEEE}
+}
+\endverbatim
+
+  \par Functionalities
+  - Input format: structured point cloud in plain-text PCD file
+  - Compute descriptors over a fixed grid with parametrized step or at user-specified positions
+  - User-specified normal orientation bins, size of patch and number of spatial divisions
+  - Optional projection of computed descriptors with PCA matrix provided by the user
+  - Output format: fvecs (see <a href="https://gforge.inria.fr/projects/yael/">YAEL</a>) or plain-text file
+  
+  \par Dependencies
+
+FINDDD depends on <a href="http://www.pointclouds.org">PCL</a> and <a href="http://www.boost.org/">Boost</a>.
+
   \subsection Pre-Requisites
 
   This package requires of the following libraries and packages

examples/50positions.txt

+148 15
+526 25
+220 34
+44 35
+249 40
+491 55
+307 65
+571 73
+224 81
+355 84
+435 87
+500 112
+245 126
+538 126
+560 131
+349 154
+38 176
+72 191
+4 192
+205 205
+412 225
+288 237
+257 259
+482 262
+552 275
+632 279
+156 286
+4 289
+381 301
+275 329
+278 330
+197 342
+137 348
+316 354
+520 375
+372 388
+322 393
+98 398
+622 399
+106 415
+446 421
+452 421
+150 422
+319 424
+90 426
+437 441
+196 453
+42 462
+376 470
+93 479

examples/display_finddd.py

+import sys
+import numpy as np
+import matplotlib.pyplot as plt
+import time
+import os
+
+def read_fvecs(filename):
+    """Function to read a binary file in 'fvec' format (See https://gforge.inria.fr/projects/yael/).
+    
+    Input: filename of the fvec file.
+    Returns: tuple with descriptor locations and descriptors."""
+    pf = open(filename, 'rb')
+    # determine size of vectors
+    dim = np.fromfile(pf,dtype=np.int32, count=1)[0]
+    pf.seek(0, os.SEEK_END)
+    size = pf.tell()
+    pf.close()
+    #print 'Vector dimension: %dx%d'%(size/((dim+1)*4),dim)
+    assert dim>0 and dim<10000
+    pf = open(filename, 'rb')
+    data = np.fromfile(pf, dtype=np.float32, count=size/4)
+    data.shape=(size/(4*(dim+1)), dim+1)
+    #remove first column, and factor 
+    descriptors = data[:,3:]
+    uv          = data[:,1:3].astype('int32')
+    return uv, descriptors
+#-----------------------------------------------------
+    
+def read_pcd_file(filename):
+    """Load a text PCD file. Returns x,y and z matrices."""
+    pf = open(filename)
+    lines = pf.readlines()
+    if lines[1].split()[0]=='VERSION':
+        header = lines[0:11]
+        width = int(header[6].split()[1])
+        height = int(header[7].split()[1])
+    else:
+        header = lines[0:10]
+        width = int(header[5].split()[1])
+        height = int(header[6].split()[1])
+    x = np.zeros((height, width))
+    y = np.zeros((height, width))
+    z = np.zeros((height, width))
+
+    i = 0
+    j = 0
+
+    fourdims=False
+    if len(lines[11].split())==4:
+        fourdims=True
+    for l in xrange(11, len(lines)):
+        if fourdims==True: # maybe some day actually get the color...
+            px, py, pz, dump = lines[l].split()
+        else:
+            px, py, pz = lines[l].split()
+        x[j,i] = float(px)
+        y[j,i] = float(py)
+        z[j,i] = float(pz)
+        
+        i+=1
+        if i>=width:
+            j+=1
+            i=0
+    return x,y,z
+#-----------------------------------------------------
+
+def drawbox(plot, u, v, offset):
+    """Draws a bounding box in the active figure."""
+    plot.plot([u-offset,u+offset],[v+offset,v+offset],'-m')
+    plot.plot([u-offset,u-offset],[v-offset,v+offset],'-m')
+    plot.plot([u+offset,u+offset],[v-offset,v+offset],'-m')
+    plot.plot([u-offset,u+offset],[v-offset,v-offset],'-m')
+#-----------------------------------------------------    
+
+def paint_descriptor_xy(npy_desc, centers, plot = plt, fig_num = 1):
+    """Creates a figure with a representation of a FINDDD descriptor."""
+    numcenters = centers.shape[0]
+    nbins=int(np.sqrt(npy_desc.shape[0]/numcenters))
+    fig = plot.figure(fig_num)
+    fig.clf()
+    for i in range(nbins*nbins):
+        ax = fig.add_subplot(nbins, nbins, nbins*nbins-i)
+        ax.set_xlim([-1.1, 1.1])
+        ax.set_ylim([-1.1, 1.1])
+        ax.set_xlabel('X')
+        ax.set_ylabel('Y')
+        #centroides
+        ax.plot(centers[:,0],centers[:,1],'bo')
+        #bins
+        subdesc=npy_desc[i*numcenters:(i+1)*numcenters]
+        if sum(subdesc)>0:
+            subdesc/=sum(subdesc)
+        for j,v in enumerate(subdesc):
+            #print subdesc
+            ax.plot(centers[j,0],centers[j,1], 'ro', markersize=v*20)
+#-----------------------------------------------------
+
+def paint_descriptor_and_depth_map_xy(uv, npy_desc, centers):
+    """Plot a representation of a FINDDD and mark its location in a depth map."""
+    plt.figure(2)
+    plt.plot(uv[0], uv[1],'+m', markersize=15)
+    drawbox(plt, uv[0], uv[1], 32)
+    paint_descriptor_xy(npy_desc, centers, plot = plt, fig_num = 1)
+    plt.draw()
+    plt.draw()
+#-----------------------------------------------------
+
+def paint_descriptor_set(filename_descriptors, filename_pcd, filename_centers, step=10):
+    """Display, one by one, all descriptors and their locations in a descriptor set."""
+    # get descriptors
+    if filename_descriptors.endswith('.geofvecs') or filename_descriptors.endswith('.fvecs'):
+        uv, descriptors  = read_fvecs(filename_descriptors)
+    else: #txt format
+        descriptors  = np.loadtxt(filename_descriptors)
+        uv = descriptors[:,:2]
+        descriptors = descriptors[:,2:]
+
+    descriptors        = descriptors[::step,:] #show one every <step> descriptors
+    uv                 = uv[::step,:]
+    
+    #get pcd data
+    x_pts,y_pts,z_pts = read_pcd_file(filename_pcd)
+
+    #get centers
+    centers = np.loadtxt(filename_centers)
+
+    time.sleep(2) # wait for 2 sec the first time
+    plt.ion()
+    fig=plt.figure(2)
+
+    for ptuv, d in zip(uv, descriptors):
+        fig=plt.figure(2)
+        fig.clf()
+        plt.imshow(z_pts*-1) #flip z-values
+        plt.ylim([0, z_pts.shape[0]])
+        plt.xlim([0, z_pts.shape[1]])
+        paint_descriptor_and_depth_map_xy(ptuv, d, centers)
+        plt.draw()
+        plt.draw()
+        time.sleep(0.1)
+        #no nice way to exit(?)
+
+def about():
+    print "\nFINDDD Visualization\n--------------------\nTool to visualize descriptors over the Z dimension of a PCD file.\nUsage: python "+sys.argv[0]+" -f <descriptors_file> -pcd <pcd_file> -c [centers_file]\n\nDescription:\nTwo figures display all the information. The first one shows the depth map and a box indicating the location and area of the descriptor, and the second one the histograms of the orientations of the normals, represented as a semi-sphere, seen from the top, for each of the sub-descriptors. NOTE: Does not work with PCA projected descriptors.\n"
+    sys.exit(-1)
+
+if __name__=="__main__":
+    """Paint, one by one, the descriptors of a fvec file over a depth map.
+    Does not work with PCA projected descriptors!"""
+    
+    filebins = 'xyz_centers13.txt'
+    filedesc = None
+    filepcd  = None
+    #parse args
+    args=sys.argv[1:]
+    while len(args):
+        a=args.pop(0)
+        if a   == '-c':       
+            filebins = args.pop(0)
+        elif a =='-f':         
+            filedesc = args.pop(0)
+        elif a == '-pcd':     
+            filepcd  = args.pop(0)
+        else: 
+            about()
+    if filedesc==None or filepcd==None:
+        about()
+
+    paint_descriptor_set(filedesc, filepcd, filebins)

examples/run_example.sh

+#!/bin/bash
+
+mkdir test
+
+# Step size
+echo "STEP SIZE: 6, 3, 1"
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -descfile test/features_step6.fvecs
+../bin/finddd_descriptor -pcd example.pcd -sample_each 3 -centroids_file xyz_centers13.txt -descfile test/features_step3.fvecs
+../bin/finddd_descriptor -pcd example.pcd -sample_each 1 -centroids_file xyz_centers13.txt -descfile test/features_step1.fvecs
+
+# Descriptor area
+echo "SUPPORT AREA: 61x61, 81x81, 121x121"
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -desc_patch_radius 61 -descfile test/features_rad61.fvecs
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -desc_patch_radius 81 -descfile test/features_rad81.fvecs
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -desc_patch_radius 121 -descfile test/features_rad121.fvecs
+
+# Num spatial bins
+echo "NUMBER OF SPATIAL BINS: 2x2, 5x5"
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -num_spatial_bins 2 -descfile test/features_spa2.fvecs
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -num_spatial_bins 5 -descfile test/features_spa5.fvecs
+
+# Disable soft voting
+echo "SOFT VOTING DISABLED"
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -use_soft_voting 0 -descfile test/features_nosv.fvecs
+
+# Custom descriptor positions
+echo "CUSTOM DESCRIPTOR POSITIONS"
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -positions_file 50positions.txt -descfile test/features_locations.fvecs
+
+#PCA compression
+echo "PCA COMPRESSION: 33"
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -pca_file pca_matrix_o13_d43.txt -pca_nkeep 33 -descfile test/features_pca33.fvecs
+
+#ASCII OUTPUT
+echo "ASCII OUTPUT"
+../bin/finddd_descriptor -pcd example.pcd -sample_each 6 -centroids_file xyz_centers13.txt -ascii -descfile test/features_ascii.txt

src/CMakeLists.txt

 # locate the necessary dependencies
-FIND_PACKAGE( Boost 1.40 COMPONENTS program_options REQUIRED )
+FIND_PACKAGE( Boost 1.54 COMPONENTS program_options REQUIRED )
 INCLUDE_DIRECTORIES( ${Boost_INCLUDE_DIR} )
 
-set(PCL_DIR "/home/aramisa/usr/local/share/pcl-1.6/PCLConfig.cmake") 
+#IF PCL in non-standard directory, uncomment this: 
+#set(PCL_DIR "<path-to-pcl>/PCLConfig.cmake") 
 find_package(PCL  1.3  REQUIRED  COMPONENTS  common io features )
 include_directories(${PCL_INCLUDE_DIRS})
 link_directories(${PCL_LIBRARY_DIRS})

src/finddd_descriptor.cpp

@@ -131,13 +131,13 @@ void compute_normals(pcl::PointCloud<pcl::Normal> &pcl_normals, pcl::PointCloud<
 class IIf
 {
 public:
-  /** Vector of float* to store the parallel integral images in linear form.*/
+  /** \short Vector of float* to store the parallel integral images in linear form.*/
   std::vector<float*> ii_;
-  /** number of bins.*/
+  /** \short Number of bins.*/
   unsigned int bins_;
-  /** width of the integral image.*/
+  /** \short Width of the integral image.*/
   unsigned int width_;
-  /** height of the integral image.*/
+  /** \short Height of the integral image.*/
   unsigned int height_;
 
   /**
@@ -435,8 +435,8 @@ void FindddAlgorithm::compute_ndescs_integral_spatial_interpolation(pcl::PointCl
  */
 void about()
 {
-  std::cout<<"Usage:\n  finddd_descriptor -pcd <file_path> -centroids_file <centroids_path> -descfile <output_descfile_path> [-use_soft_voting <bool>] [-sample_each <step>] [-normalize_desc] [-desc_patch_radius <radius>] [-num_spatial_bins <num_bins_per_side>] [-positions_file <positions_file_path>] [-keep_nan] [-pca_file <file_path>] [-pca_nkeep <num ev to keep>]"<<std::endl;
-  std::cout<<"Parameters:\n  -pcd <filename>              Input pcd file path.\n  -use_soft_voting <bool>      Disable soft-voting.\n  -sample_each <num_pix>       Density of descriptor sampling.\n  -normalize_desc <norm>       0=none 1=L1 2=L2 3=sqrt+L2.\n  -desc_patch_radius <num_pix> Radius of the local patch.\n  -num_spatial_bins <num_bins> Number of local bins per side (sqrt of total bins).\n  -centroids_file <filename>   Input centroid file path.\n  -positions_file <filename>   Input locations file path.\n  -descfile <filename>         Output descriptor file path.\n  -pca_file <filename>         PCA matrix filename\n  -pca_nkeep <num_ev_to_keep>  Number of eigenvectors to keep (output dimension).\n";
+  std::cout<<"Usage:\n  finddd_descriptor -pcd <file_path> -centroids_file <centroids_path> -descfile <output_descfile_path> [-use_soft_voting <bool>] [-sample_each <step>] [-normalize_desc] [-desc_patch_radius <radius>] [-num_spatial_bins <num_bins_per_side>] [-positions_file <positions_file_path>] [-keep_nan] [-pca_file <file_path>] [-pca_nkeep <num ev to keep>] [-ascii]"<<std::endl;
+  std::cout<<"Parameters:\n  -pcd <filename>              Input pcd file path.\n  -use_soft_voting <bool>      Disable soft-voting.\n  -sample_each <num_pix>       Density of descriptor sampling.\n  -normalize_desc <norm>       0=none 1=L1 2=L2 3=sqrt+L2.\n  -desc_patch_radius <num_pix> Radius of the local patch.\n  -num_spatial_bins <num_bins> Number of local bins per side (sqrt of total bins).\n  -centroids_file <filename>   Input centroid file path.\n  -positions_file <filename>   Input locations file path.\n  -descfile <filename>         Output descriptor file path.\n  -pca_file <filename>         PCA matrix filename\n  -pca_nkeep <num_ev_to_keep>  Number of eigenvectors to keep (output dimension).\n  -ascii                       Save descriptors in ASCII format.\n";
 }
 
 /** 

src/finddd_descriptor.hpp

@@ -42,20 +42,20 @@ public:
 
 /** \brief Class to hold one FINDDD descriptor.
  *  This class holds each one of the FINDDD descriptors in a set. 
- *  Descriptor data is stored in a vector<float>.
+ *  %Descriptor data is stored in a vector<float>.
  */
 class Descriptor
 {
 public:
-  /** X-coordinate of the descriptor in image. */
+  /** \short X-coordinate of the descriptor in image. */
   int u;
-  /** Y-coordinate of the descriptor in image. */
+  /** \short Y-coordinate of the descriptor in image. */  
   int v;
-  /** Orientation of the descriptor in image (not used yet). */
-  float orientation;
-  /** Corresponding 3D coordinates of the descriptor. */
-  P3D point3d;
-  /** Descriptor vector. */
+  /** \short Orientation of the descriptor in image (not used yet). */
+  float orientation;  
+  /** \short Corresponding 3D coordinates of the descriptor. */
+  P3D point3d; 
+  /** \short %Descriptor vector. */
   std::vector<float> descriptor;
 };
 
@@ -67,19 +67,19 @@ public:
 class DescriptorSet
 {
 public:
-  /** Number of orientation bins of each sub-descriptor. */
+  /** \short Number of orientation bins of each sub-descriptor. */
   int num_orient_bins;
-  /** Number of spatial bins per side of the full descriptor region (sqrt of total). */
+  /** \short Number of spatial bins per side of the full descriptor region (sqrt of total). */
   int num_spa_bins;
-  /** Number of descriptors. */
+  /** \short Number of descriptors. */
   int num;
-  /** Number of dimensions of the descriptor. */
+  /** \short Number of dimensions of the descriptor. */
   int len;
-  /** Width of the original range image. */
+  /** \short Width of the original range image. */
   int width;
-  /** Height of the original range image. */
+  /** \short Height of the original range image. */
   int height;
-  /** Vector with computed descriptor. */
+  /** \short Vector with computed descriptor. */
   std::vector<Descriptor> descriptors;
   
   DescriptorSet()
@@ -101,38 +101,42 @@ public:
 class FindddConfig
 {
 public:
-  /** Num of spatial subdivisions. */
+  /** \short Num of spatial subdivisions. */
   int num_spatial_bins;
-  /** Side of the patch in pixels. */
+  /** \short Side of the patch in pixels. */
   int desc_patch_radius;
-  /** Step in pixels between descriptors. */
+  /** \short Step in pixels between descriptors. */
   int sample_each;
-  /** File with the normal centroids. */
+  /** \short File with the normal centroids. */
   std::string centroids_file;
-  /** File with the (u,v) positions where descriptors have to be computed (overrides "sample_each"). */
+  /** \short File with the (u,v) positions where descriptors have to be computed (overrides "sample_each"). */
   std::string positions_file;
-  /** Normalization of new descriptors:
-      0 - No norm
-      1 - L1
-      2 - L2
-      3 - sqrt + L2 
+  /** \short Normalization of new descriptors.
+
+      Normalization of new descriptors:
+      - 0 - No norm
+      - 1 - L1
+      - 2 - L2
+      - 3 - sqrt + L2 
   */
   int normalize_desc;
-  /** Whether to use soft-voting or direct assignment. */
+  /** \short Whether to use soft-voting or direct assignment. */
   int use_soft_voting;
-  /** Input pcd file where descriptors have to be computed. */
+  /** \short Input pcd file where descriptors have to be computed. */
   std::string pcd_file;
-  /** Output file in "fvec" format containing the computed descriptors. */
+  /** \short Output file in "fvec" format containing the computed descriptors. */
   std::string geofvecs_file;
-  /** Whether to keep NaN points or discard them. */
+  /** \short Whether to keep NaN points or discard them. */
   int keep_nan_points;
-  /** Name of a file containing the mean and the PCA matrix to automatically compress the computed descriptors. If not specified no compression is done. */
+  /** \short File with PCA matrix.
+
+      Name of a file containing the mean and the PCA matrix to automatically compress the computed descriptors. If not specified no compression is done. */
   std::string pca_file;
-  /** Number of eigenvectors to keep in the PCA matrix (=0 to keep all of them). */
+  /** \short Number of eigenvectors to keep in the PCA matrix (=0 to keep all of them). */
   int pca_nkeep;
-  /** Verbosity level. */
+  /** \short Verbosity level. */
   int verbose_level;
-  /** save descriptors in ascii format */
+  /** \short save descriptors in ascii format */
   int save_in_ascii;
   FindddConfig()
   {
@@ -164,55 +168,61 @@ protected:
   // private attributes and methods
   uint nt_;
   
-  /** Vector containing the X coordinate of normal centroids. */
+  /** \short Vector containing the X coordinate of normal centroids. */
   std::vector<float> orient_bin_centers_x_;
-  /** Vector containing the Y coordinate of normal centroids. */
+  /** \short Vector containing the Y coordinate of normal centroids. */
   std::vector<float> orient_bin_centers_y_;
-  /** Vector containing the Z coordinate of normal centroids. */
+  /** \short Vector containing the Z coordinate of normal centroids. */
   std::vector<float> orient_bin_centers_z_;
   
-  /** Vector containing the U coordinate of points where descriptors have to be computed. */
+  /** \short Vector containing the U coordinate of points where descriptors have to be computed. */
   std::vector<int> desc_compute_positionsX_;
-  /** Vector containing the V coordinate of points where descriptors have to be computed. */
+  /** \short Vector containing the V coordinate of points where descriptors have to be computed. */
   std::vector<int> desc_compute_positionsY_;
-  /** Inter-bin distance, to compute soft-votes*/
+  /** \short Inter-bin distance, to compute soft-votes*/
   float radius_inf_;
-  /** Number of orientation bins in each sub-descriptor. */
+  /** \short Number of orientation bins in each sub-descriptor. */
   uint desc_num_orient_bins_;
-  /** Number of spatial bins per side of the full descriptor region (sqrt of total). */
+  /** \short Number of spatial bins per side of the full descriptor region (sqrt of total). */
   uint desc_num_side_spatial_bins_;
-  /** Total size of the descriptors. */
+  /** \short Total size of the descriptors. */
   uint desc_num_total_bins_;
-  /** Radius of area used to compute descriptor. */
+  /** \short Radius of area used to compute descriptor. */
   uint desc_patch_radius_;
-  /** Filename of the normal centroids. */
+  /** \short Filename of the normal centroids. */
   std::string centroids_file_;
-  /** Filename of the file with positions where descriptors have to be computed (if specidied overrides "sample_each"). */
+  /** \short File with positions to compute descriptors.
+
+      Filename of the file with positions where descriptors have to be computed (if specidied overrides "sample_each"). */
   std::string positions_file_;
-  /** Name of file with mean and PCA matrix to compress descriptors on the fly. If not specified no compression is done. */
+  /** \short File with PCA matrix
+
+      Name of file with mean and PCA matrix to compress descriptors on the fly. If not specified no compression is done. */
   std::string pca_file_;
-  /** Number of eigenvectors to keep in the PCA matrix (=0 to keep all of them)*/
+  /** \short Number of eigenvectors to keep in the PCA matrix (=0 to keep all of them)*/
   int pca_nkeep_;
-  /** Normalization of new descriptors:
-      0 - No norm
-      1 - L1
-      2 - L2
-      3 - sqrt + L2 
+  /** \short Normalization of new descriptors.
+
+      Normalization of new descriptors:
+      - 0 - No norm
+      - 1 - L1
+      - 2 - L2
+      - 3 - sqrt + L2 
   */
   uint normalize_desc_;
-  /** Whether to use soft-voting or direct assignment. */
+  /** \short Whether to use soft-voting or direct assignment. */
   uint use_soft_voting_;
-  /** Level of verbosity. */
+  /** \short Level of verbosity. */
   int verbose_level_;
-  /** Step in pixels between descriptors. */
+  /** \short Step in pixels between descriptors. */
   uint sample_each_;
-  /** Margin to skip around the image. Currently this variable is unused. */
+  /** \short Margin to skip around the image. Currently this variable is unused. */
   uint margin_;
 
   // [PCA stuff]
-  /** Variable holding the PCA matrix for on the fly compression. */
+  /** \short Variable holding the PCA matrix for on the fly compression. */
   std::vector< std::vector<float> > pca_matrix_;
-  /** Mean of descriptors for PCA compression. */
+  /** \short Mean of descriptors for PCA compression. */
   std::vector<float> pca_mean_;
 
   public:
@@ -286,6 +296,7 @@ protected:
   /**
    * \brief Update PCA matrix.
    * \param new_pca_matrix_file File with the PCA matrix and mean vector.
+   * \param pca_nkeep Number of ev that must be kept.
    * Update the PCA matrix used to project the computed 
    * descriptors. The function expects a string pointing
    * to a plain text file with the mean vector followed by