Add arcVertex() for creating arcs with beginShape()/endShape()

[GregStanton]

Increasing Access

This feature increases access in two main ways:

1. It addresses an inconsistency that may be an obstacle for beginners.
2. It allows the user to perform common tasks with less mathematical knowledge.

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build Process
• Unit Testing
• Internalization
• Friendly Errors
• Other (specify if possible)

Feature request details

Proposal

Add arcVertex() to the set of vertex functions in p5, to address a limitation of beginShape()/endShape().

The problem

Two of p5’s curve-vertex pairs are incomplete. In the table below, asterisks indicate missing items.

	p5 curve	p5 vertex
line/polyline	line()	vertex()
quadratic Bézier	quadratic()*	quadraticVertex()
cubic Bézier	bezier()	bezierVertex()
Catmull-Rom spline	curve()	curveVertex()
circular/elliptical arc	arc()	arcVertex()*

Of the missing items, arcVertex() is the most important. Arcs are the only type of SVG subpaths not supported by p5’s beginShape()/endShape(). Without them, p5's most powerful shape-making feature cannot make some of the most basic shapes (e.g. lines and Bézier curves can only approximate circles). This leads to complications for both users and developers.

The solution

Provide a new function called arcVertex() based on SVG’s arc command. Applications include the following:

• Rounded corners: Allow users to round corners of polygons (not just rectangles) without approximations.
• Shape objects: Retain exact data for built-in and custom shapes in a common format usable by beginShape()/endShape().
• SVG paths: Work with SVG paths by translating SVG path commands directly to p5 vertex commands.

Specification of arcVertex()

The following may serve as a draft reference page and usage tutorial.

Description

Used to draw an arc along a circle or ellipse (oval), from one vertex (point) to another. The arc may be drawn along any ellipse, even one that’s been rotated. (If the ellipse is too small to connect the two vertices, its size is automatically adjusted.)

The first vertex is specified with vertex(). The second vertex is specified with arcVertex(). Both are specified within beginShape() and endShape(), with no parameter passed to beginShape().

The arc itself is specified by indicating the shape and rotation of the ellipse (w, h, and angle), together with its type (MINOR or MAJOR) and its direction (COUNTERCLOCKWISE or CLOCKWISE).

If DEGREES is passed to angleMode(), angle may be specified in degrees; otherwise, angle should be specified in radians. If RADIUS is passed to ellipseMode(), the shape parameters are interpreted as half of the width and half of the height: arcVertex(20, 50, ... ) results in an arc drawn along an ellipse of width 40 and height 100.

Usage

beginShape();
vertex(x1, y1);
arcVertex(w, h, angle, type, direction, x2, y2);
endShape();

Syntax

arcVertex(w, h, angle, type, direction, x2, y2)

Parameters

Name	Description
w	Number: width of ellipse along which arc is drawn
h	Number: height of ellipse along which arc is drawn
angle	Number: angle by which ellipse is rotated relative to x-axis
type	Constant: either MAJOR or MINOR
direction	Constant: either COUNTERCLOCKWISE or CLOCKWISE
x2	Number: x-coordinate of ending vertex
y2	Number: y-coordinate of ending vertex

Tutorial

Related issues

• Rounded corners
  • Add rounding corners of triangles. #2529
  • Added round corner property for rect() in WebGL mode #5789
• Shape objects
  • implement PShape #37
  • shapeMode() new feature #3509
• SVG paths
  • Add first class support for SVG imports and exports #4630
  • Font paths to points #844 (suggests a complementary path-to-vertices feature)
  • Dealing with SVGs #458

[welcome]

Welcome! 👋 Thanks for opening your first issue here! And to ensure the community is able to respond to your issue, please make sure to fill out the inputs in the issue forms. Thank you!

[Qianqianye]

Thanks @GregStanton for the suggestion. I'm inviting the current p5.js Core Stewards to this discussion @limzykenneth, @davepagurek, @ChihYungChang, @teragramgius, @tuminzee, @Zarkv, @robin-haxx, @Gaurav-1306. Please feel free to leave your comments about this feature request. Thank you!

[Garavitey]

Great suggestion.

I would like to work on this one. Let me get back with details of implementation.

[GregStanton]

Amazing! Thank you so much @Gaurav-1306! And thank you to @Qianqianye for bringing the others into the conversation!

Verbal version of the tutorial
In case it helps anyone, I'll elaborate slightly on the tutorial. We want to draw an arc along the specified ellipse, from the first vertex to the second vertex. But we need to decide how to do that. We can start by imagining moving the ellipse onto the two vertices. There are two ways to do this; in the example shown, we get one copy of the ellipse attached from below and one attached from above. The vertices divide each ellipse copy into two arcs (major and minor). This means that there are four possible arcs. The type and direction parameters allow the user to specify which one they want (e.g. the minor clockwise arc is one option). Here's a quick p5 sketch that shows how the type and direction parameters allow you to specify four possible arcs (with different colors for each arc).

