Point Cloud Library (PCL)  1.8.1-dev
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
List of all members | Classes | Public Types | Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends
pcl::recognition::ObjRecRANSAC Class Reference

This is a RANSAC-based 3D object recognition method. More...

#include <pcl/recognition/ransac_based/obj_rec_ransac.h>

Classes

class  HypothesisCreator
 
class  OrientedPointPair
 
class  Output
 This is an output item of the ObjRecRANSAC::recognize() method. More...
 

Public Types

typedef ModelLibrary::PointCloudIn PointCloudIn
 
typedef ModelLibrary::PointCloudN PointCloudN
 
typedef BVH< Hypothesis * > BVHH
 
typedef SimpleOctree
< Hypothesis,
HypothesisCreator, float > 
HypothesisOctree
 

Public Member Functions

 ObjRecRANSAC (float pair_width, float voxel_size)
 Constructor with some important parameters which can not be changed once an instance of that class is created. More...
 
virtual ~ObjRecRANSAC ()
 
void clear ()
 Removes all models from the model library and releases some memory dynamically allocated by this instance. More...
 
void setMaxCoplanarityAngleDegrees (float max_coplanarity_angle_degrees)
 This is a threshold. More...
 
void setSceneBoundsEnlargementFactor (float value)
 
void ignoreCoplanarPointPairsOn ()
 Default is on. More...
 
void ignoreCoplanarPointPairsOff ()
 Default is on. More...
 
void icpHypothesesRefinementOn ()
 
void icpHypothesesRefinementOff ()
 
bool addModel (const PointCloudIn &points, const PointCloudN &normals, const std::string &object_name, void *user_data=NULL)
 Add an object model to be recognized. More...
 
void recognize (const PointCloudIn &scene, const PointCloudN &normals, std::list< ObjRecRANSAC::Output > &recognized_objects, double success_probability=0.99)
 This method performs the recognition of the models loaded to the model library with the method addModel(). More...
 
void enterTestModeSampleOPP ()
 
void enterTestModeTestHypotheses ()
 
void leaveTestMode ()
 
const std::list
< ObjRecRANSAC::OrientedPointPair > & 
getSampledOrientedPointPairs () const
 This function is useful for testing purposes. More...
 
const std::vector< Hypothesis > & getAcceptedHypotheses () const
 This function is useful for testing purposes. More...
 
void getAcceptedHypotheses (std::vector< Hypothesis > &out) const
 This function is useful for testing purposes. More...
 
const
pcl::recognition::ModelLibrary::HashTable
getHashTable () const
 Returns the hash table in the model library. More...
 
const ModelLibrarygetModelLibrary () const
 
const ModelLibrary::ModelgetModel (const std::string &name) const
 
const ORROctreegetSceneOctree () const
 
RigidTransformSpacegetRigidTransformSpace ()
 
float getPairWidth () const
 

Protected Types

enum  Recognition_Mode { SAMPLE_OPP, TEST_HYPOTHESES, FULL_RECOGNITION }
 

Protected Member Functions

int computeNumberOfIterations (double success_probability) const
 
void clearTestData ()
 
void sampleOrientedPointPairs (int num_iterations, const std::vector< ORROctree::Node * > &full_scene_leaves, std::list< OrientedPointPair > &output) const
 
int generateHypotheses (const std::list< OrientedPointPair > &pairs, std::list< HypothesisBase > &out) const
 
int groupHypotheses (std::list< HypothesisBase > &hypotheses, int num_hypotheses, RigidTransformSpace &transform_space, HypothesisOctree &grouped_hypotheses) const
 Groups close hypotheses in 'hypotheses'. More...
 
void testHypothesis (Hypothesis *hypothesis, int &match, int &penalty) const
 
void testHypothesisNormalBased (Hypothesis *hypothesis, float &match) const
 
void buildGraphOfCloseHypotheses (HypothesisOctree &hypotheses, ORRGraph< Hypothesis > &graph) const
 
