C

GeneralPath

Show Usages
Models a path that consists of lines and Bézier curves.
ImplementsInheritance Hierarchy

Remarks

This class uses double precision coordinates to model a virtual pen that can be moved across the world coordinate system and which can be used to draw lines and Bézier curves. This class provides many geometric utility methods, such as calculating the bounds, hit tests, containment tests, curve flattening, path transformation, path modification, and path iteration.

Members

No filters for this type

Constructors

GeneralPath

(capacity?: number)
Creates a new instance with the given initial capacity.

Parameters

capacity?: number
The number of elements for which storage will be allocated initially.

Properties

isVisible

: boolean
readonly
Gets a value indicating whether the path contains visible parts.
readonlyfinal

Property Value

true iff the path contains at least one LINE_TO, QUAD_TO, or CUBIC_TO segment.

lastCoordinate

: Point
readonly
Gets the last coordinates of the last path element.
readonlyfinal

Property Value

The last coordinate.

lastX

: number
readonly
Gets the last x-coordinate of the last path element.
readonlyfinal

lastY

: number
readonly
Gets the last y coordinate of the last path element.
readonlyfinal

size

: number
readonly
Gets the number of PathType operations stored in this instance.
readonlyfinal

Methods

append

(other: GeneralPath, connect: boolean)
Appends the contents of the given path to this path.
If connect is true, an initial MOVE_TO in other will be transformed into a LINE_TO.
final

Parameters

other: GeneralPath
The path to append to this path.
connect: boolean
Whether to connect the path to the end of this path.

append

(
other: GeneralPath
beginIndex: number
endIndex: number
connect: boolean
)
Appends parts of the contents of the given path to this path.
If connect is true, an initial MOVE_TO in other will be transformed into a LINE_TO.
final

Parameters

other: GeneralPath
The path to append to this path.
beginIndex: number
The first element to be copied from other, inclusively.
endIndex: number
The last element to be copied from other, exclusively.
connect: boolean
Whether to connect the path to the end of this path.

appendEllipse

(bounds: IRectangle, connect: boolean)
Appends an ellipse using the given bounds to this instance.
final

Parameters

bounds: IRectangle
The bounds of the ellipse.
connect: boolean
Whether to initially lineTo the ellipse's lowest point.

appendOrientedRectangle

(rectangle: IOrientedRectangle, connect: boolean)
Appends an IOrientedRectangle to this path instance.
final

Parameters

rectangle: IOrientedRectangle
The IOrientedRectangle to get the coordinates from.
connect: boolean
Whether to use a lineTo to the anchor corner.

appendRectangle

(rectangle: IRectangle, connect: boolean)
Appends a rectangle to this path instance.
final

Parameters

rectangle: IRectangle
The rectangle to get the coordinates from.
connect: boolean
Whether to use a lineTo to the upper left corner.

areaContains

(point: IPoint, flatteningTolerance?: number): boolean
Checks whether the point lies inside the area that is described by this path instance.
Note that this will only work as expected for closed paths. Note that for points residing exactly on the path this may return false due to rounding issues, consider also checking for pathContains in this case.
final

Parameters

point: IPoint
The coordinates of the point to test.
flatteningTolerance?: number
The value for the accuracy when flattening Bézier curves during the test. The default is 0.5.

Return Value

boolean
Whether the point lies within the area described by this path.

areaIntersects

(other: GeneralPath, flatteningTolerance?: number): boolean
Determines whether the area formed by this instance intersects with the area formed by the given path instance.
final

Parameters

other: GeneralPath
The other instance to check against.
flatteningTolerance?: number
The epsilon value that is used for the accuracy with which the implementation should test Bézier curves within the path for intersections. The default value is 0.5.

Return Value

boolean
Whether the filled area of this path intersects with the stroke or filled area of the given path.

areaOrPathContains

(point: IPoint, eps: number): boolean
Checks whether the point lies inside the area described by this path instance.
Note that this will only work as expected for closed paths. The epsilon is used for internally flattening Bézier curves. Note that for points residing exactly on the path, this may return false due to rounding issues, consider also checking for pathContains in this case.
final

Parameters

point: IPoint
The coordinates of the point to test.
eps: number
The allowed distance from the point to the path that is considered a hit.

Return Value

boolean
Whether the point lies within the area described by this path.

clear

()
Resets this path to be an empty path.
final

clone

(): Object
Creates a clone of this instance, copying the path information to the new instance.
final

Return Value

Object
An exact clone of this instance.

