Objects

Objects are intended to position components of different types (meshes, cameras, lamps etc) in a 3D scene space.

Types

The engine supports objects of the following types:

During the scene export, CURVE, TEXT, METABALL and SURFACE type objects are converted into MESH type objects.

Static and Dynamic Objects

An object can be either static or dynamic.

Static objects are objects that cannot be moved, animated or changed in any other way while running the application. For performance purposes, such objects can be merged together if they have the same material.

Dynamic objects can be moved, animated or changed in other ways while running the application. They can also interact with other objects, including static ones. Dynamic objects are never combined with each other or with static objects.

Only MESH and EMPTY type objects can be either static or dynamic. All other object types, such as CAMERA and ARMATURE, are always dynamic.

Static MESH objects are rendered much faster then the dynamic ones, so, for better performance, it is advised to keep the number of dynamic meshes to a minimum. Objects of any other type, both static and dynamic, do not significantly affect performance.

The objects which have animation, physics or a parent, which is a dynamic object, are considered dynamic, as well as the objects controlled by the following logic nodes:

  • Play Animation
  • Transform Object
  • Move To
  • Inherit Material

API methods that concern object movement, copying and animation (both object and node material) can only be applied to dynamic objects. In order to make the movement of the object without dynamic settings possible, it is necessary to activate Force Dynamic Object option in its settings.

Settings

The following is supported for all types of objects: transform, data reference, parent object, group membership and a set of the Blend4Web’s special properties.

Object Tab

_images/object_settings.png

Transform Panel

_images/object_settings_transform.png
Transform > Location
Position coordinates.
Transform > Rotation
Rotation angles. For the object rotation all available modes can be used (Rotation Mode). However only Quaternion (WXYZ) and XYZ Euler are supported for object animation.
Transform > Scale
Scaling. All 3 components (x, y, z) should be the same. Scaling for physics objects is not supported.

Groups Panel

Groups
Objects’ groups to which this object belongs.
_images/object_settings_groups.png

Level of Detail Panel

_images/object_settings_lod.png
Levels of Detail > LOD Transition Ratio
Parameter for smoothing the switching between the LOD objects. It defines the additional distance at which the LOD objects are still rendered before getting replaced by the next LOD objects. Assigned for the main object. Measured in fractions of the object’s bounding sphere radius.

Animation Panel

_images/object_settings_animation.png
Animation > Apply Default Animation
Upon loading into the engine start playback of the animation assigned to the object.
Animation > Animation Blending
Only for armature objects. Allows blending between skeletal animations.
Animation > Behavior
Animation behavior when the last frame is reached: Finish Stop - stop, Finish Reset - stop and go to the zero frame, Loop - repeat forever.

Export Options Panel

_images/object_settings_export.png
Export Options > Do Not Export
Do not export this object.
Export Options > Apply Modifiers
Apply the object’s modifiers upon export. If the SKIN modifier is used we recommend to apply it before the export because it resets vertex color and UV layers which may result in errors.
Export Options > Apply Scale and Modifiers
Upon export, apply scale and modifiers for the object.
Export Options > Export Vertex Animation
Export previously created and saved vertex animation. Applicable for MESH type objects only.
Export Options > Export Shape Keys
Export shape keys. Applicable to MESH type objects only.

Note

The following properties are mutually exclusive: Apply Modifiers, Apply Scale and Modifiers, Export Vertex Animation and Export Shape Keys.

Rendering Properties Panel

_images/object_settings_rendering.png
Rendering Properties > Hidden
An object with this property enabled will be hidden on load.
Rendering Properties > Do Not Render
Disable object rendering (for example useful for a physics object).
Rendering Properties > Disable Frustum Culling
Disable frustum culling optimization.
Rendering Properties > Force Dynamic Object
Force the object to become a dynamic object.
Rendering Properties > Dynamic Geometry
Allow overriding of the object’s geometry through Blend4Web API.

Shadows Panel

_images/object_settings_shadows.png
Shadows > Cast
The object will cast shadows.
Shadows> Cast Only
The object will cast shadows but will remain invisible itself. Becomes available after enabling Shadows > Cast.
Shadows > Receive
The object will receive shadows from other adjacent objects.

Billboard Panel

_images/object_settings_billboard.png
Billboard
Use the object as a billboard (i.e. automatically orient relative to the camera).
Billboard > Preserve Global Orientation and Scale
Take into account rotation and scale of the billboard object (in the world space). The object will be directed toward the camera with its side which is visible when viewing along the Y axis in Blender. Becomes available after enabling the Billboard checkbox.
Billboard > Billboard Type
Billboard orientation mode. Spherical (by default) - the object is always oriented with one side toward the camera, regardless of view angle, Cylindrical - similar to Spherical, but rotation is limited to Blender’s world Z axis. Becomes available after enabling Billboard