void filterGraphOfCloseHypotheses (ORRGraph< Hypothesis > &graph, std::vector< Hypothesis > &out) const
 
void buildGraphOfConflictingHypotheses (const BVHH &bvh, ORRGraph< Hypothesis * > &graph) const
 
void filterGraphOfConflictingHypotheses (ORRGraph< Hypothesis * > &graph, std::list< ObjRecRANSAC::Output > &recognized_objects) const
 
void computeRigidTransform (const float *a1, const float *a1_n, const float *b1, const float *b1_n, const float *a2, const float *a2_n, const float *b2, const float *b2_n, float *rigid_transform) const
 Computes the rigid transform that maps the line (a1, b1) to (a2, b2). More...
 

Static Protected Member Functions

static void compute_oriented_point_pair_signature (const float *p1, const float *n1, const float *p2, const float *n2, float signature[3])
 Computes the signature of the oriented point pair ((p1, n1), (p2, n2)) consisting of the angles between. More...
 

Protected Attributes

float pair_width_
 
float voxel_size_
 
float position_discretization_
 
float rotation_discretization_
 
float abs_zdist_thresh_
 
float relative_obj_size_
 
float visibility_
 
float relative_num_of_illegal_pts_
 
float intersection_fraction_
 
float max_coplanarity_angle_
 
float scene_bounds_enlargement_factor_
 
bool ignore_coplanar_opps_
 
float frac_of_points_for_icp_refinement_
 
bool do_icp_hypotheses_refinement_
 
ModelLibrary model_library_
 
ORROctree scene_octree_
 
ORROctreeZProjection scene_octree_proj_
 
RigidTransformSpace transform_space_
 
TrimmedICP< pcl::PointXYZ, float > trimmed_icp_
 
PointCloudIn::Ptr scene_octree_points_
 
std::list< OrientedPointPairsampled_oriented_point_pairs_
 
std::vector< Hypothesisaccepted_hypotheses_
 
Recognition_Mode rec_mode_
 

Friends

class ModelLibrary
 

Detailed Description

This is a RANSAC-based 3D object recognition method.

Do the following to use it: (i) call addModel() k times with k different models representing the objects to be recognized and (ii) call recognize() with the 3D scene in which the objects should be recognized. Recognition means both object identification and pose (position + orientation) estimation. Check the method descriptions for more details.

Note
If you use this code in any academic work, please cite:
Author
Chavdar Papazov

Definition at line 86 of file obj_rec_ransac.h.

Member Typedef Documentation

Definition at line 92 of file obj_rec_ransac.h.

Definition at line 142 of file obj_rec_ransac.h.

Definition at line 89 of file obj_rec_ransac.h.

Definition at line 90 of file obj_rec_ransac.h.

Member Enumeration Documentation

Enumerator
SAMPLE_OPP 
TEST_HYPOTHESES 
FULL_RECOGNITION 

Definition at line 326 of file obj_rec_ransac.h.

Constructor & Destructor Documentation

pcl::recognition::ObjRecRANSAC::ObjRecRANSAC ( float  pair_width,
float  voxel_size 
)

Constructor with some important parameters which can not be changed once an instance of that class is created.

Parameters
[in]pair_widthshould be roughly half the extent of the visible object part. This means, for each object point p there should be (at least) one point q (from the same object) such that ||p - q|| <= pair_width. Tradeoff: smaller values allow for detection in more occluded scenes but lead to more imprecise alignment. Bigger values lead to better alignment but require large visible object parts (i.e., less occlusion).
[in]voxel_sizeis the size of the leafs of the octree, i.e., the "size" of the discretization. Tradeoff: High values lead to less computation time but ignore object details. Small values allow to better distinguish between objects, but will introduce more holes in the resulting "voxel-surface" (especially for a sparsely sampled scene).
virtual pcl::recognition::ObjRecRANSAC::~ObjRecRANSAC ( )
inlinevirtual

Definition at line 155 of file obj_rec_ransac.h.

Member Function Documentation

bool pcl::recognition::ObjRecRANSAC::addModel ( const PointCloudIn points,
const PointCloudN normals,
const std::string &  object_name,
void *  user_data = NULL 
)
inline

Add an object model to be recognized.

Parameters
[in]pointsare the object points.
[in]normalsat each point.
[in]object_nameis an identifier for the object. If that object is detected in the scene 'object_name' is returned by the recognition method and you know which object has been detected. Note that 'object_name' has to be unique!
[in]user_datais a pointer to some data (can be NULL)

The method returns true if the model was successfully added to the model library and false otherwise (e.g., if 'object_name' is already in use).

Definition at line 230 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::buildGraphOfCloseHypotheses ( HypothesisOctree hypotheses,
ORRGraph< Hypothesis > &  graph 
) const
protected
void pcl::recognition::ObjRecRANSAC::buildGraphOfConflictingHypotheses ( const BVHH bvh,
ORRGraph< Hypothesis * > &  graph 
) const
protected
void pcl::recognition::ObjRecRANSAC::clear ( )
inline

Removes all models from the model library and releases some memory dynamically allocated by this instance.

Definition at line 163 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::clearTestData ( )
inlineprotected

Definition at line 346 of file obj_rec_ransac.h.

static void pcl::recognition::ObjRecRANSAC::compute_oriented_point_pair_signature ( const float *  p1,
const float *  n1,
const float *  p2,
const float *  n2,
float  signature[3] 
)
inlinestaticprotected

Computes the signature of the oriented point pair ((p1, n1), (p2, n2)) consisting of the angles between.

Parameters
p1
n1
p2
n2
[out]signatureis an array of three doubles saving the three angles in the order shown above.

Definition at line 442 of file obj_rec_ransac.h.

References pcl::recognition::aux::clamp(), pcl::recognition::aux::dot3(), and pcl::recognition::aux::normalize3().

int pcl::recognition::ObjRecRANSAC::computeNumberOfIterations ( double  success_probability) const
inlineprotected

Definition at line 331 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::computeRigidTransform ( const float *  a1,
const float *  a1_n,
const float *  b1,
const float *  b1_n,
const float *  a2,
const float *  a2_n,
const float *  b2,
const float *  b2_n,
float *  rigid_transform 
) const
inlineprotected

Computes the rigid transform that maps the line (a1, b1) to (a2, b2).

The computation is based on the corresponding points 'a1' <-> 'a2' and 'b1' <-> 'b2' and the normals 'a1_n', 'b1_n', 'a2_n', and 'b2_n'. The result is saved in 'rigid_transform' which is an array of length 12. The first 9 elements are the rotational part (row major order) and the last 3 are the translation.

Definition at line 389 of file obj_rec_ransac.h.

References pcl::recognition::aux::cross3(), pcl::recognition::aux::diff3(), pcl::recognition::aux::mult3x3(), pcl::recognition::aux::normalize3(), pcl::recognition::aux::projectOnPlane3(), and pcl::recognition::aux::sum3().

void pcl::recognition::ObjRecRANSAC::enterTestModeSampleOPP ( )
inline

Definition at line 247 of file obj_rec_ransac.h.

References SAMPLE_OPP.

void pcl::recognition::ObjRecRANSAC::enterTestModeTestHypotheses ( )
inline

Definition at line 253 of file obj_rec_ransac.h.

References TEST_HYPOTHESES.

