updated Coordinates and Transformations tutorial, added illustration, updated examples

Author: aceslowman

src/assets/learn/basic3d/images/primitives_example.png

@@ -16,7 +16,7 @@ function setup() {
 
   debugMode();
 
-  p = document.querySelector('#axisText')
+  p = document.querySelector('#axisText');
 }
 
 function draw() {
@@ -40,8 +40,11 @@ function draw() {
 
   // also added: draw lines along x, y, z axes in rotated space
   strokeWeight(4);
+  stroke('red');
   line(0, 0, 0, 100, 0, 0);
+  stroke('green');
   line(0, 0, 0, 0, 100, 0);
+  stroke('blue');
   line(0, 0, 0, 0, 0, 100);
 
   normalMaterial();
@@ -50,59 +53,8 @@ function draw() {
 
   noFill();
 
-  p.innerHTML = 'rotateX('+parseFloat(xAxisSlider.value).toFixed(3)+') <br />';
-  p.innerHTML += 'rotateY('+parseFloat(yAxisSlider.value).toFixed(3)+') <br />';
-  p.innerHTML += 'rotateZ('+parseFloat(zAxisSlider.value).toFixed(3)+') <br />'
-
-//   // draw axes vector
-//   push();
-  
-//   /*  
-//     here I should be able to apply a rotation
-//     that will align the visualization to the rotateAxis
-    
-//     I can't seem to figure out how calculate the right rotation.
-//   */
-  
-//   let a = rotateVector
-//   let b = createVector(0,-1,0)
-//   let na = a.copy() 
-//   let nb = b.copy()
-  
-//   na.normalize()
-//   nb.normalize()
-  
-//   let angle = acos(p5.Vector.dot(na,nb))
-//   let c = p5.Vector.cross(a,b)
-  
-//   rotate(-angle, c)
-
-//   stroke(0);
-//   strokeWeight(5);
-//   // line(
-//   //   -100,
-//   //   0,
-//   //   0,
-//   //   100,
-//   //   0,
-//   //   0
-//   // );
-  
-//   // rotate so that arc is oriented correctly
-//   // this seems to work correctly
-//   rotateX(PI / 2);
-//   stroke(255, 0, 255);
-//   arc(0, 0, 200, 200, 0, angleSlider.value());
-//   pop();
-  
-//   scale(1000);
-  
-//     line(
-//     -xAxisSlider.value(),
-//     -yAxisSlider.value(),
-//     -zAxisSlider.value(),
-//     xAxisSlider.value(),
-//     yAxisSlider.value(),
-//     zAxisSlider.value()
-//   );
+  p.innerHTML = 'angleMode(DEGREES) <br /><br />';
+  p.innerHTML += 'rotateX('+parseFloat(degrees(xAxisSlider.value)).toFixed(1)+') <br />';
+  p.innerHTML += 'rotateY('+parseFloat(degrees(yAxisSlider.value)).toFixed(1)+') <br />';
+  p.innerHTML += 'rotateZ('+parseFloat(degrees(zAxisSlider.value)).toFixed(1)+') <br />'
 }

src/assets/learn/basic3d/rotateExample.js

@@ -12,15 +12,15 @@ slug: learn/
   .additionalInformation {
     width: 100%;
     background-color: #dedeff;
-    font-size: 15px;
+    font-size: 17px;
     padding: 10px;
     margin: 30px 0;
   }
 
   .toc {
     width: 100%;
     background-color: #eee;
-    font-size: 15px;
+    font-size: 17px;
     padding: 10px;
     margin: 30px 0;
   }
@@ -46,7 +46,7 @@ slug: learn/
       <h1>Coordinates and Transformations</h1>
 
       <p>p5.js is a powerful tool for creating 2D graphics but it's also capable of 3D graphics.
-        Before we can get started in 3D there are some new concepts to learn and this document will introduce some ideas
+        To get started in 3D there are some new concepts to learn and this document will introduce some ideas
         that will be important to any 3D sketch.</p>
 
       <div class="toc">
@@ -63,7 +63,7 @@ slug: learn/
 
       <h2 id="what_is_webgl">What is WebGL</h2>
 
-      <p>WebGL is an API that gives us the tools we need to create 3D graphics within a web browser. To put it simply,
+      <p>WebGL is a library that gives us the tools we need to create 3D graphics within a web browser. To put it simply,
         it allows us to do all kinds of math that help arrange and display objects in 3D. p5.js makes it easier to work
         with WebGL
         through its special WebGL mode.</p>
@@ -78,7 +78,7 @@ slug: learn/
       </p>
 
       <p>
-        Let's get started by setting up the p5.js canvas to use WebGL mode.
+        Let's get started by setting up the p5.js to use WebGL, by passing a third parameter into <a class="code">createCanvas()</a>.
       </p>
 
       <pre><code class="language-javascript">
@@ -96,12 +96,12 @@ slug: learn/
 
       <div class="additionalInformation">
         If coordinates systems aren't making sense it might be helpful to revisit the tutorial titled
-        <a href="{{root}}/learn/coordinate-system-and-shapes.html">Coordinate System and Shapes</a>
+        <a href="{{root}}/learn/coordinate-system-and-shapes.html">Coordinate System and Shapes</a>.
       </div>
 
       <p>One of the most fundamental differences between working in 2D and working in 3D is the most obvious: there is
         one more dimension to work with. In addition to the horizontal and vertical position (x and y axes) of an
-        element in our drawing, 3D adds depth, (the z-axis). </p>
+        element in our drawing, 3D adds depth, the z-axis. </p>
 
       <p>When drawing in 2D, the point (0,0) is located at the top left corner of the screen. In WebGL mode, the
         origin of the sketch (0,0,0) is located in the middle of the screen. By default, the x-axis goes left-to-right,
@@ -126,10 +126,11 @@ slug: learn/
       <iframe src="{{assets}}/learn/basic3D/translateExample.html" width="720" height="350">
       </iframe>
 
-      <p><a class="code" href="{{root}}/reference/#/p5/translate">translate()</a> moves our origin point in a
-        given direction. Anything drawn after we call translate will be
+      <p><a class="code" href="{{root}}/reference/#/p5/translate">translate()</a> moves the origin in a
+        given direction. Anything drawn after we call <a class="code">translate()</a> will be
         positioned relative to that point. <a class="code">translate()</a> accepts arguments for x, y, and z
-        values.</p>
+        values. Use the sliders in the sketch above to change the translation of the box, and see how it moves along
+        each axis.</p>
 
       <pre><code class="language-javascript">
       ...
@@ -151,8 +152,9 @@ slug: learn/
       <p>There are a few methods that can be used to rotate an object in 3D. Most of the time it's easiest to call
         methods like like <a class="code" href="{{root}}/reference/#/p5/rotateX">rotateX()</a>, <a class="code"
           href="{{root}}/reference/#/p5/rotateY">rotateY()</a>, and <a class="code"
-          href="{{root}}/reference/#/p5/rotateZ">rotateZ()</a>, which allows for rotation around a specific axis.
-        Each of these methods accept a single argument specifying the angle of rotation.
+          href="{{root}}/reference/#/p5/rotateZ">rotateZ()</a>, which each allow for rotation around a specific axis.
+        Each of these methods accept a single argument specifying the angle of rotation. Try moving the sliders in the
+        example above to see how rotation is performed on each axis.
       </p>
 
       <pre><code class="language-javascript">
@@ -165,7 +167,7 @@ slug: learn/
       ..
       </code></pre>
 
-      <p>By default p5.js will expect angles to be in radians. Radians use numbers from 0 - TWO_PI to specify an
+      <p>By default p5.js will expect angles to be in radians. Radians use numbers from 0 - <a class="code">TWO_PI</a> to specify an
         angle. To use degrees, either convert degrees to radians using <a class="code">radians()</a>, or use
         <a class="code">angleMode(DEGREES)</a>.
       </p>
@@ -182,17 +184,19 @@ slug: learn/
       ..
       </code></pre>
 
-      <p>You can also use <a class="code" href="{{root}}/reference/#/p5/rotate">rotate()</a>, which allows
-        you to specify which axis you'd like to rotate around using a vector as the second argument.</p>
-
-      <pre><code class="language-javascript">
-      ...
-      // rotate 90 degrees around the y-axis
-      let axis = createVector(0,1,0);
-      rotate(HALF_PI, axis);
-      box();
-      ..
-      </code></pre>
+      <div class="additionalInformation">
+        <p>You can also use <a class="code" href="{{root}}/reference/#/p5/rotate">rotate()</a>, which allows
+          you to specify which axis you'd like to rotate around using a vector as the second argument.</p>
+
+        {{!-- <pre><code class="language-javascript">
+        ...
+        // rotate 90 degrees around the y-axis
+        let axis = createVector(0,1,0);
+        rotate(HALF_PI, axis);
+        box();
+        ...
+        </code></pre> --}}
+      </div>
 
       <h3>scale(): Size in Space</h3>
 
@@ -203,14 +207,15 @@ slug: learn/
       <p><a class="code" href="{{root}}/reference/#/p5/scale">scale()</a> changes the size of whatever is
         drawn after it. Like the other methods described so far, it accepts arguments for x, y, and z values.</p>
 
-      <h2 id="order">Order</h2>
+      <h2 id="order">The Order of Transformations Matters!</h2>
 
-      <p>Something that can feel unpredictable at first is the order of transformations. Each transformation can affect
+      <p>Something that can feel unpredictable at first is the order of transformations. Each transformation always affects
         the next one. For example, if <a class="code">rotate()</a> is called, followed by <a class="code">translate()</a>, the direction of that translation will
         be affected by the rotation. The entire coordinate system is rotating and moving, not just the shape itself. 
       </p>
 
-      <p>Transformations can be performed in any order, but using <strong>translate</strong>, <strong>rotate</strong>, and then <strong>scale</strong> will be the most intuitive.</p>
+      <p>Transformations can be performed in any order, but using <strong>translate</strong>, <strong>rotate</strong>, and then <strong>scale</strong> will be the most intuitive.
+      Translation, followed by rotation, produces the effect of moving the shape <em>and then</em> rotating around that new location.</p>
 
       <p>In the below example, try changing the order of <a class="code">translate()</a> and <a
           class="code">rotateY()</a> and see how it affects where the object is
@@ -245,7 +250,9 @@ function draw(){
           class="code">push()</a> and
         <a class="code">pop()</a>, you have to keep track of whatever transformations have already taken place, which
         can get complicated
-        and difficult to follow.
+        and difficult to follow. Consider this following example, which places two boxes in our sketch. To position the second box
+        without <a class="code">push()</a> and <a class="code">pop()</a>, you have to account for the first transformation. This 
+        can be a lot to keep track of in a more complex 3D scene. 
       </p>
 
       <pre><code class="language-javascript">
@@ -284,7 +291,7 @@ function draw(){
           transformation matrix is combined with the view matrix and the projection matrix, both of which help simulate
           the view of a camera, and this combination results in our 3D scene! </p>
         <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_model_view_projection">
-          https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/WebGL_model_view_projection
+          Learn more about Model View Projection
         </a>
       </div>
 
@@ -294,44 +301,46 @@ function draw(){
 
       {{!-- push and pop example --}}
       <script type="text/p5" data-autoplay data-p5-version="{{ version }}">
-      function setup() {
-        createCanvas(windowWidth, windowHeight, WEBGL);
-      }
+function setup() {
+  createCanvas(150, 216, WEBGL);
+  debugMode();
+}
 
-      function draw(){
-        background(255);
-        // 
-        push(); // detach our coordinate system
-        // draw a box 100 units to the right
-        translate(100,0,0);
-        box();
-        pop(); // return to our original coordinate system
+function draw() {
+  background(255);
+  camera(100, -100, 100);
 
-        translate(-100,0,0);
-        box();    
-      }
+  push(); // detach our coordinate system
+  
+  // draw a box 100 units along the x-axis
+  translate(50, 0, 0);
+  rotateY(PI/4);
+  box(30);
+  pop(); // return to our original coordinate system
+
+  // draw a second box -50 units along the x-axis
+  translate(-50, 0, 0);
+  rotateY(PI/4);
+  box(30);
+}
       </script>
 
       <h2 id="basic_shapes">Basic Shapes in 3D</h2>
 
       <p>So far we have only been using <a class="code">box()</a> but p5.js has seven different predefined geometries
         that you can use in
-        your sketch. These basic predefined geometries are often referred to as 'primitives'. <a
-          href="{{root}}/examples/3d-geometries.html">Click here</a> to view an example showing off each
-        of these types.</p>
-
-      <ul>
-        <li><a class="code" href="{{root}}/reference/#/p5/box">box(width, height, depth, detailX, detailY)</a></li>
-        <li><a class="code" href="{{root}}/reference/#/p5/plane">plane(width, height, detailX, detailY)</a></li>
-        <li><a class="code" href="{{root}}/reference/#/p5/sphere">sphere(radius, detailX, detailY)</a></li>
-        <li><a class="code" href="{{root}}/reference/#/p5/ellipsoid">ellipsoid(radiusx, radiusy, radiusz, detailX,
-            detailY)</a></li>
-        <li><a class="code" href="{{root}}/reference/#/p5/cone">cone(radius, height, detailX, detailY, cap)</a></li>
-        <li><a class="code" href="{{root}}/reference/#/p5/cylinder">cylinder(radius, height, detailX, detailY,
-            bottomCap, topCap)</a></li>
-        <li><a class="code" href="{{root}}/reference/#/p5/torus">torus(radius, tubeRadius, detailX, detailY)</a>
-        </li>
-      </ul>
+        your sketch. These basic predefined geometries are often referred to as 'primitives'.</p>
+
+        <img style="padding:60px;" src='{{assets}}/learn/basic3D/images/primitives_example.png'
+        alt="an illustration showing each of the available primitives in p5.js">
+
+      <p>These primitive shape methods are: <a class="code" href="{{root}}/reference/#/p5/box">box()</a>,
+        <a class="code" href="{{root}}/reference/#/p5/plane">plane()</a>,
+        <a class="code" href="{{root}}/reference/#/p5/sphere">sphere()</a>,
+        <a class="code" href="{{root}}/reference/#/p5/ellipsoid">ellipsoid()</a>,
+        <a class="code" href="{{root}}/reference/#/p5/cone">cone()</a>,
+        <a class="code" href="{{root}}/reference/#/p5/cylinder">cylinder()</a>, and
+        <a class="code" href="{{root}}/reference/#/p5/torus">torus()</a></p>
 
       <p>It is also possible to create custom geometry, either from scratch or from 3D models created in another
         program.
@@ -342,7 +351,7 @@ function draw(){
       <h2 id="conclusion">Conclusion</h2>
 
       <p>
-        By having basic control over a 3d coordinate space, transformations, 
+        By having basic control over a 3D coordinate space, transformations, 
         and basic shapes, you should be able to begin creating basic scenes
         in 3D. The tutorials that follow this in the Getting Started in WebGL series
         will introduce custom geometries, allow you to tweak the appearance of 
@@ -352,11 +361,10 @@ function draw(){
 
       <h2 id="glossary">Glossary</h2>
 
-      {{!-- <h3>World Space</h3>
-      <p>A coordinate space that is relative to the world origin (0,0,0)</p>
-
-      <h3>Screen Space</h3>
-      <p>A coordinate space that is relative to the top left of the screen (0,0)</p> --}}
+      <h3>GPU</h3>
+      <p>The GPU (Graphics Processing Unit) is a piece of hardware that is particularly well
+        suited for performing many calculations in parallel, making it powerful for 3D graphics.
+      </p>
 
       <h3>Model</h3>
       <p>A custom 3D geometry that can be saved and loaded from a file</p>
@@ -368,7 +376,7 @@ function draw(){
       <p>The viewpoint of a 3D scene</p>
 
       <h3>Transform</h3>
-      <p>The combined scale, rotation, and translation of a geometry.</p>
+      <p>Also referred to as <em>transformation</em>, this refers to the combined scale, rotation, and translation of a geometry.</p>
 
       <h3>Vertex</h3>
       <p>A point in space</p>