OpenCV  5.0.0-pre
Open Source Computer Vision
Public Types | Public Member Functions | Static Public Member Functions | List of all members
cv::SACSegmentation Class Referenceabstract

Sample Consensus algorithm segmentation of 3D point cloud model. More...

#include <opencv2/3d/ptcloud.hpp>

Public Types

using ModelConstraintFunction = std::function< bool(const std::vector< double > &)>
 Custom function that take the model coefficients and return whether the model is acceptable or not. More...
 

Public Member Functions

 SACSegmentation ()=default
 
virtual ~SACSegmentation ()=default
 
virtual double getConfidence () const =0
 Get the confidence that ensure at least one of selections is an error-free set of data points. More...
 
virtual const ModelConstraintFunctiongetCustomModelConstraints () const =0
 Get custom model coefficient constraint function. More...
 
virtual double getDistanceThreshold () const =0
 Get the distance to the model threshold. More...
 
virtual int getMaxIterations () const =0
 Get the maximum number of iterations to attempt. More...
 
virtual int getNumberOfModelsExpected () const =0
 Get the expected number of models. More...
 
virtual void getRadiusLimits (double &radius_min, double &radius_max) const =0
 Get the minimum and maximum radius limits for the model. More...
 
virtual uint64 getRandomGeneratorState () const =0
 Get state used to initialize the RNG(Random Number Generator). More...
 
virtual SacMethod getSacMethodType () const =0
 Get the type of sample consensus method used. More...
 
virtual SacModelType getSacModelType () const =0
 Get the type of sample consensus model used. More...
 
virtual bool isParallel () const =0
 Get whether to use parallelism or not. More...
 
virtual int segment (InputArray input_pts, OutputArray labels, OutputArray models_coefficients)=0
 Execute segmentation using the sample consensus method. More...
 
virtual void setConfidence (double confidence)=0
 Set the confidence that ensure at least one of selections is an error-free set of data points. More...
 
virtual void setCustomModelConstraints (const ModelConstraintFunction &custom_model_constraints)=0
 
virtual void setDistanceThreshold (double threshold)=0
 
virtual void setMaxIterations (int max_iterations)=0
 Set the maximum number of iterations to attempt. More...
 
virtual void setNumberOfModelsExpected (int number_of_models_expected)=0
 Set the number of models expected. More...
 
virtual void setParallel (bool is_parallel)=0
 
virtual void setRadiusLimits (double radius_min, double radius_max)=0
 
virtual void setRandomGeneratorState (uint64 rng_state)=0
 Set state used to initialize the RNG(Random Number Generator). More...
 
virtual void setSacMethodType (SacMethod sac_method)=0
 Set the type of sample consensus method to use. More...
 
virtual void setSacModelType (SacModelType sac_model_type)=0
 Set the type of sample consensus model to use. More...
 

Static Public Member Functions

static Ptr< SACSegmentationcreate (SacModelType sac_model_type=SAC_MODEL_PLANE, SacMethod sac_method=SAC_METHOD_RANSAC, double threshold=0.5, int max_iterations=1000)
 

Detailed Description

Sample Consensus algorithm segmentation of 3D point cloud model.

Example of segmenting plane from a 3D point cloud using the RANSAC algorithm:

int planeSegmentationUsingRANSAC(const cv::Mat &pt_cloud,
std::vector<cv::Vec4d> &planes_coeffs, std::vector<char> &labels)
{
using namespace cv;
Ptr<SACSegmentation> sacSegmentation =
sacSegmentation->setDistanceThreshold(0.21);
// The maximum number of iterations to attempt.(default 1000)
sacSegmentation->setMaxIterations(1500);
sacSegmentation->setNumberOfModelsExpected(2);
Mat planes_coeffs_mat;
// Number of final resultant models obtained by segmentation.
int model_cnt = sacSegmentation->segment(pt_cloud,
labels, planes_coeffs_mat);
planes_coeffs.clear();
for (int i = 0; i < model_cnt; ++i)
{
planes_coeffs.push_back(planes_coeffs_mat.row(i));
}
return model_cnt;
}
See also
  1. Supported algorithms: enum SacMethod in ptcloud.hpp.
  2. Supported models: enum SacModelType in ptcloud.hpp.

Member Typedef Documentation

◆ ModelConstraintFunction

using cv::SACSegmentation::ModelConstraintFunction = std::function<bool(const std::vector<double> &)>

Custom function that take the model coefficients and return whether the model is acceptable or not.

Example of constructing SACSegmentation::ModelConstraintFunction:

bool customFunc(const std::vector<double> &model_coefficients)
{
// check model_coefficients
// The plane needs to pass through the origin, i.e. ax+by+cz+d=0 --> d==0
return model_coefficients[3] == 0;
} // end of function customFunc()
void usageExampleSacModelConstraintFunction()
{
using namespace cv;
SACSegmentation::ModelConstraintFunction func_example1 = customFunc;
[](const std::vector<double> &model_coefficients) {
// check model_coefficients
// The plane needs to pass through the origin, i.e. ax+by+cz+d=0 --> d==0
return model_coefficients[3] == 0;
};
// Using local variables
float x0 = 0.0, y0 = 0.0, z0 = 0.0;
[x0, y0, z0](const std::vector<double> &model_coeffs) -> bool {
// check model_coefficients
// The plane needs to pass through the point (x0, y0, z0), i.e. ax0+by0+cz0+d == 0
return model_coeffs[0] * x0 + model_coeffs[1] * y0 + model_coeffs[2] * z0
+ model_coeffs[3] == 0;
};
// Next, use the constructed SACSegmentation::ModelConstraintFunction func_example1, 2, 3 ......
}
Note
The content of model_coefficients depends on the model. Refer to the comments inside enumeration type SacModelType.