void pcl::recognition::ObjRecRANSAC::filterGraphOfCloseHypotheses ( ORRGraph< Hypothesis > &  graph,
std::vector< Hypothesis > &  out 
) const
protected
void pcl::recognition::ObjRecRANSAC::filterGraphOfConflictingHypotheses ( ORRGraph< Hypothesis * > &  graph,
std::list< ObjRecRANSAC::Output > &  recognized_objects 
) const
protected
int pcl::recognition::ObjRecRANSAC::generateHypotheses ( const std::list< OrientedPointPair > &  pairs,
std::list< HypothesisBase > &  out 
) const
protected
const std::vector<Hypothesis>& pcl::recognition::ObjRecRANSAC::getAcceptedHypotheses ( ) const
inline

This function is useful for testing purposes.

It returns the accepted hypotheses generated during the recognition process. Makes sense only if some of the testing modes are active.

Definition at line 275 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::getAcceptedHypotheses ( std::vector< Hypothesis > &  out) const
inline

This function is useful for testing purposes.

It returns the accepted hypotheses generated during the recognition process. Makes sense only if some of the testing modes are active.

Definition at line 283 of file obj_rec_ransac.h.

const pcl::recognition::ModelLibrary::HashTable& pcl::recognition::ObjRecRANSAC::getHashTable ( ) const
inline

Returns the hash table in the model library.

Definition at line 290 of file obj_rec_ransac.h.

const ModelLibrary::Model* pcl::recognition::ObjRecRANSAC::getModel ( const std::string &  name) const
inline

Definition at line 302 of file obj_rec_ransac.h.

const ModelLibrary& pcl::recognition::ObjRecRANSAC::getModelLibrary ( ) const
inline

Definition at line 296 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::getPairWidth ( ) const
inline

Definition at line 320 of file obj_rec_ransac.h.

RigidTransformSpace& pcl::recognition::ObjRecRANSAC::getRigidTransformSpace ( )
inline

Definition at line 314 of file obj_rec_ransac.h.

const std::list<ObjRecRANSAC::OrientedPointPair>& pcl::recognition::ObjRecRANSAC::getSampledOrientedPointPairs ( ) const
inline

This function is useful for testing purposes.

It returns the oriented point pairs which were sampled from the scene during the recognition process. Makes sense only if some of the testing modes are active.

Definition at line 267 of file obj_rec_ransac.h.

const ORROctree& pcl::recognition::ObjRecRANSAC::getSceneOctree ( ) const
inline

Definition at line 308 of file obj_rec_ransac.h.

int pcl::recognition::ObjRecRANSAC::groupHypotheses ( std::list< HypothesisBase > &  hypotheses,
int  num_hypotheses,
RigidTransformSpace transform_space,
HypothesisOctree grouped_hypotheses 
) const
protected

Groups close hypotheses in 'hypotheses'.

Saves a representative for each group in 'out'. Returns the number of hypotheses after grouping.

void pcl::recognition::ObjRecRANSAC::icpHypothesesRefinementOff ( )
inline

Definition at line 213 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::icpHypothesesRefinementOn ( )
inline

Definition at line 207 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::ignoreCoplanarPointPairsOff ( )
inline

Default is on.

This method calls the corresponding method of the model library.

Definition at line 200 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::ignoreCoplanarPointPairsOn ( )
inline

Default is on.

This method calls the corresponding method of the model library.

Definition at line 192 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::leaveTestMode ( )
inline

Definition at line 259 of file obj_rec_ransac.h.

References FULL_RECOGNITION.

void pcl::recognition::ObjRecRANSAC::recognize ( const PointCloudIn scene,
const PointCloudN normals,
std::list< ObjRecRANSAC::Output > &  recognized_objects,
double  success_probability = 0.99 
)

This method performs the recognition of the models loaded to the model library with the method addModel().

Parameters
[in]sceneis the 3d scene in which the object should be recognized.
[in]normalsare the scene normals.
[out]recognized_objectsis the list of output items each one containing the recognized model instance, its name, the aligning rigid transform and the match confidence (see ObjRecRANSAC::Output for further explanations).
[in]success_probabilityis the user-defined probability of detecting all objects in the scene.
void pcl::recognition::ObjRecRANSAC::sampleOrientedPointPairs ( int  num_iterations,
const std::vector< ORROctree::Node * > &  full_scene_leaves,
std::list< OrientedPointPair > &  output 
) const
protected
void pcl::recognition::ObjRecRANSAC::setMaxCoplanarityAngleDegrees ( float  max_coplanarity_angle_degrees)
inline

