VectorPathBuilder Class

Namespace: Meziantou.Framework.Imaging.Drawing
Assembly: Meziantou.Framework.Imaging.dll
Package: Meziantou.Framework.Imaging 1.2.11
Source: VectorPathBuilder.cs
Available in package assets: net10.0net11.0

Builds a VectorPath.

public sealed class VectorPathBuilder

Remarks

A contour starts with VectorPathBuilder.MoveTo and continues with segments from the current point. A contour that is not closed is open when it is stroked (it gets the caps of the pen) and is closed implicitly when it is filled. After VectorPathBuilder.Close or a method that adds a closed contour (VectorPathBuilder.AddRectangle, VectorPathBuilder.AddRoundedRectangle, VectorPathBuilder.AddEllipse, VectorPathBuilder.AddCircle, VectorPathBuilder.AddPolygon, VectorPathBuilder.AddPie), the current point is the first point of the contour that was just closed, and the next segment starts a new contour there.

Angles are in degrees, from the positive x axis; Y grows downward, so a positive angle turns clockwise on the image. The ends of an arc do not depend on the platform (see AffineTransform).

A builder is not thread-safe. Every coordinate must be a finite number whose magnitude does not exceed 16777216.

Constructors

Name	Description
VectorPathBuilder()

VectorPathBuilder()

VectorPathBuilder.cs

public VectorPathBuilder()

No documentation is available.

Methods

Name	Description
AddArc(PointD, double, double, double, double)	Starts a new contour with an arc of an ellipse given by its center. The contour stays open.
AddCircle(PointD, double)	Adds a closed circular contour.
AddClosedCurve(ReadOnlySpan<PointD>, double)	Adds a closed contour that goes smoothly through consecutive points, and from the last one back to the first one.
AddCurve(ReadOnlySpan<PointD>, double)	Adds an open contour that goes smoothly through consecutive points: a curve drawn through the values of a chart.
AddEllipse(PointD, double, double)	Adds a closed elliptical contour whose axes are horizontal and vertical.
AddEllipse(PointD, double, double, double)	Adds a closed elliptical contour whose axes are turned by an angle.
AddPie(PointD, double, double, double, double)	Adds a closed contour shaped like a slice of a pie: the center of an ellipse, an arc of it, and the two radii that join them.
AddPolygon(ReadOnlySpan<PointD>)	Adds a closed contour made of straight segments between consecutive points.
AddRectangle(RectangleD)	Adds a closed rectangular contour.
AddRoundedRectangle(RectangleD, CornerRadii)	Adds a closed rectangular contour whose corners are quarters of circles, each with its own radius.
AddRoundedRectangle(RectangleD, double)	Adds a closed rectangular contour whose corners are quarters of a circle.
AddRoundedRectangle(RectangleD, double, double)	Adds a closed rectangular contour whose corners are quarters of an ellipse.
ArcTo(PointD, double, double, double, double)	Adds an arc of an ellipse given by its center, joined to the current point by a straight segment. When there is no current point, the arc starts a contour.
ArcTo(double, double, double, bool, bool, PointD)	Adds an arc of an ellipse from the current point to a point, described as the arcs of SVG paths are.
ArcTo(double, double, double, bool, bool, double, double)	Adds an arc of an ellipse from the current point to a point, described as the arcs of SVG paths are.
Build()	Creates the path. The builder keeps its content and can be extended to build another path.
Clear()	Removes every element, so that the builder can be reused.
Close()	Closes the current contour with a straight segment to its first point. Nothing is done when no contour is open.
CubicBezierTo(PointD, PointD, PointD)	Adds a cubic Bézier curve from the current point.
CubicBezierTo(double, double, double, double, double, double)	Adds a cubic Bézier curve from the current point.
CurveTo(ReadOnlySpan<PointD>, double)	Continues the contour with a curve that goes smoothly from the current point through consecutive points: the top of an area under a curve.
LineTo(PointD)	Adds a straight segment from the current point.
LineTo(double, double)	Adds a straight segment from the current point.
MoveTo(PointD)	Starts a new contour.
MoveTo(double, double)	Starts a new contour.
QuadraticBezierTo(PointD, PointD)	Adds a quadratic Bézier curve from the current point.
QuadraticBezierTo(double, double, double, double)	Adds a quadratic Bézier curve from the current point.

AddArc(PointD, double, double, double, double)

VectorPathBuilder.cs

Starts a new contour with an arc of an ellipse given by its center. The contour stays open.

public VectorPathBuilder AddArc(PointD center, double radiusX, double radiusY, double startAngle, double sweepAngle)

Parameters

center PointD: The center of the ellipse.
radiusX double: The horizontal radius. Must be zero or positive.
radiusY double: The vertical radius. Must be zero or positive.
startAngle double: The angle of the first point of the arc, in degrees from the positive x axis, clockwise on the image.
sweepAngle double: The angle of the arc, in degrees: positive to turn clockwise on the image, negative for the other way. Beyond 360 degrees either way, the arc is the whole ellipse.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate, a radius or an angle is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, a radius is negative or exceeds 16777216, or the ellipse goes beyond the largest coordinate.

AddCircle(PointD, double)

VectorPathBuilder.cs

Adds a closed circular contour.

public VectorPathBuilder AddCircle(PointD center, double radius)

Parameters

center PointD: The center.
radius double: The radius. Must be zero or positive.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate or the radius is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.

AddClosedCurve(ReadOnlySpan<PointD>, double)

VectorPathBuilder.cs

Adds a closed contour that goes smoothly through consecutive points, and from the last one back to the first one.

public VectorPathBuilder AddClosedCurve(ReadOnlySpan<PointD> points, double tension = 0.5d)

Parameters

points ReadOnlySpan<PointD>: The points the curve goes through. At least one is required.
tension double: How far the curve keeps its direction around each point, from 0 to 1.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: points is empty, or a coordinate or tension is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, tension is not between 0 and 1, or the curve goes beyond the largest coordinate.

Remarks

See VectorPathBuilder.AddCurve: the point before the first one is the last one, and the point after the last one is the first one.

AddCurve(ReadOnlySpan<PointD>, double)

VectorPathBuilder.cs

Adds an open contour that goes smoothly through consecutive points: a curve drawn through the values of a chart.

public VectorPathBuilder AddCurve(ReadOnlySpan<PointD> points, double tension = 0.5d)

Parameters

points ReadOnlySpan<PointD>: The points the curve goes through. At least one is required; a single point is a contour without length.
tension double: How far the curve keeps its direction around each point, from 0 to 1.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: points is empty, or a coordinate or tension is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, tension is not between 0 and 1, or the curve goes beyond the largest coordinate.

Remarks

The contour is one cubic Bézier curve between each point and the next one. At each point, the curve has the direction of the line between the points before and after it, and tension says how far it keeps that direction: 0.5 (the default) is the Catmull-Rom spline, 0 gives the straight segments between the points, and a larger tension rounds the curve more. The control points of the curve from a point P1 to the next one P2 are P1 + tension (P2 - P0) / 3 and P2 - tension (P3 - P1) / 3; the first point is its own previous point, and the last one its own next point. A curve can go beyond the points it goes through, where they turn sharply.

AddEllipse overloads

AddEllipse(PointD, double, double)

VectorPathBuilder.cs

Adds a closed elliptical contour whose axes are horizontal and vertical.

public VectorPathBuilder AddEllipse(PointD center, double radiusX, double radiusY)

Parameters

center PointD: The center.
radiusX double: The horizontal radius. Must be zero or positive.
radiusY double: The vertical radius. Must be zero or positive.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate or a radius is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, or a radius is negative or exceeds 16777216.

AddEllipse(PointD, double, double, double)

VectorPathBuilder.cs

Adds a closed elliptical contour whose axes are turned by an angle.

public VectorPathBuilder AddEllipse(PointD center, double radiusX, double radiusY, double rotation)

Parameters

center PointD: The center.
radiusX double: The radius along the axis that is horizontal before the rotation. Must be zero or positive.
radiusY double: The radius along the other axis. Must be zero or positive.
rotation double: The angle of the axes, in degrees, clockwise on the image.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate, a radius or the rotation is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, a radius is negative or exceeds 16777216, or the ellipse goes beyond the largest coordinate.

AddPie(PointD, double, double, double, double)

VectorPathBuilder.cs

Adds a closed contour shaped like a slice of a pie: the center of an ellipse, an arc of it, and the two radii that join them.

public VectorPathBuilder AddPie(PointD center, double radiusX, double radiusY, double startAngle, double sweepAngle)

Parameters

center PointD: The center of the ellipse, and the first point of the contour.
radiusX double: The horizontal radius. Must be zero or positive.
radiusY double: The vertical radius. Must be zero or positive.
startAngle double: The angle of the first point of the arc, in degrees from the positive x axis, clockwise on the image.
sweepAngle double: The angle of the arc, in degrees: positive to turn clockwise on the image, negative for the other way. Beyond 360 degrees either way, the arc is the whole ellipse.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate, a radius or an angle is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, a radius is negative or exceeds 16777216, or the ellipse goes beyond the largest coordinate.

AddPolygon(ReadOnlySpan<PointD>)

VectorPathBuilder.cs

Adds a closed contour made of straight segments between consecutive points.

public VectorPathBuilder AddPolygon(ReadOnlySpan<PointD> points)

Parameters

points ReadOnlySpan<PointD>: The vertices. At least one is required.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: points is empty, or a coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.

