@realsee/dnalogel 2.1.0-alpha.13 → 2.1.0-alpha.15

package/libs/src/CSS3DRenderPlugin/CSS3DRender.js

@@ -0,0 +1,445 @@
+import * as THREE from 'three';
+import { CSS3DRenderer } from 'three/examples/jsm/renderers/CSS3DRenderer';
+import { Subscribe } from '../shared-utils/Subscribe';
+import { anyPositionToVector3, evenNumber } from './utils';
+import { CSS3DObjectPlus } from './utils/CSS3DObjectPlus';
+const VERSION = 'v2.0.0';
+const PLUGIN_NAME = 'CSS3DRenderer';
+export const __ELEMENT__ = '__CSS3DOBJECT_CSS3DRENDER_CONTAINER__';
+export const PLUGIN = `${PLUGIN_NAME}@${VERSION}`;
+const pluginFlag = (name) => `${PLUGIN}--${name}`;
+export const MinRatio = 0.00216;
+export const globalStore = {};
+export class CSS3DRender {
+    constructor() {
+        Object.defineProperty(this, "hooks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Subscribe()
+        });
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                enabled: true,
+                visible: true,
+                disposed: false,
+            }
+        });
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                disposers: [],
+                frontModeCSS3DObjects: {},
+                behindModeCSS3DObjects: {},
+            }
+        });
+        /**
+         * @description 根据传入的四个点位创建一个 3d dom容器，可以通过ReactDom.render()的方式将react组件放到容器中
+         * @param { Vector3Position[] } points 矩形四个点坐标
+         * @param config 均为可选值
+         * @config_document `config` 均为可选值
+         *  | key                   | type                       | defaultValue        | comment |
+         *  | -                     | -                          | -                   | -       |
+         *  | `ratio`               | *`number`*                 | `0.00216`           | 1px对应多少米，默认为 0.00216，即1px对应2.16mm |
+         *  | `devicePixelRatio`    | *`number`*                 | `1`                 | 设备的物理像素分辨率与CSS像素分辨率的比值 |
+         *  | `container`           | *`HTMLElement`*            | `undefined`         | 自定义 return 中的 `container`
+         *  | `pointerEvents`       | *`'none'\|'auto'`*         | `'none'`            | container 的 css属性：`pointer-events` 的值 |
+         *  | `autoRender`          | *`boolean`*                | `true`              | 是否自动渲染，通常为true |
+         *  | `mode`                | *`'front'\|'behind'`*      | `front`             | 两种模式:|
+         *  |                                                                          | | | `front`  模式：DOM 处于 five Canvas 上方，所以无法模拟遮挡效果，需要手动检测是否可见去设置显隐 |
+         *  |                                                                          | | | `behind` 模式：DOM 处于 five Canvas 下方，可以模拟真实的遮挡效果，但是 DOM 必须是非透明的 |
+         *  | `scene`               | *`THREE.Scene`*            | `undefined`         | 如果 mode 为 `behind`，需要传入 |
+         *
+         * @return
+         * ```typescript
+         *    {
+         *      id: string,                             // id
+         *      container: HTMLDIVElement               // dom容器
+         *      dispose: () => void                     // 销毁
+         *      css3DObject: CSS3DObject                // THREE.CSS3DObject 实例
+         *      render?: () => void                     // 渲染函数，当 config.autoRender = true || undefined 时为 undefined
+         *      setVisible: (visible: boolean) => void  // 设置显隐, 同 setVisibleById(id, visible)
+         *      show: () => void                        // 同 setVisible(true)
+         *      hide: () => void                        // 同 setVisible(false)
+         *      setEnabled: (enabled: boolean) => void   // 添加/移除 container, 同 setEnabledById(id, enabled)
+         *      enable: () => void                      // 同 setEnabled(true)
+         *      disable: () => void                     // 同 setEnabled(false)
+         *    } | void
+         * ```
+         */
+        Object.defineProperty(this, "create3DElement", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (camera, points, config) => {
+                if (this.state.disposed)
+                    return this.disposedErrorLog();
+                // ==== init ====
+                const mergeConfig = (() => {
+                    const defaultConfig = {
+                        ratio: 0.00216,
+                        devicePixelRatio: 1,
+                        mode: 'front',
+                        autoRender: true,
+                        container: document.createElement('div'),
+                        pointerEvents: 'none',
+                    };
+                    return Object.assign(defaultConfig, config);
+                })();
+                const vector3Points = points.map(anyPositionToVector3);
+                if ((vector3Points === null || vector3Points === void 0 ? void 0 : vector3Points.length) < 4)
+                    return console.error(`${PLUGIN}: requires 4 point but params may have fewer`);
+                const { ratio, devicePixelRatio: dpr, mode, autoRender, container, pointerEvents } = mergeConfig;
+                const disposers = [];
+                // ==== init END ====
+                // 获取css3DObject, 如果mode为behind的话，也一起获取mesh
+                const { css3DObject, opacityMesh } = this.createObject(vector3Points, {
+                    ratio,
+                    dpr,
+                    container,
+                    mode,
+                    pointerEvents,
+                });
+                container.id = `container--${css3DObject.uuid}`;
+                const frontModeAndFrontModeUnInited = mode === 'front' && !globalStore.frontModeStore;
+                const behindModeAndBehindModeUnInited = mode === 'behind' && !globalStore.behindModeStore;
+                if (behindModeAndBehindModeUnInited) {
+                    globalStore.behindModeStore = {
+                        scene: mergeConfig.scene,
+                        css3DScene: new THREE.Scene(),
+                        css3DRenderer: new CSS3DRenderer(),
+                    };
+                }
+                if (frontModeAndFrontModeUnInited) {
+                    globalStore.frontModeStore = { css3DScene: new THREE.Scene(), css3DRenderer: new CSS3DRenderer() };
+                }
+                const modeStore = mode === 'front' ? globalStore.frontModeStore : globalStore.behindModeStore;
+                const { css3DScene, css3DRenderer } = modeStore;
+                const render = (() => {
+                    const renderCSS3DObject = () => {
+                        if (mode === 'front') {
+                            this.store.frontModeCSS3DObjects[css3DObject.uuid] = {
+                                visible: true,
+                                enabled: true,
+                                css3DObject,
+                                mode: 'front',
+                            };
+                        }
+                        else {
+                            this.store.behindModeCSS3DObjects[css3DObject.uuid] = {
+                                visible: true,
+                                enabled: true,
+                                css3DObject,
+                                opacityMesh: opacityMesh,
+                                mode: 'behind',
+                                scene: mergeConfig.scene,
+                            };
+                        }
+                        css3DScene.add(css3DObject);
+                        if (mode === 'behind' && opacityMesh) {
+                            mergeConfig.scene.add(opacityMesh);
+                            disposers.push(() => opacityMesh && mergeConfig.scene.remove(opacityMesh));
+                        }
+                    };
+                    if (frontModeAndFrontModeUnInited || behindModeAndBehindModeUnInited) {
+                        css3DRenderer.domElement.style.position = 'absolute';
+                        css3DRenderer.domElement.style.top = '0';
+                        css3DRenderer.domElement.style.userSelect = 'none';
+                        css3DRenderer.domElement.style.pointerEvents = 'none';
+                        css3DRenderer.domElement.classList.add(pluginFlag(mode));
+                        const renderEveryFrame = () => {
+                            const requestAnimationFrameId = requestAnimationFrame(renderEveryFrame);
+                            modeStore.requestAnimationFrameId = requestAnimationFrameId;
+                            css3DRenderer.render(css3DScene, camera);
+                        };
+                        return () => {
+                            renderCSS3DObject();
+                            renderEveryFrame();
+                        };
+                    }
+                    return () => renderCSS3DObject();
+                })();
+                const wrapper = mode === 'front' ? globalStore.frontModeContainer : globalStore.behindModeContainer;
+                if (wrapper) {
+                    this.appendToElement(wrapper, mode);
+                    const store = mode === 'front' ? globalStore.frontModeStore : globalStore.behindModeStore;
+                    if (store)
+                        store.appendedToPage = true;
+                }
+                const setVisible = (visible) => this.setVisibleById(css3DObject.uuid, visible);
+                const setEnabled = (enabled) => this.setEnabledById(css3DObject.uuid, enabled);
+                const show = () => setVisible(true);
+                const hide = () => setVisible(false);
+                const enable = () => setEnabled(true);
+                const disable = () => setEnabled(false);
+                const dispose = () => {
+                    delete this.store.frontModeCSS3DObjects[css3DObject.uuid];
+                    delete this.store.behindModeCSS3DObjects[css3DObject.uuid];
+                    disposers.forEach((d) => d === null || d === void 0 ? void 0 : d());
+                    css3DScene.remove(css3DObject);
+                    // 如果全没了，就清除父容器
+                    if (css3DScene.children.length === 0) {
+                        if (typeof modeStore.requestAnimationFrameId === 'number') {
+                            cancelAnimationFrame(modeStore.requestAnimationFrameId);
+                        }
+                        css3DRenderer.domElement.remove();
+                        if (mode === 'front')
+                            globalStore.frontModeStore = undefined;
+                        if (mode === 'behind')
+                            globalStore.behindModeStore = undefined;
+                        globalStore.resizeObserver = undefined;
+                    }
+                    return true;
+                };
+                this.store.disposers.push(dispose);
+                if (autoRender)
+                    render();
+                return {
+                    id: css3DObject.uuid,
+                    container,
+                    dispose,
+                    css3DObject,
+                    render: autoRender ? undefined : render,
+                    show,
+                    hide,
+                    setVisible,
+                    disable,
+                    enable,
+                    setEnabled,
+                    appendToElement: (container) => this.appendToElement(container, mode),
+                };
+            }
+        });
+        Object.defineProperty(this, "setVisibleById", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (id, visible) => {
+                var _a;
+                const data = (_a = this.store.frontModeCSS3DObjects[id]) !== null && _a !== void 0 ? _a : this.store.behindModeCSS3DObjects[id];
+                if (!data)
+                    return;
+                data.css3DObject.visible = visible;
+                data.visible = visible;
+                if (data.mode === 'behind')
+                    data.opacityMesh.visible = visible;
+            }
+        });
+        Object.defineProperty(this, "setEnabledById", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (id, enabled) => {
+                var _a, _b, _c;
+                const data = (_a = this.store.frontModeCSS3DObjects[id]) !== null && _a !== void 0 ? _a : this.store.behindModeCSS3DObjects[id];
+                if (!data)
+                    return;
+                const css3DScene = data.mode === 'front' ? (_b = globalStore.frontModeStore) === null || _b === void 0 ? void 0 : _b.css3DScene : (_c = globalStore.behindModeStore) === null || _c === void 0 ? void 0 : _c.css3DScene;
+                if (!css3DScene)
+                    return;
+                if (enabled) {
+                    css3DScene.add(data.css3DObject);
+                    if (data.mode === 'behind')
+                        data.scene.add(data.opacityMesh);
+                }
+                else {
+                    css3DScene.remove(data.css3DObject);
+                    if (data.mode === 'behind')
+                        data.scene.remove(data.opacityMesh);
+                }
+                data.enabled = enabled;
+            }
+        });
+        Object.defineProperty(this, "createObject", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (points, config) => {
+                const { ratio, dpr, container, mode, pointerEvents } = config;
+                const css3DObject = new CSS3DObjectPlus(container, points, ratio, dpr);
+                container.style.pointerEvents = pointerEvents;
+                container.classList.add(`${PLUGIN_NAME}__container`);
+                const { domWidthPx, domHeightPx } = css3DObject;
+                // 生成透明Mesh
+                const opacityMesh = (() => {
+                    if (mode === 'behind') {
+                        const material = new THREE.MeshBasicMaterial({
+                            opacity: 0,
+                            transparent: false,
+                            side: THREE.DoubleSide,
+                        });
+                        const geometry = new THREE.PlaneGeometry(domWidthPx, domHeightPx);
+                        const mesh = new THREE.Mesh(geometry, material);
+                        mesh.name = pluginFlag('mesh');
+                        mesh.position.copy(css3DObject.position);
+                        mesh.rotation.copy(css3DObject.rotation);
+                        mesh.scale.copy(css3DObject.scale);
+                        return mesh;
+                    }
+                })();
+                return { css3DObject, opacityMesh };
+            }
+        });
+        Object.defineProperty(this, "createResizeObserver", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (element, resizeHandler, fireImmediately = true) => {
+                if (!element) {
+                    console.error('createResizeObserver: element is undefined');
+                    return { observe: () => { }, unobserve: () => { } };
+                }
+                const resizeObserverHandler = () => {
+                    /**
+                     * 这里evenNumber策略是遇到奇数会加1，在某些浏览器中会触发滚动条显示，导致fiveElement变小，fiveElement变小又触发了这里的resize，宽高变小，滚动条消失，然后又触发resize。。。无限循环
+                     * 所以为了规避上面这种情况，evenNumber设置了一个参数，遇到奇数可选择减一
+                     */
+                    const width = evenNumber(element.clientWidth, { smaller: true });
+                    const height = evenNumber(element.clientHeight, { smaller: true });
+                    resizeHandler(width, height);
+                };
+                if (typeof ResizeObserver === 'undefined' || !ResizeObserver) {
+                    console.warn('createResizeObserver: ResizeObserver is undefined');
+                    return { observe: () => resizeObserverHandler(), unobserve: () => { } };
+                }
+                const observer = new ResizeObserver(resizeObserverHandler);
+                if (fireImmediately)
+                    resizeObserverHandler();
+                return {
+                    observe: () => observer.observe(element),
+                    unobserve: () => observer.unobserve(element),
+                };
+            }
+        });
+        Object.defineProperty(this, "disposedErrorLog", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                console.error(`${PLUGIN} is disposed`);
+            }
+        });
+    }
+    getCurrentState() {
+        return this.state;
+    }
+    setState(state, options = { userAction: true }) {
+        if (this.state.disposed)
+            return this.disposedErrorLog();
+        const prevState = Object.assign({}, this.state);
+        this.state = Object.assign(this.state, state);
+        if (prevState.visible !== this.state.visible) {
+            state.visible ? this.handleShow() : this.handleHide();
+        }
+        if (prevState.enabled !== this.state.enabled) {
+            state.enabled ? this.handleEnable() : this.handleDisable();
+        }
+        this.hooks.emit('stateChange', { state: this.state, prevState, userAction: options.userAction });
+    }
+    dispose() {
+        this.store.disposers.forEach((d) => d === null || d === void 0 ? void 0 : d());
+        this.store.disposers = [];
+        this.hooks.emit('dispose');
+        this.state.disposed = true;
+    }
+    async show({ userAction } = { userAction: true }) {
+        if (this.state.disposed)
+            return this.disposedErrorLog();
+        this.setState({ visible: true }, { userAction });
+        this.hooks.emit('show', { userAction });
+    }
+    async hide({ userAction } = { userAction: true }) {
+        if (this.state.disposed)
+            return this.disposedErrorLog();
+        this.setState({ visible: false }, { userAction });
+        this.hooks.emit('hide', { userAction });
+    }
+    enable({ userAction } = { userAction: true }) {
+        if (this.state.disposed)
+            return this.disposedErrorLog();
+        this.setState({ enabled: true }, { userAction });
+        this.hooks.emit('enable', { userAction });
+    }
+    disable({ userAction } = { userAction: true }) {
+        if (this.state.disposed)
+            return this.disposedErrorLog();
+        this.setState({ enabled: false }, { userAction });
+        this.hooks.emit('disable', { userAction });
+    }
+    appendToElement(container, mode) {
+        if (!container)
+            throw new Error(`${PLUGIN} Cannot append to container: container is ${container}`);
+        const store = mode === 'front' ? globalStore.frontModeStore : globalStore.behindModeStore;
+        if (!store) {
+            if (mode === 'front')
+                globalStore.frontModeContainer = container;
+            if (mode === 'behind')
+                globalStore.behindModeContainer = container;
+            return;
+        }
+        if (store.appendedToPage)
+            return;
+        container.appendChild(store.css3DRenderer.domElement);
+        if (!globalStore.resizeObserver) {
+            const reSize = (width, height) => {
+                var _a, _b;
+                (_a = globalStore.frontModeStore) === null || _a === void 0 ? void 0 : _a.css3DRenderer.setSize(width, height);
+                (_b = globalStore.behindModeStore) === null || _b === void 0 ? void 0 : _b.css3DRenderer.setSize(width, height);
+            };
+            const { observe, unobserve } = this.createResizeObserver(container, reSize, true);
+            globalStore.resizeObserver = { observe, unobserve };
+            observe();
+            this.store.disposers.push(unobserve);
+        }
+        store.appendedToPage = true;
+    }
+    async handleShow() {
+        Object.values(this.store.frontModeCSS3DObjects).forEach((value) => {
+            value.css3DObject.visible = value.visible;
+        });
+        Object.values(this.store.behindModeCSS3DObjects).forEach((value) => {
+            value.css3DObject.visible = value.visible;
+            value.opacityMesh.visible = value.visible;
+        });
+    }
+    async handleHide() {
+        Object.values(this.store.frontModeCSS3DObjects).forEach((value) => {
+            value.css3DObject.visible = false;
+        });
+        Object.values(this.store.behindModeCSS3DObjects).forEach((value) => {
+            value.css3DObject.visible = false;
+            value.opacityMesh.visible = false;
+        });
+    }
+    handleEnable() {
+        Object.values(this.store.frontModeCSS3DObjects).forEach((value) => {
+            var _a;
+            if (!value.enabled)
+                return;
+            (_a = globalStore.frontModeStore) === null || _a === void 0 ? void 0 : _a.css3DScene.add(value.css3DObject);
+        });
+        Object.values(this.store.behindModeCSS3DObjects).forEach((value) => {
+            var _a, _b;
+            if (!value.enabled)
+                return;
+            (_a = globalStore.behindModeStore) === null || _a === void 0 ? void 0 : _a.css3DScene.add(value.css3DObject);
+            (_b = globalStore.behindModeStore) === null || _b === void 0 ? void 0 : _b.scene.add(value.opacityMesh);
+        });
+    }
+    handleDisable() {
+        Object.values(this.store.frontModeCSS3DObjects).forEach((value) => {
+            var _a;
+            (_a = globalStore.frontModeStore) === null || _a === void 0 ? void 0 : _a.css3DScene.remove(value.css3DObject);
+        });
+        Object.values(this.store.behindModeCSS3DObjects).forEach((value) => {
+            var _a, _b;
+            (_a = globalStore.behindModeStore) === null || _a === void 0 ? void 0 : _a.css3DScene.remove(value.css3DObject);
+            (_b = globalStore.behindModeStore) === null || _b === void 0 ? void 0 : _b.scene.remove(value.opacityMesh);
+        });
+    }
+}