Constructor & Destructor Documentation

◆ SACSegmentation()

cv::SACSegmentation::SACSegmentation ( )
default

◆ ~SACSegmentation()

virtual cv::SACSegmentation::~SACSegmentation ( )
virtualdefault

Member Function Documentation

◆ create()

static Ptr<SACSegmentation> cv::SACSegmentation::create ( SacModelType  sac_model_type = SAC_MODEL_PLANE,
SacMethod  sac_method = SAC_METHOD_RANSAC,
double  threshold = 0.5,
int  max_iterations = 1000 
)
static

◆ getConfidence()

virtual double cv::SACSegmentation::getConfidence ( ) const
pure virtual

Get the confidence that ensure at least one of selections is an error-free set of data points.

◆ getCustomModelConstraints()

virtual const ModelConstraintFunction& cv::SACSegmentation::getCustomModelConstraints ( ) const
pure virtual

Get custom model coefficient constraint function.

◆ getDistanceThreshold()

virtual double cv::SACSegmentation::getDistanceThreshold ( ) const
pure virtual

Get the distance to the model threshold.

◆ getMaxIterations()

virtual int cv::SACSegmentation::getMaxIterations ( ) const
pure virtual

Get the maximum number of iterations to attempt.

◆ getNumberOfModelsExpected()

virtual int cv::SACSegmentation::getNumberOfModelsExpected ( ) const
pure virtual

Get the expected number of models.

◆ getRadiusLimits()

virtual void cv::SACSegmentation::getRadiusLimits ( double &  radius_min,
double &  radius_max 
) const
pure virtual

Get the minimum and maximum radius limits for the model.

◆ getRandomGeneratorState()

virtual uint64 cv::SACSegmentation::getRandomGeneratorState ( ) const
pure virtual

Get state used to initialize the RNG(Random Number Generator).

◆ getSacMethodType()

virtual SacMethod cv::SACSegmentation::getSacMethodType ( ) const
pure virtual

Get the type of sample consensus method used.

◆ getSacModelType()

virtual SacModelType cv::SACSegmentation::getSacModelType ( ) const
pure virtual

Get the type of sample consensus model used.

◆ isParallel()

virtual bool cv::SACSegmentation::isParallel ( ) const
pure virtual

Get whether to use parallelism or not.

◆ segment()

virtual int cv::SACSegmentation::segment ( InputArray  input_pts,
OutputArray  labels,
OutputArray  models_coefficients 
)
pure virtual

Execute segmentation using the sample consensus method.

Parameters
input_ptsOriginal point cloud, vector of Point3 or Mat of size Nx3/3xN.
[out]labelsThe label corresponds to the model number, 0 means it does not belong to any model, range [0, Number of final resultant models obtained].
[out]models_coefficientsThe resultant models coefficients. Currently supports passing in cv::Mat. Models coefficients are placed in a matrix of NxK with depth CV_64F (will automatically adjust if the passing one does not look like this), where N is the number of models and K is the number of coefficients of one model. The coefficients for each model refer to the comments inside enumeration type SacModelType.
Returns
Number of final resultant models obtained by segmentation.

◆ setConfidence()

virtual void cv::SACSegmentation::setConfidence ( double  confidence)
pure virtual

Set the confidence that ensure at least one of selections is an error-free set of data points.

◆ setCustomModelConstraints()

virtual void cv::SACSegmentation::setCustomModelConstraints ( const ModelConstraintFunction custom_model_constraints)
pure virtual

Set custom model coefficient constraint function. A custom function that takes model coefficients and returns whether the model is acceptable or not.

◆ setDistanceThreshold()

virtual void cv::SACSegmentation::setDistanceThreshold ( double  threshold)
pure virtual

Set the distance to the model threshold. Considered as inlier point if distance to the model less than threshold.

◆ setMaxIterations()

virtual void cv::SACSegmentation::setMaxIterations ( int  max_iterations)
pure virtual

Set the maximum number of iterations to attempt.

◆ setNumberOfModelsExpected()

virtual void cv::SACSegmentation::setNumberOfModelsExpected ( int  number_of_models_expected)
pure virtual

Set the number of models expected.

◆ setParallel()

virtual void cv::SACSegmentation::setParallel ( bool  is_parallel)
pure virtual

Set whether to use parallelism or not. The number of threads is set by cv::setNumThreads(int nthreads).

◆ setRadiusLimits()

virtual void cv::SACSegmentation::setRadiusLimits ( double  radius_min,
double  radius_max 
)
pure virtual

Set the minimum and maximum radius limits for the model. Only used for models whose model parameters include a radius.

◆ setRandomGeneratorState()

virtual void cv::SACSegmentation::setRandomGeneratorState ( uint64  rng_state)
pure virtual

Set state used to initialize the RNG(Random Number Generator).

◆ setSacMethodType()

virtual void cv::SACSegmentation::setSacMethodType ( SacMethod  sac_method)
pure virtual

Set the type of sample consensus method to use.

◆ setSacModelType()

virtual void cv::SACSegmentation::setSacModelType ( SacModelType  sac_model_type)
pure virtual

Set the type of sample consensus model to use.


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