Cameras

Camera controls are accessible via dopple.controls, offering a variety of methods to enable or disable specific camera functionalities.

By default, camera controls are enabled globally in the scene, but may be disabled by setting the enabled property to false.

const dopple = new DoppleXR({
  /* ... */
});

dopple.controls.enabled = true; // (Default) enable camera controls globally
dopple.controls.enabled = false; // Disable camera controls globally

Behaviors

Out of the box, Dopple allows users to freely rotate, reposition, and zoom the camera using either touch gestures (on supported devices) or the mouse.

Controlling the behavior of each mouse button and touch gesture is as easy as setting a new value to the respective control’s property.

• 0 — Disable all camera controls.
• 1 — Enable orbit rotation only.
• 2 — Enable trucking only.
• 16 — Enable dollying only.
• 32 — Enable zooming only.

// Default values for each mouse button
dopple.controls.mouseButtons.left = 1;
dopple.controls.mouseButtons.right = 2;
dopple.controls.mouseButtons.middle = 16;
dopple.controls.mouseButtons.wheel = 16;

Orbit (Rotate)

Truck (Reposition)

Dolly (Zoom)

Orbit

By default, the camera may be rotated around the product by clicking and dragging on the canvas, or by touching and dragging on touch devices.

dopple.controls.mouseButtons.left = 0; // Disable all left-click controls
dopple.controls.mouseButtons.left = 1; // (Default) enable rotation only

Truck

Trucking allows users to freely move and reposition the camera around the scene, to look at 3D products from different angles and positions.

By default, the camera may be repositioned by right-clicking and dragging the mouse, or by touching and dragging with two fingers. This behavior is controlled via dopple.controls.mouseButtons.right (set to 2 by default), and can be disabled by setting its value to 0, or setting it to 1 to have it rotate the camera as well.

dopple.controls.mouseButtons.right = 0; // Disable all right-click controls
dopple.controls.mouseButtons.right = 1; // Enable rotation only
dopple.controls.mouseButtons.right = 2; // (Default) enable trucking only

Note

Disabling the right mouse button’s action by setting controls.mouseButtons.right = 0 will re-allow right-clicking on the canvas to trigger a context menu.

Dolly

By default, the camera may be “zoomed” in and out scrolling the mouse wheel, clicking and dragging with the middle mouse button, or by pinching with two fingers on touch devices.

dopple.controls.mouseButtons.wheel = 0; // Disable all mouse wheel controls
dopple.controls.mouseButtons.wheel = 16; // (Default) enable dolly only
dopple.controls.mouseButtons.wheel = 32; // Enable zooming only

dopple.controls.mouseButtons.middle = 0; // Disable all middle mouse button controls
dopple.controls.mouseButtons.middle = 16; // (Default) enable dolly only
dopple.controls.mouseButtons.middle = 32; // Enable zooming only

“Zooming” in this case is technically a dolly movement which repositions the camera closer or further away from the target, instead of keeping the camera stationary and changing the field of view or lens focal length.

If you are looking to do a proper zoom and change the camera’s FOV instead of dollying, you can use the zoomTo() method to specify a zoom level. By default, the zoom level is set to 1.0. Optionally, you may also pass a 2nd boolean argument to control whether the transition should be smooth or instant.

dopple.controls.zoomTo(2.5, true); // Zoom to 2.5x and transition smoothly

Note

Disabling the mouse wheel’s action by setting controls.mouseButtons.wheel = 0 will allow the scroll wheel to scroll up and down the page again, even when hovering over the canvas.

Changing the Camera Position

To move the camera between different predefined positions — such as switching from a front view to a top-down view — simply use the updateSelection() method, just as you would for changing the rest of the product’s configuration.

await dopple.updateSelection({ "camera-position": "front" });

Note

This depends on the product being configured in the editor to have a property named camera-position that contains an option named front. Read more about camera settings in the glTF Editor here.

Autorotation

Autorotation is a feature that automatically orbits the camera around the product at a constant speed. The updateSelection() method can be used to toggle this autorotation behavior on or off.

await dopple.updateSelection({ autorotate: "on" });

Note

This assumes the product has been configured in the editor to have a property named autorotate that contains an option named on.

Resetting the Camera View

In some cases, it may be handy to reset the camera back to its original view, such as if a user accidentally moved the camera too far from the product and cannot locate it again.

The reset() method can be used to reset the camera back to its starting position.

await dopple.controls.reset();

Additionally, the reset() method also accepts an optional boolean argument to control whether the reset transition should be smooth or instant. By default, the transition will happen instantly.

await dopple.controls.reset(true); // Smoothly transition back to the starting position

Advanced Usage

Dopple’s camera controls utilize the camera-controls library under the hood. For advanced usage and more in-depth documentation, please refer to the camera-controls documentation.

Live Example

Loading...

Positions

Default Charger Toiletry Bag Auto-rotating

Settings

Allow rotation (left-click) Allow trucking (right-click) Allow dollying (scroll wheel) Reset Camera View

Full Code Example

index.html

<html>
  <head>
    <script type="module">
      import { DoppleXR } from "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js";

      // Initialize Dopple
      const dopple = new DoppleXR({
        container: document.getElementById("dopple-container"),
        owner: "my-org",
        workspace: "my-workspace",
        projectName: "luggage-example",
        productVersion: "1",
        selection: {},
      });

      await dopple.load();
      dopple.resize({ trackParentSize: true });
      dopple.run();

      // Disallow dollying/zooming
      dopple.controls.mouseButtons.wheel = 0

      // Make right-clicking rotate the camera instead of repositioning
      dopple.controls.mouseButtons.right = 1

      // Update the camera's position to whichever radio button is selected
      const cameraPositionRadios = cameraSettingsPanel.querySelectorAll("input[type='radio']");
      for (const radio of cameraPositionRadios) {
        radio.addEventListener("change", async () => {
          await dopple.updateSelection({
            "camera-position": radio.value,
          });
        });
      }

      // Handle the camera reset buttons
      const resetButtonInstant = document.getElementById("reset-camera-instant");
      resetButtonInstant.addEventListener("click", async () => {
        await dopple.controls.reset();
      });

      const resetButtonSmooth = document.getElementById("reset-camera-smooth");
      resetButtonSmooth.addEventListener("click", async () => {
        await dopple.controls.reset(true);
      });
    </script>
  </head>
  <body>
    <div id="dopple-container"></div>

    <!-- Camera position controls -->
    <label>
      <input type="radio" name="camera-position" value="default" checked />
      <span>Default</span>
    </label>
    <label>
      <input type="radio" name="camera-position" value="charger" />
      <span>Charger</span>
    </label>
    <label>
      <input type="radio" name="camera-position" value="toiletry-bag" />
      <span>Toiletry Bag</span>
    </label>
    <label>
      <input type="radio" name="camera-position" value="autorotate" />
      <span>Auto-rotating</span>
    </label>

    <!-- Reset view buttons -->
    <button id="reset-camera-instant">Instant Camera Reset</button>
    <button id="reset-camera-smooth">Smooth Camera Reset</button>
  </body>
</html>