Specification for out-of-range parameters
It seems like a good idea to be consistent with how the SVG specification handles parameters that are out of range. This comes from the W3C Candidate Recommendation for SVG 2.

I hope this helps!

[davepagurek]

I think this makes sense as a way to increase consistency between modes of drawing shapes.

Do you have thoughts on the current API, based on SVG path arc commands, vs something more like the vanilla J's canvas arcTo API? https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#elliptical_arc_curve The API for this one seems a bit more approachable at first glance (although your naming is much clearer than the flag names in the SVG spec!)

[GregStanton]

Thanks for your feedback @davepagurek! I'm glad you like the naming. I'm also glad you asked about other APIs. I asked myself the same question, and I think it's good to document the rationale here.

The problem with SVG's arc command, and how to mitigate it
It's commonly acknowledged that SVG's arc command is not the simplest. Yet, it does work, and we can mitigate any difficulties. The friendlier API I proposed should help. It should also be possible to improve the graphic tutorial I shared.

The problem with canvas's arcTo(), and why we can't mitigate it
A circular arc made with arcTo() may end at an unspecified point. (Really, arcToward() is a more accurate name than arcTo().) This conflicts with p5's functions, which are explicitly vertex based¹: quadraticVertex(), bezierVertex() etc. all have "vertex" in the name, and the eponymous vertex is always represented by the final parameters.

The problem with canvas's ellipse(), and why we can't mitigate it
The native canvas API also has a method that creates an elliptical arc as a sub-path. It's simply called ellipse(). However, its API has the same problem as arcTo()'s.²

The benefits of SVG's arc command
SVG's arc command is vertex based, so it's consistent with p5's commands. By adopting a version of it, p5 is not just internally consistent, but it's also consistent with all of SVG's path commands.³ This has benefits for both users and library developers. Users familiar with SVG will immediately understand how arcVertex() works, and library developers should be able to directly translate SVG path commands to p5 vertex commands.

Footnotes

1. The curveVertex() function of p5 introduces a subtle variation, in which the vertex is actually a control point (it guides the curve, but the curve does not pass through it). Nonetheless, with a separate function call, the user is able to specify where the curve will end. ↩

2. The SVG arc command and the canvas ellipse() method implement two different parameterizations of elliptical arcs. The the SVG implementation notes helpfully refer to these as the endpoint parameterization and the center parameterization, respectively. I thought a little about whether a simpler endpoint parameterization is possible, but I'm not sure if it could be simple enough to justify diverging from both the canvas and SVG APIs. ↩

3. Internal consistency is actually cited in the SVG implementation notes as a reason for the design of its arc command. The notes are clearly written and address the same issue that we face. ↩

[davepagurek]

That makes sense. In the MDN example, they also follow up arcTo with lineTo to ensure it always ends at the target point. That might be a way of using an API like the native canvas one while still preserving the quality of ending at the specified point?

Aside from the API of arcTo appearing simpler, I'm mostly considering it further because I assume we'll have to end up translating our API into an arcTo command for 2D mode anyway. Although it'll have to be turned into line segments for WebGL, so we'll be doing that part from scratch regardless. I don't have a strong preference, so if there are more issues with a combined arcTo + lineTo, I'm happy to go with the API that you suggested!

[GregStanton]

@davepagurek I really appreciate you helping to vet this idea! I think it's always good to thoroughly vet an addition to an API, especially a core feature like this.

I'll respond with some additional downsides of arcTo() that I see, followed by one approach that may address your concern about the implementation of arcVertex().

Downsides of arcTo()
Here are a few issues in addition to it not ending at a specified point:

• It doesn't actually create an arc. It creates a piecewise path made up of linear and circular pieces. It already does this without a follow-up call to lineTo(), since the arc may need to be connected to the most recent path point with a line segment. So, it's not a curve primitive in the same way that a pure circular arc is.
• It only makes circular arcs, rather than elliptical arcs, so it's less general. If we try to generalize it and also take away the linear pieces, we end up with something like the SVG arc command.
• It cannot be used with p5's existing vertex commands to reproduce general SVG paths, since it only produces circular arcs. That seems to limit applications.¹

In general, I think arcTo() is mainly provided as a more convenient way to round corners. Its behavior can be achieved in principle with canvas's ellipse() and lineTo() methods. The more general, primitive method is ellipse(), which actually draws not just ellipses but also elliptical arcs. My feeling is that the priority is to add general primitives first.²

Implementing arcVertex()
Instead of using arcTo() for 2D mode, one option is to convert the endpoint parameterization of SVG's arc command to the center parameterization of canvas's ellipse(), and then draw it with canvas's ellipse().³ For the mathematical details on this exact conversion, see the SVG implementation notes. The authors of the SVG spec anticipated the need to convert to other APIs.

As always, I'm eager to hear feedback on any of this!

Footnotes

