User Interface

When you run Koru for the very first time, you’ll see its main window:

There is a toolbar at the top, panels at the sides and the main working area in the middle. The main working area has tabbed user interface, so you can open several scenes, switch between them and even drag or copy shapes and materials between the scenes.

Main Toolbar

Koru toolbar helps you switch gizmo modes, undo or redo operations, select tools and toggle panels. Here is the left part of the toolbar:

Koru toolbar, left part

The left section controls the gizmo, then go the undo/redo buttons, the next section is for tools and the last button runs export. The right part of the toolbar is for toggling panels:

Koru toolbar, right part

You can read more about panels below.

Gizmo

Gizmo helps you move, rotate or scale objects in Koru. Although you can do this using the node properties panel, it is much easier to use the gizmo instead. Here is the gizmo:

Gizmo in Koru

These arrows (or other shapes in other modes) can be used for dragging, rotating and scaling objects in Koru. Note that you can transform only nodes, not meshes that way. In order to transform the mesh, you need to extract it first using the scene tree context menu.

You can switch gizmo modes using Scene menu by clicking Select, Move, Rotate, Scale, Set camera target or Create callouts items, or by clicking the buttons at the left of the toolbar:

Gizmo buttons in Koru toolbar

From left to right:

You can also switch gizmo modes by pressing 1, 2, 3, 4, 5 or 6 keys on your keyboard.

Textures

Koru materials have lots of parameters that can use textures, like reflection, bump, mask and so on. Almost everywhere you can also provide a tint color or a multiplier. Here’s what it looks like:

Texture control in Koru material

The top one (Bump) has a multiplier, while the bottom one (Color) has a tint color instead. Both controls have texture boxes at the right. That’s the same image, explained:

Texture control in Koru material explained

By unchecking the box between the multiplier/tint field and the texture box, you can disable the texture for that parameter. In that case, only the tint or multiplier value will be used.

If you load an image to the texture control, it will change its appearance. Here we loaded image into the bottom control:

Texture control in Koru material with loaded image

As you may see, the bottom control displays a “picture” icon in its texture box, showing that an image is loaded there. You can drag that texture box and drop it to another control that accepts textures to copy the image with all its settings to that control.

Texture Editor

By clicking the texture box you open the texture editor window:

Texture editor window in Koru

Here’s what you can configure here:

Source section

Color correction section

Here you can make a simple color correction of the image by adjusting brightness, contrast and gamma levels. As with other settings, this affects only this exactly parameter, so the same image loaded to a different material will stay intact.

Mapping section

Koru can shift, tile and rotate textures in each slot. Here you configure it using the controls below:

Wrapping options are:

Filtering options are:

Crop section

Sometimes you just need a part of the image. That’s where the crop helps. You can define the rectangle of the image you want to use, using Left/Top/Right/Bottom fields. Note that the parameters should be in [0; 1] range, as these are UV coordinates.

The difference between crop and repeat/offset approach is that crop works before repeat/offset and you can easily tile cropped image without risk of seeing the parts that should be cropped.

Other Parameters

Sometimes (for bump images) texture editor shows a different set of parameters, mostly by removing the color correction section and adding a height/normal map switch, which is essential for bump.

Koru Export

Once the scene is ready, you can export it to HTML. To do so click the export button in the toolbar:

Koru export button in toolbar

Or click File → Export in the menu. Export Wizard window will pop up:

Template selection in Koru export wizard

Here you need to decide what do you export for:

Click the links above to read the tutorials for each option.

Koru Panels

You configure absolutely everything in Koru scenes using panels. Panels can be toggled on and off at the right side of the main toolbar or via the View menu:

Koru panel buttons

You can arrange the panels the way you need around the screen. You can dock them either to the left or right sides of the window, leave them floating around or even hide them. Koru remembers the positions of all the panels, so the next time you run it — you’ll be in your comfortable environment.

Scene Tree Panel

This panel displays the current scene tree. You can choose to hide or show meshes (geometries) using the bottom menu. The scene tree also displays materials assigned to meshes:

Koru scene tree panel

The nodes are displayed gray, while the meshes are white. Materials are at the right of the meshes and can be hidden using the View menu at the bottom. You can hide and show nodes by checking the boxes next to them.

You can also display a popup menu by right–clicking the node in the scene tree:

Koru scene tree popup menu

Here’s what you can do with the menu:

You can also access some of these items using the Edit and Scene menu items in the main menu bar.

Scene Properties Panel

All the scene-related properties like background, environment, floor and so on are located in the scene properties panel:

Koru scene properties panel

See below for the details of all the controls in the panel.

Background

Here you define what is displayed behind your scene. There are 7 options to choose from:

Then come the controls:

Environment

Environment is the essential part of the scene, as it is used for reflections. It is important to use HDR images for environment to make reflections nice. Koru comes with some HDR environment textures in its materials library, but you can use your own images, too.

Here are the controls you can use:

Floor Settings

This section lets you configure the floor. Note that you can edit “Floor” material if you want to customize the floor more.

Glow effect for speculars

Koru adds some glow around bright speculars to make them even brighter. You can control this here:

Watermark

Koru lets you add your own image on top of the rendered scene. Use Location control to select where to put the image, Scale parameter helps to adjust its size. Check Resize with viewport box if you want the watermark to be automatically scaled depending on the viewport resolution. Leave it unchecked if you want it to have its original size in pixels regardless of the viewport size.

Scene Materials Panel

All the objects in Koru scene share the same list of materials. You can use the same material on several objects and if you change the material, all the objects will be updated. Koru keeps the list of scene materials in the scene materials panel for your convenience.

Koru scene materials list

On the screenshot above Koru displays the list of currently loaded materials. Not all of them are being used, but the scene still keeps them.

There are two special materials in Koru scene: default and floor. Default material is not shown in the list. Koru use that material for the meshes that have no materials assigned. If you create a mesh - it will get the default material. If you delete a material that is being used by a mesh - that mesh will also get the default material. You can’t edit that material, it is used to let Koru keep rendering the meshes that have no materials. Another special material is “Floor” which is assigned to the scene floor. You also can’t delete it, but modifications are allowed, so you can add a texture or reflection to it.

You can reorder materials in the list by dragging them with your mouse.

The bottom menu allows you to alter the list or manipulate materials.

The Scene menu lets you do some useful tricks with selected materials:

Koru scene materials list context menu

There are two items there that may ease up your life a bit:

These actions are good together, say if you need to replace a material with another. You select the material, then select all the meshes with that material, then select another material and finally apply that material to all the selected objects.

How To Assign Materials

Besides the Scene → Apply material to selected geometry there is an easier way to assign material to a shape. You simply drag and drop the material onto the shape you want in preview or in scene tree and the material is automatically assigned to it.

How To Replace Materials

If you have a scene material and want to replace it with another one, and also update all the meshes to use the new material, there are two options. The first one is obvious yet long:

The second option is somewhat faster. Simply drag the new material on top of the old one in the scene materials list. Wait a few seconds until the old material gets selected, then drop the new material on it. This will update the old material with the new one, leaving just its name. If you want to keep the old material, as well, you need to duplicate it first, then update the original one.

Materials Library Panel

Koru comes with a library of materials and images that you can use to speed up your scene setup. There is a panel called Materials Library that contains all the materials that come with Koru:

Koru materials library panel

There is a filtering box at the top of the panel and a drop-down control that helps you filter out materials by their types. Then comes the long list of materials grouped by type (metal, glass, plastic, paint and so on), there are also images there, like textures and HDR environment images.

How To Use The Materials Library

You simply pick the material you need and drag it onto the shape you need either in scene preview or in the scene tree. The material is assigned to the shape and automatically added to the scene materials list. You can also drag materials directly into the scene materials list and then assign them from there.

The same applies to the images from the library, but instead of dragging them onto shapes or into the scene materials list, you need to drag them onto the texture controls of either material or scene properties editors.

