2-Dimensional Graphics Paths
This article describes two-dimensional paths. This is an extra included in the HTML 3D Library.
Download the latest version of the Public Domain HTML 3D Library at the HTML 3D Library's Releases page.
A path is a collection of two-dimensional line segments and/or curves. Many paths describe
closed figures or connected strings of lines and curves. The
currently supports line segments, quadratic and cubic Bézier curves, and elliptical arcs,
as well as closed figures made from several path segments.
How to Use
2D paths are implemented in a class called
H3DU.GraphicsPath, found in the file extras/path.js in
the HTML 3D Library download. To use this class, you must include the script "extras/path.js",
as in this example.
There are two ways to create paths: using an SVG path string, or by calling methods that add its segments.
SVG Path String
If you've worked with SVG, you may be familiar with this format for describing 2D paths. An SVG path string consists of one or more path commands that start with a single letter. The following are examples of SVG path strings:
M50,50L100,100,100,150,150,200 M50,20C230,245,233,44,22,44 M50,50H80V60H50V70H50
The "M" command moves the current position, the "L", "H", and "V" commands create lines, the "Q", "C", "S", and "T" commands create Bézier curves, the "A" command creates elliptical arcs, and the "Z" command closes the path. If the letters are lower-cased, X and Y coordinates are relative to the current position.
For more information, see the H3DU.GraphicsPath.fromString method documentation. That method is also how you create a 2D path from an SVG path string, as in this example:
var path = H3DU.GraphicsPath.fromString("M50,20C230,245,233,44,22,44")
The other way to make paths is to call the
H3DU.GraphicsPath constructor and call methods
to add path segments to the path.
H3DU.GraphicsPath object stores a current position and a starting position, and many methods
don't have you specify a starting position, to cover the common case of drawing a series
of connected lines and curves.
- .moveTo(x, y) - Moves the starting position and current position.
- .lineTo(x, y) - Adds a line segment from the current position to a new ending position.
- .closePath() - Closes the path by drawing a line to the starting point, if needed.
Each path can include a number of line segments, Bézier curves, and elliptical arcs. Line segments are relatively easy to understand. The other two kinds of segments deserve some discussion.
A Bézier curve is a parametric curve based on a polynomial formula. In this kind of curve the endpoints are defined as they are, but the other points define the shape of the curve and generally don't cross the curve. A quadratic Bézier curve uses 3 points. A cubic Bézier curve uses 4 points.
An elliptic arc is a curve which forms part of an ellipse. There are several ways to
parameterize an elliptic arc, as seen in the .arc(), .arcTo(), and .arcSvgTo() methods
- The H3DU.GraphicsPath.getLength method finds the approximate length of a path.
- The H3DU.GraphicsPath.getBounds method finds the axis-aligned bounding box of a path.