Operator Reference

HALCON Operator Reference / XLD / Features

• HDevelop
• .NET
• Python
• C++
• C

ClassesClasses | | Operators

fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldfit_line_contour_xld (Operator)

fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldfit_line_contour_xld — Approximate XLD contours by line segments.

Signature

fit_line_contour_xld(Contours : : Algorithm, MaxNumPoints, ClippingEndPoints, Iterations, ClippingFactor : RowBegin, ColBegin, RowEnd, ColEnd, Nr, Nc, Dist)

Herror fit_line_contour_xld(const Hobject Contours, const char* Algorithm, const Hlong MaxNumPoints, const Hlong ClippingEndPoints, const Hlong Iterations, double ClippingFactor, double* RowBegin, double* ColBegin, double* RowEnd, double* ColEnd, double* Nr, double* Nc, double* Dist)

Herror T_fit_line_contour_xld(const Hobject Contours, const Htuple Algorithm, const Htuple MaxNumPoints, const Htuple ClippingEndPoints, const Htuple Iterations, const Htuple ClippingFactor, Htuple* RowBegin, Htuple* ColBegin, Htuple* RowEnd, Htuple* ColEnd, Htuple* Nr, Htuple* Nc, Htuple* Dist)

void FitLineContourXld(const HObject& Contours, const HTuple& Algorithm, const HTuple& MaxNumPoints, const HTuple& ClippingEndPoints, const HTuple& Iterations, const HTuple& ClippingFactor, HTuple* RowBegin, HTuple* ColBegin, HTuple* RowEnd, HTuple* ColEnd, HTuple* Nr, HTuple* Nc, HTuple* Dist)

void HXLDCont::FitLineContourXld(const HString& Algorithm, Hlong MaxNumPoints, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, HTuple* RowBegin, HTuple* ColBegin, HTuple* RowEnd, HTuple* ColEnd, HTuple* Nr, HTuple* Nc, HTuple* Dist) const

void HXLDCont::FitLineContourXld(const HString& Algorithm, Hlong MaxNumPoints, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, double* RowBegin, double* ColBegin, double* RowEnd, double* ColEnd, double* Nr, double* Nc, double* Dist) const

void HXLDCont::FitLineContourXld(const char* Algorithm, Hlong MaxNumPoints, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, double* RowBegin, double* ColBegin, double* RowEnd, double* ColEnd, double* Nr, double* Nc, double* Dist) const

void HXLDCont::FitLineContourXld(const wchar_t* Algorithm, Hlong MaxNumPoints, Hlong ClippingEndPoints, Hlong Iterations, double ClippingFactor, double* RowBegin, double* ColBegin, double* RowEnd, double* ColEnd, double* Nr, double* Nc, double* Dist) const   ( Windows only)

static void HOperatorSet.FitLineContourXld(HObject contours, HTuple algorithm, HTuple maxNumPoints, HTuple clippingEndPoints, HTuple iterations, HTuple clippingFactor, out HTuple rowBegin, out HTuple colBegin, out HTuple rowEnd, out HTuple colEnd, out HTuple nr, out HTuple nc, out HTuple dist)

void HXLDCont.FitLineContourXld(string algorithm, int maxNumPoints, int clippingEndPoints, int iterations, double clippingFactor, out HTuple rowBegin, out HTuple colBegin, out HTuple rowEnd, out HTuple colEnd, out HTuple nr, out HTuple nc, out HTuple dist)

void HXLDCont.FitLineContourXld(string algorithm, int maxNumPoints, int clippingEndPoints, int iterations, double clippingFactor, out double rowBegin, out double colBegin, out double rowEnd, out double colEnd, out double nr, out double nc, out double dist)

def fit_line_contour_xld(contours: HObject, algorithm: str, max_num_points: int, clipping_end_points: int, iterations: int, clipping_factor: float) -> Tuple[Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[float]]

def fit_line_contour_xld_s(contours: HObject, algorithm: str, max_num_points: int, clipping_end_points: int, iterations: int, clipping_factor: float) -> Tuple[float, float, float, float, float, float, float]

Description

fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldfit_line_contour_xld approximates the XLD contours ContoursContoursContourscontourscontours by line segments. It does not perform a segmentation of the input contours. Thus, one has to make sure that each contour corresponds to one and only one line segment. The operator returns for each contour the start point (RowBeginRowBeginRowBeginrowBeginrow_begin, ColBeginColBeginColBegincolBegincol_begin), the end point (RowEndRowEndRowEndrowEndrow_end, ColEndColEndColEndcolEndcol_end), and the regression line to the contour given by the normal vector (NrNrNrnrnr, NcNcNcncnc) of the line and its distance DistDistDistdistdist from the origin, i.e., the line equation is given by .

The algorithm used for the fitting of lines 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).

'drop'"drop""drop""drop""drop":

'least squares' line fitting, where outliers are ignored. In particular, all contour points further away from the contour than the mean distance to the regression line multiplied with the ClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (see below) are ignored for the calculation of the undistorted regression line.

'gauss'"gauss""gauss""gauss""gauss":

Weighted 'least squares' line fitting, where the impact of outliers is decreased based on the mean value and the standard deviation of the distances of all contour points from the approximating line.