package/libs/src/CSS3DRenderPlugin/Controller.d.ts

@@ -0,0 +1,78 @@
+import type * as BasePlugin from '../base/BasePlugin';
+import type { Five } from '@realsee/five';
+import { CSS3DRender, CSS3DRenderEventMap, CSS3DRenderState } from './CSS3DRender';
+import { AnyPosition } from './utils';
+export declare const PLUGIN_NAME: string;
+export interface Create3DDomContainerParamsType {
+    points: AnyPosition[];
+    config?: {
+        ratio?: number;
+        /** @deprecated dpr renamed as devicePixelRatio */
+        dpr?: number;
+        devicePixelRatio?: number;
+        autoRender?: boolean;
+        container?: HTMLElement;
+        pointerEvents?: 'none' | 'auto';
+    } & ({
+        mode?: 'front';
+    } | {
+        mode: 'behind';
+        behindFiveContainer: HTMLElement;
+    });
+}
+export default class Controller extends CSS3DRender implements BasePlugin.Controller<CSS3DRenderState, CSS3DRenderEventMap> {
+    five: Five;
+    constructor(five: Five);
+    /** @deprecated disposeAll() renamed as dispose() */
+    disposeAll(): void;
+    setState(...params: Parameters<InstanceType<typeof CSS3DRender>['setState']>): void;
+    /**
+     * @description 根据传入的四个点位创建一个 3d dom容器，可以通过ReactDom.render()的方式将react组件放到容器中
+     * @param { Vector3Position[] } points 矩形四个点坐标
+     * @param config 均为可选值
+     * @config_document `config` 均为可选值
+     *  | key                   | type                       | defaultValue        | comment |
+     *  | -                     | -                          | -                   | -       |
+     *  | `ratio`               | *`number`*                 | `0.00216`           | 1px对应多少米，默认为 0.00216，即1px对应2.16mm |
+     *  | ~~`dpr`~~             | ~~*`number`*~~             | ~~`undefined`~~     | ~~**已改名**，请使用~~ `devicePixelRatio` |
+     *  | `devicePixelRatio`    | *`number`*                 | `1`                 | 设备的物理像素分辨率与CSS像素分辨率的比值 |
+     *  | `container`           | *`HTMLElement`*            | `undefined`         | 自定义 return 中的 `container`
+     *  | `pointerEvents`       | *`'none'\|'auto'`*         | `'none'`            | container 的 css属性：`pointer-events` 的值 |
+     *  | `autoRender`          | *`boolean`*                | `true`              | 是否自动渲染，通常为true |
+     *  | `mode`                | *`'front'\|'behind'`*      | `front`             | 两种模式:|
+     *  |                                                                          | | | `front`  模式：DOM 处于 five Canvas 上方，所以无法模拟遮挡效果，需要手动检测是否可见去设置显隐 |
+     *  |                                                                          | | | `behind` 模式：DOM 处于 five Canvas 下方，可以模拟真实的遮挡效果，但是 DOM 必须是非透明的 |
+     *  | `behindFiveContainer` | *`HTMLElement`*            | `undefined`         | 如果 mode 为 `behind`，需要传入容器，并确保此容器位five下方，且中间无其他不透明的dom元素遮挡 |
+     *
+     * @return
+     * ```typescript
+     *    {
+     *      id: string,                             // id
+     *      container: HTMLDIVElement               // dom容器
+     *      dispose: () => void                     // 销毁
+     *      css3DObject: CSS3DObject                // THREE.CSS3DObject 实例
+     *      render?: () => void                     // 渲染函数，当 config.autoRender = true || undefined 时为 undefined
+     *      setVisible: (visible: boolean) => void  // 设置显隐, 同 setVisibleById(id, visible)
+     *      show: () => void                        // 同 setVisible(true)
+     *      hide: () => void                        // 同 setVisible(false)
+     *      setEnabled: (enabled: boolean) => void  // 添加/移除 container, 同 setEnabledById(id, enabled)
+     *      enable: () => void                      // 同 setEnabled(true)
+     *      disable: () => void                     // 同 setEnabled(false)
+     *    } | void
+     * ```
+     */
+    create3DDomContainer: (points: Create3DDomContainerParamsType['points'], config?: Create3DDomContainerParamsType['config']) => void | {
+        render: () => void;
+        id: string;
+        container: HTMLElement;
+        dispose: () => boolean;
+        css3DObject: import("./utils/CSS3DObjectPlus").CSS3DObjectPlus<HTMLElement>;
+        show: () => void;
+        hide: () => void;
+        setVisible: (visible: boolean) => void;
+        disable: () => void;
+        enable: () => void;
+        setEnabled: (enabled: boolean) => void;
+        appendToElement: (container: Element) => void;
+    };
+}

