2.4 Orbit Controls

Hello and welcome back, in our last lesson, we introduced you to our new project file. And right now it's kind of boring. We've got a bunch of dodecahedrons scattered throughout space, but they're not really doing anything. So what I wanna do in this lesson, is I wanna create some orbit controls. And orbit controls allow you to navigate through the 3D space using your mouse. And these are very easy to setup, it really only takes one line of code to get this going. But, again, as we mentioned in the last lesson, if we go to our Settings > JavaScript, we do need to link to the OrbitControls JavaScript file separately, if we want to use these controls. So in order to plug this in and get it working, let's take a look at our JavaScript. And you can find the URL for this particular starting CodePen in your course notes for this lesson. And once we open that up, go ahead and click on Fork to open a new copy, and all of our changes will be saved in this new copy. So we're gonna leave most of this alone. We've got our scene, we've got our camera, we've got our renderer, and then we've got 1,001 shapes and our lights. So after we create the lights, but before our animate function, I'm going to create our orbit controls. So I'm gonna create a variable here called controls. And we're gonna set this equal to = new THREE, with all Capital letter, .Orbit with a capital O, Controls, with a capital C. And then inside our parenthesis we need two parameters, we need the camera and then we need the dom element for our renderer. So we're gonna point our camera, which stored in a variable called camera. And then we're gonna point to our renderer, and we're gonna point to the dom element property of that renderer. So renderer.dom, with all lowercase letters, and then Element with a capital E, semicolon at the end of that statement. So we've created our controls, now I'm gonna click on the Run button, and we'll see if that works. So everything refreshes. Now, I'm going to click and drag, and we see that our orbit controls are working just fine. So we can click and drag to move our camera around the scene. We can also use the middle mouse wheel to dolly in and out, or move our camera forward and back. And then we can also use the right mouse button, if we right click and drag, then we can pan around our scene. So again, that's a lot of really great functionality that we get with just one line of code. All of that functionality is built into this OrbitControls JavaScript file that we're now linking to. Now there are other things that we can do with our OrbitControls, we can set some properties on it. For example, there's a property called minDistance and another one called maxDistance. And that determines how far in and out you can dolly your camera or how far forwards and backwards we can move it. So let's point to our controls here. And then I'm gonna call on the minDistance property by saying .minDistance, with a capital D, and then we're gonna set this equal to a value of, let's say, 50. If we set it to zero, then it would allow us to zoom in all the way, or to move in all the way to a value of zero, which would put us right in the middle of the scene. But I don't wanna be able to go all the way to the middle, let's say we just wanna go within 50 units of the center there. So our minDistance is 50, but you'll notice we can zoom out as far as we want to. If we just keep scrolling our zoom wheel, we just keep going until everything disappears. So let's say that we wanted to put a maxDistance on there. So again, we'll just point to our controls, and as you could probably guess, we're gonna point to maxDistance. And let's set this one to, let's try 300. So with that done, we're going to save, and then click on Run to refresh the screen. And now I'm gonna try to zoom in and you'll see it's not letting me dolly in. I'm hitting up on this scroll wheel and it's not letting me get any closer. But if I go backwards on the scroll wheel, I can zoom away, and right now it stopped. It won't let me go any further back. And we can zoom back in and it will stop us once we get 50 units away from the center. So we could play around with that a little bit, maybe set our maxDistance to 200, so we can't go quite as far back. Click on Run again, and after it refreshes we'll zoom out a little bit. And you'll see that it wont let us go quite as far as it did last time. So those are a couple of properties we have access to. There's also a really helpful property. You'll notice, if we click and drag, as soon as we let go of the mouse cursor while we're dragging, the scene comes to a complete stop. It stops immediately as soon as we let go of the mouse cursor. Well, there's a property called enableDamping, where if we set that to true, then instead of just coming to an abrupt stop, it'll actually slow down. So it gives our camera some inertia. So the way we turn that on is we point to our controls dot, and then it's called enableDamping. And I'm gonna set that to a value of true. Now it's important to point out that if you turn this property on, it's not gonna work right unless we add something to our animation loop. So just after our request animation frame line, I'm gonna add another line here to update our controls, otherwise our damping isn't going to work. So we're gonna point to our controls and then call the update method by saying .update(); open and close parentheses semicolon to end our statement. So now we're gonna save that again and click on Run, and it's gonna refresh. And now, when we click and drag around, you'll notice that when I let go, it kind of slows down a little bit before it comes to a stop. So it gives our camera some inertia, so it's kind of a cool effect. So that's how you can turn on your OrbitControls in Three.js. It's very, very easy to do. And as always, you can jump into the documentation to see what other properties you can set, what other methods are available with the OrbitControls. But those are the basics of how to use it. So thank you for watching, and I'll see you in the next lesson.