[p5.js 2.0 RFC Proposal]: New API for vertex functions

[GregStanton]

Increasing access

Implementing this proposal would

• decrease complexity
• increase consistency
• enable new features

As a result, p5.js would be more accessible to beginners, while offering others access to a wider feature set.

Which types of changes would be made?

• [X] Breaking change (Add-on libraries or sketches will work differently even if their code stays the same.)
• [X] Systemic change (Many features or contributor workflows will be affected.)
• [X] Overdue change (Modifications will be made that have been desirable for a long time.)
• [ ] Unsure (The community can help to determine the type of change.)

Most appropriate sub-area of p5.js?

• [ ] Accessibility
• [ ] Color
• [X] Core/Environment/Rendering
• [ ] Data
• [ ] DOM
• [ ] Events
• [ ] Image
• [ ] IO
• [ ] Math
• [ ] Typography
• [ ] Utilities
• [X] WebGL
• [ ] Build process
• [ ] Unit testing
• [ ] Internationalization
• [ ] Friendly errors
• [ ] Other (specify if possible)

What's the problem?

Short version

The current API for vertex functions contains complexities, inconsistencies, and hard-to-extend features. It's included below for easier comparison with the proposed API.

// vertex functions (brackets indicate optional parameters)
// copied from the syntax section of the p5.js reference
// note that arcVertex() is planned but not currently included

vertex(x, y, [z], [u], [v])
// arcVertex(x2, y2, x3, y3, x4, y4, x5, y5)
// arcVertex(x2, y2, z2, x3, y3, z3, x4, y4, z4, x5, y5, z5) 
quadraticVertex(cx, cy, x3, y3)
quadraticVertex(cx, cy, cz, x3, y3, z3)
bezierVertex(x2, y2, x3, y3, x4, y4)
bezierVertex(x2, y2, z2, x3, y3, z3, x4, y4, z4)
curveVertex(x, y, [z])

Long version

Eleven distinct problems arise from the current API for vertex functions. Below, each problem is listed and tagged with a problem type. (In case we want to modify the proposed solution, we can check the new version against this list.)