close

()
Appends a CLOSE operation to the path elements, creating a line to the last MOVE_TO position.
This draws a line from the current end point to the last moveTo position, closing the current sub path.
final

compress

()
Compresses the internal data structures so that the amount of memory used by this instance is minimal with respect to the information stored in it.
final

createCursor

(): GeneralPathCursor
Creates a cursor for iterating over the elements of this path.
The cursor is fail-fast, i.e. if the path's structure is modified after the construction of the cursor any cursor operation will fail.
final

Return Value

GeneralPathCursor
A cursor to iterate over this path.

createSmoothedPath

(
smoothingLength: number
smoothingPolicy?: SmoothingPolicy
straightEnds?: boolean
): GeneralPath
Creates a new path based on this one where corners are smoothed with a quadratic Bézier arc starting at smoothingLength away from the corner.
final

Parameters

smoothingLength: number
Distance from the corner where the arc begins.
smoothingPolicy?: SmoothingPolicy
A SmoothingPolicy value specifying how corners should be smoothed.
straightEnds?: boolean
A value indicating whether the first and last segment of a path figure should end with a straight line segment, or whether the adjacent corner can be smoothed up to the very end of the path (if smoothingLength is large enough).

Return Value

GeneralPath
A new path, with its corners smoothed.

createSvgPath

(transform?: Matrix): SVGPathElement
Creates an SVG path element using the provided parameters.
final

Parameters

transform?: Matrix
The matrix to apply to the path data.

Return Value

SVGPathElement
A path that displays this instance using the provided attributes.

createSvgPathData

(transform?: Matrix): string
Creates the data for a SVG path element that corresponds to this instance with the provided transform.
final

Parameters

transform?: Matrix
The transform to apply to the created data.

Return Value

string
The path data for an SVG path element that corresponds to this instance with the provided transform.

createTransformedPath

(transform: Matrix): GeneralPath
Creates a new GeneralPath that is a copy of this path with all geometry transformed using the supplied matrix.
final

Parameters

transform: Matrix
The matrix to multiply the geometry with.

Return Value

GeneralPath
A new path.

cropAfter

(cursor: GeneralPathCursor)
Crops the path after the position indicated by the cursor.
This will remove all path operations that follow the position indicated by the cursor.
final

Parameters

cursor: GeneralPathCursor
The cursor that depicts a position in this path.

cropBefore

(cursor: GeneralPathCursor)
Crops the path before the position indicated by the cursor.
This will remove all path operations that precede the position indicated by the cursor.
final

Parameters

cursor: GeneralPathCursor
The cursor that depicts a position in this path.

cubicTo

(
c1: IPoint
c2: IPoint
end: IPoint
)
Appends a cubic Bézier curve to the path elements.
This draws a cubic Bézier curve from the current end point to the given position using the two given control points.
final

Parameters

c1: IPoint
The coordinates of the first Bézier control point.
c2: IPoint
The coordinates of the second Bézier control point.
end: IPoint
The coordinates of the curve's end point.

cubicTo

(
c1x: number
c1y: number
c2x: number
c2y: number
x: number
y: number
)
Appends a cubic Bézier curve to the path elements.
This draws a cubic Bézier curve from the current end point to the given position using the two given control points.
final

Parameters

c1x: number
The x coordinate of the first Bézier control point.
c1y: number
The y coordinate of the first Bézier control point.
c2x: number
The x coordinate of the second Bézier control point.
c2y: number
The y coordinate of the second Bézier control point.
x: number
The x coordinate of the curve's end point.
y: number
The y coordinate of the curve's end point.

findLineIntersection

(
start: IPoint
end: IPoint
eps?: number
): number
Finds an intersection point between a line and this GeneralPath.
The value returned will be the smallest positive value smaller than 1 such that the point depicted by start + result * (end - start) is an intersection point between the line and the path.
final

Parameters

start: IPoint
The coordinates of the first point of the line.
end: IPoint
The coordinates of the second point of the line.
eps?: number
The value to use for interpolating Bézier curves.

Return Value

number
The factor to calculate the intersection point or double.PositiveInfinity.

findRayIntersection

(
anchor: IPoint
direction: IPoint
flatteningTolerance?: number
): number
Finds the first intersection of a ray with this GeneralPath using a given epsilon for flattening Bézier curves contained in the path.
The ray is treated like an infinite line starting at the given anchor point and continuing in the direction of rayX, rayY. The ray vector does not need to be normalized. The value returned will be the smallest positive value such that the point depicted by (anchorX + result * rayX, anchorY + result * rayY) is an intersection point between the ray and the path.
final

