Boxshot 3D Packaging Mockup Software
Download Download Download
Download for Windows Download for Mac Download for Mac Dropdown arrow

Exporting 3D scene for hosting on server

Although Koru can make single-file self-contained 3D HTML scenes, it is not always a good idea to use them everywhere. They are perfect for their simplicity, they can easily be emailed or replace 3D PDF, but when it comes to uploading to web-sites they are not the perfect option.

This tutorial explains why and shows the proper way of exporting for web server.

Why special mode for exporting to server?

First of all, here are some under-the-hood information on how Koru exported scenes work. Each exported Koru model consists of:

That’s all is pretty obvious and when you export a single-file HTML Koru packs all these components into the exported file. Browser then loads the file, starts Koru engine, it parses the model and displays it to you. So what’s wrong?

First of all, the size. 3D models can be quite large, a couple of megabytes or even tens of megabytes is not a problem for a nice-looking detailed shape. Top this up with your artwork and you get quite a large amount of data to download. Koru tries its best to pack everything as compact as possible, but if you export to HTML you have to export to text format which takes more space to store the same amount of data, compared to the binary formats. So the first problem is that by exporting to single-file HTML you increase the size of your shape to about 30 percents.

The second problem is again the size. When exporting to a single-file HTML, Koru adds its 3D engine to each exported file. This means if your site has 10 Koru models exported as self-contained files, it will have 10 copies of Koru engine. And your visitor will download all theses copies to see your shapes. Extra traffic, extra downloading time, extra waiting… You hardly need that.

The third reason is interactivity. When the scene is exported as a single file, the browser first downloads the whole file and then starts Koru engine that displays the shape. While the file is loading the user sees nothing, then “boom” and the scene is loaded. Most of the users expect to see some kind of loading progress bar to get a better idea of what is going on.

The last reason is the integration complexity. Unless you want a full-screen visualisation of your scene, you probably have some kind of header and footer on your page, maybe a navigation menu and some text around, so the exported scene is just a part of the page. You need a way to embed it like you embed an image, but if you export to single file, you’ll have to deal with a huge HTML file containing everything at will be really hard to embed it to an existing page.

So the rule of thumb: use single-file export for offline only. Sending by email? Saving to a flash drive? Sharing via DropBox? That’s fine for single-file export, otherwise use the server export mode.

How does server export help?

When exporting for server, Koru creates 3 files instead of one:

Here’s how this helps to fight the issues listed above:

  1. The exported scene is stored in compact binary format, so you get 30% smaller files, compared to text-bases single-file HTML;
  2. You can have just a single copy of Koru rendering engine on your website and use it on all the pages you need to display 3D models. The first page that loads it will put it into the browser cache and further pages will not load it at all - you save traffic and downloading time;
  3. Integration is now dead simple, as the HTML file is now very small: it simply loads Koru engine and passes it the scene file name. You can easily embed these few lines into your web page;
  4. As the HTML file is small and Koru rendering engine is stored and loaded separately, it starts much faster and displays interactive progress bar letting the user know how the loading is going.

You may ask that if everything is that good with server-mode export, why can’t we have the same for offline or single-file mode? Unfortunately, modern browsers are quite strict when it comes to security and they don’t let HTML pages to access files on your computer. So if you try to open a server-exported file in your browser, you will most likely get an error that the model cannot be loaded.

That’s why we have separate exporting modes for online and offline. Use the one which fits better.

So, Let’s Start?

Run Koru and open its Shapes Library panel (click images to see them in full resolution):

Koru shapes library

Drag any shape into the working area to make a test scene:

Sample Koru scene

Note that you can use your own 3D model here, it doesn’t really matter. We just need a sample scene for our tutorial.

Now switch to Materials Library panel, select a material and drag onto the shape:

Applying gold material to 3D model in Koru

Once again, you can setup your own material if you like or leave everything by default.

Finally you can add some extra details to your scene like snapshots or callouts:

Adding callout in Koru

Rotate the scene around with your mouse in Koru and make sure it looks exactly the way you need. Leave the camera in the “default” position that you want the exported file to show and click the Export button:

Clicking the export button in Koru

You will see the Export Wizard window.

Export Wizard

At the first step of the Export Wizard you will be asked to select the export target. As we need to export for server, click the Server option.

Koru export target selection

Then you will be asked to select the target file for saving and after that Export Wizard will ask you to choose the template you want to use for export:

Selecting export template in Koru Export Wizard

For this tutorial you’d better select “Minimalistic DIV” template as it better fits the idea of embedding something into existing page. Then click Next to proceed to exporting options.

Export Options in Koru

Here you can configure scene title, add <noscript> block for browsers that don’t support JavaScript and also pack everything to a ZIP file.

You can also configure textures downscaling options here if you have a Koru license.

Configure the options you need and click Next to see the exporting progress:

Exporting in Koru

And after a couple of seconds the results page will pop up:

The results of scene export in Koru

You can check Open exported folder box if you like, or simply manually navigate to the export folder. You will see 3 files there:

If you see the files, it means that the export went fine and we are ready for the next step.

Uploading Results

The further steps depend on how you manage your website. You may use some kind of content management system, or just have a control panel - it doesn’t really matter at the moment. All you need for now is to make a temporary folder on your website and upload all the exported files there.

Let’s name the folder “koru” and place it to the root folder of your website. Then after uploading the files you should be able to access it using the url: http://yourwebsite.com/koru/. We used a local-running web-server and here’s what we get for this tutorial:

Koru server export results

You should have something like this on your web server, as well. If not - make sure you uploaded the files to the right folder and that your web server is configured to use this folder.

Embedding to Existing Page

Note that you need a basic HTML knowledge to continue past this point. If you never made HTML yourself, it would be a good idea to take some online lessons, as otherwise it may be quite difficult to continue.

Once you have your scene on your site, it is now time to have a look inside the HTML file and see how it is done. If you open the HTML file in a text editor, you’ll see something like this:

Koru server-exported HTML contents

There are two and a half places that you need to understand to be able to embed a Koru shape into your own web page:

  1. The koru-viewport block. Koru engine looks for DIV tags with koru-viewport class and treats them as 3D scenes. In order to load the scene it reads the data-scene attribute and loads the scene model file mentioned there;
  2. The koru-1.2.2.js script block at the bottom. This is how you load Koru rendering engine.
  3. The parent block - that’s the “and a half” place of our “two and a half” places. As Koru scene usually takes as much space as it is given, you need another DIV block to define its size. Here we define a parent block of 800x600 pixels.

By this moment you should get an idea on how to embed Koru model into your own page: you simply need to make a koru-viewport DIV probably embedded into something to control its size and load the Koru engine script file somewhere at the bottom of your page. You can have both Koru engine and models in separate folders, just provide proper paths to both of them.

One More Thing

Exported scene needs proper version of Koru engine - the one it’s been exported with.

So when you update your Koru installation, you should either place the new engine next to the old one and use the new one with newly exported scenes, or re-export all the scenes using the latest Koru and then use the latest engine for all of them.

The latter is preferred as this way you get the most stable Koru engine with all the issues fixed and new features added.

That’s All

That’s not the only one export option in Koru, here are some more: