| OpenCV 5.0.0alpha Open Source Computer Vision

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | List of all members
cv::SACSegmentation Class Referenceabstract
3D vision functionality

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

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

Collaboration diagram for cv::SACSegmentation:

## Public Types
using | ModelConstraintFunction
| 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

Initial value:
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 | ( |  | ) |
| virtual default

## 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