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)
Herror fit_rectangle2_contour_xld(const Hobject Contours, const char* Algorithm, const Hlong MaxNumPoints, double MaxClosureDist, const Hlong ClippingEndPoints, const Hlong Iterations, double ClippingFactor, double* Row, double* Column, double* Phi, double* Length1, double* Length2, char* PointOrder)
Herror T_fit_rectangle2_contour_xld(const Hobject Contours, const Htuple Algorithm, const Htuple MaxNumPoints, const Htuple MaxClosureDist, const Htuple ClippingEndPoints, const Htuple Iterations, const Htuple ClippingFactor, Htuple* Row, Htuple* Column, Htuple* Phi, Htuple* Length1, Htuple* Length2, Htuple* PointOrder)
void FitRectangle2ContourXld(const HObject& Contours, const HTuple& Algorithm, const HTuple& MaxNumPoints, const HTuple& MaxClosureDist, const HTuple& ClippingEndPoints, const HTuple& Iterations, const HTuple& ClippingFactor, HTuple* Row, HTuple* Column, HTuple* Phi, HTuple* Length1, HTuple* Length2, HTuple* PointOrder)
void HXLDCont::FitRectangle2ContourXld(const HString& Algorithm, Hlong MaxNumPoints, double MaxClosureDist, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, HTuple* Row, HTuple* Column, HTuple* Phi, HTuple* Length1, HTuple* Length2, HTuple* PointOrder) const
void HXLDCont::FitRectangle2ContourXld(const HString& Algorithm, Hlong MaxNumPoints, double MaxClosureDist, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, double* Row, double* Column, double* Phi, double* Length1, double* Length2, HString* PointOrder) const
void HXLDCont::FitRectangle2ContourXld(const char* Algorithm, Hlong MaxNumPoints, double MaxClosureDist, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, double* Row, double* Column, double* Phi, double* Length1, double* Length2, HString* PointOrder) const
void HXLDCont::FitRectangle2ContourXld(const wchar_t* Algorithm, Hlong MaxNumPoints, double MaxClosureDist, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, double* Row, double* Column, double* Phi, double* Length1, double* Length2, HString* PointOrder) const
(
Windows only)
static void HOperatorSet.FitRectangle2ContourXld(HObject contours, HTuple algorithm, HTuple maxNumPoints, HTuple maxClosureDist, HTuple clippingEndPoints, HTuple iterations, HTuple clippingFactor, out HTuple row, out HTuple column, out HTuple phi, out HTuple length1, out HTuple length2, out HTuple pointOrder)
void HXLDCont.FitRectangle2ContourXld(string algorithm, int maxNumPoints, double maxClosureDist, int clippingEndPoints, int iterations, double clippingFactor, out HTuple row, out HTuple column, out HTuple phi, out HTuple length1, out HTuple length2, out HTuple pointOrder)
void HXLDCont.FitRectangle2ContourXld(string algorithm, int maxNumPoints, double maxClosureDist, int clippingEndPoints, int iterations, double clippingFactor, out double row, out double column, out double phi, out double length1, out double length2, out string pointOrder)
def fit_rectangle2_contour_xld(contours: HObject, algorithm: str, max_num_points: int, max_closure_dist: float, clipping_end_points: int, iterations: int, clipping_factor: float) -> Tuple[Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[str]]
def fit_rectangle2_contour_xld_s(contours: HObject, algorithm: str, max_num_points: int, max_closure_dist: float, clipping_end_points: int, iterations: int, clipping_factor: float) -> Tuple[float, float, float, float, float, str]
Description
fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld fits rectangles to the
rectangular XLD contours given by ContoursContoursContourscontourscontours and returns the
parameters of the rectangles in RowRowRowrowrow, ColumnColumnColumncolumncolumn
(center), PhiPhiPhiphiphi (orientation), as well as Length1Length1Length1length1length_1
and Length2Length2Length2length2length_2 (half edge lengths). The angle PhiPhiPhiphiphi is
returned in radians and specifies the angle between the horizontal
axis and the edge with the half length Length1Length1Length1length1length_1 in the
mathematically positive direction (counterclockwise). In addition,
the point order of the contour is returned in PointOrderPointOrderPointOrderpointOrderpoint_order.
PointOrderPointOrderPointOrderpointOrderpoint_order = '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 AlgorithmAlgorithmAlgorithmalgorithmalgorithm:
- 'regression'"regression""regression""regression""regression"
-
Standard least-squares line fitting.
- '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"
Weighted least-squares line fitting, where
outliers are ignored based on the approach of Tukey(see below).
For 'huber'"huber""huber""huber""huber" and '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 ClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (a scaling factor
relative to the standard deviation) controls the amount of outliers:
The smaller the value chosen for ClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor the more outliers
are detected. The detection of outliers is iterated. The parameter
IterationsIterationsIterationsiterationsiterations specifies the number of iterations. For
AlgorithmAlgorithmAlgorithmalgorithmalgorithm = '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"),
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"),
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 MaxNumPointsMaxNumPointsMaxNumPointsmaxNumPointsmax_num_points, only up to
MaxNumPointsMaxNumPointsMaxNumPointsmaxNumPointsmax_num_points points, uniformly distributed across the
contour, are used.
Depending on the processing used to create ContoursContoursContourscontourscontours, the
start and end points of a contour may contain positional errors.
Therefore, it is possible to exclude ClippingEndPointsClippingEndPointsClippingEndPointsclippingEndPointsclipping_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 <= MaxClosureDistMaxClosureDistMaxClosureDistmaxClosureDistmax_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_xldFitRectangle2ContourXldFitRectangle2ContourXldfit_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, ClippingFactorClippingFactorClippingFactorclippingFactorclipping_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 AlgorithmAlgorithmAlgorithmalgorithmalgorithm = 'tukey'"tukey""tukey""tukey""tukey". If the above
conditions are observed, fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldfit_rectangle2_contour_xld returns
highly accurate rectangle parameters. If the outlier suppression
according to Tukey is used, fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldfit_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
ContoursContoursContourscontourscontours (input_object) xld_cont(-array) → objectHXLDContHObjectHObjectHobject
Input contours.
AlgorithmAlgorithmAlgorithmalgorithmalgorithm (input_control) string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)
Algorithm for fitting the rectangles.
Default:
'regression'
"regression"
"regression"
"regression"
"regression"
List of values:
'huber'"huber""huber""huber""huber", 'regression'"regression""regression""regression""regression", 'tukey'"tukey""tukey""tukey""tukey"
MaxNumPointsMaxNumPointsMaxNumPointsmaxNumPointsmax_num_points (input_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Maximum number of contour points used for the
computation (-1 for all points).
Default:
-1
Restriction:
MaxNumPoints == -1 || MaxNumPoints >= 8
MaxClosureDistMaxClosureDistMaxClosureDistmaxClosureDistmax_closure_dist (input_control) real → HTuplefloatHTupleHtuple (real) (double) (double) (double)
Maximum distance between the end points of a
contour to be considered as closed.
Default:
0.0
Restriction:
MaxClosureDist >= 0.0
ClippingEndPointsClippingEndPointsClippingEndPointsclippingEndPointsclipping_end_points (input_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Number of points at the beginning and at the end of the
contours to be ignored for the fitting.
Default:
0
Suggested values:
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Restriction:
ClippingEndPoints >= 0
IterationsIterationsIterationsiterationsiterations (input_control) integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)
Maximum number of iterations
(not used for 'regression'"regression""regression""regression""regression").
Default:
3
Restriction:
Iterations >= 0
ClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (input_control) real → HTuplefloatHTupleHtuple (real) (double) (double) (double)
Clipping factor for the elimination of outliers
(typical values: 1.0 for 'huber'"huber""huber""huber""huber" and
2.0 for 'tukey'"tukey""tukey""tukey""tukey").
Default:
2.0
Suggested values:
1.0, 1.5, 2.0, 2.5, 3.0
Restriction:
ClippingFactor > 0
RowRowRowrowrow (output_control) rectangle2.center.y(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)
Row coordinate of the center of the rectangle.
ColumnColumnColumncolumncolumn (output_control) rectangle2.center.x(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)
Column coordinate of the center of the rectangle.
PhiPhiPhiphiphi (output_control) rectangle2.angle.rad(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)
Orientation of the main axis of the rectangle [rad].
Length1Length1Length1length1length_1 (output_control) rectangle2.hwidth(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)
First radius (half length) of the rectangle.
Length2Length2Length2length2length_2 (output_control) rectangle2.hheight(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)
Second radius (half width) of the rectangle.
PointOrderPointOrderPointOrderpointOrderpoint_order (output_control) string(-array) → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)
Point order of the contour.
List of values:
'negative'"negative""negative""negative""negative", 'positive'"positive""positive""positive""positive"
Result
fit_rectangle2_contour_xldfit_rectangle2_contour_xldFitRectangle2ContourXldFitRectangle2ContourXldfit_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>)set_system("no_object_result",<Result>). If necessary, an
exception is raised. If the parameter ClippingFactorClippingFactorClippingFactorclippingFactorclipping_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.
Possible Predecessors
gen_contours_skeleton_xldgen_contours_skeleton_xldGenContoursSkeletonXldGenContoursSkeletonXldgen_contours_skeleton_xld,
lines_gausslines_gaussLinesGaussLinesGausslines_gauss,
lines_facetlines_facetLinesFacetLinesFacetlines_facet,
edges_sub_pixedges_sub_pixEdgesSubPixEdgesSubPixedges_sub_pix,
smooth_contours_xldsmooth_contours_xldSmoothContoursXldSmoothContoursXldsmooth_contours_xld,
union_collinear_contours_xldunion_collinear_contours_xldUnionCollinearContoursXldUnionCollinearContoursXldunion_collinear_contours_xld,
union_collinear_contours_ext_xldunion_collinear_contours_ext_xldUnionCollinearContoursExtXldUnionCollinearContoursExtXldunion_collinear_contours_ext_xld,
union_adjacent_contours_xldunion_adjacent_contours_xldUnionAdjacentContoursXldUnionAdjacentContoursXldunion_adjacent_contours_xld
Possible Successors
dist_rectangle2_contour_points_xlddist_rectangle2_contour_points_xldDistRectangle2ContourPointsXldDistRectangle2ContourPointsXlddist_rectangle2_contour_points_xld,
gen_rectangle2_contour_xldgen_rectangle2_contour_xldGenRectangle2ContourXldGenRectangle2ContourXldgen_rectangle2_contour_xld
Alternatives
smallest_rectangle2_xldsmallest_rectangle2_xldSmallestRectangle2XldSmallestRectangle2Xldsmallest_rectangle2_xld
See also
fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldfit_line_contour_xld,
fit_circle_contour_xldfit_circle_contour_xldFitCircleContourXldFitCircleContourXldfit_circle_contour_xld,
fit_ellipse_contour_xldfit_ellipse_contour_xldFitEllipseContourXldFitEllipseContourXldfit_ellipse_contour_xld
Module
Foundation