Reflections Panel

_images/object_settings_reflections.png
Reflections > Reflexible
When enabled the object is reflected in the dynamic mirror surfaces.
Reflections > Reflexible Only

The object will be reflected but will remain invisible itself. Becomes available after enabling Reflections > Reflexible.

Note

If the Reflexible Only parameter is enabled simultaneously with the Shadows > Cast Only parameter, the engine will not render the object itself, but will render its shadow and reflection, like it is shown on the picture below.

_images/objects_cast_reflexible_only.png
Reflections > Reflective
When enabled the object surface reflects other objects.
Reflections > Reflection Plane
Text field for name of an empty object which defines the reflection plane. Becomes available after enabling Reflections > Reflective.

Selection and Outlining Panel

_images/object_settings_selection.png
Selection and Outlining > Selectable
Enable object selection with the mouse or another input device.
Selection and Outlining > Enable Outlining
Enable outline glow for the object.

Anchors Panel

Anchors > Enable Anchor

This parameter enables interface for adding anchors (2D tags) to objects. Available for EMPTY objects only. Described in the corresponding section.

_images/objects_enable_anchors.png

Meta Tags Panel

_images/object_settings_meta_tags.png
Meta Tags

Interface for adding meta tags to the object:

Meta Tags > Title
Object’s title.
Meta Tags > Category
Object’s category.
Meta Tags > Description
Description for the object. Depending on Description Source, this field accepts either description text itself, or the name of a file where this description is contained.
Meta Tags > Description Source
Source type for the description: text or text file.

Relations Panel

_images/object_settings_relations.png
Relations > Parent

Reference to the parent object.

If the parent object is a camera, Viewport Alignment settings are available.

_images/objects_viewport_alignment.png

These settings can be used to align the object to an active camera. They are described in the Camera chapter.

Wind Bending Panel

_images/object_settings_wind.png
Wind Bending
Enables wind bending procedural animation. Thoroughly described at the outdoor rendering page.

Special Effects Panel

_images/object_settings_fx.png
Special Effects > Disable Fogging
Disable fog for the object.
Special Effects > Caustics
The object will render caustics effects from the adjacent water.

Physics Tab

_images/object_setup_phys.png

Detect Collisions
Activate the object’s physics.
Floating
Make the object floating. The settings for floating objects are described in detail in the physics section.
Vehicle
Use the object as part of a vehicle. The vehicle settings are described in detail in the physics section.
Character
Use the object for character physics. The character settings are described in detail in the physics section.

Anchor Settings

Anchors can be used to attach annotations to 3D objects. The annotation is displayed near the object regardless of the camera position and even follows it throughout the animation.

_images/objects_anchors_example.png

Annotations can be created entirely in Blender. All you need to do is to place an Empty object in the required position and enable the Anchor property. The text for the annotations can be assigned in the Title and Description fields on the Meta Tags panel.

_images/objects_anchors_settings.png
Enable Anchor
This parameter enables the interface for adding anchors (2D tags) to objects. This is available for EMPTY objects only.
Type

Anchor type

  • Annotation - content is obtained from the meta tags assigned to the object and displayed in the standard section.
  • Custom Element - an arbitrary HTML element from the current web page is used as an anchor.
  • Generic - an anchor’s position can be detected using the anchors API module.

Default value is Annotation.

HTML Element ID
This specifies the ID of the HTML element that will be used as the anchor. This is available only if the Type parameter is set to Custom Element.
Detect Visibility
Detect whether the anchor object is overlapped by other objects. This is disabled by default. Turning this option on decreases performance and should be used only when necessary.
Max Width
This parameter limits the expanding info window by a predefined value (measured in CSS pixels). This is available only if the Type parameter is set to Annotation, and it is set to 250 by default.

Object Transform API

Note

Make sure that the object you are trying to transform is a dynamic object.

Use the following methods of the transform module to move objects in the engine:

