Skip to content

Commit d42571f

Browse files
aceslowmanaceslowman
committed
added new text and example image
1 parent cac7c74 commit d42571f

File tree

2 files changed

+162
-43
lines changed

2 files changed

+162
-43
lines changed

‎src/assets/learn/basic3d/images/2d3d_coordinates.png

58.6 KB
Loading

‎src/templates/pages/learn/getting-started-in-3d.hbs

Lines changed: 162 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,8 @@ slug: learn/
4141
well suited to 3D graphics is that it can process many things at once, which is important when you are drawing
4242
many shapes. </p>
4343

44-
<p>Working with WebGL can be difficult, so p5.js helps us by handling a lot of things in the background. </p>
45-
46-
<p>Before we can do anything else, we need to set up our canvas to use the p5.js WebGL mode. This will give us
47-
access
48-
to some new methods and tools that will help us with the challenges that come with 3D.
44+
<p>Working with WebGL can be difficult, so p5.js helps us by handling a lot of things in the background. Before we
45+
can do anything else, we need to set up our canvas to use the p5.js WebGL mode.
4946
</p>
5047

5148
<pre><code class="language-javascript">
@@ -59,24 +56,26 @@ slug: learn/
5956
}
6057
</code></pre>
6158

62-
<h2>What is 3D? Coordinate spaces</h2>
59+
<h2>3D Coordinate Space</h2>
6360

6461
<p>One of the most fundamental differences between working in 2d and working in 3d is the most obvious: we are
6562
working with one more dimension. In addition to the horizontal and vertical position (x and y axes) of an
6663
element in our drawing, 3D adds depth, (the z-axis). </p>
6764

68-
{{!-- sketch illustrating coordinate space --}}
69-
{{!-- <iframe src="{{assets}}/learn/basic3d/transformExample.html" width="720" height="350">
70-
</iframe> --}}
71-
7265
<p>When you are drawing in 2d, the point (0,0) is located at the top left corner of the screen. In WebGL mode, the
7366
origin of the sketch (0,0,0) is located in the middle of the screen. By default, the X axis goes left-to-right,
7467
Y goes up-to-down, and Z goes from further-to-closer.</p>
7568

69+
<img style="padding:60px;" src='{{assets}}/learn/basic3d/images/2d3d_coordinates.png'
70+
alt="an illustration showing a 2d coordinate system on the left, showing an origin of (0,0) and a 3d coordinate system on the right, showing an origin of (0,0,0)">
71+
7672
<h2>Transformations</h2>
7773

78-
<p>p5.js has a few methods, <a class="code" href="{{root}}/reference/#/p5/translate">translate()</a>, <a class="code" href="{{root}}/reference/#/p5/rotate">rotate()</a>, and <a class="code" href="{{root}}/reference/#/p5/scale">scale()</a>, that we can use to position and orient objects
79-
within space. Collectively these are known as the <em>transformation</em> of an object. These methods are
74+
<p>p5.js has a few methods, <a class="code" href="{{root}}/reference/#/p5/translate">translate()</a>, <a
75+
class="code" href="{{root}}/reference/#/p5/rotate">rotate()</a>, and <a class="code"
76+
href="{{root}}/reference/#/p5/scale">scale()</a>, that we can use to position and orient objects
77+
within space. Each of these methods affect what is known as the <em>model matrix</em>. Collectively these are
78+
known as the <em>transformation</em> of an object. These methods are
8079
available for
8180
both 2D and 3D drawing.</p>
8281

@@ -90,6 +89,14 @@ slug: learn/
9089
given direction. Anything drawn after we call translate will be
9190
positioned relative to that point.</p>
9291

92+
<pre><code class="language-javascript">
93+
...
94+
// draw a box 100 units to the right
95+
translate(100,0,0);
96+
box();
97+
..
98+
</code></pre>
99+
93100
<h3>rotate()</h3>
94101

95102
{{!-- sketch illustrating rotation of geometry --}}
@@ -99,14 +106,51 @@ slug: learn/
99106
<p><a class="code" href="{{root}}/reference/#/p5/rotate">rotate(angle, [axis])</a> reorients whatever ever is
100107
drawn after it.</p>
101108

102-
<p>When given one argument it rotates around the Z-axis, but you can rotate
103-
in any direction by passing a vector as the second argument. Methods like <a class="code"
104-
href="{{root}}/reference/#/p5/rotateX">rotateX(angle)</a>, <a class="code"
109+
<p>There are a few methods that we can use to rotate an object in 3d. Most of the time it's easiest to call
110+
methods like like <a class="code" href="{{root}}/reference/#/p5/rotateX">rotateX(angle)</a>, <a class="code"
105111
href="{{root}}/reference/#/p5/rotateY">rotateY(angle)</a>, and <a class="code"
106-
href="{{root}}/reference/#/p5/rotateZ">rotateZ(angle)</a> apply an angle to the
107-
specific axis, but each can be called in combination. </p>
112+
href="{{root}}/reference/#/p5/rotateZ">rotateZ(angle)</a>, which allow you to rotate around a specific axis.
113+
</p>
114+
115+
<pre><code class="language-javascript">
116+
...
117+
// rotate each axis by 45 degrees
118+
rotateX(PI/4);
119+
rotateY(PI/4);
120+
rotateZ(PI/4);
121+
box();
122+
..
123+
</code></pre>
108124

109-
{{!-- TODO explain Euler angles --}}
125+
<p>By default p5.js will want you to supply an angle in radians. Radians use numbers from 0 - 2PI to specify an
126+
angle. If you want to use degrees, you can either convert degrees to radians using radians(), or you can use
127+
angleMode(DEGREES).</p>
128+
129+
<pre><code class="language-javascript">
130+
...
131+
// rotate each axis by 45 degrees
132+
rotateX(radians(45));
133+
box();
134+
//or
135+
angleMode(DEGREES);
136+
rotateY(45);
137+
box();
138+
..
139+
</code></pre>
140+
141+
<p>You can also use <a class="code" href="{{root}}/reference/#/p5/rotate">rotate(angle, [axis])</a>, which allows
142+
you to specify which axis you'd like to rotate around using a vector as the second argument.</p>
143+
144+
<pre><code class="language-javascript">
145+
...
146+
// rotate 90 degrees around the Y axis
147+
let axis = createVector(0,1,0);
148+
rotate(PI/2, axis);
149+
box();
150+
..
151+
</code></pre>
152+
153+
{{!-- TODO explain Euler angles or maybe note that quaternions exist but not yet in p5.js? --}}
110154

111155
<h3>scale()</h3>
112156

@@ -125,19 +169,62 @@ slug: learn/
125169
the object itself.</p>
126170

127171
<p>The order that you use will depend on what you’re trying to do, but a good place to start is to follow the
128-
order of translate, rotate, and then scale. If you perform these out of order you might find that your
129-
transformations don’t act the way that you expect them to.</p>
172+
order of <strong>translate</strong>, <strong>rotate</strong>, and then <strong>scale</strong>. If you perform
173+
these out of order you might find that your
174+
transformations don’t act the way that you expect them to.
130175
</p>
131176

132-
<p>Another tool we have in p5.js is <a class="code" href="{{root}}/reference/#/p5/push">push()</a> and <a class="code" href="{{root}}/reference/#/p5/pop">pop()</a>. Since transformations accumulate and affect each other, you
133-
might want to control which objects are affected by a certain transformation. push() saves and sets aside our
134-
current transformations (and certain styling, like stroke() or fill()), which allows you to perform other
135-
transformations. pop() restores those transformations.</p>
136-
</p>
177+
<p>In the below example, try changing the order of translate and rotate and see how it affects where the object is
178+
drawn.</p>
179+
180+
{{!--
181+
<pre><code class="language-javascript">
182+
...
183+
//
184+
translate(100,0,0);
185+
rotateZ(PI/4);
186+
scale(2);
187+
188+
box();
189+
...
190+
191+
...
192+
//
193+
rotateZ(PI/4);
194+
translate(100,0,0);
195+
196+
scale(2);
197+
198+
box();
199+
...
200+
</code></pre> --}}
201+
202+
<script type="text/p5" data-autoplay data-p5-version="{{ version }}">
203+
function setup() {
204+
createCanvas(150, 216, WEBGL);
205+
debugMode();
206+
}
207+
208+
function draw(){
209+
background(255);
210+
camera(100,-100,100)
211+
212+
translate(25,0,25);
213+
rotateY(PI/3);
214+
215+
scale(2);
216+
217+
box(10);
218+
}
219+
</script>
137220

138-
<p>You might use push() and pop() so that you can move each object individually. If you don’t use push() and
221+
<p>Another tool we have in p5.js is <a class="code" href="{{root}}/reference/#/p5/push">push()</a> and <a
222+
class="code" href="{{root}}/reference/#/p5/pop">pop()</a>. push() and pop() makes it easier to move objects
223+
individually. If you don’t use push() and
139224
pop(), you have to keep track of whatever transformations have already taken place, which can get complicated
140-
and difficult to follow. </p>
225+
and difficult to follow. push() saves and sets aside our
226+
current transformations (and certain styling, like stroke() or fill()), which allows you to perform other
227+
transformations. pop() restores those transformations.
141228
</p>
142229

143230
<pre><code class="language-javascript">
@@ -180,32 +267,64 @@ slug: learn/
180267

181268
{{!-- TODO push and pop example --}}
182269
<script type="text/p5" data-autoplay data-p5-version="{{ version }}">
270+
function setup() {
271+
createCanvas(windowWidth, windowHeight, WEBGL);
272+
}
273+
274+
function draw(){
275+
background(255);
276+
//
277+
push(); // detach our coordinate system
278+
// draw a box 100 units to the right
279+
translate(100,0,0);
280+
box();
281+
pop(); // return to our original coordinate system
183282
283+
translate(-100,0,0);
284+
box();
285+
}
184286
</script>
185287

186-
<h2>Camera and View</h2>
288+
<h2>3d Primitives</h2>
187289

188-
<p>The camera is an important piece to the 3d scene. In p5.js, the WebGL mode uses a perspective camera by
189-
default, meaning that as the view of the camera extends into the distance, geometry appears smaller. This is in
190-
contrast to an orthographic camera, where the geometry stays the same size as it gets further away, it has no
191-
vanishing point. </p>
290+
<p>So far we have only been using box() but p5.js has seven different predefined geometries that you can use in
291+
your sketch.</p>
192292

193-
{{!-- sketch illustrating 3d camera --}}
194-
<iframe src="{{assets}}/learn/basic3d/cameraExample.html" width="720" height="350">
195-
</iframe>
293+
<ul>
294+
<li><a class="code" href="{{root}}/reference/#/p5/box">box(width, height, depth, detailX, detailY)</a></li>
295+
<li><a class="code" href="{{root}}/reference/#/p5/plane">plane(width, height, detailX, detailY)</a></li>
296+
<li><a class="code" href="{{root}}/reference/#/p5/sphere">sphere(radius, detailX, detailY)</a></li>
297+
<li><a class="code" href="{{root}}/reference/#/p5/ellipsoid">ellipsoid(radiusx, radiusy, radiusz, detailX, detailY)</a></li>
298+
<li><a class="code" href="{{root}}/reference/#/p5/cone">cone(radius, height, detailX, detailY, cap)</a></li>
299+
<li><a class="code" href="{{root}}/reference/#/p5/cylinder">cylinder(radius, height, detailX, detailY, bottomCap, topCap)</a></li>
300+
<li><a class="code" href="{{root}}/reference/#/p5/torus">torus(radius, tubeRadius, detailX, detailY)</a>
301+
</li>
302+
</ul>
196303

197-
{{!-- <h2>Vertices and Faces</h2>
304+
<p>You can also load a custom 3d geometry using <a class="code"
305+
href="{{root}}/reference/#/p5/loadModel">loadModel()</a>.</p>
198306

199-
<p>3d geometry is ultimately a collection of points, called vertices, that are connected into faces. </p>
307+
{{!-- TODO how should I include a minimal example of how to import geometry from files? --}}
200308

201-
<p>In many 3d environments there is a collection of 3d primitives, simple built-in objects like boxes, spheres,
202-
torus', etc. </p>
309+
<h2>Camera and View</h2>
203310

204-
<p>It is certainly possible to create your own custom geometry, vertex but vertex, but that is outside of the
205-
scope of this article. </p>
311+
<p>The camera is an important piece to the 3d scene. In p5.js, the WebGL mode provides us with a perspective
312+
camera by
313+
default, but we can change this using perspective() or ortho().</p>
206314

207-
<p>Another common method for working with custom geometry in WebGL is to use a 3d model exported from software
208-
like Blender (for p5.js, an obj or stl file).</p> --}}
315+
<p> A perspective camera skews objects so they appear to get smaller as they get further away, vanishing at a
316+
single point in the distance.This is in contrast to an orthographic camera, where the geometry stays the same
317+
size as it gets further away and has no vanishing point. </p>
318+
319+
<ul>
320+
<li><a class="code" href="{{root}}/reference/#/p5/ortho">ortho(left, right, bottom, top, near, far)</a></li>
321+
<li><a class="code" href="{{root}}/reference/#/p5/perspective">perspective(fovy, aspect, near, far)</a></li>
322+
<li><a class="code" href="{{root}}/reference/#/p5/camera">camera(x, y, z, centerX, centerY, centerZ, upX, upY, upZ)</a></li>
323+
</ul>
324+
325+
{{!-- sketch illustrating 3d camera --}}
326+
<iframe src="{{assets}}/learn/basic3d/cameraExample.html" width="720" height="350">
327+
</iframe>
209328

210329
<h2>Lights</h2>
211330

0 commit comments

Comments
 (0)