path.tangentAtLength(length [, opt])
Return a line tangent to the path at point that lies length
away from the beginning of the path.
If negative length
is provided, the algorithm starts looking from the end of the path. If length
is higher than path length, a line tangent to the closest valid path endpoint is returned instead. If point at length
is a point of discontinuity (e.g. it is a point shared by two Lineto segments with different slopes), the tangent line is constructed for the earlier segment (i.e. the segment closer to the beginning of the path).
The tangent line starts at the specified point. The direction from start
to end
is the same as the direction of the path segment at the specified point.
The algorithm skips over segments that are not differentiable. This includes all invisible segments (e.g. Moveto segments) and visible segments with zero length. If the path contains no valid segments, null
is returned. If the path has no segments at all, null
is returned, as well. The segment.isDifferentiable()
functions may be used to determine whether a given segment is valid; the path.isDifferentiable()
function may be used to determine whether the path contains at least one valid segment.
One valid segment is identified which contains the point at length
. Finding the desired point is straightforward for linear segments (see line.pointAtLength()
for reference). Finding the desired point in curved segments is more complex, as illustrated by the curve.pointAtLength()
function. A tangent line is then obtained that touches the path at the identified point (see curve.tangent()
for reference).
The opt
argument is optional. Two properties may be specified, opt.precision
and opt.segmentSubdivisions
, which determine maximum error allowed in pointAtLength
calculations for curved segments (default precision is 3; this corresponds to maximum observed error of 0.1%). The opt.segmentSubdivisions
property is an array of individual segments' subdivision arrays. The path.getSegmentSubdivisions()
function may be used to obtain the segmentSubdivisions
array. The opt.precision
property is still necessary, however; it determines the precision of the point search algorithm in curved segments.