get_translation()
Get the coordinates of the object’s center in world space. The method with a single argument returns a new vector (i.e. this is a non-optimized option) while the method with two arguments requires an additional vector to write the result down.
get_translation_rel()
Similar to the get_translation() method, but if this object has a parent, the obtained coordinates are measured in the parent’s space.
set_translation(), set_translation_v()
Move the object’s center into the specified location. The first method takes separate coordinates as arguments while the second one takes a three-component vector (Array or Float32Array).
set_translation_rel(), set_translation_rel_v()
Similar to set_translation() and set_translation_v(), but if this object has a parent, the set coordinates are measured in the parent’s space.
get_rotation()
Get the object’s rotation quaternion in world space. Similar to get_translation(), there are two options for calling this function.
get_rotation_rel()
Get the object’s rotation quaternion measured in its parent’s space. Similar to get_translation_rel(), there are two options for calling this function.
set_rotation(), set_rotation_v()
Set the object’s rotation quaternion in world space. The first function takes separate coordinates as arguments while the second one takes a four-component vector (Array or Float32Array).
set_rotation_rel(), set_rotation_rel_v()
Set the object’s rotation quaternion measured in its parent’s space. The first function takes separate coordinates as arguments while the second one takes a four-component vector (Array or Float32Array).
get_scale()
Get the object’s scale in world space.
get_scale_rel()
Get the object’s scale in its parent’s space.
set_scale()
Set the object’s scale in world space. Unity corresponds to the original scale of the object. Values less than unity mean scaling down, bigger than unity - scaling up. Note that not all objects can be scaled. Particularly, scaling is not allowed for physics objects.
set_scale_rel()
Set the object’s scale in its parent’s space.
set_rotation_euler(), set_rotation_euler_v()
Set the object’s rotation using Euler angles. An intrinsic YZX rotation system is used (that means the angles follow in the YZX order and the origin of coordinates rotates and takes up a new position for every angle).
set_rotation_euler_rel(), set_rotation_euler_rel_v()
Set the object’s rotation using Euler angles measured in its parent’s space.
move_local()
Move the object relative to its original position (in local space).
rotate_x_local(), rotate_y_local(), rotate_z_local()
Rotate the object relative to its original position (in local space).

Get Object API

To perform any operation with an object, you first need to get it (i.e. receive the link to it). There are several API functions for doing this. A link to an object has Object3D type.

get_object_by_name()

Get object by name.

// ...
var obj = m_scenes.get_object_by_name("Object");
// ...
get_object_by_dupli_name()

Get the duplicated object by empty name and dupli name.

// ...
var obj = m_scenes.get_object_by_dupli_name("Empty", "Object");
// ...
get_object_by_dupli_name_list()

Get the duplicated object by empty name and dupli name list (an array of String type elements).

// ...
var obj = m_scenes.get_object_by_dupli_name_list(["Empty1", "Empty2", "Object"]);
// ...
get_object_name_hierarchy()

Returns the object names hierarchy array (from the highest parent to the object itself) for a given object.

// ...
var names = m_scenes.get_object_name_hierarchy(obj);
// ...
check_object_by_name()

Check if object with given name is present on scene.

// ...
var object_exists = m_scenes.check_object_by_name("Cube");
// ...
check_object_by_dupli_name()

Check if duplicated object is present on scene by empty name and dupli name.

// ...
var object_exists = m_scenes.check_object_by_dupli_name("Empty", "Cube");
// ...
check_object_by_dupli_name_list()

Check if duplicated object is present on scene by empty name and dupli name list (an array of String type elements).

// ...
var object_exists = m_scenes.check_object_by_dupli_name_list(["Empty1", "Empty2", "Object"]);
// ...
get_object_name()

Get the object’s name.

// ...
var object_name = m_scenes.get_object_name(obj);
// ...

Object Selection

In order to enable selection of a certain object, it is required to enable the Selectable checkbox on the Selection and Outlining panel.

Note

Make sure that the status on the Scene > Object Outlining panel is set to ON or AUTO.

Object selection is possible programmatically via API, for example, in the scenes.js module there is the pick_object function which selects an object based on canvas 2D coordinates,

// ...
var x = event.clientX;
var y = event.clientY;

var obj = m_scenes.pick_object(x, y);
// ...

or using the Logic Editor.

If the selectable object has enabled Enable Outlining and Outline on Select checkboxes on the Object > Selection and Outlining panel, then the pick_object function call will activate outline glow animation.

Note

If the selected object is transparent (Blend, Add and Sort transparency types), outline glow will only be visible on the parts that have Alpha value higher than 0.5.

Copying Objects (Instancing)

It is often required to copy (to make instances of) objects during application work.

Copying objects has its limitations:
  • only MESH objects can be copied
  • the object should be dynamic (enable Rendering Properties > Force Dynamic Object)
  • the source object should belong to the active scene

Making a Simple Copy

In case of simple copying the new object will share the mesh with the original object. Thus, if the original object’s mesh is changed, the copied object’s mesh will be changed too. To make simple copying possible, it’s enough to turn on the Blend4Web > Force Dynamic Object setting in the source object’s properties.

Making a Deep Copy

