This command can search for one or more primitive shapes in the combined point clouds of opened stereo cameras. Currently the only supported shapes are planes, spheres and cylinders.

FitPrimitive uses the RANSAC algorithm to robustly identify parametric surfaces. You might have a look at the corresponding Wikipedia article for a short description of the algorithm. Below you can also find a short example of the steps performed for a plane search.


Considering the example of searching a plane the steps taken are as follows:

  1. Choose 3 random points from the input point cloud

  2. Compute the parameters of the plane defined by the 3 points; the plane is called a hypothesis

  3. Count how many other points in the input point cloud are on the plane (closer than a chosen distance, defined by the InlierThreshold search parameter); these points are called inliers.

  4. Remember the plane parameters if we found more inliers than before, otherwise just discard it.

  5. start over with 1.

If we happen to choose all 3 points on the plane we are looking for in one of the iterations all other plane points will be counted as inliers. The number of inliers will then be much larger than for random planes intersecting the scene at arbitrary angles and this hypothesis will never be replaced again in step 4 in the remaining iterations (except if we find another plane which is larger and has more points, but that’s ok too!).

If we know a priori approximately the percentage of the points lying on the plane (the InlierFraction search parameter) we can derive a number of iterations through steps 1 to 5 we have to perform in order to achieve a very small probability of _not_ finding the plane. This tolerated probability of failing can be specified in the FailureProbability parameter and can be set very low (like 1e-6 or smaller). Note that the FailureProbability cannot be zero, because we would need to take infinitely many iterations to reach that.

Implications and usage guidelines

It is easier to find primitives represented by a large number of points in the point cloud

  • Try to use as much scene information as possible to reduce the number of other points beside your searched primitive

    • You can use the BoundingBox parameter to restrict the algorithm to points in the specified 3d box volume.

    • If your images contain a large background plane, but you are searching for a smaller cylinder in the foreground you can simply add a plane search as first primitive search. The plane is covered by a large fraction points from the point cloud and will be found easily. The plane points will then be removed from the point cloud before searching for the next primitive. So removing the plane points first effectively increased the percentage of the points on the cylinder when the cylinder search is started.

Better underestimate the percentage of inlier points or overestimate the necessary FailureProbability (choose an even smaller value for FailureProbability )

  • The specified FailureProbability will only be reached or exceeded when the a priori guess of the InlierFraction was correct or too small. So choosing a smaller value will give you more safety margin that your object will be found.

  • The assumption stated in the example above that any 3 points on the plane will allow to find the correct plane parameters is in general not correct. Noise in the point cloud will prevent to find the correct parameters if the points are too close together. So again underestimating the InlierFraction or overestimating the necessary FailureProbability (choosing a smaller failure probability than actually needed) is a safer choice.


This command can be interrupted by the Break command.