Automatic Camera Rotation

When Koru loads a scene it just leaves it "as is" until someone drags it with a mouse or click a snapshot button. Sometimes you may want to change that and make a scene interactive by itself. There is a way to do that in Koru with some JavaScript code.

In this tutorial we'll show you how to make your exported scene rotating when idle. Best of all, you will not need a special template for that as we'll use the built-in script editor.

For more details on Koru Javascript API see this page that has all the answers.

Let's Spin It

Start Koru, make a simple scene, setup the camera and then click Scene -> Script Editor... in the menu to open the editor. An empty text window will pop up where you can enter a script that will run when Koru exported file is opened in browser.

Click Snippets button at the bottom left corner and select Rotating Camera item there. The following code will appear in the editor:

function koruInit(koru) {
    koru.addEventListener('update', onKoruUpdate);
}

function onKoruUpdate(event)
{
    var koru = event.koru;
    if (event.idleTime > 5) {
        var t = event.idleTime - 5;
        t = t < 1 ? t * t * 0.5 : (t - 0.5);
        var angle = t * 30;
        koru.camera.rotation.z = koru.camera.userData.startAngle + angle;
        koru.invalidate(3);
    } else {
        koru.camera.userData.startAngle = koru.camera.rotation.z;
    }
}

The code defines two functions: koruInit() and onKoruUpdate(). The first one is called immediately after the Koru engine has started and there we ask Koru to call our other function when the scene is updated (basically, every frame). The second function does all the rotation job.

First of all, onKoruUpdate() function gets its Koru engine from the event variable. Then it checks how long the scene was idle, i.e. had no user interaction. The idle time is measured in seconds and until it less than 5 seconds the function does nothing and simply stores the current camera rotation angle to its internal variable.

When the idle time runs over 5 seconds, the function computes the rotation time be subtracting 5 from the idle time counter. Then in the next line it makes a smooth start by applying some maths to the time variable and then it computes the rotation angle by multiplying the rotation time by 30. This means the speed will be 30 degrees per second. You can adjust that, if you like.

Finally, the function sets the camera rotation angle by adding the computed angle to the one which was stored before. And in the very last line it asks Koru to redraw the screen with 3 smoothing steps. You can adjust that value, as well. It lets you choose between speed and quality and the more the value is, the better is the quality and the longer is the rendering. For spinning objects, values of 1 to 4 are better as they provide nice frame per second ratio.

Make It Better

Let's add just three lines to our code to make it even better. Make your code looks like this:

function koruInit(koru) {
    koru.addEventListener('update', onKoruUpdate);
}

function onKoruUpdate(event)
{
    var koru = event.koru;
    if (event.idleTime > 5) {
        var t = event.idleTime - 5;
        t = t < 1 ? t * t * 0.5 : (t - 0.5);
        var angle = t * 30;
        koru.camera.rotation.z = koru.camera.userData.startAngle + angle;
        var vangle = 20 * Math.sin(t * 0.5);
        koru.camera.rotation.y = koru.camera.userData.startVertAngle + vangle;
        koru.invalidate(3);
    } else {
        koru.camera.userData.startAngle = koru.camera.rotation.z;
        koru.camera.userData.startVertAngle = koru.camera.rotation.y;
    }
}

Note that we added two lines just before the invalidate(3) call and one line at the else block that saves the other camera rotation component. The first two lines make the camera oscillates up and down to 20 degrees while rotating. Modify the 20 value to change the amplitude, modify the 0.5 value to change the speed. Easy as :)

That's All!

You can move, rotate or scale virtually any part of the scene the same way as the camera. Make simple animations or do data-driven 3D scenes easily!