eVision .NET API
Loading...
Searching...
No Matches
eVision.Easy3D.EPlaneFinder Class Reference

A EPlaneFinder object is used to search an E3DPlane in an EPointCloud. More...

Inheritance diagram for eVision.Easy3D.EPlaneFinder:
Collaboration diagram for eVision.Easy3D.EPlaneFinder:

Public Member Functions

 EPlaneFinder (float maxDeviation, float pcExpectedInCloud)
 Creates an EPlaneFinder object.
 EPlaneFinder (float maxDeviation)
 Creates an EPlaneFinder object.
 EPlaneFinder (float maxDeviation, eVision.EFloatRange pcExpectedInCloudRange)
 Creates an EPlaneFinder object.
 EPlaneFinder (eVision.Easy3D.EPlaneFinder other)
 Creates an EPlaneFinder object.
void EnableDecimator ()
 Enables the default decimation which reduces the input point cloud by drawing points randomly.
void DisableDecimator ()
 Disables the default decimation.
bool IsDecimatorEnabled ()
 Returns true if the default decimator is enabled (enabled by default).
void UnsetNormal ()
 Unsets the normal vector definition.
void SetNormal (eVision.Easy3D.E3DPoint normal)
 Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.
void SetNormal (eVision.Easy3D.E3DPoint normal, float angleTolerance)
 Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.
void SetNormal (float nx, float ny, float nz)
 Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.
void SetNormal (float nx, float ny, float nz, float angleTolerance)
 Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.
void SetNormal (eVision.Easy3D.E3DPlane referencePlane)
 Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.
void SetNormal (eVision.Easy3D.E3DPlane referencePlane, float angleTolerance)
 Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.
eVision.Easy3D.E3DPoint GetNormal ()
 Returns the expected normal direction (that has been set by EPlaneFinder.SetNormal).
bool IsNormalSet ()
 Returns true if the expected normal direction has been set (not set by default).
void UnsetPoints ()
 Unsets the 1 or 2 points that the plane is constrained to contain.
void SetTwoPoints (eVision.Easy3D.E3DPoint point1, eVision.Easy3D.E3DPoint point2)
 Sets two points that the plane will be constrained to contain.
eVision.Easy3D.E3DPoint GetPoint (bool first)
 Returns an E3DPoint the plane is constrained to contain (that has been set by EPlaneFinder.OnePoint or EPlaneFinder.SetTwoPoints).
float Find (eVision.Easy3D.EPointCloud pointCloud, eVision.Easy3D.E3DPlane foundPlane)
 Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.
float Find (eVision.Easy3D.EPointCloud pointCloud, eVision.Easy3D.E3DPlane foundPlane, eVision.Easy3D.EPointCloud inliers)
 Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.
float Find (eVision.Easy3D.EPointCloud pointCloud, eVision.Easy3D.E3DPlane foundPlane, eVision.Easy3D.EPointCloud inliers, eVision.Easy3D.EPointCloud outliers)
 Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.
eVision.Easy3D.E3DPlane Find (eVision.Easy3D.EPointCloud pointCloud)
 Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.
eVision.Easy3D.E3DPlane Find (eVision.Easy3D.EPointCloud pointCloud, out float effectiveInliersRatio)
 Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.
eVision.Easy3D.E3DPlane Find (eVision.Easy3D.EPointCloud pointCloud, out float effectiveInliersRatio, eVision.Easy3D.EPointCloud inliers)
 Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.
eVision.Easy3D.E3DPlane Find (eVision.Easy3D.EPointCloud pointCloud, out float effectiveInliersRatio, eVision.Easy3D.EPointCloud inliers, eVision.Easy3D.EPointCloud outliers)
 Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.
void Load (string path)
 Loads the plane finder configuration. The given ESerializer must have been created for reading.
void Load (eVision.ESerializer serializer)
 Loads the plane finder configuration. The given ESerializer must have been created for reading.
void Save (string path)
 Saves the plane finder configuration. The given ESerializer must have been created for writing.
void Save (eVision.ESerializer serializer)
 Saves the plane finder configuration. The given ESerializer must have been created for writing.
bool IsSeedSet ()
 Returns true if the seed was set to a custom value.
void UnsetSeed ()
 Reset seed to its default state of being randomly initialized.

Properties

float MaxDeviation [get, set]
 Sets/gets the maximum distance of an inlier to the plane.
int NumberOfPointsAfterDecimation [get, set]
 Sets/gets the number of points surviving the decimation. Using the setter enables the decimation if it wasn't already. if numberOfPointsAfterDecimation is bigger than the point cloud size, no decimation occurs.
float ExpectedCloudInliersRatio [get, set]
 Sets/gets the expected ratio of inliers in the EPointCloud.
eVision.EFloatRange ExpectedCloudInliersRatioRange [get, set]
 Sets/gets the expected ratio of inliers in the EPointCloud.
float NormalTolerance [get]
 Returns the angle tolerance around the expected normal (that has been set by EPlaneFinder.SetNormal).
eVision.Easy3D.E3DPoint OnePoint [set]
 Sets one point that the plane will be constrained to contain.
int NumberOfPointsSet [get]
 Returns the number of points set (this will be either 0, 1 or 2).
uint Seed [get, set]
 Returns the seed (that has been set by EPlaneFinder.Seed).

Detailed Description

A EPlaneFinder object is used to search an E3DPlane in an EPointCloud.

The algorithm searches the largest plane in terms of number of "inliers". A point is an "inlier" when its distance to the plane is smaller than a specified threshold (parameter "maximum distance"). Another parameter specifies the expected ratio of inliers over the total number of points in the point cloud (by default, this is set to 0.3).

For more control, you can also set the expected ratio of inliers as a range, when a single number is given the behavior is equivalent to a range (number/2, number). The method Find throws an error if it cannot achieve a proportion of inliers better than the min of the range. It stops as soon as the max of the range is achieved.

Reducing the size of the range increases speed. A decimation is applied by default to accelerate the search. Furthermore, the expected normal to the plane and/or up to two points contained in the plane may be specified.

The method EPlaneFinder.Find processes an EPointCloud object and returns an E3DPlane object when a sufficiently good plane is found in the input point cloud. The returned plane is the result of fitting an EPlaneFitter on the inliers.

License(s): Easy3D

Constructor & Destructor Documentation

◆ EPlaneFinder() [1/4]

eVision.Easy3D.EPlaneFinder.EPlaneFinder ( float maxDeviation,
float pcExpectedInCloud )

Creates an EPlaneFinder object.

Parameters
maxDeviationMaximum distance of an inlier to the plane. This value has to be strictly positive.
pcExpectedInCloudThis is an estimation of the ratio of inliers in the point cloud. The algorithm stops as soon as a pointCloud with at least pcExpectedInCloud inliers is found. It throws an error if the best plane has less than pcExpectedInCloud/2 inliers.

This optional parameter has a default value of 0.3.

◆ EPlaneFinder() [2/4]

eVision.Easy3D.EPlaneFinder.EPlaneFinder ( float maxDeviation)

Creates an EPlaneFinder object.

Parameters
maxDeviationMaximum distance of an inlier to the plane. This value has to be strictly positive.

◆ EPlaneFinder() [3/4]

eVision.Easy3D.EPlaneFinder.EPlaneFinder ( float maxDeviation,
eVision.EFloatRange pcExpectedInCloudRange )

Creates an EPlaneFinder object.

Parameters
maxDeviationMaximum distance of an inlier to the plane. This value has to be strictly positive.
pcExpectedInCloudRangeThis is an estimation of the ratio of inliers in the point cloud as a range within ]0, 1[. The algorithm throws an error if the best plane has less than inliersProportion.min inliers. The algorithm stops as soon as a model with inliersProportion.max is found.

Increasing inliersProportion.min can increase speed but at the risk of missing the plane. Decreasing the max of the range can increase speed but at the risk of finding a bad plane.

◆ EPlaneFinder() [4/4]

eVision.Easy3D.EPlaneFinder.EPlaneFinder ( eVision.Easy3D.EPlaneFinder other)

Creates an EPlaneFinder object.

Parameters
otherThe EPlaneFinder object that should be copied.

Member Function Documentation

◆ DisableDecimator()

void eVision.Easy3D.EPlaneFinder.DisableDecimator ( )

Disables the default decimation.

The decimation should be disabled when the input point cloud is already decimated.

◆ EnableDecimator()

void eVision.Easy3D.EPlaneFinder.EnableDecimator ( )

Enables the default decimation which reduces the input point cloud by drawing points randomly.

This decimation is enabled by default. The decimation accelerates the search.

◆ Find() [1/7]

eVision.Easy3D.E3DPlane eVision.Easy3D.EPlaneFinder.Find ( eVision.Easy3D.EPointCloud pointCloud)

Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.

Parameters
pointCloudThe input point cloud in which the plane should be searched (need at least 3 points)

The normal vector of the fitted plane is always oriented towards the positive Z axis, see E3DPlaneNormalOrientation.E3DPlaneNormalOrientation_PosZ.

Deprecated
Deprecated in version 24.6. Scheduled to be removed in version 27.6.

◆ Find() [2/7]

float eVision.Easy3D.EPlaneFinder.Find ( eVision.Easy3D.EPointCloud pointCloud,
eVision.Easy3D.E3DPlane foundPlane )

Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.

Parameters
pointCloudThe input point cloud in which the plane should be searched (need at least 3 points)
foundPlaneAn E3DPlane that will contain the plane found

The normal vector of the fitted plane is always oriented towards the positive Z axis, see E3DPlaneNormalOrientation.E3DPlaneNormalOrientation_PosZ.

◆ Find() [3/7]

float eVision.Easy3D.EPlaneFinder.Find ( eVision.Easy3D.EPointCloud pointCloud,
eVision.Easy3D.E3DPlane foundPlane,
eVision.Easy3D.EPointCloud inliers )

Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.

Parameters
pointCloudThe input point cloud in which the plane should be searched (need at least 3 points)
foundPlaneAn E3DPlane that will contain the plane found
inliersA pointcloud that will contain the inliers of the plane

The normal vector of the fitted plane is always oriented towards the positive Z axis, see E3DPlaneNormalOrientation.E3DPlaneNormalOrientation_PosZ.

◆ Find() [4/7]

float eVision.Easy3D.EPlaneFinder.Find ( eVision.Easy3D.EPointCloud pointCloud,
eVision.Easy3D.E3DPlane foundPlane,
eVision.Easy3D.EPointCloud inliers,
eVision.Easy3D.EPointCloud outliers )

Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.

Parameters
pointCloudThe input point cloud in which the plane should be searched (need at least 3 points)
foundPlaneAn E3DPlane that will contain the plane found
inliersA pointcloud that will contain the inliers of the plane
outliersA pointcloud that will contain the outliers of the plane

The normal vector of the fitted plane is always oriented towards the positive Z axis, see E3DPlaneNormalOrientation.E3DPlaneNormalOrientation_PosZ.

◆ Find() [5/7]

eVision.Easy3D.E3DPlane eVision.Easy3D.EPlaneFinder.Find ( eVision.Easy3D.EPointCloud pointCloud,
out float effectiveInliersRatio )

Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.

Parameters
pointCloudThe input point cloud in which the plane should be searched (need at least 3 points)
effectiveInliersRatioThis passed by reference float will contain the effective ratio of inliers

The normal vector of the fitted plane is always oriented towards the positive Z axis, see E3DPlaneNormalOrientation.E3DPlaneNormalOrientation_PosZ.

Deprecated
Deprecated in version 24.6. Scheduled to be removed in version 27.6.

◆ Find() [6/7]

eVision.Easy3D.E3DPlane eVision.Easy3D.EPlaneFinder.Find ( eVision.Easy3D.EPointCloud pointCloud,
out float effectiveInliersRatio,
eVision.Easy3D.EPointCloud inliers )

Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.

Parameters
pointCloudThe input point cloud in which the plane should be searched (need at least 3 points)
effectiveInliersRatioThis passed by reference float will contain the effective ratio of inliers
inliersA pointcloud that will contain the inliers of the plane

The normal vector of the fitted plane is always oriented towards the positive Z axis, see E3DPlaneNormalOrientation.E3DPlaneNormalOrientation_PosZ.

Deprecated
Deprecated in version 24.6. Scheduled to be removed in version 27.6.

◆ Find() [7/7]

eVision.Easy3D.E3DPlane eVision.Easy3D.EPlaneFinder.Find ( eVision.Easy3D.EPointCloud pointCloud,
out float effectiveInliersRatio,
eVision.Easy3D.EPointCloud inliers,
eVision.Easy3D.EPointCloud outliers )

Searches the biggest plane in the supplied EPointCloud. If a sufficiently good plane is not found, an exception is thrown.

Parameters
pointCloudThe input point cloud in which the plane should be searched (need at least 3 points)
effectiveInliersRatioThis passed by reference float will contain the effective ratio of inliers
inliersA pointcloud that will contain the inliers of the plane
outliersA pointcloud that will contain the outliers of the plane

The normal vector of the fitted plane is always oriented towards the positive Z axis, see E3DPlaneNormalOrientation.E3DPlaneNormalOrientation_PosZ.

Deprecated
Deprecated in version 24.6. Scheduled to be removed in version 27.6.

◆ GetNormal()

eVision.Easy3D.E3DPoint eVision.Easy3D.EPlaneFinder.GetNormal ( )

Returns the expected normal direction (that has been set by EPlaneFinder.SetNormal).

◆ GetPoint()

eVision.Easy3D.E3DPoint eVision.Easy3D.EPlaneFinder.GetPoint ( bool first)

Returns an E3DPoint the plane is constrained to contain (that has been set by EPlaneFinder.OnePoint or EPlaneFinder.SetTwoPoints).

Parameters
firstTrue if you want to get the first point and false if you want the second instead.

◆ IsDecimatorEnabled()

bool eVision.Easy3D.EPlaneFinder.IsDecimatorEnabled ( )

Returns true if the default decimator is enabled (enabled by default).

◆ IsNormalSet()

bool eVision.Easy3D.EPlaneFinder.IsNormalSet ( )

Returns true if the expected normal direction has been set (not set by default).

◆ IsSeedSet()

bool eVision.Easy3D.EPlaneFinder.IsSeedSet ( )

Returns true if the seed was set to a custom value.

Deprecated

Always returns true.

Deprecated in version 24.6. Scheduled to be removed in version 27.6.

◆ Load() [1/2]

void eVision.Easy3D.EPlaneFinder.Load ( eVision.ESerializer serializer)

Loads the plane finder configuration. The given ESerializer must have been created for reading.

Parameters
serializerThe serializer.

◆ Load() [2/2]

void eVision.Easy3D.EPlaneFinder.Load ( string path)

Loads the plane finder configuration. The given ESerializer must have been created for reading.

Parameters
pathThe file path.

◆ Save() [1/2]

void eVision.Easy3D.EPlaneFinder.Save ( eVision.ESerializer serializer)

Saves the plane finder configuration. The given ESerializer must have been created for writing.

Parameters
serializerThe ESerializer object that is written to.

◆ Save() [2/2]

void eVision.Easy3D.EPlaneFinder.Save ( string path)

Saves the plane finder configuration. The given ESerializer must have been created for writing.

Parameters
pathThe file path.

◆ SetNormal() [1/6]

void eVision.Easy3D.EPlaneFinder.SetNormal ( eVision.Easy3D.E3DPlane referencePlane)

Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.

If the angular tolerance is not specified, a default value of 5 degrees is assumed. If the tolerance is specified, the value should be strictly positive and correspond to less than 90 degrees.

Parameters
referencePlaneThe reference plane specifies the expected perpendicular direction.

◆ SetNormal() [2/6]

void eVision.Easy3D.EPlaneFinder.SetNormal ( eVision.Easy3D.E3DPlane referencePlane,
float angleTolerance )

Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.

If the angular tolerance is not specified, a default value of 5 degrees is assumed. If the tolerance is specified, the value should be strictly positive and correspond to less than 90 degrees.

Parameters
referencePlaneThe reference plane specifies the expected perpendicular direction.
angleToleranceThe angle tolerance is the maximum angular deviation around the expected normal (strictly positive and smaller than 90 degrees). It's set to 5 degrees by default.

◆ SetNormal() [3/6]

void eVision.Easy3D.EPlaneFinder.SetNormal ( eVision.Easy3D.E3DPoint normal)

Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.

If the angular tolerance is not specified, a default value of 5 degrees is assumed. If the tolerance is specified, the value should be strictly positive and correspond to less than 90 degrees.

Parameters
normalThe normal vector specifies the expected perpendicular direction of the plane.

◆ SetNormal() [4/6]

void eVision.Easy3D.EPlaneFinder.SetNormal ( eVision.Easy3D.E3DPoint normal,
float angleTolerance )

Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.

If the angular tolerance is not specified, a default value of 5 degrees is assumed. If the tolerance is specified, the value should be strictly positive and correspond to less than 90 degrees.

Parameters
normalThe normal vector specifies the expected perpendicular direction of the plane.
angleToleranceThe angle tolerance is the maximum angular deviation around the expected normal (strictly positive and smaller than 90 degrees). It's set to 5 degrees by default.

◆ SetNormal() [5/6]

void eVision.Easy3D.EPlaneFinder.SetNormal ( float nx,
float ny,
float nz )

Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.

If the angular tolerance is not specified, a default value of 5 degrees is assumed. If the tolerance is specified, the value should be strictly positive and correspond to less than 90 degrees.

Parameters
nxThe x component of the normal vector.
nyThe y component of the normal vector.
nzThe z component of the normal vector.

◆ SetNormal() [6/6]

void eVision.Easy3D.EPlaneFinder.SetNormal ( float nx,
float ny,
float nz,
float angleTolerance )

Sets the expected normal direction and the tolerance around it. These values are used to limit the scope of the plane search.

If the angular tolerance is not specified, a default value of 5 degrees is assumed. If the tolerance is specified, the value should be strictly positive and correspond to less than 90 degrees.

Parameters
nxThe x component of the normal vector.
nyThe y component of the normal vector.
nzThe z component of the normal vector.
angleToleranceThe angle tolerance is the maximum angular deviation around the expected normal (strictly positive and smaller than 90 degrees). It's set to 5 degrees by default.

◆ SetTwoPoints()

void eVision.Easy3D.EPlaneFinder.SetTwoPoints ( eVision.Easy3D.E3DPoint point1,
eVision.Easy3D.E3DPoint point2 )

Sets two points that the plane will be constrained to contain.

Parameters
point1The first point.
point2The second point.

To set 1 point, use the function SetOnePoint

◆ UnsetNormal()

void eVision.Easy3D.EPlaneFinder.UnsetNormal ( )

Unsets the normal vector definition.

◆ UnsetPoints()

void eVision.Easy3D.EPlaneFinder.UnsetPoints ( )

Unsets the 1 or 2 points that the plane is constrained to contain.

◆ UnsetSeed()

void eVision.Easy3D.EPlaneFinder.UnsetSeed ( )

Reset seed to its default state of being randomly initialized.

Deprecated

This function doesn't have any effect.

Deprecated in version 24.6. Scheduled to be removed in version 27.6.

Property Documentation

◆ ExpectedCloudInliersRatio

float eVision.Easy3D.EPlaneFinder.ExpectedCloudInliersRatio
getset

Sets/gets the expected ratio of inliers in the EPointCloud.

This setter/getter is used to access the max of the range, its behavior is the same as SetExpectedCloudInliersRatioRange(EFloatRange(pcExpectedInCloud/2, pcExpectedInCloud)) and GetExpectedCloudInliersRatioRange().GetUpperBound()

◆ ExpectedCloudInliersRatioRange

eVision.EFloatRange eVision.Easy3D.EPlaneFinder.ExpectedCloudInliersRatioRange
getset

Sets/gets the expected ratio of inliers in the EPointCloud.

This is an estimation of the ratio of inliers in the point cloud as a range within ]0, 1[.

If pcExpectedInCloudRange.min is too small, we risk missing the plane. The algorithm throws an error if the best plane has less than pcExpectedInCloudRange.min inliers. The algorithm stops as soon as a model with pcExpectedInCloudRange.max is found.

Increasing pcExpectedInCloudRange.min can increase speed. Decreasing pcExpectedInCloudRange.max can increase speed.

◆ MaxDeviation

float eVision.Easy3D.EPlaneFinder.MaxDeviation
getset

Sets/gets the maximum distance of an inlier to the plane.

◆ NormalTolerance

float eVision.Easy3D.EPlaneFinder.NormalTolerance
get

Returns the angle tolerance around the expected normal (that has been set by EPlaneFinder.SetNormal).

◆ NumberOfPointsAfterDecimation

int eVision.Easy3D.EPlaneFinder.NumberOfPointsAfterDecimation
getset

Sets/gets the number of points surviving the decimation. Using the setter enables the decimation if it wasn't already. if numberOfPointsAfterDecimation is bigger than the point cloud size, no decimation occurs.

◆ NumberOfPointsSet

int eVision.Easy3D.EPlaneFinder.NumberOfPointsSet
get

Returns the number of points set (this will be either 0, 1 or 2).

◆ OnePoint

eVision.Easy3D.E3DPoint eVision.Easy3D.EPlaneFinder.OnePoint
set

Sets one point that the plane will be constrained to contain.

To set 2 points, use the function SetTwoPoints. If two points were previously set, the second one will be removed by this function.

◆ Seed

uint eVision.Easy3D.EPlaneFinder.Seed
getset

Returns the seed (that has been set by EPlaneFinder.Seed).

Deprecated

Users shouldn't have to get the seed.

Deprecated in version 24.6. Scheduled to be removed in version 27.6.