AddRectangle(RectangleD)

VectorPathBuilder.cs

Adds a closed rectangular contour.

public VectorPathBuilder AddRectangle(RectangleD rectangle)

Parameters

rectangle RectangleD: The rectangle.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.

AddRoundedRectangle overloads

AddRoundedRectangle(RectangleD, CornerRadii)

VectorPathBuilder.cs

Adds a closed rectangular contour whose corners are quarters of circles, each with its own radius.

public VectorPathBuilder AddRoundedRectangle(RectangleD rectangle, CornerRadii radii)

Parameters

rectangle RectangleD: The rectangle.
radii CornerRadii: The radius of each corner.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.

Remarks

The contour starts at the left end of the straight part of its top side and turns clockwise on the image. A corner whose radius is zero is a corner of the rectangle. Radii that do not fit are reduced together: see CornerRadii.

AddRoundedRectangle(RectangleD, double)

VectorPathBuilder.cs

Adds a closed rectangular contour whose corners are quarters of a circle.

public VectorPathBuilder AddRoundedRectangle(RectangleD rectangle, double radius)

Parameters

rectangle RectangleD: The rectangle.
radius double: The radius of the corners. Must be zero or positive; it is limited to half the shortest side of the rectangle.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate or the radius is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, or the radius is negative or exceeds 16777216.

AddRoundedRectangle(RectangleD, double, double)

VectorPathBuilder.cs

Adds a closed rectangular contour whose corners are quarters of an ellipse.

public VectorPathBuilder AddRoundedRectangle(RectangleD rectangle, double radiusX, double radiusY)

Parameters

rectangle RectangleD: The rectangle.
radiusX double: The horizontal radius of the corners. Must be zero or positive; it is limited to half the width of the rectangle.
radiusY double: The vertical radius of the corners. Must be zero or positive; it is limited to half the height of the rectangle.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate or a radius is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, or a radius is negative or exceeds 16777216.

Remarks

The contour starts at the left end of the straight part of its top side and turns clockwise on the image. With a radius of zero it is the rectangle; with radii of half the sides it is an ellipse.

ArcTo overloads

ArcTo(PointD, double, double, double, double)

VectorPathBuilder.cs

Adds an arc of an ellipse given by its center, joined to the current point by a straight segment. When there is no current point, the arc starts a contour.

public VectorPathBuilder ArcTo(PointD center, double radiusX, double radiusY, double startAngle, double sweepAngle)

Parameters

center PointD: The center of the ellipse.
radiusX double: The horizontal radius. Must be zero or positive.
radiusY double: The vertical radius. Must be zero or positive.
startAngle double: The angle of the first point of the arc, in degrees from the positive x axis, clockwise on the image.
sweepAngle double: The angle of the arc, in degrees: positive to turn clockwise on the image, negative for the other way. Beyond 360 degrees either way, the arc is the whole ellipse.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate, a radius or an angle is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, a radius is negative or exceeds 16777216, or the ellipse goes beyond the largest coordinate.

ArcTo(double, double, double, bool, bool, PointD)

VectorPathBuilder.cs

Adds an arc of an ellipse from the current point to a point, described as the arcs of SVG paths are.

public VectorPathBuilder ArcTo(double radiusX, double radiusY, double rotation, bool largeArc, bool clockwise, PointD point)

Parameters

radiusX double: The first radius of the ellipse. Must be zero or positive.
radiusY double: The second radius of the ellipse. Must be zero or positive.
rotation double: The angle of the first radius, in degrees from the x axis, clockwise on the image.
largeArc bool: true for an arc of more than half a turn.
clockwise bool: true for the arc that turns clockwise on the image.
point PointD: The end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate, a radius or the rotation is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, a radius is negative or exceeds 16777216, or the arc goes beyond the largest coordinate.
InvalidOperationException: There is no current point: no contour was started.

Remarks

See VectorPathBuilder.ArcTo.

ArcTo(double, double, double, bool, bool, double, double)

VectorPathBuilder.cs

Adds an arc of an ellipse from the current point to a point, described as the arcs of SVG paths are.

public VectorPathBuilder ArcTo(double radiusX, double radiusY, double rotation, bool largeArc, bool clockwise, double x, double y)

Parameters

radiusX double: The first radius of the ellipse. Must be zero or positive.
radiusY double: The second radius of the ellipse. Must be zero or positive.
rotation double: The angle of the first radius, in degrees from the x axis, clockwise on the image.
largeArc bool: true for an arc of more than half a turn.
clockwise bool: true for the arc that turns clockwise on the image.
x double: The horizontal coordinate of the end point.
y double: The vertical coordinate of the end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate, a radius or the rotation is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, a radius is negative or exceeds 16777216, or the arc goes beyond the largest coordinate.
InvalidOperationException: There is no current point: no contour was started.