In case of deep copying, the new object will have unique properties, namely it will have its own mesh. Thus, if the original object’s mesh is changed, the copied object’s mesh will not be changed. Also, the canvas textures on the copied objects are different textures and not one and the same like it is the case with the simple copying. To make deep copying possible, it is required to enable the Rendering Properties > Dynamic Geometry checkbox for the source object. |

Copying objects in runtime can be performed with the copy method of the objects.js module. This method requires three arguments: the id of the source object, a unique name for the new object and the boolean value to specify the copy mode (i.e. simple or deep). By default, simple copying will be performed.

The newly created object should be added to the scene. This can be performed with the append_object method of the scenes.js module. The new object should be passed to it as an argument.

// ...
var new_obj = m_objects.copy(obj, "New_name", true);
m_scenes.append_object(new_obj);
m_transform.set_translation(new_obj, 2, 0, 2);
// ...

Removing Objects

To remove objects, use the remove_object method of the scenes.js module. Pass the object to it as an argument. Dynamic mesh- and empty-type objects can be removed this way.

// ...
m_objects.remove_object(new_obj);
// ...

Quaternions

Quaternion is a four-component vector used to perform rotating. Quaternions have a number of advantages over other rotation methods such as:

  • A quaternion has no ambiguity and doesn’t depend on the rotation order as the Euler angles.
  • Quaternion’s memory usage is more effective (2-4 times less depending on the matrix used).
  • Better computing efficiency than for matrices in case of a series of rotations.
  • Numeric stability - compensation for multiplication errors arising from float number inaccuracy.
  • Convenient interpolation method.
Quaternions have some drawbacks:
  • Rotating a vector with a quaternion is more computationally expensive than rotating with a matrix.
  • It is difficult to use quaternions for non-rotation transformations (such as perspective or orthogonal projection).

The engine has a number of functions to make it more convenient to work with quaternions:

quat.multiply
Quaternion multiplication. Note that left-multiplying A quaternion by B quaternion A*B is a rotation by A. I.e. the object already has some rotation B which we supplement with a new rotation by A.
quat.setAxisAngle
A quaternion is an alternative presentation of rotation by an arbitrary angle relative to the arbitrary axis (vector). Positive direction of rotation is defined as anticlockwise when viewing from the vector’s end. For example the :code`quat.setAxisAngle([1, 0, 0], Math.PI/2, quat)` call forms a quaternion which can be used for rotating the object by 90 degrees (anticlockwise if viewing from the X axis’ end) relative to the X axis.
quat.slerp
Spherical interpolation of quaternions. Used for smoothing the object’s rotation and animation.
util.euler_to_quat, util.quat_to_euler.
Conversion from Euler angles and back.

Quaternion Example

We need to rotate the object by 60 degrees in a horizontal plane to the right. We have a model named “Cessna” in Blender.

_images/objects_aircraft.png

Let’s save a reference to the object in the aircraft variable:

var aircraft = m_scenes.get_object_by_name("Cessna");

Let’s rotate it:

  • A clockwise rotation corresponds to the rotation to the right (i.e. in the negative direction).
  • 60 degrees = \(\pi/3\) radians.

As a result we get:

// compose quaternion
var quat_60_Z_neg = m_quat.setAxisAngle([0, 0, 1], -Math.PI/3, m_quat.create());

// get old rotation
var quat_old = m_transform.get_rotation(aircraft);

// left multiply: quat60_Z_neg * quat_old
var quat_new = m_quat.multiply(quat_60_Z_neg, quat_old, m_quat.create());

// set new rotation
m_transform.set_rotation_v(aircraft, quat_new);

The optimized version which does not create new objects:

// cache arrays as global vars
var AXIS_Z = new Float32Array([0, 0, 1])
var quat_tmp = new Float32Array(4);
var quat_tmp2 = new Float32Array(4);
...
// rotate
m_quat.setAxisAngle(AXIS_Z, -Math.PI/3, quat_tmp);
m_transform.get_rotation(aircraft, quat_tmp2);
m_quat.multiply(quat_tmp, quat_tmp2, quat_tmp);
m_transform.set_rotation_v(aircraft, quat_tmp);

Moving via TSR Vectors

It is sometimes convenient to move objects using vectors of the following format:

\([T_x, T_y, T_z, S, R_x, R_y, R_z, R_w]\)

Here \(T_x, T_y, T_z\) - the components of the translation vector, \(S\) - scale factor, \(R_x, R_y, R_z, R_w\) - the components of the quaternion vector. Hence the name of this vector: TSR or TSR-8.

This vector can be operated via tsr module, as well as via set_tsr()/get_tsr() methods of the transform module.