lines_colorlines_colorLinesColorLinesColorlines_color (Operator)

Name

lines_colorlines_colorLinesColorLinesColorlines_color — Detect color lines and their width.

Signature

lines_color(Image : Lines : Sigma, Low, High, ExtractWidth, CompleteJunctions : )

Herror lines_color(const Hobject Image, Hobject* Lines, double Sigma, double Low, double High, const char* ExtractWidth, const char* CompleteJunctions)

Herror T_lines_color(const Hobject Image, Hobject* Lines, const Htuple Sigma, const Htuple Low, const Htuple High, const Htuple ExtractWidth, const Htuple CompleteJunctions)

void LinesColor(const HObject& Image, HObject* Lines, const HTuple& Sigma, const HTuple& Low, const HTuple& High, const HTuple& ExtractWidth, const HTuple& CompleteJunctions)

HXLDCont HImage::LinesColor(const HTuple& Sigma, const HTuple& Low, const HTuple& High, const HString& ExtractWidth, const HString& CompleteJunctions) const

HXLDCont HImage::LinesColor(double Sigma, double Low, double High, const HString& ExtractWidth, const HString& CompleteJunctions) const

HXLDCont HImage::LinesColor(double Sigma, double Low, double High, const char* ExtractWidth, const char* CompleteJunctions) const

HXLDCont HImage::LinesColor(double Sigma, double Low, double High, const wchar_t* ExtractWidth, const wchar_t* CompleteJunctions) const   (Windows only)

static void HOperatorSet.LinesColor(HObject image, out HObject lines, HTuple sigma, HTuple low, HTuple high, HTuple extractWidth, HTuple completeJunctions)

HXLDCont HImage.LinesColor(HTuple sigma, HTuple low, HTuple high, string extractWidth, string completeJunctions)

HXLDCont HImage.LinesColor(double sigma, double low, double high, string extractWidth, string completeJunctions)

def lines_color(image: HObject, sigma: Union[float, int], low: Union[float, int], high: Union[float, int], extract_width: str, complete_junctions: str) -> HObject

Description

lines_colorlines_colorLinesColorLinesColorLinesColorlines_color extracts color lines from the input image ImageImageImageImageimageimage and returns the extracted lines as subpixel precise XLD-contours in LinesLinesLinesLineslineslines. Color lines are defined as dark lines in the amplitude image of the color edge filter (see edges_coloredges_colorEdgesColorEdgesColorEdgesColoredges_color). lines_colorlines_colorLinesColorLinesColorLinesColorlines_color always uses the Canny color edge filter. Hence, the required partial derivatives of the image are always computed by convolution with the respective partial derivatives of the Gaussian smoothing masks (see derivate_gaussderivate_gaussDerivateGaussDerivateGaussDerivateGaussderivate_gauss). The corresponding smoothing is determined by the parameter SigmaSigmaSigmaSigmasigmasigma.

By defining color lines as dark lines in the amplitude image, in contrast to lines_gausslines_gaussLinesGaussLinesGaussLinesGausslines_gauss, for single-channel images no distinction is made whether the lines are darker or brighter than their surroundings. Furthermore, lines_colorlines_colorLinesColorLinesColorLinesColorlines_color also returns staircase lines, i.e., lines for which the gray value of the lines lies between the gray values in the surrounding area to the left and right sides of the line. In multi-channel images, the above definition allows each channel to have a different line type. For example, in a three-channel image the first channel may have a dark line, the second channel a bright line, and the third channel a staircase line at the same position.

If ExtractWidthExtractWidthExtractWidthExtractWidthextractWidthextract_width is set to 'true'"true""true""true""true""true" the line width is extracted for each line point. Because the line extractor is unable to extract certain junctions because of differential geometric reasons, it tries to extract these by different means if CompleteJunctionsCompleteJunctionsCompleteJunctionsCompleteJunctionscompleteJunctionscomplete_junctions is set to 'true'"true""true""true""true""true".

lines_colorlines_colorLinesColorLinesColorLinesColorlines_color links the line points into lines by using an algorithm similar to a hysteresis threshold operation, which is also used in lines_gausslines_gaussLinesGaussLinesGaussLinesGausslines_gauss and edges_color_sub_pixedges_color_sub_pixEdgesColorSubPixEdgesColorSubPixEdgesColorSubPixedges_color_sub_pix. Points with an amplitude larger than HighHighHighHighhighhigh are immediately accepted as belonging to a line, while points with an amplitude smaller than LowLowLowLowlowlow are rejected. All other points are accepted as lines if they are connected to accepted line points (see also lines_gausslines_gaussLinesGaussLinesGaussLinesGausslines_gauss). Here, amplitude means the line amplitude of the dark line (see lines_gausslines_gaussLinesGaussLinesGaussLinesGausslines_gauss and lines_facetlines_facetLinesFacetLinesFacetLinesFacetlines_facet). This value corresponds to the third directional derivative of the smoothed input image in the direction perpendicular to the line.

