Paintables

• What's a Paintable?
• Usage with tag manager
• SVGs & external resources like fonts and images

What's a Paintable?

Paintables can be used to let the client/browser draw graphics on a 3d model. Those graphics can be anything that can be internally converted to a ImageBitmap like SVGs.

You can set paintables on each material of the 3d model. The viewer will draw the graphic as a texture on the corresponding mesh(es). The positioning and scaling can be adapted via the UV parameters, see PaintableOptions

Usage with tag manager

Paintables are nothing more than a material parameter of the tag manager. You can set a source string, which will be loaded into an image bitmap and applied as texture on the desired material.

viewer.tagManager.setMaterialParameterValue('matPaintable', Parameter.PAINTABLE, 'https://path.to/image.jpg');

The paintable can be flipped, rescaled or repositioned if needed. In this case the parameter value has to be a JSON string.

viewer.tagManager.setMaterialParameterValue('matPaintable', Parameter.PAINTABLE, JSON.stringify({
    // the source string
    src: 'https://path.to/image.jpg',
    // -1 for flipping the texture on the mesh
    uScale: -1,
    vScale: -1,
  })
);

viewer.tagManager.setMaterialParameterValue('matPaintable', Parameter.PAINTABLE, JSON.stringify({
    // the source string as Svg
    src: '<svg>SVG Content...</svg>',
    // texture adjustment in v direction
    vScale: 0.5,
    vOffset: 0.1
  })
);

It's recommended to use JSON.stringify for converting the paintable definition into a JSON string, to avoid syntax errors caused by typos.

Besides uScale and vScale you can also use uOffset and vOffset to tweak the image appearence on the corresponding mesh, see PaintableOptions. These properties will be forwarded to the corresponding UV properties of the associated texture. Have a look at the official Babylon.js docs about these UV properties.

SVGs & external resources like fonts and images

The viewer is automatically handling external resources within the SVG like images or fonts embedded via URLs in font face defintions or image tags etc.

In order to do so it needs to download those resources first so that it can convert them to their Base64 textual representation and exchange the external URLs with the "local" data URI.

This does not mean that it has to re-download each external resource on every update since it can fetch the resources from the browsers cache if they already exist there.

However, there's one important thing you need to consider: The viewer cannot differentiate between external resources that are visible or in use and ones that are invisible or not in use.

It will download & process each external URL it finds in the SVG you hand him over!

This means the following:

Always ensure that the SVG only consits of external URLs (images, font faces, ...) which are actually visible or in use! Do not put every font face into the SVG which is available in the configurator but only the ones which are actually in use! Doing otherwise will decrease the Paintables render performance very drastically!