Adding Your Own Materials

You can add your own materials to the library by dragging them from the scene materials panel into the materials library panel. Koru puts your materials into the special folder and you can then use them in other scenes.

Note that Koru doesn’t save textures with your custom materials, instead it saves absolute paths to them. This means if you add a custom material to the library and then move or delete its artwork, you will not be able to use that material later.

You can browse the saved materials folder with Explorer of Finder by clicking File → Open My Materials Library… item in the main menu.

Shapes Library Panel

Shapes panel displays some built–in shapes that you can start your scene with. Simply drag them into the scene or make a new one by dragging them into the empty workspace area. This way you can quickly test the application or add a simple shape to existing scene.

The panel is called Shapes Library and looks like this:

Koru shapes library panel

Koru does not (yet) provide an option to add your own shapes to the library, but we’re going to add this in the near future.

Materials Editor Panel

This is probably the most important panel in Koru. Here you can configure materials to make your scene looking the way you need. Here’s what it looks like:

Koru materials editor panel

The panel consists of three blocks:

Materials editor displays the properties of the currently selected material. You can select material by clicking an object in the scene, or directly in the scene materials list. The name of currently selected material is displayed in the panel title, so you always know what you edit.

Material Structure

It is described in more details here, but in two words materials consist of layers. Koru draws material layer by layer to render a surface.

Materials editor displays these layers in the material tree. By clicking items in the materials tree you see their properties at the right (or at the bottom for the narrow panel).

Main Parameters

Here you define if the material is single or double-sided. This affects culling and needs to be adjusted if geometry looks inverted.

Material Layer

Layers are the objects that actually define material. Here we’ll briefly run through all the properties.

Each layer can be emissive, diffuse or specular (or both). You activate the parts of the layer with check boxes in material editor. Each part has its own settings described below. There are also some common settings that works regardless of the layer’s type:

Then goes Diffuse layer check box that toggles diffuse properties panel:

The Specular layer check box lets you configure the reflective options of the layer:

You can also add an optional thin-film interference effect to reflecting material (think of soap bubble, oil on water or color-coated sunglasses). Check Thin-film interference box to see these extra options:

Finally, there is Emissive layer section that lets you make materials emissive. The options are quite straightforward:

Snapshots Panel

This panel lets you save a specific scene state for further usage. This includes camera position, node visibility and positions, assigned materials. Use this to capture nice views and layouts of the scene for further usage:

Snapshots panel in Koru

All the snapshots operations are done using the bottom menu:

You can double-click an item to activate the snapshot.

Snapshot Parameters

Below the list you can find controls that modify the properties of currently selected snapshot.

First comes Snapshot properties section that control the main parameter of a snapshot:

Then comes Saved information section which controls what information is restored when snapshot is activated:

Koru stores both camera state, node visibility and transformations and assigned materials when you make a snapshot. However, by checking the boxes on and off, you can decide what options to restore when you activate a snapshot. You don’t need to re-take snapshot after changing the options.

Next section is Snapshot activation crossfade and it controls how one snapshot changes another:

Finally comes the Sequence section that lets you automatically switch to another snapshot after specific period of time:

Callout Styles Panel

Koru lets you create pre-defined styles that you can later use with callouts. Callout style contains all the information about the look and feel of callouts and you can easily make multiple callouts looks the same using styles.

The panel is called Callout Styles and looks like this:

Callout styles panel in Koru

All the styles are listed at the top, and the buttons under the list lets you make basic operations:

You can export callout style for further usage by dragging the list item onto your desktop or into a folder on your computer. Later you can drag that file back into the callout styles list of another scene to re-use the style. You can also drag the style directly into another Koru scene opened in another tab.

Then goes the controls that you use to configure the currently selected callout style:

Text Parameters

This block controls the appearance of the callout text.

Background

Here you control the callout background.

Border

This section lets you configure the border around the callout.

Node Properties Panel

Node properties panel displays the properties of the currently selected node. Here’s what it looks like for most of the nodes:

Node properties panel in Koru

These are the same translation, rotation and scale parameters that you edit using gizmo. Actually using gizmo is probably the best way to edit them, so the panel can be used just for fine tuning the parameters.

The panel displays the node name in its title, so you always know what node you are working with.

Rendering Priority

Sometimes you need to make sure that a particular node is rendered after all the other ones are rendered. This is useful for semi-transparent objects and labels, for instance.

By default, Koru first renders opaque objects, then sorts the translucent ones from the further to nearer and renders them in that order. You can change that by setting a higher rendering priority. The larger the priority, the later the node will be rendered.

Lightmap Parameters

These parameters lets you specify if you want the node to cast or receive shadows. Read more about lightmaps here.

Callout Properties

Callouts don’t have all the transformation parameters like other nodes in Koru, here’s what callout properties panel looks like:

Callout properties panel in Koru

Here is the list of callout options you can use:

Then goes the transformation section where you can configure callout target position and define its rendering priority.

Decal properties

Decals have their own parameters in Node Properties panel:

Decal properties panel in Koru

See here for more details on decal parameters.

Image node properties

Image nodes (watermarks) also have their custom parameters explained in the watermarks tutorial.

Camera Settings Panel

This panel controls the Koru camera:

Camera settings panel in Koru

Here is the list of properties you can change:

You can restrict exported camera behavior using Camera Restrictions section:

Tools

Koru provides some tools to modify the scene for better visual appearance. The tool buttons are in the middle of the toolbar, or can be accessed via the Tools menu:

Koru tools buttons

The tools are explained below.

Fit To View Tool

Sometimes you need to quickly set the camera so it sees the whole scene (or just a part of it) leaving just a thin border of empty space around. That’s what the “Fit to View” tool is for. You can run it by clicking a toolbar button, or using the Tools menu.

Let’s make a simple scene like this one:

Simple Koru scene of plane and sphere

Now run the “Fit to View” tool and see its window pops up:

Fit to view tool in Koru

As you may see, the tool has some options:

Now if you see, by default Koru fits to the whole scene and keeps aspect: the result can be seen in background. The whole scene is visible, there is some space around and the camera aspect is the same. Let’s check Just selected objects and see what happens:

Fit to view tool in Koru just for selected objects

The only selected object in the scene is the blue sphere, so after checking the “selected objects only” option, we see that Koru adjusted the camera to better see the sphere. There is still some padding around and the camera aspect is still the same, but the plane is not completely visible anymore.

You now need to confirm the changes you made by clicking the OK button, or revert them by clicking Cancel.

UV Mapping Tool

Koru needs meshes to have texture mapping in order to apply textures to them. Sometimes models don’t have that mapping or have incorrect one. The UV Mapping tool helps you generate or correct the mapping, if necessary.

We’ll start with a koru model with incorrect texture mapping and a sample checkers texture applied:

Koru with a koru model

As you may see, texture mapping is not perfect, as the front face doesn’t look mapped at all. Let’s fix it with UV Mapping tool. To do so, click the Tools → Generate UV Mapping in the menu, or click the UV Mapping tool button in the toolbar. The UV Mapping generator window will pop up:

UV Mapping generator in Koru

Note that the mapping in background becomes better. Here’s what you can configure:

Koru supports 4 standard mapping types: Box, Planar, Cylindrical and Spherical. For all the types (except the Box one) you can choose the main axis. For instance by selecting “Spherical Z” you choose the spherical mapping along the Z axis.

Edit Normals Tool

Sometimes you need to re-generate normals of a single mesh or even the whole model. You may need to make them smooth or hard, or even flip them. You can do this in Koru using the Edit Normals tool.

Let’s start with a simple sphere shape with reflective metallic material (Steel for instance):

Koru with a 3d sphere

Now click the Tools → Edit Normals menu item or the corresponding button in the toolbar to see the normals editor window pops up:

Normals editor in Koru

Nothing really changed for the sphere, as by default the normals editor tool runs in “Auto” mode that tries to make normals smooth. As the sphere was smooth enough before we started, there is no much difference so far. However, things will change when we switch to the “Hard” mode that makes all the edges hard:

Normals editor in Koru - hard mode

As you may see, all the edges are now hard and the sphere looks like a disco ball. This is good when you need to focus on sharp edges of the shape.

The other two options are Flip normals and Flip facing. They let you heal inverted meshes that sometimes comes from improperly exported files or in case of import errors. Try them if you see the inside of your shape instead of the outer side. They usually help.

Edit Pivot Tool

Pivot point is the central point of the node which is used to scale or rotate the geometry of the node. Sometimes you may need to move that point to the center or to the bottom of the node for easier scene management. That’s what the Pivot Editor tool is for.

Let’s make a scene with a box and a sphere:

Koru scene with box and sphere

Both nodes have their pivot points at the bottom. If you need to rotate both shapes around their centers, you need to move their pivot points first. Click Tools → Setup Pivot Parameters in the menu, or click the pivot editor button in the toolbar. A pivot editor window pops up:

Koru pivot editor window

As you may see, both pivot points were automatically moved to the centers of shapes. That’s the default behavior of the pivot editor tool. Here’s what you can configure:

There are several methods of calculating pivot point position. You choose one using the Calculate pivot combo box:

As for the pivot moving rules, there are 3 options: Minimum, Maximum and Center. By default all the options are set to “Center” and this moves the pivot into the very middle of the shape. If for instance, you need to put a pivot in the middle of the bottom of the shape, you need to put “Pivot Z” to “Minimum”, while keeping the other two at “Center”.

Put On The Floor

This tool is quite straightforward, it simply places the selected object right on the floor surface. It is useful when you have something floating around or under the floor and want it has a nice floor shadow. No settings provided, it just works :)

Fix Transparent Meshes

It is quite a tricky process to display semi-transparent objects with hardware acceleration. For ideal results, all the triangles must be sorted by the distance from the camera in order to maintain a proper scene transparency. Unfortunately, this takes relatively long time to re-sort the scene each frame or after any camera movement, so we ended up in compromise.

This tool tries to re-order triangles of the mesh to help it look better when transparent. So if you import a bottle and it doesn’t look well with glass material - try this tool to fix it.

There is no parameters here, just select a mesh and click the tool button.

Geometry Optimization Tool

Sometimes scene geometry has too much details and exported scenes become large and take long time to load. To address this you can reduce the number of details in some meshes or in the whole scene, using the geometry optimization tool.

Let’s start with an Owlet model which is quite heavy. Drag it into the scene, then select it and click Tools → Optimize Geometry… item in the menu. You will see a wireframe mesh on the selected object and the tool starts pre-processing the mesh:

Pre-processing optimized mesh in Koru

Once the mesh is pre-processed you can see it optimized to some extent:

Optimized Mesh in Koru

You can now adjust the optimization parameters to get the best balance between the number of triangles and the visual appearance of the shape.

There are two parameters you can configure:

As both parameters affect the shape, Koru uses the one that gives more optimized result.

Here we limited the number of vertices by 1000 and got quite a low-poly model:

Over-optimized Mesh in Koru

Find the proper balance using these parameters then click OK to commit the changes.

Sometimes mesh optimization can lead to artifacts in texture mapping. If your shape has texture, especially a wrapped one - it is a good idea to double-check the optimized version for artifacts. You can always undo the optimization and try less aggressive parameters or avoid the optimization completely.

Metadata Editor

You can edit metadata for nodes and snapshots. Metadata is a list of key-value pairs that you can setup in scene and access later in exported scene using JavaScript.

Select a node in scene and then click Scene → Metadata Editor… in the main menu to see the editor:

Koru Metadata Editor

The buttons at the bottom-left corner lets you add and delete metadata, that are displayed in the list. Here is the same window after inserting and editing some data:

Koru Metadata Editor with values

Click OK when done, or Cancel if you don’t want to update the metadata of the selected node.

That’s All!

You can find more information at our Koru tutorials page.