fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld (Operator)

Name

fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld — Fit rectangles to XLD contours.

Signature

fit_rectangle2_contour_xld(Contours : : Algorithm, MaxNumPoints, MaxClosureDist, ClippingEndPoints, Iterations, ClippingFactor : Row, Column, Phi, Length1, Length2, PointOrder)

Description

fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld fits rectangles to the rectangular XLD contours given by ContoursContoursContoursContourscontourscontours and returns the parameters of the rectangles in RowRowRowRowrowrow, ColumnColumnColumnColumncolumncolumn (center), PhiPhiPhiPhiphiphi (orientation), as well as Length1Length1Length1Length1length1length_1 and Length2Length2Length2Length2length2length_2 (half edge lengths). The angle PhiPhiPhiPhiphiphi is returned in radians and specifies the angle between the horizontal axis and the edge with the half length Length1Length1Length1Length1length1length_1 in the mathematically positive direction (counterclockwise). In addition, the point order of the contour is returned in PointOrderPointOrderPointOrderPointOrderpointOrderpoint_order. PointOrderPointOrderPointOrderPointOrderpointOrderpoint_order = 'positive'"positive""positive""positive""positive""positive" means that the contour is traversed in the mathematically positive direction (counterclockwise).

The algorithm used for the fitting of the rectangles can be selected via AlgorithmAlgorithmAlgorithmAlgorithmalgorithmalgorithm:

'regression'"regression""regression""regression""regression""regression": Standard least-squares line fitting.
'huber'"huber""huber""huber""huber""huber": Weighted least-squares line fitting, where the impact of outliers is decreased based on the approach of Huber (see below).
'tukey'"tukey""tukey""tukey""tukey""tukey": Weighted least-squares line fitting, where outliers are ignored based on the approach of Tukey(see below).

For 'huber'"huber""huber""huber""huber""huber" and 'tukey'"tukey""tukey""tukey""tukey""tukey", a robust error statistics is used to estimate the standard deviation of the distances of the contour points from the approximating sides of the rectangle while ignoring outliers. The standard deviation is computed separately for each side of the rectangle to allow the processing of rectangles whose sides are not exactly perpendicular to each other. The parameter ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (a scaling factor relative to the standard deviation) controls the amount of outliers: The smaller the value chosen for ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor the more outliers are detected. The detection of outliers is iterated. The parameter IterationsIterationsIterationsIterationsiterationsiterations specifies the number of iterations. For AlgorithmAlgorithmAlgorithmAlgorithmalgorithmalgorithm = 'regression'"regression""regression""regression""regression""regression", the values of the last two parameters are ignored. Note that in the approach of Tukey ('tukey'"tukey""tukey""tukey""tukey""tukey"), the outliers are removed before performing the approximation and all other points are weighted, whereas in the approach of Huber ('huber'"huber""huber""huber""huber""huber"), the outliers still have a small influence. Particularly, for outliers the optimization is influenced linearly and for points with a smaller distance it is influenced to the square. For the algebraic approach, all distances of the points influence the optimization to the square and thus are not robust against outliers. In practice, the approach of Tukey is recommended.

To reduce the computational load, the fitting of rectangles can be restricted to a subset of the contour points: If a value other than -1 is assigned to MaxNumPointsMaxNumPointsMaxNumPointsMaxNumPointsmaxNumPointsmax_num_points, only up to MaxNumPointsMaxNumPointsMaxNumPointsMaxNumPointsmaxNumPointsmax_num_points points, uniformly distributed across the contour, are used.

Depending on the processing used to create ContoursContoursContoursContourscontourscontours, the start and end points of a contour may contain positional errors. Therefore, it is possible to exclude ClippingEndPointsClippingEndPointsClippingEndPointsClippingEndPointsclippingEndPointsclipping_end_points points at the beginning and at the end of a contour from the rectangle fitting.

Contours, for which the distance between their start points and their end points is <= MaxClosureDistMaxClosureDistMaxClosureDistMaxClosureDistmaxClosureDistmax_closure_dist are considered to be closed. For closed contours, the end point of the contour is not used for the rectangle fitting because it would receive twice the weight of the remaining points in the fit.