This is a threshold.

The larger the value the more point pairs will be considered as co-planar and will be ignored in the off-line model pre-processing and in the online recognition phases. This makes sense only if "ignore co-planar points" is on. Call this method before calling addModel. This method calls the corresponding method of the model library.

Definition at line 178 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::setSceneBoundsEnlargementFactor ( float  value)
inline

Definition at line 185 of file obj_rec_ransac.h.

void pcl::recognition::ObjRecRANSAC::testHypothesis ( Hypothesis hypothesis,
int &  match,
int &  penalty 
) const
inlineprotected
void pcl::recognition::ObjRecRANSAC::testHypothesisNormalBased ( Hypothesis hypothesis,
float &  match 
) const
inlineprotected

Friends And Related Function Documentation

friend class ModelLibrary
friend

Definition at line 328 of file obj_rec_ransac.h.

Member Data Documentation

float pcl::recognition::ObjRecRANSAC::abs_zdist_thresh_
protected

Definition at line 459 of file obj_rec_ransac.h.

std::vector<Hypothesis> pcl::recognition::ObjRecRANSAC::accepted_hypotheses_
protected

Definition at line 478 of file obj_rec_ransac.h.

bool pcl::recognition::ObjRecRANSAC::do_icp_hypotheses_refinement_
protected

Definition at line 468 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::frac_of_points_for_icp_refinement_
protected

Definition at line 467 of file obj_rec_ransac.h.

bool pcl::recognition::ObjRecRANSAC::ignore_coplanar_opps_
protected

Definition at line 466 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::intersection_fraction_
protected

Definition at line 463 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::max_coplanarity_angle_
protected

Definition at line 464 of file obj_rec_ransac.h.

ModelLibrary pcl::recognition::ObjRecRANSAC::model_library_
protected

Definition at line 470 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::pair_width_
protected

Definition at line 455 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::position_discretization_
protected

Definition at line 457 of file obj_rec_ransac.h.

Recognition_Mode pcl::recognition::ObjRecRANSAC::rec_mode_
protected

Definition at line 479 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::relative_num_of_illegal_pts_
protected

Definition at line 462 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::relative_obj_size_
protected

Definition at line 460 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::rotation_discretization_
protected

Definition at line 458 of file obj_rec_ransac.h.

std::list<OrientedPointPair> pcl::recognition::ObjRecRANSAC::sampled_oriented_point_pairs_
protected

Definition at line 477 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::scene_bounds_enlargement_factor_
protected

Definition at line 465 of file obj_rec_ransac.h.

ORROctree pcl::recognition::ObjRecRANSAC::scene_octree_
protected

Definition at line 471 of file obj_rec_ransac.h.

PointCloudIn::Ptr pcl::recognition::ObjRecRANSAC::scene_octree_points_
protected

Definition at line 475 of file obj_rec_ransac.h.

ORROctreeZProjection pcl::recognition::ObjRecRANSAC::scene_octree_proj_
protected

Definition at line 472 of file obj_rec_ransac.h.

RigidTransformSpace pcl::recognition::ObjRecRANSAC::transform_space_
protected

Definition at line 473 of file obj_rec_ransac.h.

TrimmedICP<pcl::PointXYZ, float> pcl::recognition::ObjRecRANSAC::trimmed_icp_
protected

Definition at line 474 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::visibility_
protected

Definition at line 461 of file obj_rec_ransac.h.

float pcl::recognition::ObjRecRANSAC::voxel_size_
protected

Definition at line 456 of file obj_rec_ransac.h.


The documentation for this class was generated from the following file: