Cog3DRangeImagePlaneEstimator.Execute Method

Cog3DRangeImagePlaneEstimator Execute Method

Cognex VisionPro

Perform plane fitting on the supplied range image.

Namespace: Cognex.VisionPro3D
Assembly: Cognex.VisionPro3D (in Cognex.VisionPro3D.dll) Version: 65.1.0.0

Syntax

public Cog3DRangeImagePlaneEstimatorResult Execute(
	ICogImage image,
	ICogRegion region
)

public Cog3DRangeImagePlaneEstimatorResult Execute(
	ICogImage image,
	ICogRegion region
)

Public Function Execute ( 
	image As ICogImage,
	region As ICogRegion
) As Cog3DRangeImagePlaneEstimatorResult

Public Function Execute ( 
	image As ICogImage,
	region As ICogRegion
) As Cog3DRangeImagePlaneEstimatorResult

public:
Cog3DRangeImagePlaneEstimatorResult^ Execute(
	ICogImage^ image, 
	ICogRegion^ region
)

public:
Cog3DRangeImagePlaneEstimatorResult^ Execute(
	ICogImage^ image, 
	ICogRegion^ region
)

Parameters

image: Type: Cognex.VisionPro ICogImage
The input range image.

region: Type: Cognex.VisionPro ICogRegion
An optional two dimensional region of interest used only if FitMethod is set to Area. May be null. If used, this region limits the input range image pixels that contribute to the fit plane. When used, this region is applied in accordance with the RegionMode, which defaults to PixelAlignBoundingBoxAdjustMask. If no region is supplied, the entire input range image is processed.

Return Value

Type: Cog3DRangeImagePlaneEstimatorResult
The plane (defined in SelectedSpaceName3D), the RMS error, and the number of points used to fit the plane.

Exceptions

Exception	Condition
CogImageBadTypeException	If the supplied input image argument is not a CogImage16Range.
CogOperatorNoInputImageException	If the supplied input image argument is null.
CogImageNoPixelsException	If the supplied input image is unbound.
ArgumentException	If the transform is not linear.
ArgumentException	If region is outside of the image.
Cog3DException	There are fewer than 3 points in the list of points that correspond to visible pixel locations in the image, or the combination of the input mask and visible pixel mask contains less than 3 care/visible pixels.
Cog3DException	The list of points doesn't include 3 non-collinear points.
Cog3DException	The number of input points is fewer than 3.
Cog3DException	The pixel location of one or more points in the list of input points falls outside of the image.
Cog3DException	The RMS residual was above the threshold specified in the runtime params.
Cog3DException	The tool was unable to compute the plane.
CogTimeoutExpiredException	The operation took longer than the enabled Timeout value.
CogSecurityViolationException	If licensing for this operator cannot be confirmed.

Remarks

There are two key aspects to range image plane estimation:

Sampling
Fitting

The sampling mechanism is specified by the FitMethod property, and can be either Area or Points.

When FitMethod is Area, input range image pixels that meet the following criteria are evaluated when fitting the plane:

Must be contained within the 2D region of interest. No region means use all of the input image.
Must be marked as "Care" if an InputImageMask is provided.
Must be marked as "Visible" in the range image's visible pixel mask.

When FitMethod is Points, however, both the region of interest and the InputImageMask are ignored. Instead, pixels are sampled from the input range image at the user specified point locations. As above, pixels that are not marked "Visible" are ignored. But in this scenario, input range image pixels are identified for evaluation based upon ZLookupMethod, possibly in conjuction with NeighborhoodSizeXInPixels and NeighborhoodSizeYInPixels.

The fitting mechanism is specified by RobustFitParameters' RobustFitTechnique property, and may be either AllPoints or AdaptiveRANSAC. The default AllPoints fitting mechanism will fit a plane to all sampled points. The AdaptiveRANSAC mechanism, on the other hand, will adaptively attempt to ignore "outlier" points. While the AdaptiveRANSAC mechanism can produce much more robust answers in the presence of noisy input data, it can also take a long time to run.