The fitting of the rectangle to the contour is based on finding the correspondence between the contour points and the four sides of the rectangle. To enable a successful fit, there must be at least one point that lies in the interior of the line segment that represents the respective rectangle side, i.e., the point must not lie at the ends of the line segment. Because of this, at least eight contour points are necessary to fit the rectangle. A point is internally assigned to the side of the rectangle to which it has the minimum distance. For this, the currently optimal rectangle parameters, i.e., the parameters used for the current iteration step, are used internally. If no corresponding points are found for at least one side of the rectangle, the rectangle parameters cannot be determined uniquely. In this case, the error 3266 is returned. Because of this, the caller of fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld must ensure that the input contours sufficiently resemble a rectangle. In particular, none of the interior angles of the contour, if the contour was approximated by four lines, should be smaller than 45 degrees or larger than 135 degrees. Because of the assignment of contour points to the closest side of the rectangle this would mean that at least one side of the rectangle would have no corresponding points. Furthermore, ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor should not be chosen too small to avoid that the outlier suppression creates rectangle sides without corresponding contour points. This can only happen for AlgorithmAlgorithmAlgorithmAlgorithmalgorithmalgorithm = 'tukey'"tukey""tukey""tukey""tukey""tukey". If the above conditions are observed, fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld returns highly accurate rectangle parameters. If the outlier suppression according to Tukey is used, fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld can be used to robustly fit rectangles, e.g., to rectangular contours with rounded corners.

Execution Information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Automatically parallelized on tuple level.

Parameters

ContoursContoursContoursContourscontourscontours (input_object) xld_cont(-array) → object

Input contours.

AlgorithmAlgorithmAlgorithmAlgorithmalgorithmalgorithm (input_control) string → (string)

Algorithm for fitting the rectangles.

Default value: 'regression' "regression" "regression" "regression" "regression" "regression"

List of values: 'huber'"huber""huber""huber""huber""huber", 'regression'"regression""regression""regression""regression""regression", 'tukey'"tukey""tukey""tukey""tukey""tukey"

MaxNumPointsMaxNumPointsMaxNumPointsMaxNumPointsmaxNumPointsmax_num_points (input_control) integer → (integer)

Maximum number of contour points used for the computation (-1 for all points).

Default value: -1

Restriction: MaxNumPoints == -1 || MaxNumPoints >= 8

MaxClosureDistMaxClosureDistMaxClosureDistMaxClosureDistmaxClosureDistmax_closure_dist (input_control) real → (real)

Maximum distance between the end points of a contour to be considered as closed.

Default value: 0.0

Restriction: MaxClosureDist >= 0.0

ClippingEndPointsClippingEndPointsClippingEndPointsClippingEndPointsclippingEndPointsclipping_end_points (input_control) integer → (integer)

Number of points at the beginning and at the end of the contours to be ignored for the fitting.

Default value: 0

Suggested values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

Restriction: ClippingEndPoints >= 0

IterationsIterationsIterationsIterationsiterationsiterations (input_control) integer → (integer)

Maximum number of iterations (not used for 'regression'"regression""regression""regression""regression""regression").

Default value: 3

Restriction: Iterations >= 0

ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (input_control) real → (real)

Clipping factor for the elimination of outliers (typical values: 1.0 for 'huber'"huber""huber""huber""huber""huber" and 2.0 for 'tukey'"tukey""tukey""tukey""tukey""tukey").

Default value: 2.0

Suggested values: 1.0, 1.5, 2.0, 2.5, 3.0

Restriction: ClippingFactor > 0

RowRowRowRowrowrow (output_control) rectangle2.center.y(-array) → (real)

Row coordinate of the center of the rectangle.

ColumnColumnColumnColumncolumncolumn (output_control) rectangle2.center.x(-array) → (real)

Column coordinate of the center of the rectangle.

PhiPhiPhiPhiphiphi (output_control) rectangle2.angle.rad(-array) → (real)

Orientation of the main axis of the rectangle [rad].

Length1Length1Length1Length1length1length_1 (output_control) rectangle2.hwidth(-array) → (real)

First radius (half length) of the rectangle.

Length2Length2Length2Length2length2length_2 (output_control) rectangle2.hheight(-array) → (real)

Second radius (half width) of the rectangle.

PointOrderPointOrderPointOrderPointOrderpointOrderpoint_order (output_control) string(-array) → (string)

Point order of the contour.

List of values: 'negative'"negative""negative""negative""negative""negative", 'positive'"positive""positive""positive""positive""positive"

Result

fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld returns 2 (H_MSG_TRUE) if all parameter values are correct, and rectangles could be fitted to the input contours. If the input is empty the behavior can be set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>). If necessary, an exception is raised. If the parameter ClippingFactorClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor is chosen too small, i.e., all points are classified as outliers, the error 3266 is raised. If no points could be found for at least one side of the rectangle, the error 3266 is raised as well.