You are here: Start » Function Reference » Shape Adjustment » AdjustPathArrayToEdges

AdjustPathArrayToEdges

Header:	AVL.h
Namespace:	avl

Translates, rotates and scales the given contour set to the edges of the input image with subpixel precision.

Syntax

void avl::AdjustPathArrayToEdges
(
	const avl::Image& inImage,
	const atl::Array< avl::Path >& inPaths,
	atl::Optional<float> inPointSpacing,
	atl::Optional<const avl::CoordinateSystem2D&> inAlignment,
	float inAttractionRadius,
	avl::AdjustmentMetric::Type inAdjustmentMetric,
	bool inAdjustTranslation,
	bool inAdjustRotation,
	bool inAdjustScale,
	int inIterationCount,
	float inBaseGradient,
	atl::Array< avl::Path >& outAdjustedPaths,
	avl::CoordinateSystem2D& outAlignment,
	atl::Array<avl::Segment2D>& diagAttractionVectors
)

Parameters

Name	Type	Range	Default	Description
inImage	const Image&			Input image.
inPaths	const Array< Path >&			Paths to be adjusted. For sparse, synthetic paths the inPointSpacing needs to be specified.
inPointSpacing	Optional<float>	1.0 -	NIL	If set, sampling points of the input path will be equidistant with specified spacing. Useful for increasing density of synthetic, sparse paths.
inAlignment	Optional<const CoordinateSystem2D&>		NIL	Alignment to be corrected, usually connects to outObject.Alignment of LocateObjects filter.
inAttractionRadius	float	0.1 -	2.0f	Expected initial distance between inPaths and edges of the input image.
inAdjustmentMetric	AdjustmentMetric::Type		SegmentDistance	Metric used for path attraction. The SegmentDistance minimizes distances along path normal vectors, and thus adjustment is more accurate. PointDistance_* minimize euclidean distance, adjustment tends to be more stable.
inAdjustTranslation	bool		True	Compute the translation part of adjustment transform. Must be true when using AttractPathTangents estimation method.
inAdjustRotation	bool		True	Compute the rotation part of adjustment transform.
inAdjustScale	bool		False	Compute the scale part of adjustment transform.
inIterationCount	int	0 - 100	6	Number of iterations of internal adjustment algorithm.
inBaseGradient	float	0.1 -	1.0f	Threshold for suppression of weak input image gradients. Increase for very noisy images.
outAdjustedPaths	Array< Path >&			Adjusted output paths.
outAlignment	CoordinateSystem2D&			Corrected alignment - the inAlignment input modified with estimated adjustment parameters.
diagAttractionVectors	Array<Segment2D>&			Attraction vectors from first iteration.

Requirements

For input inImage only pixel formats are supported: 1⨯uint8, 2⨯uint8, 3⨯uint8, 4⨯uint8.

Read more about pixel formats in Image documentation.

Hints

In order to use the filter to fine-tune the results of template matching, connect the outObjectEdges output of the template matching filter to the inPaths input, outObject.Alignment to inAlignment and the same input image to the inImage input.
When using template matching with AdjustPathArrayToEdges filter, you may try to speed up template matching by increasing its inMinPyramidLevel parameter. The potential loss of template matching precision should be mitigated by the AdjustPathArrayToEdges filter.
The inAttractionRadius should be set to the average initial distance between inPaths and edges of the input image. Although the filter tolerance to this parameter is high, setting it too low may result in adjustment failure, setting it too high will result in reduced accuracy. The parameter directly influences attraction vectors, which may be observed via diagnostic output diagAttractionVectors.
SegmentDistance is the default value of inAdjustmentMetric parameter and usually it is the best choice. However, in some special cases one should consider other options:
- inImage contains glares – the PointDistance_Median method may perform better as the median error metric is more robust than least squares.
- inPaths is a degenerate path array, such as a 1D straight line – the SegmentDistance could fail, the PointDistance_* methods may work.
Please note that you need to increase inIterationCount to 10 when using PointDistance_* adjustment metrices, as the default value of 6 is fine-tuned to the SegmentDistance metric.
Increasing inIterationCount may result in more accurate results, however gains are diminishing quickly. The only downside of increasing inIterationCount in higher computation time.
Sparse paths - with a low amount of points - need to be densened to obtain acceptable accuracy and stability of the filter. Set the inPointSpacing parameter to a desired distance between consecutive path points.
For paths with large amount of points, the filter execution may be considerably accelerated without perceivable influence on the accuracy. Set the inPointSpacing parameter to a value higher than average spacing of input paths.
Noise on the input image may introduce false adjustment vectors, reducing accuracy. To mitigate the influence of noise, the inBaseGradient parameter may be used, which governs suppression of weak input image gradients. In order to tune the parameter, observe the diagAttractionVectors output. Note that its better to have some noise in attraction vectors directions than to considerably reduce their strength.

Examples

Improving results of template matching. Blue – input paths, orange – attraction vectors, green – corrected paths.

Errors

List of possible exceptions:

Error type	Description
DomainError	ComputeTranslation must be enabled for SegmentDistance adjustment metric
DomainError	Not supported inImage pixel format in AdjustPathArrayToEdges.