1. For example, the p5.teach add-on library by @two-ticks adds a dependency (anime.js) in order to animate typeset math expressions in the style of Manim. It uses MathJax to convert the expressions to SVG, which is then animated with anime.js. I suspect this requirement could be satisfied with p5 alone if it were possible to reproduce SVG paths with beginShape()/endShape(). I'm very curious to hear others' thoughts on this. ↩

2. If we want to add a utility function that creates composite paths like arcTo(), its convenience would need to be weighed against the complication it introduces: it wouldn't correspond neatly to any p5 curve primitive. The convenience might well outweigh that complication! But it's something to consider. ↩

3. When I was looking into this originally, one thing that surprised me is that p5's own arc() and ellipse() are not implemented with the canvas's ellipse(). The implementation approximates the ellipse with Beziér curves. Maybe this was easier to use with WebGL, since the Beziér curves had already been adapted for that? ↩

[davepagurek]

Instead of using arcTo() for 2D mode, one option is to convert the endpoint parameterization of SVG's arc command to the center parameterization of canvas's ellipse(), and then draw it with canvas's ellipse(). For the mathematical details on this exact conversion, see the SVG implementation notes.

Thanks for the link, this will be helpful for implementing later! It looks like ellipse() will be able to do what we need it to.

It only makes circular arcs, rather than elliptical arcs, so it's less general. If we try to generalize it and also take away the linear pieces, we end up with something like the SVG arc command.

This is a good point. Do you think we can make a version of the API where the elliptical aspects of the command come last and are optional, so that if they're missing we can default them to circular arcs? I assume that will likely be the most common use.

When I was looking into this originally, one thing that surprised me is that p5's own arc() and ellipse() are not implemented with the canvas's ellipse(). The implementation approximates the ellipse with Beziér curves. Maybe this was easier to use with WebGL, since the Beziér curves had already been adapted for that?

I'm actually not sure why the 2D mode uses Bezier paths. The WebGL mode version just uses trig functions.

[GregStanton]

Replying to #6459 (comment) by @davepagurek:

Thanks for the link, this will be helpful for implementing later! It looks like ellipse() will be able to do what we need it to.

Sure thing! I'm glad that helped.

Do you think we can make a version of the API where the elliptical aspects of the command come last and are optional, so that if they're missing we can default them to circular arcs? I assume that will likely be the most common use.

The arcVertex API that I proposed accommodates the circle case in the same way that p5's arc does. As in the first example of the p5 reference page for arc, the user can create circular arcs by choosing the width and height parameters to be equal. I think it's nice to be as consistent as possible, so this seems like a good solution to me.

The only other option that's obvious to me is to do something like p5's ellipse. In that case, it's possible to omit the height parameter, in which case it works just like circle, since the height is automatically set equal to the width. If we try this with arcVertex by moving the width parameter to the end, we'd introduce inconsistencies. Most significantly, arcVertex wouldn't end in vertex parameters like p5's other vertex functions.

I'm actually not sure why the 2D mode uses Bezier paths. The WebGL mode version just uses trig functions.

I got curious, so I did a little digging. It looks like the use of Bézier curves in p5's 2D implementation of arc and ellipse dates to p5's addition of ellipse on July 4, 2013. At that time, the canvas didn't have a native ellipse method.¹

Would it make sense to create a separate issue to update p5's implementation of arc and ellipse, as part of modernization efforts? The current implementation is complicated enough that the source comments include a link to a paper on the underlying math; using the canvas's native ellipse should be a pretty significant simplification.

Footnotes

1. According to MDN's browser compatibility table for CanvasRenderingContext2D, bezierCurveTo was implemented in browsers as early as 2005, whereas the ellipse method didn't appear in any of the listed browsers until November 2013. ↩

[davepagurek]

I think that all makes sense, thanks for bearing with me and fur such thorough explanations! I think this API looks good to me then.

For the 2d implementation of ellipse, making another issue for that would be great, thanks!

[GregStanton]

Replying to #6459 (comment) by @davepagurek:

I think that all makes sense, thanks for bearing with me and fur such thorough explanations! I think this API looks good to me then.

Absolutely! I'm glad I'm not the only one considering the design from various perspectives.

For the 2d implementation of ellipse, making another issue for that would be great, thanks!

Done: #6485

---

Do you have a recommendation for the next step? I'm not sure if @Gaurav-1306 has been following the discussion, but they expressed interest in working on the implementation. Hopefully, our discussion will help with that. Here are the most relevant parts:

Specification for out-of-range parameters
It seems like a good idea to be consistent with how the SVG specification handles parameters that are out of range. This comes from the W3C Candidate Recommendation for SVG 2.

Implementing arcVertex()
One option is to convert the endpoint parameterization of SVG's arc command to the center parameterization of canvas's ellipse(), and then draw it with canvas's ellipse(). For the mathematical details on this exact conversion, see the SVG implementation notes.

[Garavitey]

Hey I have been following your discussions and would still like to implement this.

Let me understand all that you guys discussed and get back with the implementation details.