package/libs/src/CSS3DRenderPlugin/Controller.js

@@ -0,0 +1,108 @@
+import { CSS3DRender } from './CSS3DRender';
+import { random } from './utils';
+const VERSION = 'v2.0.0';
+export const PLUGIN_NAME = `CSS3DRenderPlugin-${random()}@${VERSION}`;
+export default class Controller extends CSS3DRender {
+    constructor(five) {
+        super();
+        Object.defineProperty(this, "five", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * @description 根据传入的四个点位创建一个 3d dom容器，可以通过ReactDom.render()的方式将react组件放到容器中
+         * @param { Vector3Position[] } points 矩形四个点坐标
+         * @param config 均为可选值
+         * @config_document `config` 均为可选值
+         *  | key                   | type                       | defaultValue        | comment |
+         *  | -                     | -                          | -                   | -       |
+         *  | `ratio`               | *`number`*                 | `0.00216`           | 1px对应多少米，默认为 0.00216，即1px对应2.16mm |
+         *  | ~~`dpr`~~             | ~~*`number`*~~             | ~~`undefined`~~     | ~~**已改名**，请使用~~ `devicePixelRatio` |
+         *  | `devicePixelRatio`    | *`number`*                 | `1`                 | 设备的物理像素分辨率与CSS像素分辨率的比值 |
+         *  | `container`           | *`HTMLElement`*            | `undefined`         | 自定义 return 中的 `container`
+         *  | `pointerEvents`       | *`'none'\|'auto'`*         | `'none'`            | container 的 css属性：`pointer-events` 的值 |
+         *  | `autoRender`          | *`boolean`*                | `true`              | 是否自动渲染，通常为true |
+         *  | `mode`                | *`'front'\|'behind'`*      | `front`             | 两种模式:|
+         *  |                                                                          | | | `front`  模式：DOM 处于 five Canvas 上方，所以无法模拟遮挡效果，需要手动检测是否可见去设置显隐 |
+         *  |                                                                          | | | `behind` 模式：DOM 处于 five Canvas 下方，可以模拟真实的遮挡效果，但是 DOM 必须是非透明的 |
+         *  | `behindFiveContainer` | *`HTMLElement`*            | `undefined`         | 如果 mode 为 `behind`，需要传入容器，并确保此容器位five下方，且中间无其他不透明的dom元素遮挡 |
+         *
+         * @return
+         * ```typescript
+         *    {
+         *      id: string,                             // id
+         *      container: HTMLDIVElement               // dom容器
+         *      dispose: () => void                     // 销毁
+         *      css3DObject: CSS3DObject                // THREE.CSS3DObject 实例
+         *      render?: () => void                     // 渲染函数，当 config.autoRender = true || undefined 时为 undefined
+         *      setVisible: (visible: boolean) => void  // 设置显隐, 同 setVisibleById(id, visible)
+         *      show: () => void                        // 同 setVisible(true)
+         *      hide: () => void                        // 同 setVisible(false)
+         *      setEnabled: (enabled: boolean) => void  // 添加/移除 container, 同 setEnabledById(id, enabled)
+         *      enable: () => void                      // 同 setEnabled(true)
+         *      disable: () => void                     // 同 setEnabled(false)
+         *    } | void
+         * ```
+         */
+        Object.defineProperty(this, "create3DDomContainer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (points, config) => {
+                if (this.state.disposed)
+                    return;
+                // ==== init ====
+                const mergeConfig = (() => {
+                    var _a;
+                    if ((config === null || config === void 0 ? void 0 : config.dpr) !== undefined)
+                        console.warn(`${PLUGIN_NAME}: please use "config.devicePixelRatio" replace "config.dpr"`);
+                    const defaultconfig = {
+                        ratio: 0.00216,
+                        devicePixelRatio: (_a = config === null || config === void 0 ? void 0 : config.dpr) !== null && _a !== void 0 ? _a : 1,
+                        mode: 'front',
+                        autoRender: true,
+                    };
+                    return Object.assign(defaultconfig, config, (config === null || config === void 0 ? void 0 : config.mode) === 'behind' ? { scene: this.five.scene } : undefined);
+                })();
+                const fiveElement = this.five.getElement();
+                if (!fiveElement)
+                    return console.error(`${PLUGIN_NAME}: five.getElement() is ${fiveElement}`);
+                const { autoRender, mode } = mergeConfig;
+                // 自动添加dom
+                const wrapper = mode === 'front' ? fiveElement.parentElement : mergeConfig.behindFiveContainer;
+                this.appendToElement(wrapper || document.body, mode);
+                const create3DElementResault = this.create3DElement(this.five.camera, points, Object.assign(Object.assign({}, mergeConfig), { autoRender: false }));
+                if (!create3DElementResault)
+                    return;
+                const oldRender = create3DElementResault.render;
+                const newRender = () => {
+                    var _a;
+                    if (mode === 'front') {
+                        oldRender();
+                    }
+                    if (mode === 'behind') {
+                        if ((_a = this.five.model) === null || _a === void 0 ? void 0 : _a.loaded)
+                            oldRender();
+                        else
+                            this.five.once('modelLoaded', () => oldRender());
+                    }
+                };
+                if (autoRender)
+                    newRender();
+                return Object.assign(Object.assign({}, create3DElementResault), { render: autoRender ? undefined : newRender });
+            }
+        });
+        this.five = five;
+    }
+    /** @deprecated disposeAll() renamed as dispose() */
+    disposeAll() {
+        return this.dispose();
+    }
+    setState(...params) {
+        const result = super.setState(...params);
+        this.five.needsRender = true;
+        return result;
+    }
+}