1. Texture coordinates: Texture coordinates are currently supported inconsistently, and it's infeasible to fix this without a change to the API. Specifically, the user can specify texture coordinates to vertex() but not to quadraticVertex(), curveVertex(), or bezierVertex(), as noted in #5722. Under the current API, specifying texture coordinates would require up to fifteen parameters in a single function call, with the following syntax: bezierVertex(x2, y2, z2, u2, v2, x3, y3, z3, u3, v3, x4, y4, z4, u4, v4). [Inconsistency/Inflexibility]
2. Parameter grouping: The last example may look like it contains a typo, but it doesn't. The current parameter lists for quadraticVertex() and bezierVertex() really do start with x2, y2/x2, y2, z2. That's because the first set of parameters x1, y1/x1, y1, z1 must be specified separately, and we need a way to distinguish the second, third, and fourth points since they're grouped together in the same function call. [Complexity]
3. Mixed commands: If we want to make a quadratic or cubic Bézier curve, that first point x1, y1/x1, y1, z1 gets passed to vertex(). But that's just for Bézier curves. If we want to make a Catmull-Rom spline, the first point and all successive points get specified directly to curveVertex(). In other words, the current API allows the user to call vertex() to start and continue a polyline, and to call curveVertex() to start and continue a Catmull-Rom spline; however, to start a shape with a quadratic or cubic Bézier curve, the user needs to mix commands. [Inconsistency]
4. Singularity of "vertex": A function like bezierVertex() is named after a single vertex, but it accepts coordinates for three points. We may try to reconcile this by identifying the first two of those points as "control points" and the last point as a "vertex," but this is an uncommon distinction, and it doesn't hold up: we cannot reconcile it with the meaning of "vertex" in curveVertex(). [Inconsistency]
5. Multiple signatures: With the current API, it's necessary to specify multiple signatures for the same function, which increases complexity. For example, we have both bezierVertex(x2, y2, x3, y3, x4, y4) and bezierVertex(x2, y2, z2, x3, y3, z3, x4, y4, z4). Each of these signatures looks rather complicated by itself. [Complexity]
6. Missing primitives: Right now, bezierVertex() and bezier() are supported, and curveVertex() and curve() are supported. We also have quadraticVertex(), but quadratic() is not supported. (I've proposed separately that we should introduce a new function arcVertex() to address a similar inconsistency.) [Inconsistency]
7. "Quadratic" confusion: The name quadraticVertex() is confusing for multiple reasons. Both quadraticVertex() and bezierVertex() produce Bézier curves, but only one of them contains the name "Bézier"; in other words, one function is named after the type of curve while the other is named after the order of the curve. Also, many p5 users are students who will have recently learned in algebra that "the vertex of a quadratic" (a parabola) corresponds to its lowest or highest point; that's not generally true of a vertex specified with quadraticVertex(). [Inconsistency]
8. Higher-order Bézier curves: With the current API, supporting general higher-order Bézier curves is not possible. (Even if p5.js may not want to implement higher-order Bézier curves, add-on libraries may want to.) [Inflexibility]
9. Bézier surfaces: Right now, supporting Bézier surfaces (in p5.js or in an add-on library) would introduce more complications to the API. For example, a quadratic Bézier triangle is defined by six control points. If we specify the first of these with vertex() and specify the next four with quadraticVertex(), we only have five vertices. We could potentially use vertex() to specify the sixth vertex at the end, but this is inconsistent with how vertex() is used everywhere else, and it still requires us to mix command types to create a single primitive. [Inflexibility]
10. Bézier syntax vs. other syntax: The syntax for the vertex functions is inconsistent. The current API bundles multiple points together into a single function call for quadratic and cubic Bézier curves, but it uses one function call per point for polylines and Catmull-Rom splines. [Inconsistency]
11. Two meanings of "curve": The name curveVertex() uses a general term for a special shape, which leads to inconsistencies. For example, in the p5 reference, “Curves” is used as a general section heading that includes Béziers, while curve() specifically creates Catmull-Rom splines only. This may lead to confusion. For instance, if we introduce a function such as curveType() for different spline implementations, it will be hard to guess whether it applies to all curves or only curves made with curveVertex(). [Inconsistency]

What's the solution?

The main idea is to pass only one vertex into each vertex function.

Proposed API

The proposed API is indicated below.[^1]

// mode function (could default to n = 3, with native support for n = 2 and 3, at least)
bezierOrder(n)

// vertex functions (brackets indicate optional parameters)
vertex(x, y, [z], [u], [v])
arcVertex(x, y, [z], [u], [v])
bezierVertex(x, y, [z], [u], [v])
splineVertex(x, y, [z], [u], [v])

Amazingly, this simple API solves all eleven problems listed above 🤯The basic design was inspired by this comment from @davepagurek.

Notes:

• bezierOrder() eliminates the need for quadraticVertex()
• arcVertex() is based on the latest iteration of #6459
• splineVertex() replaces curveVertex()[^2]

Code examples

Example 1: Consistency across all types of curves Note: Conceptually, polylines can be viewed as linear splines or as chained first-order Béziers.

Polylines (no change proposed)	Splines (proposed)	Bézier curves (proposed)
beginShape(); // polyline // (with three segments) vertex(x0, y0, z0); vertex(x1, y1, z1); vertex(x2, y2, z2); vertex(x3, y3, z3); endShape();	beginShape(); // Catmull-Rom spline // (a type of cubic spline) splineVertex(x0, y0, z0); splineVertex(x1, y1, z1); splineVertex(x2, y2, z2); splineVertex(x3, y3, z3); endShape();	beginShape(); // cubic Bezier curve bezierOrder(3); bezierVertex(x0, y0, z0); bezierVertex(x1, y1, z1); bezierVertex(x2, y2, z2); bezierVertex(x3, y3, z3); endShape();

---

Example 2: Clear function names, readable parameter lists, and flexible design Note: Chaining quadratic and cubic Bézier curves does not currently work in p5, but issue #6560 aims to address this.

Chained Bézier curves (current)

Chained Bézier curves (proposed)

beginShape(); // two quadratic Bezier curves // explicit starting vertex required vertex(x0, y0, z0); quadraticVertex(x1, y1, z1, x2, y2, z2); quadraticVertex(x3, y3, z3, x4, y4, z4); // one cubic Bezier curve // implicit starting vertex at x4, y4, z4 bezierVertex(x5, y5, z5, x6, y6, z6, x7, y7, z7); endShape();

beginShape(); // two quadratic Bezier curves // explicit starting vertex required bezierOrder(2); bezierVertex(x0, y0, z0); bezierVertex(x1, y1, z1); bezierVertex(x2, y2, z2); bezierVertex(x3, y3, z3); bezierVertex(x4, y4, z4); // one cubic Bezier curve // implicit starting vertex at x4, y4, z4 bezierOrder(3); bezierVertex(x5, y5, z5); bezierVertex(x6, y6, z6); bezierVertex(x7, y7, z7); endShape();

---

Example 3: Consistency across all chained shapes (curves, triangles, and quads) Note: Bézier control points are rendered below as a visual aid, but the code for that is not shown.

Quad strip (no change proposed)	Bézier curves (proposed)
beginShape(QUAD_STRIP); // first quad // four vertices required vertex(30, 20); vertex(30, 75); vertex(50, 20); vertex(50, 75); // one more quad // two vertices required (two reused) vertex(65, 20); vertex(65, 75); // one more quad // two vertices required (two reused) vertex(85, 20); vertex(85, 75); endShape();	beginShape(); // first quadratic Bezier curve // three vertices required bezierOrder(2); bezierVertex(5, 12); bezierVertex(41, 12); bezierVertex(23, 30); // one more quadratic Bezier curve // two vertices required (one reused) bezierVertex(5, 48); bezierVertex(41, 48); // one more quadratic Bezier curve // two vertices required (one reused) bezierVertex(182, 54); bezierVertex(41, 57); endShape();

Pros (updated based on community comments)

• Simplicity: All the complexities noted in the problem statement are eliminated.
• Consistency: All inconsistencies noted in the problem statement are eliminated.
• Flexibility: Multiple new features are possible, with a more intuitive API.
• Readability: Code is easier to read since long lists of positional parameters are eliminated.
• Predictability: An arc starts with arcVertex(), rather than vertex(). Same for other curve types.

Cons (updated based on community comments)

• Breaking changes: Breaking changes will always cause difficulties when they are first introduced, for some people. For example, YouTubers may need to update their video tutorials, and add-on library authors may need to update their code if they want to use the most recent version of p5.js. However, the proposal can be implemented without breaking changes, at a small cost.[^3]
• Differences with other APIs: Changing the p5.js API would mean a bigger departure from the Processing API, the native canvas API, and the SVG API. The latter two API's are similar to p5's, but they sidestep some of the problems by referring to their commands as "curve" commands rather than "vertex" commands. In the context of p5, beginners won't tend to know those other APIs, and more experienced users may have less trouble adapting, so this seems like a smaller concern.

Another issue has also been observed that is currently under discussion, but it's not an issue with the API per se. It's based on usage.

[^1]: We may also want to support texture coordinates when a z-coordinate is not passed. This is currently supported by vertex() (see the last example for texture() in the reference); however, it requires a separate signature for vertex() that is not documented on its reference page (i.e. vertex(x, y, [u], [v])). We'd need to discuss whether the benefits justify the extra complexity (namely, documenting and supporting an extra signature for every type of vertex function). [^2]: For consistency, we could also rename curve() as spline(). [^3]: We can distinguish new and old usage of bezierVertex() by detecting the number of arguments, and we can deprecate the old usage. We could deprecate quadraticVertex() and curveVertex() entirely with the @deprecated tag in the inline documentation.

Proposal status

Under review

Updates

This proposal has been updated to reflect some small adjustments, based on the discussion in the comments section:

1. bezierOrder() was added to the API so that chained segments of different orders can be distinguished
2. arcVertex() was added based on the current consensus in #6459
3. curveVertex() was replaced with splineVertex() based on Problem 11, which was added to the problem list

Additional code examples have also been included.

[davepagurek]

Thanks for the writeup @GregStanton! I'm in favor of the consistency we'd get from an API like this, as well as the readability (any time a function has a bunch of positional arguments, I find myself having to write comments between arguments to remind myself which is which.)

For curveVertex texture coordinates, I think the same pattern we're suggesting for bezier vertices will also apply. When getting a position along a Catmull-Rom curve in between two control points, the interpolated position is a weighted sum of the curve's control points. I think we can do the same weighting for texture coordinates if we have one texture coordinate per control point, similar to position.

[limzykenneth]

I do really like the overall simplicity and flexibility this can potentially give. One thing I would like to illustrate this proposal a bit more would be some more complete code examples, maybe even a before and after versions to make the use case clearer.

I'll probably share this with my colleagues teaching with p5.js to get their thoughts as well.

[GregStanton]

@limzykenneth Thanks! Code examples are a great idea. Here's a list of examples that illustrates some key differences:

Example 1

Current syntax:

beginShape();
vertex(x0, y0, z0); 
bezierVertex(x1, y1, z1, x2, y2, z2, x3, y3, z3);
endShape();

beginShape()
curveVertex(x0, y0, z0); 
curveVertex(x1, y1, z1); 
curveVertex(x2, y2, z2); 
curveVertex(x3, y3, z3);
endShape();

Proposed Syntax:

beginShape();
bezierVertex(x0, y0, z0); 
bezierVertex(x1, y1, z1); 
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endShape();

beginShape();
curveVertex(x0, y0, z0); 
curveVertex(x1, y1, z1); 
curveVertex(x2, y2, z2); 
curveVertex(x3, y3, z3);
endShape();

Example 2

Current syntax (the Bézier case isn't actually supported, but a user might expect this to work):

beginShape();
vertex(x0, y0, z0, u0, v0);
vertex(x1, y1, z1, u1, v1);
vertex(x2, y2, z2, u2, v2);
vertex(x3, y3, z3, u3, v3);
endShape();

beginShape();
vertex(x0, y0, z0, u0, v0);
bezierVertex(x1, y1, z1, u1, v1, x2, y2, z2, u2, v2, x3, y3, z3, u3, v3);
quadraticVertex(x4, y4, z4, u4, v4, x1, y1, z1, u1, v1);
endShape();

Proposed syntax (contours are used to specify separate pieces of different orders):

beginShape();
vertex(x0, y0, z0, u0, v0);
vertex(x1, y1, z1, u1, v1);
vertex(x2, y2, z2, u2, v2);
vertex(x3, y3, z3, u3, v3);
endShape();

beginShape();
beginContour();
bezierVertex(x0, y0, z0, u0, v0);
bezierVertex(x1, y1, z1, u1, v1);
bezierVertex(x2, y2, z2, u2, v2);
bezierVertex(x3, y3, z3, u3, v3);
endContour();
beginContour();
bezierVertex(x4, y4, z4, u4, v4);
bezierVertex( x1, y1, z1, u1, v1);
endContour();
endShape()

Example 3

Current syntax (the first one will cause an error because it's not supported, due to an inconsistency):

quadratic(x0, y0, x1, y1, x2, y2); 
bezier(x0, y0, x1, y1, x2, y2, x3, y3);

Proposed syntax:

bezier(x0, y0, x1, y1, x2, y2);
bezier(x0, y0, x1, y1, x2, y2, x3, y3);

Example 4

Current syntax (this will produce an error because higher-order Bézier curves aren't currently supported):

beginShape();
vertex(x0, y0); 
bezierVertex(x1, y1, x2, y2, x3, y3, x4, y4);
endShape();

beginShape();
curveVertex(x0, y0); 
curveVertex(x1, y1); 
curveVertex(x2, y2); 
curveVertex(x3, y3); 
curveVertex(x4, y4)
endShape();

Proposed syntax (this assumes we want to support higher-order Bézier curves):

beginShape();
bezierVertex(x0, y0); 
bezierVertex(x1, y1); 
bezierVertex(x2, y2); 
bezierVertex(x3, y3); 
bezierVertex(x4, y4);
endShape();

beginShape();
curveVertex(x0, y0); 
curveVertex(x1, y1); 
curveVertex(x2, y2); 
curveVertex(x3, y3); 
curveVertex(x4, y4);
endShape();

Example 5

Current syntax (this is how a user might try to create a Bézier triangle, but that's not currently supported):

beginShape(TRIANGLES); 
vertex(x0, y0, z0); 
quadraticVertex(x1, y1, z1, x2, y2, z2); 
quadraticVertex(x3, y3, z3, x4, y4, z4); 
vertex(x5, y5, z5); 
endShape();

Proposed syntax:

beginShape(TRIANGLES); 
bezierVertex(x0, y0, z0); 
bezierVertex(x1, y1, z1); 
bezierVertex(x2, y2, z2); 
bezierVertex(x3, y3, z3); 
bezierVertex(x4, y4, z4); 
bezierVertex(x5, y5, z5); 
endShape();

Special cases

Shape built from multiple béziers

One issue with having a single bezierVertex() function (instead of separate functions for quadratic and cubic cases), is that we need some other way to infer the order when a single shape is made out of multiple Bézier curves or surfaces. See Example 2. (A similar situation arises with Bézier surfaces. For example, the case of three cubic Bézier triangles and the case of five quadratic Bézier triangles each require a total of thirty vertices; so, we can no longer determine the order of the surface based on the number of function calls.) One possible solution, based on contours, is indicated in Example 2.

Composite shapes

Currently, composite shapes aren't supported, but #6560 would address this, and it provides more examples of that type in the current syntax.

TODO / Invitation for contributions

1. Fully consider the contour approach to handling multiple pieces of possibly different orders, to make sure it will work.
2. Consider if there are any other cases (e.g. cases of composite shapes) that would be good to explore here.
3. When describing which examples would produce errors in the current version of p5.js, I was using my understanding of the current feature set; I haven't tested those examples yet. If anyone wants to choose reasonable values for the parameters and run the code examples for the current API, that would be a nice, quick contribution.
4. @capGoblin: If I understand correctly, you're already working on a trial implementation for some of this, right? How would you feel about implementing some of the examples of the proposed API above, in the p5.js Web Editor? (You could pass in your own hard-coded values.) We could link this issue to any examples you make; also, if this proposal is accepted, we could maybe turn them into examples for the p5.js reference.
5. @davepagurek Do you have any examples to add? Or would you like to make modifications to the examples I gave?

[limzykenneth]

I want to also invite @peilingjiang who created the p5.bezier addon library to have a look at this. Seeing that your library also deals with Bezier curves and also support higher order Bezier curves, it would be great to hear your thoughts, we can even look at the implementation you have in p5.bezier as a starting point for this too.

[peilingjiang]

Thanks for the invite! Looking at the example code comparisons, I think this would be a very nice update, syntax-wise (I don't know how differently the updated functions will be implemented, so I'll only share some thoughts on the proposed syntax)! The vertex-related syntax would be unified, and having consistent, separate functions with a manageable number of arguments, instead of a crazy list of 9 or 15 arguments, would greatly improve the code readability.

For the implementation, I hope my implementation for the higher-order Bézier curves would be helpful to serve as a starting point for the new native support.

Moreover, I wonder if you would consider having an array of arrays of vertices, e.g.,

beginShape();
bezierVertices([
  [x0, y0, z0, u0, v0],
  [x1, y1, z1, u1, v1],
  [x2, y2, z2, u2, v2],
  [x3, y3, z3, u3, v3]
])
endShape();

I did something similar for the addon for the usability of the API, as managing items in an array (e.g., when adding or removing vertices) would be easier than modifying separate function calls. Moreover, the users may already maintain the positions somewhere else using nested arrays. This would be a further departure from the native Canvas API, but that might not be a bad thing - we could keep the old APIs for a few more minor version updates, mark them as deprecated, and introduce new ones like vertices and bezierVertices.

[GregStanton]

Thanks for your feedback @peilingjiang! Your library looks really cool, by the way. I think it'd be great to flesh out the pros and cons of your API idea, for the sake of discussion. I've already written up a partial list, but that gave me a new idea that I want to think about a bit more. I'll share what I have as soon as I'm able to think it over a bit more.

[GregStanton]

Okay, @peilingjiang! I have some initial feedback to share regarding the API you proposed.

Pros

The bezierVertices() API (as opposed to the bezierVertex() API) has some nice benefits. Here are a few of them.

1. This might make the implementation a bit simpler, since all the data for a path segment is provided in one command.
   1. Right now, we do have a plan for handling an API like the one I've proposed, since that same API is already implemented for curveVertex(). Roughly, the way it works is that each vertex function adds its arguments to a primitive shape object. Since we're going to support composite shapes made of multiple types of primitives, curveVertex() will check to see if the current primitive consists of curve vertices. If so, it will add its data to that segment, and if not, it will start a new primitive shape and add its data to that. With your API, we shouldn't need to check the type of the current segment.
   2. Another issue is that, in order to support different shape kinds in a more extensible way, we end up creating a new curve primitive before checking the type of the current primitive. If the current primitive is already made of curve vertices, the new curve primitive's data is added to that, and then the containing object will be discarded, i.e. the memory should be reclaimed. So we sometimes have a very temporary object, which should be easier to avoid with your API.
2. The API would match the internal representation more closely, since internally, we end up gathering up all the vertices into a primitive shape object. I already noted above that this may simplify the implementation, but it might have other benefits.
3. In the proposed API, it's not quite as easy to create composite paths made up of Bézier curves of different orders; however, this is probably a fairly uncommon use case, and surrounding each piece with beginContour()/endContour() is a pretty simple solution (for a piece with control points A, B, C, and D, the user would also have to make sure the next piece starts with D, since using contours means it's no longer implied that pieces are glued together; but that seems like a minor issue).

Cons

The bezierVertices() API also has some potential cons.

1. With the WEBGL renderer, it's possible to specify color (stroke or fill) for each vertex. Here's an example sketch. Similarly, the user can specify a normal vector for each vertex with normal(). It's not immediately obvious how to achieve these kinds of features in a simple way with bezierVertices(). (Thanks to @davepagurek for raising this point in conversation.)
2. Nested array arguments are not found anywhere else in the p5.js API, as far as I know, so this would be less consistent with the usual interface.
3. For beginners, the extra complexity of a nested array argument might be significant.
4. This API could lead to an inconsistency when we introduce arcVertex(), which I proposed previously in #6459; arcVertex() is a crucial feature, for reasons cited in that issue. Fortunately, this discussion gave me an idea for a new arcVertex() API that would eliminate this inconsistency; we're in the process of exploring its viability.

Questions for the community

1. Does anyone have any additional pros or cons to add?
2. Does anyone have any other variations of the API for us to consider?

Edit: Added first point under cons, about features of the WEBGL renderer.

[davepagurek]

Just noticed a small thing that might need some clarification, and that's how to distinguish multiple segments of bezier curves.

In current p5, let's say I want to draw a square with two rounded corners, plus a cutout contour:

beginShape() vertex(20, 20) vertex(100, 20) quadraticVertex(180, 20, 180, 100) quadraticVertex(180, 180, 100, 180) vertex(20, 180) beginContour() vertex(40, 40) vertex(40, 100) vertex(100, 100) vertex(100, 40) endContour() endShape(CLOSE)

There are a few things going on here:

• each quadratic segment starts from where the last segment or vertex left off
• there are two quadratic semgents side-by-side
• there's also a contour in the middle that is a separate path

I think based on the proposal currently, the code would look like this:

beginShape()
vertex(20, 20)
vertex(100, 20)

// top right corner
beginContour()
bezierVertex(100, 20)
bezierVertex(180, 20)
bezierVertex(180, 100)
endContour()

// bottom right corner
beginContour()
bezierVertex(180, 100)
bezierVertex(180, 180)
bezierVertex(100, 180)
endContour()

vertex(20, 180)

// The inner contour
beginContour()
vertex(40, 40)
vertex(40, 100)
vertex(100, 100)
vertex(100, 40)
endContour(CLOSE)

endShape(CLOSE)

• Right now it's using begin/endContour to disambiguate different sections. Currently, contours start separate shapes, similar to a moveTo in native canvas. I think these two uses are different, as fill winding order needs composite paths to still be part of one contour in order to calculate the winding order of the whole path correctly.
  • Alternatively, can we call the segment boundaries begin/endSegment and leave begin/endContour as is?
• If I'm understanding correctly, I think it also requires values to be duplicated when paths connect, and it's only when they're disconnected that it moves to a new shape.
  • I think it's more common to have paths with multiple segments than to have higher order curves, so I think this it's better to prioritize those two cases in the opposite order.

A suggestion

I think it might solve some of those problems if you still have separate methods for separate orders as before, e.g. bezierVertex and quadraticVertex (and adding new ones for higher orders), but split each control point into multiple function calls.

So this:	...becomes this:
beginShape() vertex(20, 20) vertex(100, 20) quadraticVertex(180, 20, 180, 100) quadraticVertex(180, 180, 100, 180) vertex(20, 180) beginContour() vertex(40, 40) vertex(40, 100) vertex(100, 100) vertex(100, 40) endContour() endShape(CLOSE)	beginShape() vertex(20, 20) vertex(100, 20) quadraticVertex(180, 20) quadraticVertex(180, 100) quadraticVertex(180, 180) quadraticVertex(100, 180) vertex(20, 180) beginContour() vertex(40, 40) vertex(40, 100) vertex(100, 100) vertex(100, 40) endContour(CLOSE) endShape(CLOSE)

Now:

• you don't need contours to disambiguate segments: quadratic segments will always need two quadraticVertex calls and cubic segments will always need three bezierVertex calls, so you can just continue to add more and p5 will know where each one ends
• contours still always represent whole paths this way
• there's less code involved when you need to make longer, multi-segment paths, which I think is quite common
• every segment always picks up from where the last segment left off without the need for duplication

Like in your initial proposal:

• you still have a reasonable amount of params per function, with the ability to add z and/or uv coordinates to each
• you can still place fill() or normal() between each control point if you want to change those per control point instead of per segment

curveVertex

In current p5, curveVertex is the odd one out when it comes to picking up where the last segment left off, but that's mostly because it interprets the whole shape as curve vertices whenever you use a single curve vertex. Here are some thoughts about how to handle them now.

I think it makes sense for curve vertices to connect to the last point if it exists to add API consistency. I imagine Catmull-Rom splines like being a set of points, where we determine the tangents by looking at line between the previous and text points:

I'm imagining that if you put a Catmull-Rom curve in the middle of some other curves, it would connect thesecond curveVertex(which is the first that gets drawn) to the previous segment, and connect the second-last curveVertex to the next segment. e.g.:

[GregStanton]

Thanks so much @davepagurek! This is a great discussion.

Disambiguating primitives

I'm glad you raised the issue about using beginContour()/endContour() for two different purposes. This leads us to a possible improvement: how about having beginPrimitive()/endPrimitive() (instead of beginSegment()/endSegment()) and beginContour()/endContour() for the two purposes? The "Primitive" in the name would coincide with our current refactoring plan, which handles not just segments but other types of shape kinds as well.

Having beginPrimitive()/endPrimitive() in addition to beginContour()/endContour() would have several benefits, including improvements not directly related to the problem you identified. I think that's a sign of a good design. Here's a list of advantages:

1. It seems to solve the problem of disambiguating segments (or other primitives) internally.
2. It improves readability of the user's code. For example, let's say you're using the TRIANGLES shape kind. Right now, we may have fifteen vertex() calls in a row, and it's up to the person reading the code to mentally separate vertex() calls into groups of three, and then determine that the code should produce five triangles based on that. If users wrap every three vertices in beginPrimitive()/endPrimitive(), it's easier to determine that the code should produce five triangles. (The code would be a bit longer, but the added length seems worthwhile.)
3. This allows us to support implicit start vertices for segments in composite paths, since beginPrimitive() won't entail a moveTo() operation for segments like beginContour() does.
4. Having beginPrimitive()/endPrimitive() seems to provide most of the benefits of bezierVertices(), without the downsides we identified.
   1. The API might allow us to simplify the implementation. (This requires more thought, but I guess beginPrimitive() may just set a flag to indicate that a new primitive is to be started, and it'd no longer be necessary to check the type of the previous primitive.)
   2. The API would match the internal representation more closely.
   3. It's still possible to specify color and normal data per vertex.
5. We'd still be able to solve problems 6, 7, 8, and 9 from the original proposal; using quadraticVertex() for disambiguation would reintroduce those problems or replace them with new problems.

Implicit start vertices

Yep! The current refactoring plan handles curveVertex() in the way that you described. Each type of segment will be represented internally by its own class (LineSegment, BezierSegment, etc.) These classes implement the Segment interface, which has the methods getStartVertex() and getEndVertex(). These can work differently depending on the type of segment. For example, the getEndVertex() method of a CurveSegment object will get its second-to-last vertex. So, "end vertex" doesn't refer to the last vertex specified, since that may be a control point that's not on the segment itself; instead, it refers to the vertex that's on the actual end of the segment. If we can come up with a clearer name, that might clear up any confusion. Maybe getStartPoint() and getEndPoint()?

Note: These are initial thoughts. It will be good to confirm the details when time permits.

[davepagurek]

I think beginPrimitive()/endPrimitive() addresses the conflicts with beginContour, so that makes sense, thanks! Engineering-wise, I think this all would be safe to implement.

I think as a matter of opinion, I'm still unsure that the extra code required to surround each segment by begin/endPrimitive is worth it? It seems like it has the following pros:

• It can support higher-order Beziers more easily
• It addresses the confusing naming of quadraticVertex and bezierVertex
• It makes segment boundaries more explicit in code
• It maps more closely to the internal structure

The con for me is really just:

• It makes it more verbose to write composite paths, involving duplicated vertices for continuity

At least in my own experience, I've rarely felt the need to go higher than a cubic Bezier, and SVG/CanvasRenderingContext2D APIs don't natively support them either. I'd still love to support them, but I'm personally OK going with a more complex API for those since I see them as a very special case. Meanwhile, most shapes I'd want to draw (imagine drawing text glyphs as a motivating example) are composed of connected lines and curves, often with many connected cubic segments. Since a single text glyph can have upwards of 20 segments in it, and each segment would now need a duplicate vertex to remain connected, this adds a lot of overhead, which gives me pause.

As an alternative, I think if we break each control point into their own call but don't try to support multi-order bezier and don't try to surround segments with other functions, we'd still check the other boxes we wanted.

That's just an opinion based on my own experience though! I want to hear if other people's experience is similar to that too.

As a final aside, I think if we keep separate methods for the different bezier orders, maybe it's worth aliasing bezierVertex to cubicVertex and referring to it as the latter in our docs.

[GregStanton]

Thanks @davepagurek! I'll reply to your points about using beginPrimitve()/endPrimitive() to distinguish primitive shapes, as well as your ideas about naming.

Considerations for beginPrimitive()/endPrimitive()

Duplicate vertices

With beginPrimitve()/endPrimitive(), I don't think we need to duplicate vertices for continuity. That's what I meant by the following:

This allows us to support implicit start vertices for segments in composite paths, since beginPrimitive() won't entail a moveTo() operation for segments like beginContour() does.

If I'm thinking about that incorrectly, please let me know!

Consistency

For me, part of the problem right now is that Bézier curves are already a special case that needs to be thought about differently. If we support higher-order Bézier curves and distinguish individual segments with beginPrimitive()/endPrimitive(), then all segment primitives will work in a consistent way (I'll paraphrase a comment I made on #6459):

With the proposed API, none of the vertex functions has an upper bound on the number of vertices that may be specified:

1. vertex() works with any number of vertices greater than one
2. bezierVertex() works with any number of vertices greater than two
3. curveVertex() works with any number of vertices greater than three
4. arcVertex() works with any number of vertices greater than four

General notes on naming

I'm glad you raised the issue of naming.

quadraticVertex()

I think quadraticVertex() is a problematic name by itself (see Problem 7 in the body of this issue). Regarding the name bezierVertex(), cubicVertex() is better in some ways, but it introduces other problems; for example, Catmull-Rom splines are also cubic, and there'd be no obvious indication in the API whether we're using Bézier curves or something else. This discussion also raises an issue with curveVertex() that's been in the back of my mind...

curveVertex()

The name "curve" kind of pollutes the namespace since there are a lot of possible curves, and now we can't use "curve" to refer to anything but Catmull-Rom splines, unless we want to be inconsistent. We can already see this inconsistency in the p5.js reference, where "Curve" is used as a generic section heading for functions that include "curve()" and also "bezier()". Using "curve" to refer to Catmull-Rom splines is also inconsistent with the native canvas API's use of the term "curve" (it uses that term in bezierCurveTo(), for example).

In other words, "curve" is ambiguous since it doesn't specify the type of curve. The name catmullRomVertex() is a bit long and maybe hard to spell, so maybe hermiteVertex()? This would be pretty specific, it'd be consistent with the name bezierVertex() in that both are named after people, and it'd allow some flexibility (e.g. Cardinal splines, Catmull-Rom splines, and Kochanek–Bartels splines are Hermite splines with different choices of tangents). I feel like it might take some getting used to, and naming ideas after people can lead to other problems (but for better or worse, this usage is pretty well established and won't be easy to change).

Another option is something like splineVertex(), which is not ideal since Béziers are also sometimes referred to as splines, but it's at least more precise than curveVertex().

Feedback welcome! / Mock reference page

Just to be clear, I haven't fully thought through beginPrimitive()/endPrimitive() yet, and I'm making these points for the sake of discussion. So it'd be great if anyone wants to add to their feedback! Fleshing out a mock documentation page could be helpful too; that would force us to think through the different uses and how we'd explain them.

[davepagurek]

This allows us to support implicit start vertices for segments in composite paths, since beginPrimitive() won't entail a moveTo() operation for segments like beginContour() does.

I think the issue I was thinking of is that, if there isn't an implicit moveTo, then a cubic vertex segment only needs 3 control points (the fourth is borrowed from the previous curve.) In example 1 above though, we have this:

Current API	Proposed API
beginShape(); vertex(x0, y0, z0); bezierVertex(x1, y1, z1, x2, y2, z2, x3, y3, z3); endShape();	beginShape(); bezierVertex(x0, y0, z0); bezierVertex(x1, y1, z1); bezierVertex(x2, y2, z2); bezierVertex(x3, y3, z3); endShape();

Here we've got all four in the segment. I guess the point I'm unclear on is whether or not that's a special case for just the first segment? e.g. would the following also be valid?

beginShape();

vertex(x0, y0, z0); 

beginPrimitive();
bezierVertex(x1, y1, z1); 
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endPrimitive();

endShape();

If it is, then does that mean that within the first primitive, bezier segments will always have one fewer point than in the later ones?

For me, part of the problem right now is that Bézier curves are already a special case that needs to be thought about differently.

For context, what is the special case you're referring to here?

[GregStanton]

Thanks for bringing up these points @davepagurek! This is all helpful for filling in the details.

Bézier curves are a special case?

Yeah, I probably could've worded that more clearly. What I meant was that vertex() can be called an unbounded number of times to create a polyline, and curveVertex() can be called an unbounded number of times to create a Catmull-Rom spline. With the latest idea in #6459, we can even call arcVertex() an unbounded number of times to create an elliptical arc that fits the data. If we continue to use quadraticVertex() for quadratic Béziers and bezierVertex() for cubic Béziers, then unlike all the other vertex functions, these may only be called a fixed number of times.

So, I really meant that quadraticVertex()/bezierVertex() represent a distinct case. If we remove quadraticVertex() and use bezierVertex() to specify Bézier curves of any order, then Bézier curves will no longer be a distinct case. They'll work the same as all the other kinds of curves. That's a simplification regardless of whether people end up using higher-order Bézier curves, since we won't have to remind them to never use quadraticVertex() more than three times and to never use bezierVertex() more than four times.

Implied beginPrimitive()/endPrimitive()?

For the very first primitive, we might want to make beginPrimitive()/endPrimitive() optional, so that the following two code snippets do the same thing:

With beginPrimitive()/endPrimitive():

beginShape();
beginPrimitive();
bezierVertex(x0, y0, z0); 
bezierVertex(x1, y1, z1); 
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endPrimitive();
endShape();

Without beginPrimitive()/endPrimitive():

beginShape();
bezierVertex(x0, y0, z0); 
bezierVertex(x1, y1, z1); 
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endShape();

There are pros and cons to making these commands optional for the first primitive. If we always use beginPrimitive()/endPrimitive(), we'll increase consistency, but we'll also add an extra pair of commands that won't be entirely necessary in all cases. I guess I'd probably prefer to err on the side of consistency in the reference examples, but we could make it so that the code still works if the first primitive is specified without beginPrimitive()/endPrimitive() (then users who forget these commands won't have to do any debugging).

Handling the first vertex

I think it makes sense for all of a primitive's vertices to always go inside beginPrimitive()/ endPrimitive(), including the first vertex. For example, we could make it so that a cubic Bézier segment can always be made with four vertices, each of which would be passed to bezierVertex():

beginPrimitive();
bezierVertex(x0, y0, z0); 
bezierVertex(x1, y1, z1); 
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endPrimitive();

However, if the first vertex duplicates the last vertex of a previous primitive, then we could allow the first vertex to be omitted.

I don't think we ever need to use vertex() to specify a vertex in any kind of segment except a line segment (I guess using vertex() to start off other kinds of segments is only necessary in the current API because quadraticVertex() and bezierVertex() aren't currently designed to accept a single vertex).

Implementation notes

I haven't thought through the implementation yet, but I wanted to reply quickly to keep the conversation going. As a next step, one thing we might consider is replacing the segment primitives in our refactoring plan with classes for polylines, Béziers, Catmull-Rom splines, and elliptical arcs. Each of these could hold an unbounded number of vertices. For example, the polyline class would replace the line segment class. That way, we could specify a whole polyline between beginPrimitive()/endPrimitive(), and that would match the internal representation.

[davepagurek]

Thanks for explaining! I think my confusion about the special casing is because I saw a different pattern in vertex/quadraticVertex/bezierVertex: all can be used to chain multiple segments, but each segment has an increasing number of control points (1, 2, then 3) from the last point. In fact, vertex() can be seen as a linear bezier, which is just a line segment, needing no control point in the middle. In that sense, adding multiple vertices isn't different from cubic beziers, since each straight line is a segment, not the whole polyline.

(That's also why curveVertex felt like the odd one out to me, where all the points make up one segment. For what it's worth, the curveVertex workflow feels pretty separate from the rest, which are shared in other vector software. A possibly simplifying mental model would just be to treat curve vertices as a shortcut to bezier segments rather than a "real" primitive?)

One of the things that still feels inconsistent in the variable-order proposal is that multiple vertices adds more segments, but multiple of arc or bezier vertices increases the order of the same segment. To me it feels that to be consistent, more vertices in a row would do a line of beat fit through them rather than a polyline. I think the heart of what I'm suggesting is to always add more segments as the standard behavior.

The shift I was initially imagining was from grouping all control points of a segment extension into a single function call, to putting each control point into its own call., and the difference between segment extension types would be the interval at which a whole segment is complete. So vertex() calls, needing only one control point, add a new segment each time, quadratic points add a new segment every other point, cubic every three, and one could add quartic and quintic in the future that add a segment every four and five. (One could maybe add a generic version where you pass in the order into the first parameter.)

Of course, this is all from a frame of mind where chaining is key. I still think this in my own work this is the case that is most common, where paths are composed of many segments. I ideally want the freedom that vertex() has in your proposal, where you can keep chaining more of them without boilerplate, for bezier curves too, since I think in your proposal right now every cubic segment would need to be bounded by begin/endPrimitive. Do you think there's anything we can do in the API proposal to make that use case a bit easier?

[davepagurek]

Another thought: if we do go the route of having chains of vertices be all one segment like you're suggesting, maybe curve vertices don't have to be a separate thing, but just an interpolation strategy for those vertices?

• The default value is linear
• The behaviour of Catmull-Rom splines where the first and last points don't render seems to be one of the most confusing aspects of it. maybe rather than keeping that in the exact form it's currently in, we can do something that goes through all the vertices?
  • e.g. for midpoint vertices, get their tangents from adjacent points like normal, but for endpoints, take the tangents from the tangents going in/out
• Maybe treating the whole set as control points of a higher order bezier would be another form of interpolation?
• Same with arc vertices jointly approximating a single arc?

So for an API, that would mean quadratic and cubic vertices continue to chain the same way normal vertices do, but you could surround vertices in begin/endSegment(interpolationStrategy) where instead of chaining, we use something akin to basing the order off of the number of points like before?

Sorry if I'm derailing a bit haha, just wanted to share some thoughts that might combine both models!

[GregStanton]

This is getting very interesting @davepagurek! I'm going to think about this some more. As if we didn't already have enough to think about, here are some papers that your recent comments inspired me to discover:

• A Class of C^2 Interpolating Splines
• Blended Elliptic Arc Splines

I've only barely glanced through them, but the first of these seems to provide an interesting framework for a whole class of splines, which includes Bézier splines and elliptical splines (splines made from elliptical arcs) as special cases. They're distinguished by choosing different interpolation functions. The second article seems to develop an approach that's specific to splines made up of elliptical arcs.

I need to think through everything again in light of all this discussion, so I'm not sure if these will be relevant yet, but I figured I'd share them in case they inspire ideas from others.

[davepagurek]

Good morning again, just adding a summary comment about some of the discussion so far so it's easier to follow!

• Regardless of what we do, we want to split up large function calls into multiple smaller calls for readability, e.g. splitting each point of bezierVertex() into its own call.
• It feels like there are two "modes" one might want to create curves in:
  1. Aggregating: The more points you add, a single segment will interpret those points, e.g. by interpolating a curve through all of them, or approximating them all with a curve. (The p5.bezier library works like this, where more points make a higher-order single bezier segment. Another idea mentioned for arcs is to draw a single arc that best fits all the points provided. curveVertex also arguably works like this.)
  2. Chaining: The more points you add, the more segments get added. (This is how quadraticVertex, bezierVertex, and arguably vertex currently work.)
• Originally Greg was proposing an aggregating-first API, and I was proposing keeping a chaining-first API.
• Potentially we can include both: the approximating/interpolating mode proposal would surround segments with begin/endPrimitive(). This could potentially coexist with chaining API functions, which aren't surrounded, e.g.:

  beginShape()
  // Chaining
  vertex(0, 0)
  quadraticVertex(50, 0)
  quadraticVertex(50, 50) // completes one quadratic segment
  quadraticVertex(50, 100)
  quadraticVertex(0, 100) // completes a second quadratic segment
  
  // Aggregating
  beginSegment(BEZIER)
  vertex(-20, 80)
  vertex(20, 50)
  vertex(-20, 20)
  vertex(0, 0)
  endSegment() // completes a single quintic bezier segment
  endShape()
  

[GregStanton]

Thanks so much for the summary @davepagurek! I'll add a few thoughts about the existing options and propose a new one.

A chaining-only API

One option is to keep the original proposal, with a few changes.

• Rename bezier() to cubicBezier() and create a new quadraticBezier() function. (This solves Problem 6 of the proposal.)
• Rename quadraticVertex() and bezierVertex() as quadraticBezierVertex() and cubicBezierVertex(), respectively. These names are longer, but the parameter lists are shorter, so it should be okay. (This solves Problem 7.)

In this case, we would sacrifice extensibility (e.g. higher-order Bézier curves); in other words, we wouldn't try to solve Problem 8 of the original proposal.[^1] We’d also lose the simplicity of being able to call any vertex function an unlimited amount of times.

Separate APIs for chaining and aggregating

Here I'll add some issues to consider in relation to the idea you recently proposed.

1. Ideally, we want an API that's easy to guess. Since segments are just one shape kind, a user may guess that in addition to beginSegment(), we'll have beginTriangleFan(), etc. Rather than expanding the size of the API significantly, one way to possibly address this is to replace beginSegment(interpolationStrategy) with beginPrimitive(kind). Then BEZIER_SEGMENT would be just one example of a shape kind. This isn't perfect, since it'd be nice if the primitive kinds would be the same as the shape kinds, but that'd require some extra complexity, e.g. beginPrimitive(vertexKind, shapeKind).
2. It may be confusing to have two APIs, mainly because they don't seem entirely consistent. In the chaining API, the segment type is part of the function name, whereas in the other API, it's a parameter. Another way to think of this is that vertex() is just used for linear shapes in one API [^2], but it's used for other kinds of shapes in the other API.

Combined API for chaining and aggregating

Below, I'll describe one approach that seems to do everything we want in a simple way. It's a variation of the API proposed by @peilingjiang. I'm not sure about it yet, but it seems really nice.

The idea is to have four vertex functions:

1. linearVertices() for polylines
2. bezierVertices() for Bézier curves
3. catmullRomVertices() for Catmull-Rom splines [^3]
4. arcVertices() for elliptical arc splines [^4]

As in the current version of p5.js, each function call creates a new segment (when the default shape kind is being used), and multiple calls will chain segments. There are two main differences from the current API:

1. The vertex functions all accept a variable number of arguments, so that a single function call can create a polyline, a Bézier curve of arbitrary order, a Catmull-Rom spline through any number of points, or an elliptical spline.
2. The arguments would be instances of a new p5.Vertex class. Vertex objects would have properties for position, texture coordinates, color, and a normal vector. [^5] This would make it possible to support features like per-vertex coloring while retaining the benefits of @peilingjiang’s API. In particular, it makes code easier to read by explicitly grouping vertices into primitives, and it may allow for a simpler implementation that directly reflects the API.

As an initial example, here's how we could create a cubic Bézier segment:

let v1 = createVertex(...);
let v2 = createVertex(...);
let v3 = createVertex(...);
let v4 = createVertex(...);

beginShape();
bezierVertices(v1, v2, v3, v4) //vertices could also be created inline, with one argument per line
endShape();

//ALTERNATIVE
let vertices = [
  createVertex(...), 
  createVertex(...), 
  createVertex(...), 
  createVertex(...)
];

beginShape();
bezierVertices(...vertices); //could support array arguments if we want to avoid spread syntax
endShape();

This would be a slight departure from typical p5.js usage, which has users passing coordinates directly into functions, but it's similar to how we already allow users to pass a p5.Vector object directly into point().

If we don't immediately see any major problems with this overall approach, I can work out more of the details (e.g. I can redo this list of examples in the new API).

[^1]: With this approach, it might still be possible to mostly solve Problem 9, e.g. by calling quadraticBezierVertex() six times for a quadratic Bézier triangle and calling cubicBezierVertex(x, y, z) ten times for a cubic Bézier triangle. Similarly, we could call quadraticBezierVertex() nine times for a biquadratic patch and cubicBezierVertex() sixteen times for a bicubic patch. [^2]: Here, I'm ignoring the possibility of manually specifying normal vectors for vertices, since that's a less common use case. [^3]: Although curveVertex() is a friendly name, in that "curve" is a common word, it's overly generic and inconsistent with the other names, which are more specific. This can lead to confusion. For example, right now, there's a section of the reference called “Curves,” and underneath, it has both bezier() and curve() commands; so according to the reference, a bezier() is a curve, but it's not a curve(). So we may consider renaming curveVertex() (or curveVertices()) to something less generic, like hermiteVertex(), catmullRomVertex(), or even splineVertex(). Although splineVertex() is still too general (e.g. one can also make Bézier splines), it’s more precise than the current name. This note applies to all three APIs considered in this comment. [^4]: The idea is that we can interpolate points with elliptical arcs instead of Bézier curves or something else. I cited a couple papers on this previously: here's one interesting paper that shows how to create both Bézier and elliptical splines in a common framework, and another paper that focuses specifically on "blended elliptic arc" splines. If we were to adopt an approach like this, we'd still need to consider how easy it'd be to create a single ellipse or elliptical arc. Also, this would probably mean that we would not try to support curve fitting (e.g. for fitting a single arc or line segment to a large number of vertices), as discussed in #6459, unless we provide a separate API for that. [^5]: If this idea seems promising, we'll want to vet the idea of a p5.Vertex class more carefully. One issue we've come across before is that we may end up with some null properties, which may be a sign that we need to split the class up. However, a single p5.Vertex class would be consistent with p5's usual approach of providing a small interface to a large number of features (e.g. p5.Vector combines 2D and 3D vectors).

[davepagurek]

Thanks @GregStanton! Here are a few thoughts on the different ideas you mentioned.

• A chaining-only API
  • To me this is probably the smallest departure from the current API that still accomplishes many of the goals we've set out, so could be a good option to keep in our back pocket if other departures seem too large.
• Separate APIs for chaining and aggregating
  • Using beginPrimitive to handle all those cases seems good to me.
  • I think I'm also ok with the tradeoff of having a slightly different pattern for curve vertices and higher-order beziers if the idea is that they're more advanced, less commonly used, and less clear how they would work in conjunction with the chaining API functions, given that this more advanced set of features has a pattern to it too. (I think the interplay between curveVertex and other vertex functions is pretty confusing to people currently, based on some Discord questions in the past.)
• Combined API for chaining and aggregating
  • This does a nice job of supporting the things we want. I think we need to dig into createVertex though: if it takes positional arguments (e.g. createVector(x, y, z, u, v)) it becomes hard to supply just a color and not a texture coordinate, or something like that. We might need it to be createVector(x, y, z, options) where options can be { u: 0, v: 0 } and only fill in the keys that are needed.
  • I wonder if people who teach with p5 have any opinions on the teachability of this sort of API, since it uses a few more JS concepts compared to the current one. @nickmcintyre do you have any thoughts?

[nickmcintyre]

@davepagurek I have some initial impressions but haven't had the opportunity to teach this part of API yet. I'll share some thoughts soon.

@tabreturn you know much more about teaching curves than I do. What do you think about the proposal?

[tabreturn]

I'll need to make some time to study this properly -- but it looks interesting!