Parameters

anchor: IPoint
The coordinates of the anchor point of the ray.
direction: IPoint
The coordinates of the direction vector of the ray.
flatteningTolerance?: number
The epsilon value that is used for the accuracy with which the implementation should test Bézier curves within the path for intersections. By default this is 0.5.

Return Value

number
The factor to calculate the intersection point or double.PositiveInfinity.

flatten

(flatteningTolerance?: number): GeneralPath
Creates a new path from this instance flattening all Bézier curves using the given tolerance.
This will create a path that consists of MOVE_TO, LINE_TO, and CLOSE operations only.
final

Parameters

flatteningTolerance?: number
The maximum value the flattened path may diverge from the original path for the Bézier curve line interpolations. The default is 0.5.

Return Value

GeneralPath
A new path that does not contain Bézier curve segments.

getApproximateBounds

(): Rect
Calculates approximate bounds of this path.
Contrary to getBounds, this method will not yield tight bounds if the path contains Bézier curves. The bounds are calculated using the union of all points and control points contained in this path. However, this method is much faster than the exact version. Choose this method if the call is performance-critical.
final

Return Value

Rect
The approximate bounds of the path.

getBounds

(flatteningTolerance?: number): Rect
Calculates the exact bounds of the path.
Contrary to getApproximateBounds, this method calculates tight bounds for Bézier segments. However, this method is slower than getApproximateBounds if the path contains Bézier segments. Choose this method if the bounds need to be exact and the call is not performance-critical.
final

Parameters

flatteningTolerance?: number
The maximum value the flattened path may diverge from the original path for the Bézier curve line interpolations. The default is 0.5. If the given epsilon is 0.0, the path's B ézier curve segments are not flattened. Instead, this method calculates exact tight bounds for Bézier curve segments.

Return Value

Rect
The exact bounds of the path.

getLength

(): number
Returns the geometric length of this path.
Note that Bézier curves are still treated as line segments.
final

Return Value

number
The length of this path.

getPoint

(ratio: number): Point
Gets a point on this path instance at the given ratio.
Note that this implementation still treats Bézier curves as linear segments.
final

Parameters

ratio: number
A value between 0 and 1 inclusively that indicates a ratio from the beginning to the end of this path.

Return Value

Point
The coordinates of the point.

getProjection

(point: IPoint, segmentIndex: number): number
Gets the projection of point onto the segment segmentIndex.

This method does not directly return the projection point, but the parameter ratio for the segment, or null if no projection on the segment could be found within the interval [0,1]. To determine the actual projection point, you can use the ratio as input for getTangentForSegment.

Note that this implementation still treats quadratic as linear segments.

final

Parameters

point: IPoint
The point which should be projected onto the segment.
segmentIndex: number
The segment index. Note that only linear, cubic, or close segments are considered.

Return Value

number
A ratio describing the projection onto the segment, or null if no such projection exists in the interval [0,1].

getSegmentCount

(): number
Gets the number of segments in this path, that is the number of LINE_TO and CLOSE operations.
final

Return Value

number
The number of segments.

getTangent

(ratio: number): Tangent
Gets the tangent on this path instance at the given ratio.
Note that this implementation still treats Bézier curves as linear segments.
final

Parameters

ratio: number
A value between 0 and 1 inclusively that indicates a ratio from the beginning to the end of this path.

Return Value

Tangent
The tangent, if any exists; null otherwise. The tangent vector may not be normalized.

getTangentForSegment

(segmentIndex: number, ratio: number): Tangent
Gets the tangent on this path instance at the segment and segment ratio.
Note that this implementation still treats quadratic curves as linear segments.
final

Parameters

segmentIndex: number
The segment index to determine a point at.
ratio: number
A value between 0 and 1 inclusively that indicates a ratio from the beginning to the end of the segment at segmentIndex for this path.

Return Value

Tangent
The tangent, if any exists; null otherwise. The tangent vector may not be normalized.

hasSameValue

(path: GeneralPath): boolean
Determines whether a given GeneralPath instance can be considered equivalent to this one, that is, both represent the same path with the same sub-path types and coordinates.
final

Parameters

path: GeneralPath
The other GeneralPath instance to compare.

Return Value

boolean
true if path and this instance have the same sub-path types and coordinates, false if not.

lineTo

(point: IPoint)
Appends a LINE_TO operation to the path elements.
This draws a line from the current end point to the given position.
final

