Table of Contents
Objects are intended to position components of different types (meshes, cameras, lamps etc) in a 3D scene space.
The engine supports objects of the following types:
During the scene export,
SURFACE type objects are converted into
MESH type 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.
EMPTY type objects can be either static or dynamic. All other object types, such as
ARMATURE, are always dynamic.
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:
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.
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.
- Transform > Location
- Position coordinates.
- Transform > Rotation
- Rotation angles. For the object rotation all available modes can be used (
Rotation Mode). However only
XYZ Eulerare supported for object animation.
- Transform > Scale
- Scaling. All 3 components (x, y, z) should be the same. Scaling for physics objects is not supported.
- Objects’ groups to which this object belongs.
Level of Detail Panel¶
- 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 > 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¶
- Export Options > Do Not Export
- Do not export this object.
- Export Options > Apply Modifiers
- Apply the object’s modifiers upon export. If the
SKINmodifier 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
MESHtype objects only.
- Export Options > Export Shape Keys
- Export shape keys. Applicable to
MESHtype objects only.
The following properties are mutually exclusive: Apply Modifiers, Apply Scale and Modifiers, Export Vertex Animation and Export Shape Keys.
Rendering Properties Panel¶
- 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 > 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.
- 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 > 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 > 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.
- 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¶
- Anchors > Enable Anchor
This parameter enables interface for adding anchors (2D tags) to objects. Available for
EMPTYobjects only. Described in the corresponding section.
- Relations > Parent
Reference to the parent object.
If the parent object is a camera,
Viewport Alignmentsettings are available.
These settings can be used to align the object to an active camera. They are described in the Camera chapter.
Wind Bending Panel¶
- Wind Bending
- Enables wind bending procedural animation. Thoroughly described at the outdoor rendering page.
Special Effects Panel¶
- Special Effects > Disable Fogging
- Disable fog for the object.
- Special Effects > Caustics
- The object will render caustics effects from the adjacent water.
- Detect Collisions
- Activate the object’s physics.
- Make the object floating. The settings for floating objects are described in detail in the physics section.
- Use the object as part of a vehicle. The vehicle settings are described in detail in the physics section.
- Use the object for character physics. The character settings are described in detail in the physics section.
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.
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
Description fields on the
Meta Tags panel.
- Enable Anchor
- This parameter enables the interface for adding anchors (2D tags) to objects. This is available for
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
Default value is
- HTML Element ID
- This specifies the ID of the HTML element that will be used as the anchor. This is available only if the
Typeparameter is set to
- 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
Typeparameter is set to
Annotation, and it is set to 250 by default.
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 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.
- 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 (
- set_translation_rel(), set_translation_rel_v()
- Similar to
set_translation_v(), but if this object has a parent, the set coordinates are measured in the parent’s space.
- Get the object’s rotation quaternion in world space. Similar to
get_translation(), there are two options for calling this function.
- 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 (
- 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 (
- Get the object’s scale in world space.
- Get the object’s scale in its parent’s space.
- 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 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 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).
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
Get object by name.
// ... var obj = m_scenes.get_object_by_name("Object"); // ...
Get the duplicated object by empty name and dupli name.
// ... var obj = m_scenes.get_object_by_dupli_name("Empty", "Object"); // ...
Get the duplicated object by empty name and dupli name list (an array of
// ... var obj = m_scenes.get_object_by_dupli_name_list(["Empty1", "Empty2", "Object"]); // ...
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 if object with given name is present on scene.
// ... var object_exists = m_scenes.check_object_by_name("Cube"); // ...
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 if duplicated object is present on scene by empty name and dupli name list (an array of
// ... var object_exists = m_scenes.check_object_by_dupli_name_list(["Empty1", "Empty2", "Object"]); // ...
Get the object’s name.
// ... var object_name = m_scenes.get_object_name(obj); // ...
In order to enable selection of a certain object, it is required to enable the
Selectable checkbox on the
Selection and Outlining panel.
Make sure that the status on the
Scene > Object Outlining panel is set to
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.
If the selected object is transparent (
Sort transparency types), outline glow will only be visible on the parts that have
Alpha value higher than 0.5.
It is often required to copy (to make instances of) objects during application work.
- Copying objects has its limitations:
MESHobjects can be copied
- the object should be dynamic (enable
Rendering Properties > Force Dynamic Object)
- the source object should belong to the active scene
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.
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); // ...
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:
- 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.
- 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.
- 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.
We need to rotate the object by 60 degrees in a horizontal plane to the right. We have a model named “Cessna” in Blender.
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);
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.