cv::SACSegmentation Class Reference

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

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

Collaboration diagram for cv::SACSegmentation:

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.

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

Static Public Member Functions
static Ptr< SACSegmentation >	create (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::create(SAC_MODEL_PLANE, SAC_METHOD_RANSAC);
    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;
 
    SACSegmentation::ModelConstraintFunction func_example2 =
            [](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;
    SACSegmentation::ModelConstraintFunction func_example3 =
            [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_pts	Original point cloud, vector of Point3 or Mat of size Nx3/3xN.
[out]	labels	The 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_coefficients	The 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:

• opencv2/3d/ptcloud.hpp