For 'huber'"huber""huber""huber""huber", 'tukey'"tukey""tukey""tukey""tukey", and 'drop'"drop""drop""drop""drop" a robust error statistics is used to estimate the standard deviation of the distances from the contour points without outliers from the approximating line. The parameter ClippingFactorClippingFactorClippingFactorclippingFactorclipping_factor (a scaling factor for 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 repeated. The parameter IterationsIterationsIterationsiterationsiterations specifies the number of iterations. In the mode 'regression'"regression""regression""regression""regression" this value is 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. In practice, the approach of Tukey is recommended.

To reduce the computational load, the fitting of lines 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 over the contour - are used.

The start point and the end point of a line segment is determined by projecting the first and the last point of the corresponding contour to the approximating line. Due to artifacts in the pre-processing the start and end points of a contour might be faulty. Therefore, it is possible to exclude ClippingEndPointsClippingEndPointsClippingEndPointsclippingEndPointsclipping_end_points points at the beginning and at the end of a contour from the line fitting. However, they are still used for the determination of the start point and the end point of the line segment.

The minimum necessary number of contour points for fitting a line is two. Therefore, it is required that the number of contour points is at least .

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

Parameters

ContoursContoursContourscontourscontours (input_object)  xld_cont(-array) → objectHXLDContHObjectHObjectHobject

Input contours.

AlgorithmAlgorithmAlgorithmalgorithmalgorithm (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Algorithm for the fitting of lines.

Default: 'tukey' "tukey" "tukey" "tukey" "tukey"

List of values: 'drop'"drop""drop""drop""drop", 'gauss'"gauss""gauss""gauss""gauss", '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 >= 2

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

Restriction: ClippingEndPoints >= 0

IterationsIterationsIterationsiterationsiterations (input_control)  integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Maximum number of iterations (unused for 'regression'"regression""regression""regression""regression").

Default: 5

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 'drop'"drop""drop""drop""drop" 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

RowBeginRowBeginRowBeginrowBeginrow_begin (output_control)  line.begin.y(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Row coordinates of the starting points of the line segments.

ColBeginColBeginColBegincolBegincol_begin (output_control)  line.begin.x(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Column coordinates of the starting points of the line segments.

RowEndRowEndRowEndrowEndrow_end (output_control)  line.end.y(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Row coordinates of the end points of the line segments.

ColEndColEndColEndcolEndcol_end (output_control)  line.end.x(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Column coordinates of the end points of the line segments.

NrNrNrnrnr (output_control)  number(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Line parameter: Row coordinate of the normal vector

NcNcNcncnc (output_control)  number(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Line parameter: Column coordinate of the normal vector

DistDistDistdistdist (output_control)  number(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Line parameter: Distance of the line from the origin

Example (HDevelop)

read_image (Image, 'mreut')
edges_sub_pix (Image, Edges, 'lanser2', 0.5, 20, 40)
gen_polygons_xld (Edges, Polygons, 'ramer', 2)
split_contours_xld (Polygons, Contours, 'polygon', 1, 5)
fit_line_contour_xld (Contours, 'regression', -1, 0, 5, 2, RowBegin, \
                      ColBegin, RowEnd, ColEnd, Nr, Nc, Dist)

Example (HDevelop)

read_image (Image, 'mreut')
edges_sub_pix (Image, Edges, 'lanser2', 0.5, 20, 40)
gen_polygons_xld (Edges, Polygons, 'ramer', 2)
split_contours_xld (Polygons, Contours, 'polygon', 1, 5)
fit_line_contour_xld (Contours, 'regression', -1, 0, 5, 2, RowBegin, \
                      ColBegin, RowEnd, ColEnd, Nr, Nc, Dist)

Example (C++)

read_image (Image, 'mreut');
edges_sub_pix (Image, Edges, 'lanser2', 0.5, 20, 40);
gen_polygons_xld (Edges, Polygons, 'ramer', 2);
split_contours_xld (Polygons, Contours, 'polygon', 1, 5);
fit_line_contour_xld (Contours, 'regression', -1, 0, 5, 2, RowBegin,
                      ColBegin, RowEnd, ColEnd, Nr, Nc, Dist);

Example (HDevelop)

read_image (Image, 'mreut')
edges_sub_pix (Image, Edges, 'lanser2', 0.5, 20, 40)
gen_polygons_xld (Edges, Polygons, 'ramer', 2)
split_contours_xld (Polygons, Contours, 'polygon', 1, 5)
fit_line_contour_xld (Contours, 'regression', -1, 0, 5, 2, RowBegin, \
                      ColBegin, RowEnd, ColEnd, Nr, Nc, Dist)

Result

fit_line_contour_xldfit_line_contour_xldFitLineContourXldFitLineContourXldfit_line_contour_xld returns 2 ( H_MSG_TRUE) if all parameter values are correct, and line segments 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 3264 is raised.

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

Possible Successors

disp_linedisp_lineDispLineDispLinedisp_line, line_orientationline_orientationLineOrientationLineOrientationline_orientation

See also

regress_contours_xldregress_contours_xldRegressContoursXldRegressContoursXldregress_contours_xld, get_regress_params_xldget_regress_params_xldGetRegressParamsXldGetRegressParamsXldget_regress_params_xld

Module

Foundation

---

ClassesClasses | | Operators