You are here: Start » Function Reference » Path » Path Combinators » JoinAdjacentPaths

JoinAdjacentPaths

Header:	AVL.h
Namespace:	avl
Module:	FoundationPro

Joins those paths of an array which endpoints lie near enough.

Syntax

void avl::JoinAdjacentPaths
(
	const atl::Array<avl::Path>& inPaths,
	float inMaxDistance,
	float inMaxAngle,
	atl::Optional<float> inMaxDeviation,
	float inExcessTrim,
	atl::Optional<float> inEndingLength,
	avl::PathJoiningMethod::Type inJoiningMethod,
	avl::PathJoiningAngleMeasure::Type inAngleMeasure,
	bool inIgnorePathEndsOrder,
	bool inAllowCycles,
	float inMinPathLength,
	atl::Array<avl::Path>& outPaths,
	atl::Optional<atl::Array<avl::Path>&> outMatchedPieces = atl::NIL
)

Parameters

Name	Type	Range	Default	Description
inPaths	const Array<Path>&
inMaxDistance	float	0.0 -	10.0f	Maximal distance between paths that can be joined
inMaxAngle	float	0.0 - 180.0	30.0f	Maximal allowed angle between paths being joined
inMaxDeviation	Optional<float>	0.0 -	NIL	Maximal allowed thickness of a minimal stripe containing both paths being joined
inExcessTrim	float	0.0 -		Length of the part of each path to be removed from its both sides
inEndingLength	Optional<float>	0.0 -	0.0f	Determines the length of the path end used for path angle computing
inJoiningMethod	PathJoiningMethod::Type		AddBridge	Determines a method to join two paths in one
inAngleMeasure	PathJoiningAngleMeasure::Type		InputPathOrientation	Determines a method to measure the angle between two input paths
inIgnorePathEndsOrder	bool		True	If set to false, only the end of a path can be joined with the begin of another path
inAllowCycles	bool		True	Determines if cycles can be created during joining process
inMinPathLength	float	0.0 -	0.0f	Minimal length of a path
outPaths	Array<Path>&
outMatchedPieces	Optional<Array<Path>&>		NIL	Input paths that have been joined with another path

Optional Outputs

The computation of following outputs can be switched off by passing value atl::NIL to these parameters: outMatchedPieces.

Description

The operation repeatedly connects the pair of endpoints of open paths of an array until no such pair can be connected. If an endpoint can be joined with more than one another, the endpoint which generates smallest joining value is chosen. The joining value is computed by combining distance between endpoints being joined, their angle difference and their deviation value. An endpoint can be joined with another one in its vicinity only if the distance between them is not greater than inMaxDistance. Their angle difference, which is computed in one of available ways depending on inAngleMeasure value, cannot be greater than inMaxAngle. Their deviation value, which is the thickness of a minimal stripe containing both path endings being joined, cannot exceed inMaxDeviation.

The deviation value for two orange segments is the distance between two parallel blue lines.

Before joining process begins, the input paths are shortened by inExcessTrim on both their ends. The parameter makes it possible to use the filter for paths that can be a bit curly on their ends.

Only orange part of the path takes part in joining process. The curly blue path ending is removed by inExcessTrim parameter.

While joining takes place, the inEndingLength parameter determines what part of the path ending is used to determine the angle between two paths. If it is set to Nil, the segment connecting path begin and path end is decisive.

The last orange segment is taken into account while determining angle between two paths. The omitted blue path ending has length inEndingLength.

There are also two flags controlling the joining process. If the inIgnorePathEndsOrder is set, a path begin can also be joined with another path begin and a path end with another path end. Otherwise a path begin can be joined with a path end only. The inAllowCycles parameter determines if a cycle is allowed to emerge during joining. Finally, after the joining phase paths that are shorter than inMinPathLength are removed from the final results.

Examples

JoinAdjacentPaths run on the sample path array with inMaxDistance = 25.