package/libs/src/CSS3DRenderPlugin/index.d.ts

@@ -0,0 +1,5 @@
+import type { FivePlugin } from '@realsee/five';
+import Controller from './Controller';
+export * from './typing';
+export declare const CSS3DRenderPlugin: FivePlugin<void, InstanceType<typeof Controller>>;
+export default CSS3DRenderPlugin;

package/libs/src/CSS3DRenderPlugin/index.js

@@ -0,0 +1,4 @@
+import Controller from './Controller';
+export * from './typing';
+export const CSS3DRenderPlugin = (five) => new Controller(five);
+export default CSS3DRenderPlugin;

package/libs/src/CSS3DRenderPlugin/typing.d.ts

@@ -0,0 +1,26 @@
+import type CSS3DRenderPlugin from '.';
+import type * as BasePlugin from '../base/BasePlugin';
+import type { CSS3DRender } from './CSS3DRender';
+export declare type CSS3DRenderPluginParameterType = undefined;
+export declare type CSS3DRenderPluginExportType = ReturnType<typeof CSS3DRenderPlugin>;
+export declare type CSS3DRenderExportType = InstanceType<typeof CSS3DRender>;
+export declare type Create3DDomContainerReturnType = ReturnType<CSS3DRenderPluginExportType['create3DDomContainer']>;
+export declare type Create3DElementReturnType = ReturnType<InstanceType<typeof CSS3DRender>['create3DElement']>;
+export interface CSS3DRenderPluginState extends BasePlugin.State {
+    enabled: boolean;
+    visible: boolean;
+}
+export interface CSS3DRenderPluginEventMap extends BasePlugin.EventMap<CSS3DRenderPluginState> {
+    show: (options?: {
+        userAction?: boolean;
+    }) => void;
+    hide: (options?: {
+        userAction?: boolean;
+    }) => void;
+    enable: (options?: {
+        userAction?: boolean;
+    }) => void;
+    disable: (options?: {
+        userAction?: boolean;
+    }) => void;
+}