Modify Scene Properties

This documentation demonstrates how to use the Scene API. It allows you to manage 3D objects, scene properties and various rendering settings.

Add and remove objects

add(myObject)

You can add supported scene objects using:

twin.scene.add(myObject);
Parameter
  1. myObject: Type: TextLabel2D, HtmlLabel2D, and LabelLine. For more, take a look at CustomLabels

remove(myObject)

You can remove them using:

twin.scene.remove(myObject);
Parameter
  1. myObject: Type: TextLabel2D, HtmlLabel2D, and LabelLine. For more, take a look at CustomLabels

Get object information

getObject3DAsJson(guid)

You can retrieve a scene object by its guid:

let guid = "my-guid"; 

let obj = twin.scene.getObject3DAsJson(guid);
Parameter
  1. guid: The Guid of the desired Object3D.
Returns
  1. object3D Type: Json. The desired Object 3D with the given information as Json.

getObject3D(guid)

You can retrieve a scene object by its guid:

let guid = "my-guid"; 

let obj = twin.scene.getObject3D(guid);
Parameter
  1. guid: The Guid of the desired Object3D.
Returns
  1. object3D Type: Object3D. The desired Object 3D with the given guid.

Selection handling

You can select and deselect objects:

selectObject3D(guid)

This selects a specific object by its guid:

let guid = "my-guid"; 

twin.scene.selectObject3D(guid);
Parameter
  1. guid: The Guid of the desired Object3D.

deselectObject3D(guid)

This deselects a specific object by its guid:

let guid = "my-guid"; 

twin.scene.deselectObject3D(guid);
Parameter
  1. guid: The Guid of the desired Object3D.

deselectAllObject3D()

This deselects all object:

twin.scene.deselectAllObject3D();

getGuidsOfSelectedObject3Ds()

To get all selected objects:

let selected = twin.scene.getGuidsOfSelectedObject3Ds();
Returns
  1. selected Type: string list. The desired Object3D with the given guid.

Scene background and rendering

setBackgroundColor(color)

You can set the scene background color:

const color = "#000088"

twin.scene.setBackgroundColor(color);
Parameter
  1. color: hex color code of your desired color.

getBackgroundColor(color)

You can get the current background color:

let color = twin.scene.getBackgroundColor();
Return
  1. color: hex color code of the current color.

Display quality

This section covers the visual display options that will make your scene appear more vivid and bring more depth. It also covers option that can positively influence the performance of your mirror.

Shadows

Shadows allow your scene to appear more lively and spatial. In return, they need a lot of computing power. Depending on your hardware performance, it is advisable to switch this off. It is necessary that the scene is loaded before enabling the shadows.

enableShadows(enable)

Enable or disable shadows:

window.twin.host.notify = function (topic, payload) {
    if (topic === "sceneLoaded") {
        window.twin.scene.enableShadows(true);
    }
};
Parameter
  1. enable: Type: bool. Enables/disables shadows.

This is a scene with shadows enabled: Scene with Shadows

This is a scene with shadows disabled: Scene without Shadows

Scalable Ambient Occlusion

Scalable Ambient Occlusion is a technique that adds soft shadows to corners and edges to make them look more realistic and three-dimensional. Depending on your hardware performance, it is advisable to switch this off.

enableScaleableAmbientOcclusion(enable)

Enable scaleable ambient occlusion:

twin.scene.enableScaleableAmbientOcclusion(enable);
Parameter
  1. enable: Type: bool. Enables/disables Scalable Ambient Occlusion.

This example shows SAO enabled with two cubes: one above the other. You can clearly see, that there are two cubes. One above and one below. Scene with SAO

This is the same scene but without SAO. Now it looks just like one cube. Scene without SAO

Antialiasing

Antialiasing is a technique that smooths jagged edges in digital images to make them look cleaner and more natural. Depending on your hardware performance, it is advisable to switch this off.

enableAntialiasing(enable)

Enable antialiasing:

twin.scene.enableAntialiasing(enable);
Parameter
  1. enable: Type: bool. Enables/disables Antialiasing.

This is an edge with antialiasing:

Scene with Antialiasing

This is an edge without antialiasing. You can clearly see the difference, especially when you look at the two people or the robots.

Scene without Antialiasing

Frame Rate

The frame rate can be adjusted. This could help to reduce system load on limited hardware or to run even more smoothly on better hardware.

You can manually set/get the rendering frame rate:

setFPS(fps)

twin.scene.setFPS(fps);
Parameter
  1. fps: Type: int. Value of the desired frame rate.

getFPS(fps)

let fps = twin.scene.getFPS();
Return
  1. fps: Type: int. Value of the current frame rate.

Get parent hierarchy

getParentGuids(guid)

You can get the full parent chain of a 3D object:

let parents = twin.scene.getParentGuids(guid);
Parameter
  1. guid: Type: string. GUID of the object you want to access.
Return
  1. parents: Type: string list with the guids of the parents.

Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Scene API Demo</title>
  <script src="./js/twin.min.js"></script>
  <style>
    html, body {
      margin: 0;
      padding: 0;
      height: 100%;
      font-family: sans-serif;
    }

    #twinMirror {
      position: relative;
      width: 100%;
      height: 100%;
      overflow: hidden;
    }

    #controls {
      position: absolute;
      top: 10px;
      left: 10px;
      z-index: 10;
      background: rgba(255, 255, 255, 0.9);
      padding: 10px;
      border-radius: 4px;
    }

    #controls button, 
    #controls input[type="text"],
    #controls input[type="number"],
    #controls input[type="color"] {
      display: block;
      margin-bottom: 5px;
      width: 180px;
      font-size: 14px;
    }

    #controls label {
      font-size: 13px;
      margin-top: 10px;
      display: block;
    }
  </style>
</head>
<body>
  <div id="twinMirror"></div>
  <div id="controls">
    <label>GUID:</label>
    <input type="text" id="guidInput" placeholder="Object GUID">

    <button onclick="selectObject()">Select Object</button>
    <button onclick="deselectObject()">Deselect Object</button>
    <button onclick="deselectAll()">Deselect All</button>
    <button onclick="getSelected()">Get Selected GUIDs</button>
    <button onclick="getObject3D()">Get Object3D</button>
    <button onclick="getParents()">Get Parent Guids</button>

    <label>Background Color:</label>
    <input type="color" id="bgColorPicker" value="#000088">
    <button onclick="setBackgroundColor()">Set Background Color</button>
    <button onclick="getBackgroundColor()">Get Background Color</button>

    <button onclick="toggleShadows()">Toggle Shadows</button>
    <button onclick="toggleSAO()">Toggle SAO</button>
    <button onclick="toggleAA()">Toggle Antialiasing</button>

    <label>Set FPS:</label>
    <input type="number" id="fpsInput" placeholder="e.g. 30">
    <button onclick="setFPS()">Set FPS</button>
    <button onclick="getFPS()">Get FPS</button>
  </div>

  <script>
    window.twin = new twinLibrary.Twin();
    window.twin.start("twinMirror", "http://localhost:3000");
    window.twin.host.notify = function (topic, payload) {
        if (topic == "objectClicked") {
          let clickedObject = JSON.parse(window.twin.scene.getObject3DAsJson(payload.guid));
          let name = clickedObject.Name;
          let guid = clickedObject.Guid;

          console.log(`Clicked object: Name = ${name}, GUID = ${guid}`);
        }
      };
    let state = {
      shadows: true,
      sao: true,
      aa: true,
    };

    function selectObject() {
      const guid = document.getElementById("guidInput").value.trim();
      if (guid) twin.scene.selectObject3D(guid);
    }

    function deselectObject() {
      const guid = document.getElementById("guidInput").value.trim();
      if (guid) twin.scene.deselectObject3D(guid);
    }

    function deselectAll() {
      twin.scene.deselectAllObject3D();
    }

    function getSelected() {
      const selected = twin.scene.getGuidsOfSelectedObject3Ds();
      alert("Selected GUIDs:\n" + selected.join("\n"));
    }

    function getObject3D() {
      const guid = document.getElementById("guidInput").value.trim();
      if (guid) {
        const obj = twin.scene.getObject3D(guid);
        console.log("Object3D:", obj);
        alert("Object3D logged to console.");
      }
    }

    function getParents() {
      const guid = document.getElementById("guidInput").value.trim();
      if (guid) {
        const parents = twin.scene.getParentGuids(guid);
        alert("Parent GUIDs:\n" + parents.join("\n"));
      }
    }

    function setBackgroundColor() {
      const color = document.getElementById("bgColorPicker").value;
      twin.scene.setBackgroundColor(color);
    }

    function getBackgroundColor() {
      const color = twin.scene.getBackgroundColor();
      alert("Background color is: " + color);
    }

    function toggleShadows() {
      state.shadows = !state.shadows;
      twin.scene.enableShadows(state.shadows);
    }

    function toggleSAO() {
      state.sao = !state.sao;
      twin.scene.enableScaleableAmbientOcclusion(state.sao);
    }

    function toggleAA() {
      state.aa = !state.aa;
      twin.scene.enableAntialiasing(state.aa);
    }

    function setFPS() {
      const fps = parseInt(document.getElementById("fpsInput").value, 10);
      if (!isNaN(fps)) twin.scene.setFPS(fps);
    }

    function getFPS() {
      const fps = twin.scene.getFPS();
      alert("Current FPS: " + fps);
    }
  </script>
</body>
</html>