FEATURE: Save and load object X-ray states in BCF

[xeolabs]

Published in xeokit-sdk 2.4.2-beta-10 and xeokit-bim-viewer 2.4.16

This PR adds to BCFViewpointsPlugin a new xrayAsZeroAlpha option, which specifies how the plugin should handle X-ray effect for BCF viewpoints.

const bcfViewpoints = new BCFViewpointsPlugin(viewer, {
    xrayAsZeroAlpha: true // Default is false
});

When xrayAsZeroAlpha is true:

• when saving a viewpoint, for each X-rayed object, save 0 in the object's BCF color opacity
• when saving a viewpoint, for each non-X-rayed object, save the object's colorized opacity in its BCF color opacity, as usual
• when loading a viewpoint saved from a xeokit application (i.e. BCF originating_system == "xeokit.io"), if an object's BCF color opacity is 0 then set that object X-rayed
• when loading a viewpoint saved from a xeokit application, if an object's BCF color opacity is not 0, then set the opacity of that object to that color opacity, as usual.

The semantic here is that when xrayAsZeroAlpha is enabled, a saved BCF viewpoint sets color opacity 0 to indicate the object is X-rayed. When loading, the BCF color opacity 0 means the object is X-rayed. This assumes that we never colorize an object to 0 opacity when we use xrayAsZeroAlpha. That would make the object invisible, and that can be better done by simply setting it invisible anyway.

When xrayAsZeroAlpha is false (default):

• don't save any X-ray information in the A channel of each coloring component
• reset all objects as not X-rayed whenever loading a viewpoint.

Rationale

• Ensures that color opacities in BCF saved from other BIM applications are treated as colorize opacities, and not as X-ray, because X-ray is not supported in BCF and that would break assumption made by those applications.
• Ensures that no extra fields (i.e. xray) are added to BCF viewpoints, which would break compatibility with the BCF schema.
• If a xeokit application will save and load the same BCF, it must be careful not to colorize any objects with opacity == '0'

Demos

• Saving BCF with xrayAsZeroAlpha
• Loading BCF with xrayAsZeroAlpha

What this solves

Users have found that BCF viewpoints don't properly capture and restore xeokit's "x-ray objects" effect.

• xeokit-sdk has the concept of "x-raying" objects, where in the Viewer we can apply the X-ray effect to objects and mark them as X-rayed, ie. e can enable or disable "x-ray" for each object
• However, the BCF specification does not have the concept of "x-raying". When we save a BCF viewpoint, all the viewpoint can do is save RGBA color values with A as a value less than 1. The BCF doesn't indicate that A<1 could mean x-ray.
• Then when loading a BCF viewpoint back into a Viewer, or another Viewer, the Viewer doesn't know that A<1 could mean that the object is X-rayed.

[ghost]

👇 Click on the image for a new way to code review

Legend