Remarks

Two ellipses of the given radii and rotation pass through both points (or one, or none), and each has two arcs between them: largeArc chooses the arcs of more than half a turn, and clockwise the one that turns clockwise on the image. Radii too small for an ellipse to reach both points are enlarged, in proportion, until one does.

When a radius is zero, the arc is a straight segment; when the point is the current point, nothing is added.

Build()

VectorPathBuilder.cs

Creates the path. The builder keeps its content and can be extended to build another path.

public VectorPath Build()

Returns

VectorPath An immutable path.

Clear()

VectorPathBuilder.cs

Removes every element, so that the builder can be reused.

public void Clear()

Close()

VectorPathBuilder.cs

Closes the current contour with a straight segment to its first point. Nothing is done when no contour is open.

public VectorPathBuilder Close()

Returns

VectorPathBuilder This builder.

CubicBezierTo overloads

CubicBezierTo(PointD, PointD, PointD)

VectorPathBuilder.cs

Adds a cubic Bézier curve from the current point.

public VectorPathBuilder CubicBezierTo(PointD control1, PointD control2, PointD point)

Parameters

control1 PointD: The first control point.
control2 PointD: The second control point.
point PointD: The end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.
InvalidOperationException: There is no current point: no contour was started.

CubicBezierTo(double, double, double, double, double, double)

VectorPathBuilder.cs

Adds a cubic Bézier curve from the current point.

public VectorPathBuilder CubicBezierTo(double control1X, double control1Y, double control2X, double control2Y, double x, double y)

Parameters

control1X double: The horizontal coordinate of the first control point.
control1Y double: The vertical coordinate of the first control point.
control2X double: The horizontal coordinate of the second control point.
control2Y double: The vertical coordinate of the second control point.
x double: The horizontal coordinate of the end point.
y double: The vertical coordinate of the end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.
InvalidOperationException: There is no current point: no contour was started.

CurveTo(ReadOnlySpan<PointD>, double)

VectorPathBuilder.cs

Continues the contour with a curve that goes smoothly from the current point through consecutive points: the top of an area under a curve.

public VectorPathBuilder CurveTo(ReadOnlySpan<PointD> points, double tension = 0.5d)

Parameters

points ReadOnlySpan<PointD>: The points the curve goes through, after the current point. At least one is required.
tension double: How far the curve keeps its direction around each point, from 0 to 1.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: points is empty, or a coordinate or tension is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216, tension is not between 0 and 1, or the curve goes beyond the largest coordinate.
InvalidOperationException: There is no current point: no contour was started.

Remarks

The curve is the one of VectorPathBuilder.AddCurve through the current point then points: the current point is its first point, whatever comes before it in the contour.

LineTo overloads

LineTo(PointD)

VectorPathBuilder.cs

Adds a straight segment from the current point.

public VectorPathBuilder LineTo(PointD point)

Parameters

point PointD: The end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.
InvalidOperationException: There is no current point: no contour was started.

LineTo(double, double)

VectorPathBuilder.cs

Adds a straight segment from the current point.

public VectorPathBuilder LineTo(double x, double y)

Parameters

x double: The horizontal coordinate of the end point.
y double: The vertical coordinate of the end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.
InvalidOperationException: There is no current point: no contour was started.

MoveTo overloads

MoveTo(PointD)

VectorPathBuilder.cs

Starts a new contour.

public VectorPathBuilder MoveTo(PointD point)

Parameters

point PointD: The first point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.

MoveTo(double, double)

VectorPathBuilder.cs

Starts a new contour.

public VectorPathBuilder MoveTo(double x, double y)

Parameters

x double: The horizontal coordinate of the first point.
y double: The vertical coordinate of the first point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.

QuadraticBezierTo overloads

QuadraticBezierTo(PointD, PointD)

VectorPathBuilder.cs

Adds a quadratic Bézier curve from the current point.

public VectorPathBuilder QuadraticBezierTo(PointD control, PointD point)

Parameters

control PointD: The control point.
point PointD: The end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.
InvalidOperationException: There is no current point: no contour was started.

QuadraticBezierTo(double, double, double, double)

VectorPathBuilder.cs

Adds a quadratic Bézier curve from the current point.

public VectorPathBuilder QuadraticBezierTo(double controlX, double controlY, double x, double y)

Parameters

controlX double: The horizontal coordinate of the control point.
controlY double: The vertical coordinate of the control point.
x double: The horizontal coordinate of the end point.
y double: The vertical coordinate of the end point.

Returns

VectorPathBuilder This builder.

Exceptions

ArgumentException: A coordinate is not a finite number.
ArgumentOutOfRangeException: The magnitude of a coordinate exceeds 16777216.
InvalidOperationException: There is no current point: no contour was started.