Yourk - documentation
[work in progress]
Your(for)k - providing a free web-based platform to design stuff - no prior experience, technical background or drawings skills required. To get there, the app builds upon some theory of Bézier curves, dissecting and understanding the SVG file format, as well as a fair amount of JavaScript spiced with tons and tons of high school geometry. Because that is where it's at.
From its first simple 2d version, the main JavaScript engine has turned into a stand-alone library called dChisel.js, allowing splines to be drawn and edited in the browser. Its JSDocs documentation, although not yet professional, gives a sense of its structure..
The documentation you're reading now is quite a bit more intuitive than technical. I strongly felt necessary to describe the underlying principles in plain words - tremendously useful for me, and hopefully also interesting to you. Enjoy reading!
0. Theory - the Bézier Curve
How can we describe curves? In recollection of my high school years, I would usually go by finding a mathematical function that comes close. If the curve starts out flat and curves upwards, there is most likely a y = f(x) = x2 term involved. Combine that with sines, tangents, exponentials, and eventually, you'd get what you want.
Although there are usually better ways to go, let me note that this method has great potential. If you're interested and not horrified by some bulky formulas, read up on the design process of the gridshell roof of the British Museum.
And now, on to Bézier curves. Let's start with a simple example. All we need to accurately describe the curve is the five points. And now go ahead and interact with the curve. See how easily you can customize its appearance?
For those who are interested in the math behind generating these curves, let's take a small detour. If we had only two control points P[0], P[1] they would form a line. All points on the curve could be obtained by linearly combining the coordinates of the control points, as follows: P(@s) = (1-s) x P[0] + s x P[1]. Take three points, and the deal becomes:
P(@s) = (1-s)2 s0 P[0] + 2 (1-s)1 s1 P[1] + (1-s)0 s2 P[2]
[remember (1-s)2 s0 + 2 (1-s)1 s1 + (1-s)0 s2 = [(1-s) + s]2 = 12 = 1?]
To generalize it, just take [(1-s) + s]n, take its terms and combine them with your control points.
If you look at them image above, you'll notice that some points are on the curve, others are not. So which are the control points? Is there a difference between how these points are treated? The answer is not really, and this has to do with a curious property of the Bézier curve: if three consecutive control points are on the same line, the second will be on the curve. How lovely!
For those who got scared by all the math above: we will only deal with Bézier curves having 4 control points, that is, all larger curves will be broken up into segments. If we want these curves to join smoothly, all we need to do is to make sure that the three control points at the joint are on the same line. And yes, the control handles represent the tangent.
1. Bézier Curves in Practice - the SVG Format
If you draw a curve with the pen tool in Adobe Illustrator, it is in fact always a Bézier curve. If you export this into SVG and look at the file, what you get a series of coordinates - the coordinates of the control points described in the previous section.
This is how it looks like, straight from Illustrator:
d="
M141.327,79.233c-43.334,91.874,17.958,103.338,19.348,182.851c2.037,116.528-34.822,174.91,29.191,177.626
c74.608,3.165,24.522-92.389,19.008-182.614c-4.115-67.333,62.002-66.075,15.102-178.748c0,0-10.688,25.155-10.01,55.874
c0.44,19.927-6.901,24.666-6.901,24.666s-11.371-6.235-11.089-30.606c0.339-29.361-11.531-44.805-11.531-44.805
s-12.399,13.747-11.89,43.956c0.36,21.375-9.843,31.908-9.843,31.908s-8.826-9.505-8.147-31.568
C155.444,99.201,141.327,79.233,141.327,79.233z"
Which is, in a more orderly universe, equivalent to:
d="M141.327,79.233
C111.83,110.57,107.11,85.35,74.39,84.78
C26.44,83.94,2.42,99.11,1.30,72.76
C0.00,42.06,39.32,62.67,76.45,64.94
C104.15,66.64,103.64,39.43,150.00,58.73
C150.00,58.73,139.65,63.13,127.01,62.85
C118.81,62.67,116.86,65.69,116.86,65.69
C116.86,65.69,119.42,69.25,129.45,69.13
C141.53,68.99,147.89,75.00,147.89,75.00
C147.89,75.00,142.23,80.66,129.80,80.45
C121.01,80.30,116.67,83.94,116.67,83.94
C116.67,83.94,120.58,87.57,129.66,87.29
C141.42,86.93,149.64,92.74,141.327,79.233z"
The first version is chopped up, processed and sent to an object constructor and built into an array.
This coordinate extraction was the first step in the Yourk implementation, reproducing the path on HTML5 Canvas using the moveTo and bezierCurveTo methods only. It was a cloudy, nerdily beautiful Sunday towards the end of November, 2013. The work started at the Black Brick coffee shop in Williamsburg and ended in the afternoon at the Schwarzmann Building of the New York Public Library, by Bryant Park.
2. The Yourk Code - Concept
The goal of Yourk is to take a closed Bézier curve that resembles a fork, and make it interactive so that the users can drag its points and handles around as they wish, making the design object their very own. Download it as 2d SVG or 3d script files, send it to a laser cutter, 3d printer and so on. Concept in a nutshell.
3. The Yourk Code - the Specifics
The code is just a little bit short of 1000 lines, and I would argue that it is not that long or not that complicated. This is the first code documentation I have ever written, so it is a bit freestyle.
3.0. Drawing Modes
Whenever control points are not selected, dragging the mouse pans the image, if this is allowed.
Panning, zooming, rotating, centering, and of course, drawing - lots to do in a decent drawing tool. Inspired by commercial and open source drawing software, in particular Rhinoceros, AutoCAD and Goodle Sketchup, there are a number of drawing modes in Yourk, only one of which is active at a time. The drawing modes are the following:
- mode 1 - curve edit 1 - independent handles: modify the curve. If subnode 2 is selected, all three subnodes are moved. If subnodes 1 or 3 are selected, they are moved independently of the other.
- mode 2 - curve edit 2 - rotationally coupled handles: modify the curve. If subnode 2 is selected, all three subnodes are moved. If subnode 1 is selected, it is moved with the cursor, whereas subnode 3 is moved such that it rotates about subnode 2 by the same amount as subnode 1, but keeping the 2-3 distance constant. Analogously if subnode 3 is moved.
- mode 3 - curve edit 3 - fully coupled handles: modify the curve. If subnode 2 is selected, all three subnodes are moved. Subnodes are moved such that they rotate and scale by equal amounts with respect to subnode 2.
3.1. Stages
The stage variable stores stores the current stage/page/part of the application, including intros, tutorials and the full drawing environments - both 2d and 3d. Its values are as follows:
- 0 - initialization, setting the start time of the program;
- 1 - intro part 1;
- 2 - intro part 2;
- 3 through 3.9 in 0.1 increments: tutorial;
- 4 - 2d design environment;
- 5 - 3d design environment;
4. Wrap-up
Yourk is a very lightweight app. Offering 3d design capabilities with this lightness is its core strength that will allow it to grow and scale easily later on.
Feel free to reach out with comments and suggestions. I would also be thrilled to see your creations!