Parameters

point: IPoint
The coordinates of the line's end point.

lineTo

(x: number, y: number)
Appends a LINE_TO operation to the path elements.
This draws a line from the current end point to the given position.
final

Parameters

x: number
The x coordinate of the line's end point.
y: number
The y coordinate of the line's end point.

moveTo

(point: IPoint)
Appends a MOVE_TO operation to the path elements.
This moves the pen to a new position without drawing a line.
final

Parameters

point: IPoint
The next coordinate.

moveTo

(x: number, y: number)
Appends a MOVE_TO operation to the path elements.
This moves the pen to a new position without drawing a line.
final

Parameters

x: number
The next x coordinate.
y: number
The next y coordinate.

pathContains

(point: IPoint, eps: number): boolean
Tests whether the line of the path is hit at the given point using an epsilon for fuzzy hit testing.
final

Parameters

point: IPoint
The coordinates of the point to test.
eps: number
The allowed distance from the point to the path that is considered a hit.

Return Value

boolean
Whether the point hits the path.

pathIntersects

(other: GeneralPath, flatteningTolerance?: number): boolean
Determines whether this path's stroked segments intersect with a given path.
If one path is contained within an enclosed area of the other but the stroked segments do not intersect, this method will return false.
final

Parameters

other: GeneralPath
The other path to check against this path.
flatteningTolerance?: number
The epsilon value that is used for the accuracy of the Bézier curves with which the implementation should test Bézier curves within the path for intersections. The default is 0.5.

Return Value

boolean
True if this path's stroked segments intersect the other path's stroked segments.

See Also

API
areaIntersects

pathIntersects

(rectangle: IRectangle, flatteningTolerance?: number): boolean
Checks whether this path intersects the given rectangle.
This will yield false if the rectangle is fully contained within the area of the path.
final

Parameters

rectangle: IRectangle
The rectangle to test.
flatteningTolerance?: number
The epsilon value that is used for the accuracy of the Bézier curves with which the implementation should test Bézier curves within the path for intersections. The default is 0.5.

Return Value

boolean
Whether the path described by this instance intersects the rectangle.

pathMayIntersectClip

(clip: IRectangle, strokeWidth: number): boolean
Performs a quick test to decide whether this path might intersect the clipping rectangle, provided the path would be rendered using a stroke of the given width.
This method will return false if the clip is entirely inside the area of this path.
final

Parameters

clip: IRectangle
The clip to check for intersection.
strokeWidth: number
The width of the stroke.

Return Value

boolean
false if it is guaranteed that this instance would not intersect the given clip.

prepend

(other: GeneralPath, connect: boolean)
Adds the contents of the given path to the beginning of this path.
If connect is true, the initial MOVE_TO in this will be transformed into a LINE_TO.
final

Parameters

other: GeneralPath
The path to append to this path.
connect: boolean
Whether to connect the path to the end of this path.

quadTo

(center: IPoint, point: IPoint)
Appends a quadratic Bézier curve to the path elements.
This draws a quadratic Bézier curve from the current end point to the given position using the given control point.
final

Parameters

center: IPoint
The coordinates of the Bézier control point.
point: IPoint
The coordinates of the curve's end point.

quadTo

(
cx: number
cy: number
x: number
y: number
)
Appends a quadratic Bézier curve to the path elements.
This draws a quadratic Bézier curve from the current end point to the given position using the given control point.
final

Parameters

cx: number
The x coordinate of the Bézier control point.
cy: number
The y coordinate of the Bézier control point.
x: number
The x coordinate of the curve's end point.
y: number
The y coordinate of the curve's end point.

transform

(transform: Matrix)
Transforms this GeneralPath in place using the given transform.
final

Parameters

transform: Matrix
The matrix to multiply the geometry with.

Static Methods

getCubicSplitPoints

(
cp0: Point
cp1: Point
cp2: Point
cp3: Point
splitBefore: boolean
t: number
): Point
static
Determines new control points for splitting a cubic Bézier segment.
static

Parameters

cp0: Point
The start point of the segment
cp1: Point
The first control point of the segment
cp2: Point
The second control point of the segment
cp3: Point
The control points of the cubic segment
splitBefore: boolean
A value indicating whether the new control points for the segment before or after the cut should be returned
t: number
The parameter for De Casteljau's algorithm to determine the splitting point in the interval [0..1].

Return Value

Point
An array of length 4 with the new start, end, and control points for the segment either preceding or following the desired split point.