• Version 2.0.2
  • Added updateHTMLAnchor function
  • Usage
    • Advanced Usage

Version 2.0.2

List of all changes

Added updateHTMLAnchor function

The API of the ShapeDiver 3D viewer provides the possibility to add HTML elements on certain positions within the 3d scene.
These HTML elements will be repositioned each time the camera gets updated so that they behave just like all other 3d assets in this scene.
See Shapediver API Docs for further details.

The default update function from the ShapeDiver API is capable of text and image HTML elements.
But in many cases other HTML element types are required, such as buttons.
For this cases the new updateHtmlAnchor function can be used.

Usage

In order to get the HTML element into the scene an asset has to be defined using the structure of HtmlAnchorAsset.
The minimum required configuration consists of:

• Group name: For marking the assets
• Location: Absolute 3d position in the scene
• HTML string: String representation of the HTML element that should be assigned to the anchor position

/** @type {Cbn.CJS.HtmlAnchorAsset} */
const assetMinimum = {
  group: 'customHtmlAssets',
  content: [
    {
      location: { x: 0, y: 0, z: 0 },
      data: {
        html: '<span>HTML Anchor</span>',
      },
    },
  ],
};

await SdvCtrlUtils.updateHtmlAnchor([assetMinimum]);

For removing assets the ShapeDiver API function scene.removeAsync can be used.
The group name of the HTML anchor assets can be used as the filter criteria for scene.removeAsync:

sdApi.scene.removeAsync({ group: 'customHtmlAssets' });

Advanced Usage

Optionally a unique id can be added to the assets.
The id can be used as a more specific filter option or to update existing assets instead of adding new ones.
If an asset with a certain id is already available it will be updated and no additional asset will be created.

It is also possible to overwrite or extend certain tasks within the anchor workflow, such as:

• Adding anchors: For example adding listeners to the new HTML element
• Removing anchors
• Anchor position update: For example aligning the HTML element on the left side instead of the center of the element

These callbacks can be defined within the callbacks property of the asset.

For overwriting the position update it required to assign new values for htmlEl.style.left and htmlEl.style.top

/** @type {Cbn.CJS.HtmlAnchorAsset} */
const asset = {
  id: 'customHtmlAssets_1',
  group: 'customHtmlAssets',
  callbacks: {
    addAnchorCb: (htmlEl) => {
      htmlEl.onclick = () => {
        console.log('HS Button clicked');
      };
    },
    positionUpdateCb: (htmlEl, elSize, anchorPos) => {
      // align HTML element on left top side
      htmlEl.style.left = anchorPos.x + 'px';
      htmlEl.style.top = anchorPos.y + 'px';
    },
  },
  content: [
    {
      location: { x: 0, y: 0, z: 0 },
      data: {
        html: '<button>Btn Left</button>'
      },
    },
  ],
};

await SdvCtrlUtils.updateHtmlAnchor([asset]);

Finally the behaviour can be customized even more by adding payload data to the asset.
This freely configurable payload object can be accessed within all callbacks.
A common use case for this payload object is to define the type of hotspot or the alignment of the element.

/** @type {Cbn.CJS.HtmlAnchorAsset} */
const asset = {
  id: 'customHtmlAssets_1',
  group: 'customHtmlAssets',
  callbacks: {
    addAnchorCb: htmlEl => {
      htmlEl.onclick = () => {
        console.log('HS Button clicked');
      };
    },
    positionUpdateCb: (htmlEl, elSize, anchorPos, payload) => {
      htmlEl.style.top = anchorPos.y - elSize.y / 2 + 'px';
      if (payload.align === 'left') {
        // align left
        htmlEl.style.left = anchorPos.x + 'px';
      } else if (payload.align === 'right') {
        // align right
        htmlEl.style.left = anchorPos.x - elSize.x + 'px';
      } else {
        // align center
        htmlEl.style.left = anchorPos.x - elSize.x / 2 + 'px';
      }
    },
  },
  content: [
    {
      location: { x: 0, y: 0, z: 0 },
      data: {
        html: '<button>Btn Left</button>',
        payload: {
          align: 'left',
        },
      },
    },
    {
      location: { x: 100, y: 0, z: 0 },
      data: {
        html: '<button>Btn Right</button>',
        payload: {
          align: 'right',
        },
      },
    },
  ],
};

await SdvCtrlUtils.updateHtmlAnchor([asset]);