For the choice of the thresholds HighHighHighHighhighhigh and LowLowLowLowlowlow one has to keep in mind that the third directional derivative depends on the amplitude and width of the line as well as the choice of SigmaSigmaSigmaSigmasigmasigma. The value of the third derivative depends linearly on the amplitude, i.e., the larger the amplitude, the larger the response. For the width of the line there is an inverse dependence: The wider the line is, the smaller the response gets. This holds analogously for the dependence on SigmaSigmaSigmaSigmasigmasigma: The larger SigmaSigmaSigmaSigmasigmasigma is chosen, the smaller the second derivative will be. This means that for larger smoothing correspondingly smaller values for HighHighHighHighhighhigh and LowLowLowLowlowlow should be chosen.

The extracted lines are returned in a topologically sound data structure in LinesLinesLinesLineslineslines. This means that lines are correctly split at junction points.

lines_colorlines_colorLinesColorLinesColorLinesColorlines_color defines the following attributes for each line point if ExtractWidthExtractWidthExtractWidthExtractWidthextractWidthextract_width was set to 'false'"false""false""false""false""false":

If ExtractWidthExtractWidthExtractWidthExtractWidthextractWidthextract_width was set to 'true'"true""true""true""true""true", additionally the following attributes are defined:

Use get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldGetContourAttribXldGetContourAttribXldget_contour_attrib_xld to obtain attribute values. See the operator reference of get_contour_attrib_xldget_contour_attrib_xldGetContourAttribXldGetContourAttribXldGetContourAttribXldget_contour_attrib_xld for further information about contour attributes.

Attention

In general, but in particular if the line width is to be extracted, should be selected, where w is the width (half the diameter) of the lines in the image. As the lowest allowable value must be selected. If, for example, lines with a width of 4 pixels (diameter 8 pixels) are to be extracted, should be selected. If it is expected that staircase lines are present in at least one channel, and if such lines should be extracted, in addition to the above restriction, should be selected. This is necessary because staircase lines turn into normal step edges for large amounts of smoothing, and therefore no longer appear as dark lines in the amplitude image of the color edge filter.

Note that filter operators may return unexpected results if an image with a reduced domain is used as input. Please refer to the chapter Filters.

Execution Information

Parameters

ImageImageImageImageimageimage (input_object)  (multichannel-)image objectHImageHObjectHImageHobject (byte / uint2)

Input image.

LinesLinesLinesLineslineslines (output_object)  xld_cont-array objectHXLDContHObjectHXLDContHobject *

Extracted lines.

SigmaSigmaSigmaSigmasigmasigma (input_control)  number HTupleUnion[float, int]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Amount of Gaussian smoothing to be applied.

Default value: 1.5

Suggested values: 1, 1.2, 1.5, 1.8, 2, 2.5, 3, 4, 5

Recommended increment: 0.1

Restriction: Sigma > 0.0

LowLowLowLowlowlow (input_control)  number HTupleUnion[float, int]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Lower threshold for the hysteresis threshold operation.

Default value: 3

Suggested values: 0, 0.5, 1, 2, 3, 4, 5, 8, 10

Typical range of values: 0 ≤ Low Low Low Low low low

Recommended increment: 0.5

HighHighHighHighhighhigh (input_control)  number HTupleUnion[float, int]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Upper threshold for the hysteresis threshold operation.

Default value: 8

Suggested values: 0, 0.5, 1, 2, 3, 4, 5, 8, 10, 12, 15, 18, 20, 25

Typical range of values: 0 ≤ High High High High high high

Recommended increment: 0.5

Restriction: High >= Low

ExtractWidthExtractWidthExtractWidthExtractWidthextractWidthextract_width (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Should the line width be extracted?

Default value: 'true' "true" "true" "true" "true" "true"

List of values: 'false'"false""false""false""false""false", 'true'"true""true""true""true""true"

CompleteJunctionsCompleteJunctionsCompleteJunctionsCompleteJunctionscompleteJunctionscomplete_junctions (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Should junctions be added where they cannot be extracted?

Default value: 'true' "true" "true" "true" "true" "true"

List of values: 'false'"false""false""false""false""false", 'true'"true""true""true""true""true"

Complexity

The amount of temporary memory required is dependent on the height H of the domain of ImageImageImageImageimageimage.

Result

lines_colorlines_colorLinesColorLinesColorLinesColorlines_color returns 2 (H_MSG_TRUE) if all parameters are correct and no error occurs during execution. 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.

Possible Successors

gen_polygons_xldgen_polygons_xldGenPolygonsXldGenPolygonsXldGenPolygonsXldgen_polygons_xld

Alternatives

lines_gausslines_gaussLinesGaussLinesGaussLinesGausslines_gauss, lines_facetlines_facetLinesFacetLinesFacetLinesFacetlines_facet

See also

edges_coloredges_colorEdgesColorEdgesColorEdgesColoredges_color, edges_color_sub_pixedges_color_sub_pixEdgesColorSubPixEdgesColorSubPixEdgesColorSubPixedges_color_sub_pix

References

C. Steger: “Subpixel-Precise Extraction of Lines and Edges”; International Archives of Photogrammetry and Remote Sensing, vol. XXXIII, part B3; pp. 141-156; 2000.
C. Steger: “An Unbiased Detector of Curvilinear Structures”; IEEE Transactions on Pattern Analysis and Machine Intelligence; vol. 20, no. 2; pp. 113-125; 1998.
C. Steger: “Unbiased Extraction of Curvilinear Structures from 2D and 3D Images”; Herbert Utz Verlag, München; 1998.

Module

2D Metrology