Class cv::SACSegmentation#

Sample Consensus algorithm segmentation of 3D point cloud model. View details

#include <opencv2/geometry/segment.hpp>

Collaboration diagram for cv::SACSegmentation:

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;
}

Member Typedef Documentation#

ModelConstraintFunction#

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

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()

~SACSegmentation()#

cv::SACSegmentation::~SACSegmentation()

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 )

getConfidence()#

double cv::SACSegmentation::getConfidence()

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

getCustomModelConstraints()#

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

Get custom model coefficient constraint function.

getDistanceThreshold()#

double cv::SACSegmentation::getDistanceThreshold()

Get the distance to the model threshold.

getMaxIterations()#

int cv::SACSegmentation::getMaxIterations()

Get the maximum number of iterations to attempt.

getNumberOfModelsExpected()#

int cv::SACSegmentation::getNumberOfModelsExpected()

Get the expected number of models.

getRadiusLimits()#

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

Get the minimum and maximum radius limits for the model.

getRandomGeneratorState()#

uint64 cv::SACSegmentation::getRandomGeneratorState()

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

getSacMethodType()#

SacMethod cv::SACSegmentation::getSacMethodType()

Get the type of sample consensus method used.

getSacModelType()#

SacModelType cv::SACSegmentation::getSacModelType()

Get the type of sample consensus model used.

isParallel()#

bool cv::SACSegmentation::isParallel()

Get whether to use parallelism or not.

segment()#

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

Execute segmentation using the sample consensus method.

Parameters

input_pts — Original point cloud, vector of Point3 or Mat of size Nx3/3xN.
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].
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()#

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

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

setCustomModelConstraints()#

void cv::SACSegmentation::setCustomModelConstraints(const ModelConstraintFunction & custom_model_constraints)

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

setDistanceThreshold()#

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

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

setMaxIterations()#

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

Set the maximum number of iterations to attempt.

setNumberOfModelsExpected()#

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

Set the number of models expected.

setParallel()#

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

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

setRadiusLimits()#

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

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

setRandomGeneratorState()#

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

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

setSacMethodType()#

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

Set the type of sample consensus method to use.

setSacModelType()#

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

Set the type of sample consensus model to use.

Source file#

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

opencv2/geometry/segment.hpp