@realsee/dnalogel 2.0.0-alpha.2 → 2.0.0-alpha.22

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# CHANGELOG
+
+## 2.0.0-alpha.22
+- 1.fix: 修复 PanoMeasurePlugin disable 状态下仍有背景色占位问题。
+
+## 2.0.0-alpha.21
+- 1.fix: 修复 PanoMeasurePlugin 仅初始化 UI 面板仍占位为题。
+
+## 2.0.0-alpha.20
+- 1.fix: 修复 PanoMeasurePlugin hide 时 UI 面板仍占位为题。
+
+## 2.0.0-alpha.19
+- 1.fix: 修复在模型中切换全部楼层，切换回户型图，展示的是上一次展示时的楼层；
+- 2.fix: 修复户型图界面切换楼层时，图片与SVG渲染有时间差导致闪烁的问题；
+- 3.feat: TopviewFloorplanPlugin 插件支持放大缩小；
+- 4.feat: ModelFloorplanPlugin 插件，autoShowEnable 和 hoverEnable 能同时支持；
+- 5.chore: 设置 tsconfig.json importsNotUsedAsValues 为 error，在引用类型时，必须显示写为 import type。
+
+## 2.0.0-alpha.18
+- 1.fix: 修复 PanoMeasurePlugin 使用时 hammerjs 报错问题。
+
+## 2.0.0-alpha.17
+- 1.fix: 修复构建输出 px2rem 失效问题。
+
+## 2.0.0-alpha.16
+- 1.fix: 修复 z-index 问题；
+- 2.fix: 修复 ModelItemLabelPlugin 事件监听问题。
+
+## 2.0.0-alpha.15
+- 1.refactor: 优化 ModelItemLabelPlugin 在调用 five.setState() 时的动画显示。
+
+## 2.0.0-alpha.14
+- 1.feat: 新增 ModelTVVideoPlugin 插件；
+- 2.fix: 修复 ModelItemLabelPlugin disable & enable 方法逻辑；
+- 3.refactor: 增加 ModelItemLabelPlugin 类型导出。
+
+## 2.0.0-alpha.13
+- 1.chore: 修改 tsconfig.json target 配置项为 es6。
+
+## 2.0.0-alpha.12
+- 1.feat: 新增 ModelItemLabelPlugin
+
+## 2.0.0-alpha.11
+- 1.fix: 修复 ModelRoomLabelPlugin 未监听多楼层切换 rerender 问题。
+- 2.feat: ModelFloorplanPlugin & TopviewFloorplanPlugin 新增 `northDesc?: string` 配置项，支持用户修改指北针名称。
+
+## 2.0.0-alpha.10
+- 1.feat: 新增空间三维标签插件 PanoSpatialTagPlugin
+- 2.feat: 新增轻量 ejs 渲染模板函数 shared-utils/tinyEJSrender.js
+
+## 2.0.0-alpha.9
+- 1.refactor: 增加插件独立 js 输出及对 svelte 的编译。
+
+## 2.0.0-alpha.8
+- 1.fix: 修复 ModelViewPlugin 实景 VR 模型不居中问题；
+- 2.fix: 修复 ModelRoomLabelPlugin fov 更新未 rerender 问题；
+- 2.fix: 修复 ModelRoomLabelPlugin enable 判断问题；
+- 4.fix: 修改 ModelFloorplanPlugin 在全景态满足户型图的俯仰角时会自动切换户型图问题。
+
+## 2.0.0-alpha.7
+- 1.fix: PanoCompassPlugin 向下兼容；
+- 2.feat: 新增 PC 全景测量插件：PanoMeasurePlugin；
+- 3.docs: 修改 README.md；
+
+## 2.0.0-alpha.6
+- 1.fix: 标尺插件 PanoRulerPlugin 所有标尺仅展示一次问题；
+- 2.fix: TopviewFloorplanPlugin && ModelFloorplanPlugin 插件小雷达位置显示不正确问题；
+- 3.feat: 为 TopviewFloorplanPlugin && ModelFloorplanPlugin 插件新增线框图吸附位置配置选项。 
+  - 可选地板、天花板、模型中心，默认吸附选项为模型中心。
+
+## 2.0.0-alpha.5
+1.修复全景指南针插件 PanoCompassPlugin 默认导出 name
+
+## 2.0.0-alpha.4
+1.新增全景标尺插件 PanoRulerPlugin
+
+## 2.0.0-alpha.3
+1.新增全景指南针插件 PanoCompassPlugin

package/README.md

@@ -1,11 +1,100 @@
-# 注意
+<p align="center">
+	<a href="https://realsee.js.org/"><img src="https://vrlab-public.ljcdn.com/common/file/web/ea031fa5-ad82-46b3-86c8-7b20ec1e635a.jpg" width="60" /></a>
+</p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@realsee/dnalogel">
+    <img src="https://img.shields.io/npm/v/@realsee/dnalogel.svg" alt="npm version" >
+  </a>
+  <a href="https://packagephobia.now.sh/result?p=@realsee/dnalogel">
+    <img src="https://packagephobia.now.sh/badge?p=@realsee/dnalogel" alt="install size" >
+  </a>
+  <a href="https://github.com/realsee-developer/dnalogel/blob/main/plugins/TERMS.txt">
+    <img src="https://img.shields.io/npm/l/@realsee/dnalogel.svg" alt="license">
+  </a>
+</p>
 
-此版本为 **测试** 版本， 不推荐使用。
+<h1 align="center">@realsee/dnalogel</h1>
 
-如您有插件使用需求，请安装 1.x 版本。
+# 👀 Overview
 
-此版本依赖 `svelte`， 使用时请同时安装 
+@realsee/dnalogel 将 [如视(realsee.com)](https://realsee.com) **VR 看房** 常用能力沉淀，并以 `Five Plugins` 形式进行抽象。
+结合[如视 VR 看房 SDK Five](https://open-platform.realsee.com/developer/docs/front/3d-space/get-started/rendering-engine/) 
+与 [如视开放 API](https://open-platform.realsee.com/developer/open/api/#/) ,可以制作出丰富多彩的三维空间应用。不论是经过线上环境千锤百炼的刚需功能，还是灵感一现的炫酷尝试，所有已经落地的功能我们均毫无保留的开源至github [realsee-developer/dnalogel](https://github.com/realsee-developer/dnalogel) 。
+
+# 🔨 Usage
+
+**1、安装**
+
+```bash
+npm install @realsee/dnalogel
+```
+
+```bash
+yarn add @realsee/dnalogel
+```
+
+2.x 版本依赖 `svelte`， 使用时请同时安装:
 ```bash
 npm install svelte 
 ```
+
+```bash
+yarn add svelte 
+```
+
+**2、插件注册**
+
+```js
+import { Five } from '@realsee/five'
+import { Plugin } from '@realsee/dnalogel'
+const five = new Five({
+  plugins: [[Plugin, 'PluginName', initOptions]],
+})
+```
+
+**3、插件方法使用**
+
+```js
+// 不同插件提供的方法可能存在差异,请参考各插件 API 文档
+five.plugins.PluginName.load(data)
+five.plugins.PluginName.enable()
+five.plugins.PluginName.disable()
+five.plugins.PluginName.dispose()
+```
+
+**4、插件依赖数据获取**
+
+您可以通过 [open API](https://open-platform.realsee.com/developer/open/api#/) 查看数据获取方式及相关 open API 。
+
+# 📖 Documents
+
+- [说明文档](https://open-platform.realsee.com/developer/docs/front/3d-space/advanced/dnalogel/ModelViewPlugin/)
+- [API 文档](https://unpkg.com/@realsee/dnalogel/docs/index.html)
+- [demo 源码](https://github.com/realsee-developer/dnalogel/tree/main/examples/src)
+- [数据依赖来源：open API](https://open-platform.realsee.com/developer/open/api/)
+- [CHANGELOG](https://github.com/realsee-developer/dnalogel/blob/main/plugins/CHANGELOG.md)
+
+# 💡 Preview
+
+我们为每个插件书写了简单的效果示例，您可点击预览：
+[@realsee/dnalogel showcase](https://realsee.js.org/dnalogel/)
+
+
+# 🧾 Lists
+
+- 🔌 ModelViewPlugin：模型小窗插件
+- 🔌 PanoFloorplanRadarPlugin：全景户型雷达图插件
+- 🔌 ModelRoomLabelPlugin：模型态房屋标签插件
+- 🔌 TopviewFloorplanPlugin：俯视模型户型图插件
+- 🔌 ModelChassisCompassPlugin：模型底盘指南针插件
+- 🔌 ModelEntryDoorGuidePlugin：模型入户门引导插件
+- 🔌 CSS3DRenderPlugin：CSS3D渲染插件
+- 🔌 CameraMovementPlugin：相机运镜插件
+- 🔌 ModelFloorplanPlugin：模型户型图插件
+- 🔌 PanoRulerPlugin：全景标尺插件
+- 🔌 PanoCompassPlugin：全景指南针插件
+- 其他插件持续更新中...
+
+# License
+[TERMS](https://github.com/realsee-developer/dnalogel/blob/main/plugins/TERMS.txt)

package/TERMS.txt

@@ -0,0 +1,56 @@
+Realsee SDK License Agreement
+
+Update: July 28, 2021
+
+THIS LICENSE AGREEMENT BETWEEN YOU AND 【BEIKE REALSEE TECHNOLOGY (HK) LIMITED】(“Realsee”) FORMS A LEGALLY BINDING CONTRACT BETWEEN YOU AND REALSEE IN RELATION TO YOUR USE OF THE SDK. This License Agreement accompanies the Realsee Software Development Kit(s) for the software and related explanatory materials (the "SDK") and includes any upgrades, modified versions, updates, additions, and copies of the SDK licensed to You by Realsee.
+BY DOWNLOADING, INSTALLING, OR OTHERWISE ACCESSING OR USING THE SDK, YOU AGREE THAT YOU HAVE READ, UNDERSTOOD, AND AGREE TO BE BOUND BY THIS AGREEMENT. YOU ARE AGREEING ON YOUR OWN BEHALF AND/OR ON BEHALF OF YOUR COMPANY OR ORGANIZATION TO THE TERMS AND CONDITIONS STATED BELOW.
+This Agreement applies to Your use of the SDK in the country in which You legally install it (“Territory”) and is subject to the laws of such Territory and further subject to Section 12 below. Different terms, conditions, and limitations may apply to the use of the SDK in any additional countries.
+1. DEFINITIONS.
+“Agreement” means this Realsee SDK License Agreement.
+“Developer”, “You” and “Your” means the person(s) or entity acquiring or using the SDK or otherwise exercising rights under the terms of this Agreement.
+“Documentation” means the technical or other specifications or documentation that Realsee may provide to You for use in connection with the SDK.
+“Integrated Product” means any software, website, or on-line service developed by You based on or using the SDK (collectively, the “Integrated Product”).
+“Intellectual Property” means any patents, patent rights, trademarks, service marks, registered and unregistered designs, applications for any of the foregoing, copyright, and any other similar protected rights in any country and to the extent recognised by any relevant jurisdiction as intellectual property, trade secrets, know-how and confidential information. Realsee reserves all rights not expressly granted to You.
+“Realsee” means [Beike Realsee Technology (HK) Limited, a company incorporated and validly existing under the laws of Hong Kong].
+“SDK” means the Realsee-proprietary Software Development Kits (SDK) provided hereunder, includes all development tools (including any compiler and debugger), application programming interfaces (“APIs”), libraries, binary utilities, header files, Documentation, content, data, code samples, and other materials provided to You in connection with this Agreement, whether delivered through a download, or any other media or form, and is licensed, not sold, to You by Realsee for use only under the terms of this Agreement. The terms of this Agreement will govern any updates provided by Realsee that replace and/or supplement the original SDK delivered to You, unless such update is accompanied by a separate license, in which case the terms of such license will govern.
+2. LICENSED USES AND RESTRICTIONS.
+2.1 Subject to the restrictions contained in this Section 2, Realsee grants to You during the term, a limited, non-exclusive, revocable, non-sublicensable, non-transferable license to install and use the SDK within the Territory only for the purpose of internal development.
+2.2 Restrictions. You acknowledge and agree that, You shall not, and shall ensure that Your affiliates, employees, agents, representatives, officers, representatives, and subcontractors do not (directly or indirectly):
+2.2.1 decompile, reverse engineer, disassemble or attempt to derive the source code of, those components of the SDK provided in object code form, or any part thereof;
+2.2.2 remove, alter, or obscure any copyright notice or other proprietary rights notice on any part of the SDK;
+2.2.3 sell, assign, pledge, rent, lease, lend, upload to or host on any website or server for use by any third party except You, redistribute, or sublicense the SDK (or any part thereof), or operate the SDK (or any part thereof) in the capacity of a service bureau or other hosted services provider, in whole or in part, nor may You enable others to do so;
+2.2.4 or alter, modify, customize or improve the SDK, or any part thereof;
+2.2.5 use the SDK (or any part thereof) for any illegal purpose, in any manner that is inconsistent with the terms of this Agreement, or to engage in any illegal activity;
+2.2.6 use the SDK (or any part thereof) in any manner that may damage the operation of Realsee’s products or services; or
+2.2.7 use the SDK or any information contained therein or otherwise provided by Realsee for the purpose of developing, or having developed, any product competitive with any Realsee product or service, as determined by Realsee in its sole discretion;
+2.2.8 include any portion of the SDK in Your Developer products.
+2.3 Realsee has the right to impose reasonable conditions such as a reasonable fee for use of the SDK in Integrated Product in the future.
+2.4 You may make a limited number of copies of the SDK to be used by Your employees or consultants as provided herein, and not for general business purposes, and such employees or consultants shall be subject to the obligations and restrictions in this Agreement.
+2.5 All licenses not expressly granted in this Agreement are reserved and no other licenses, immunity, or rights, express or implied, are granted by Realsee, by implication, estoppel, or otherwise.
+3. CONFIDENTIALITY.
+The SDK and all source code, Documentation, specifications, engineering details, and related information pertaining to the SDK, whether in oral, written, graphic, or electronic form, are and shall remain the confidential and proprietary information of Realsee or its licensors (collectively, the “Confidential Information”). You shall (i) disclose Confidential Information to only those directors and employees (collectively, “Affiliates”) whose duties justify their need to know such information and who have been clearly informed of their obligation to maintain the confidential, proprietary, and/or trade secret status of such Confidential Information; and (ii) use Confidential Information solely in accordance with the license granted hereunder. In any event, You and Your Affiliates shall treat Confidential Information as strictly confidential and shall use the same care to prevent disclosure of such information as You use with respect to Your own similar confidential and/or proprietary information, which shall not be less than the care a reasonable person would use under similar circumstances. All Confidential Information, and any copies thereof, shall be returned promptly to Realsee upon request. You shall ensure that Your Affiliates comply with the provisions of this Section 3, and You shall be liable for any breach of this Section 3 resulting from the act or omission of any of Your Affiliates. You shall not disclose Confidential Information to any third party, including, without limitation, any of Your subcontractors.
+4. PROPRIETARY RIGHTS.
+4.1 As between You and Realsee, Realsee and/or its licensors retain ownership of all right, title, and interest in, to, and under the SDK, including, without limitation, all patents, copyrights, trade secrets, trademarks and other intellectual property and other proprietary rights therein, and reserve all rights not expressly granted to You.
+4.2 The items contained in the SDK are the intellectual property of Realsee and its licensors and are protected by PRC copyright and patent law, international treaty provisions and applicable laws of the country in which it is being used. You agree to protect all copyright and other ownership interests of Realsee and/or its licensors in all items in the SDK supplied under this License Agreement. You agree that all copies of the items in the SDK, reproduced for any reason by You, contain the same copyright notices, and other proprietary notices as appropriate, as appear on or in the original items delivered by Realsee in the SDK. Realsee and/or its licensors retain title and ownership of the items in the SDK, the media on which it is loaded, and all subsequent copies, regardless of the form or media in or on which the original and other copies may exist. Except as stated above, this Agreement does not grant You any rights to patents, copyrights, trade secrets, trademarks or any other rights in respect to the items in the SDK.
+5. TERM AND TERMINATION.
+5.1 This Agreement is effective until terminated. Realsee has the right to terminate this Agreement immediately, without judicial intervention, if You fail to comply with any term herein. Upon any such termination You must remove all full and partial copies of the items in the SDK from Your computer and discontinue the use of the items in the SDK.
+5.2 Realsee may at any time, terminate the Agreement with You if: (A) You have breached any provision of the Agreement; or (B) Realsee is required to do so by law; or (C) Realsee decides to no longer provide the SDK or certain parts of the SDK to users in the country in which You are resident or from which You use the service, or the provision of the SDK or certain SDK services to You by Realsee is, in Realsee's sole discretion, no longer legally or commercially viable.
+5.3 When the Agreement comes to an end, all of the legal rights, obligations and liabilities that You and Realsee have benefited from, been subject to (or which have accrued over time whilst the Agreement has been in force) or which are expressed to continue indefinitely, shall be unaffected by this cessation, and the provisions of Section 3, 4, 6, 7 and 8 shall continue to apply to such rights, obligations and liabilities indefinitely.
+6. DISCLAIMER OF WARRANTY.
+YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, USE OF THE SDK (OR ANY PART THEREOF) IS AT YOUR SOLE RISK AND THAT THE ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH YOU. REALSEE LICENSES THE SDK TO YOU ONLY ON AN "AS-IS" BASIS. REALSEE MAKES NO REPRESENTATION WITH RESPECT TO THE ADEQUACY OF ANY ITEMS IN THE SDK, WHETHER OR NOT USED BY YOU IN THE DEVELOPMENT OF INTEGRATED PRODUCT, FOR ANY PARTICULAR PURPOSE OR WITH RESPECT TO THEIR ADEQUACY TO PRODUCE ANY PARTICULAR RESULT. REALSEE AND ITS LICENSORS SHALL NOT BE LIABLE FOR LOSS OR DAMAGE ARISING OUT OF THIS AGREEMENT OR FROM THE DISTRIBUTION OR USE OF INTEGRATED PRODUCT CONTAINING PORTIONS OF THE SDK. REALSEE AND ITS LICENSORS DISCLAIM ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED CONDITIONS OR WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT OF ANY THIRD PARTY RIGHT IN RESPECT OF THE ITEMS IN THE SDK OR ANY SERVICES RELATED TO THE SDK.
+REALSEE IS UNDER NO OBLIGATION TO PROVIDE ANY SUPPORT UNDER THIS LICENSE AGREEMENT, INCLUDING UPGRADES OR FUTURE VERSIONS OF THE SDK OR ANY PORTIONS THEREOF, TO YOU, END USER OR TO ANY OTHER PARTY.
+7. LIMITATION OF LIABILITY.
+TO THE EXTENT NOT PROHIBITED BY APPLICABLE LAW, IN NO EVENT WILL REALSEE OR ITS LICENSORS BE LIABLE FOR ANY DIRECT, INCIDENTAL, SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, LOSS OF BUSINESS, REVENUE, OR PROFITS, LOSS OF OPPORTUNITY (WHETHER DIRECT OR INDIRECT), CORRUPTION OR LOSS OF DATA, LOSS OF REPUTATION OR SAVINGS, DOWNTIME, OR DAMAGE TO, LOSS OF OR REPLACEMENT OF DATA OR TRANSACTIONS, COST OF PROCUREMENT OF SUBSTITUTE SERVICES, BUSINESS INTERRUPTION, OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE THE SDK (OR ANY PART THEREOF), ANY INTEGRATED PRODUCT, OR ANY THIRD PARTY SOFTWARE, APPLICATIONS, OR SERVICES IN CONJUNCTION WITH THE SDK (OR ANY PART THEREOF), HOWEVER CAUSED, REGARDLESS OF THE THEORY OF LIABILITY (CONTRACT, TORT, OR OTHERWISE) AND EVEN IF REALSEE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT WILL REALSEE’S TOTAL LIABILITY TO YOU FOR ALL DAMAGES EXCEED ONE HUNDRED DOLLARS ($100.00). THE FOREGOING LIMITATIONS WILL APPLY EVEN IF THE ABOVE STATED REMEDY FAILS OF ITS ESSENTIAL PURPOSE. THE LIMITATIONS CONTAINED IN SECTIONS 6 AND THIS SECTION 7 ARE A FUNDAMENTAL PART OF THE BASIS OF REALSEE’S BARGAIN HEREUNDER, AND REALSEE WOULD NOT ENTER INTO THIS AGREEMENT OR PROVIDE YOU WITH ACCESS TO THE SDK ABSENT SUCH LIMITATIONS.
+8. INDEMNIFICATION.
+To the extent permitted by applicable law, You agree to indemnify, defend and hold harmless Realsee, its affiliates and each of their directors, officers, employees, independent contractors, and agents (each a “Realsee Indemnified Party”) from any and all claims, losses, liabilities, damages, expenses, and costs (including without limitation attorneys’ fees and court costs) incurred by a Realsee Indemnified Party as a result of: (i) Your non-compliance with any terms of this Agreement; (ii) Your use of the SDK (or any part thereof); or (iii) Your use of any Integrated Product, including any claim that Integrated Product infringes the copyright, trademark, trade secret or other intellectual property right of a third party.
+9. ACKNOWLEDGEMENTS.
+Portions of the SDK may utilize or include third party software and other copyrighted material. Acknowledgments, licensing terms, and disclaimers for such material are contained in Documentation for the SDK or may otherwise accompany such material, and Your use of such materials governed by their respective terms. In the event of conflict between the terms of this Agreement and an applicable open source or third party agreement, the open source or third party agreement will control solely with respect to the open source software or third party software. Moreover, You shall not subject any items (including not limited to source code, object code, and any software)  included in the SDK to any open source license.
+10. NON-BLOCKING OF REALSEE DEVELOPMENT.
+You acknowledge that Realsee is currently developing or may develop technologies and products in the future that have or may have design and/or functionality similar to Integrated Product that You may develop based on Your license herein. Nothing in this Agreement shall impair, limit or curtail Realsee's right to continue with its development, maintenance and/or distribution of Realsee's technology or products.
+11. GENERAL.
+11.1 Export Control. You may not use or otherwise export or re-export the SDK (or any part thereof) except as authorized by United States law and the laws of the jurisdiction(s) in which the SDK (or any part thereof) was obtained. In particular, but without limitation, the SDK may not be exported or re-exported (i) into any U.S. embargoed countries or (ii) to anyone on the U.S. Treasury Department's list of Specially Designated Nationals or the U.S. Department of Commerce Denied Person's List or Entity List. By using the SDK (or any part thereof), You represent and warrant that You are not located in any such country or on any such list.
+11.2 Governing Law. This Agreement and the rights of the parties hereunder shall be governed by and construed in accordance with the laws of People’s Republic of China (for purpose of this Agreement, excluding Hong Kong, Taiwan, and Macau), without reference to its conflict of laws principles. Any dispute, controversy or claim arising from or in connection with this Agreement, or the breach, termination or invalidity thereof, shall be submitted to China International Economic and Trade Arbitration Commission (“CIETAC”) for arbitration in Beijing which shall be conducted in accordance with the CIETAC's arbitration rules in effect at the time of applying for arbitration. The arbitral award is final and binding upon both parties.
+11.3 Severability. If any provision of this Agreement is held by a court of competent jurisdiction to be unenforceable for any reason, the remaining provisions hereof will be unaffected and remain in full force and effect.
+11.4. Modifications. Realsee reserves the right, from time to time, with or without notice to You, to make revisions to this Agreement in our sole and absolute discretion.  The most current version of this Agreement will supersede all previous versions and shall be made available on the website where the SDK is made available, or by such other means as Realsee may determine in its discretion. Any modified versions of this Agreement hereto shall take effect from the time that it is made available. You shall be responsible for regularly checking for notice of any such modifications. You agree that Your continued use of the SDK constitutes Your agreement to the modified Agreement.
+11.5 Relationship of the Parties. This Agreement will not be construed as creating an agency, partnership, joint venture, fiduciary duty, or any other form of legal association between You and Realsee, and You will not represent to the contrary, whether expressly, by implication, appearance, or otherwise.
+11.6 Entire Agreement; Governing Language. This Agreement constitutes the entire agreement between You and Realsee with respect to the use of the SDK licensed hereunder and supersedes all prior understandings regarding such subject matter. No amendment to or modification of this Agreement will be binding unless in writing and signed by Realsee. You and Realsee hereto confirm that this Agreement and all related documents shall be drafted in English.

package/dist/CSS3DRenderPlugin/index.d.ts

@@ -0,0 +1,49 @@
+import type { FivePlugin } from '@realsee/five';
+import type { Vector3Position } from '../typings/math.type';
+import { Vector3 } from 'three';
+import { CSS3DObject } from 'three/examples/jsm/renderers/CSS3DRenderer';
+export declare type CSS3DRenderPluginParameterType = undefined;
+export interface CSS3DRenderPluginExportType {
+    /**
+     * @description: 根据传入的四个点位创建一个3d dom容器，可以通过ReactDom.render()的方式将react组件放到容器中
+     * @param {Five} five
+     * @param {Vector3[] | Vector3Position[]} points: 矩形四个点坐标
+     * @param {number} config.ratio: 1px对应多少米，默认为 0.002，即1px对应2mm
+     * @param {number} config.dpr: dpr, 默认为1
+     * @param {HTMLElement} config.container: HTMLElement
+     * @param {number} config.autoRender: 默认为true，如果需要手动render则传false
+     * @param {'front' | 'behind'} config.mode: 两种模式
+     * @param {HTMLElement} config.behindFiveContainer: 如果config.mode为'behind'，需要传入容器，并确保此容器位five下方，且中间没有其他dom元素遮挡
+     * @return {{ container: HTMLElement; dispose: () => void }}: container: dom容器, dispose: 清理函数
+     */
+    create3DDomContainer: (points: Vector3[] | Vector3Position[], config?: {
+        ratio?: number;
+        dpr?: number;
+        autoRender?: boolean;
+        container?: HTMLElement;
+        [key: string]: any;
+    } & ({
+        mode?: 'front';
+    } | {
+        mode: 'behind';
+        behindFiveContainer: HTMLElement;
+    })) => {
+        container: HTMLElement;
+        dispose: () => void;
+        css3DObject: CSS3DObject;
+        render?: () => void;
+    } | void;
+    /**
+     * @description: 销毁所有的渲染内容
+     * @return {void}
+     */
+    disposeAll: () => void;
+}
+/**
+ * **CSS3DRenderPlugin** 提供矩形区域（三维空间四个坐标点），你可以在此矩形区域中渲染 DOM 内容。
+ * 实现原理参考[CSS3DRenderer](https://threejs.org/docs/index.html?q=CSS3D#examples/en/renderers/CSS3DRenderer)。
+ *
+ * @returns
+ */
+export declare const CSS3DRenderPlugin: FivePlugin<CSS3DRenderPluginParameterType, CSS3DRenderPluginExportType>;
+export default CSS3DRenderPlugin;

package/dist/CSS3DRenderPlugin/index.js

@@ -0,0 +1,234 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var THREE = require('three');
+var CSS3DRenderer = require('three/examples/jsm/renderers/CSS3DRenderer');
+
+function _interopNamespace(e) {
+    if (e && e.__esModule) return e;
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n["default"] = e;
+    return Object.freeze(n);
+}
+
+var THREE__namespace = /*#__PURE__*/_interopNamespace(THREE);
+
+function evenNumber(num, config) {
+    const roundNum = Math.round(num);
+    return roundNum % 2 === 0 ? roundNum : roundNum + Number((config === null || config === void 0 ? void 0 : config.smaller) ? -1 : 1);
+}
+
+function centerPoint(point1, point2) {
+    return new THREE.Vector3((point1.x + point2.x) / 2, (point1.y + point2.y) / 2, (point1.z + point2.z) / 2);
+}
+
+const transformPositionToVector3 = ({ x, y, z }) => new THREE.Vector3(x, y, z);
+
+/**
+ * @description: 究极简陋的 ResizeObserver polyfill
+ */
+function createResizeObserver(func, element) {
+    if (!element || typeof ResizeObserver === 'undefined') {
+        return {
+            observe: () => window.addEventListener('resize', func),
+            unobserve: () => window.removeEventListener('resize', func),
+        };
+    }
+    else {
+        const observer = new ResizeObserver(func);
+        return {
+            observe: () => observer.observe(element),
+            unobserve: () => observer.unobserve(element),
+        };
+    }
+}
+
+/**
+ * **CSS3DRenderPlugin** 提供矩形区域（三维空间四个坐标点），你可以在此矩形区域中渲染 DOM 内容。
+ * 实现原理参考[CSS3DRenderer](https://threejs.org/docs/index.html?q=CSS3D#examples/en/renderers/CSS3DRenderer)。
+ *
+ * @returns
+ */
+const CSS3DRenderPlugin = (five) => {
+    const state = { disposeCallbacks: [] };
+    const create3DDomContainer = (...params) => {
+        var _a, _b, _c;
+        const points = params[0].map((point) => (point instanceof THREE.Vector3 ? point : transformPositionToVector3(point)));
+        const config = params[1];
+        if ((points === null || points === void 0 ? void 0 : points.length) < 4)
+            return console.error('points must be equal or greater than than 4');
+        if (!((_a = five === null || five === void 0 ? void 0 : five.model) === null || _a === void 0 ? void 0 : _a.loaded))
+            return console.error('five.model.loaded is: ', (_b = five === null || five === void 0 ? void 0 : five.model) === null || _b === void 0 ? void 0 : _b.loaded);
+        const fiveElement = five.getElement();
+        if (!fiveElement)
+            return console.error('five.getElement() is ' + fiveElement);
+        const disposers = [];
+        const ratio = (config === null || config === void 0 ? void 0 : config.ratio) || 0.00216;
+        if (ratio <= 0.00215)
+            console.warn('if you need click css3DElement on safari, ratio must be greater than 0.00215');
+        const dpr = (config === null || config === void 0 ? void 0 : config.dpr) || 1;
+        const mode = (config === null || config === void 0 ? void 0 : config.mode) || 'front';
+        const autoRender = (_c = config === null || config === void 0 ? void 0 : config.autoRender) !== null && _c !== void 0 ? _c : true;
+        const behindFiveContainer = (config === null || config === void 0 ? void 0 : config.behindFiveContainer) || fiveElement.parentElement || document.body;
+        const container = (config === null || config === void 0 ? void 0 : config.container) || document.createElement('div');
+        container.classList.add('__Dnalogel-plugin--CSS3DRenderPlugin');
+        // 获取css3DObject, 如果mode为behind的话，一起获取mesh
+        const { css3DObject, mesh } = createObject(points, { ratio, dpr, container, mode });
+        // ======= INIT START =======
+        let resizeObserver;
+        const frontModeUnInited = mode === 'front' && !state.frontMode;
+        const behindModeUnInited = mode === 'behind' && !state.behindMode;
+        const inited = !(frontModeUnInited || behindModeUnInited);
+        if (behindModeUnInited) {
+            state.behindMode = { scene: new THREE.Scene(), css3DRenderer: new CSS3DRenderer.CSS3DRenderer() };
+        }
+        if (frontModeUnInited) {
+            state.frontMode = { scene: new THREE.Scene(), css3DRenderer: new CSS3DRenderer.CSS3DRenderer() };
+        }
+        const stateMode = mode === 'behind' ? state.behindMode : state.frontMode;
+        const { scene, css3DRenderer } = stateMode;
+        const render = (() => {
+            if (!inited) {
+                const css3DRendererSetSize = () => {
+                    // 这里evenNumber策略是遇到奇数会加1，不知道为啥会触发滚动条显示，导致fiveElement变小，fiveElement变小又触发了这里的resize，宽高变小，滚动条消失，然后又触发resize。。。无限循环
+                    // 为了规避上面这种情况，evenNumber设置了一个参数，遇到奇数可选择减一
+                    const rendererWidth = evenNumber(fiveElement.clientWidth, { smaller: true });
+                    const rendererHeight = evenNumber(fiveElement.clientHeight, { smaller: true });
+                    css3DRenderer.setSize(rendererWidth, rendererHeight);
+                };
+                css3DRendererSetSize();
+                resizeObserver = createResizeObserver(css3DRendererSetSize, fiveElement);
+                css3DRenderer.domElement.style.position = 'absolute';
+                css3DRenderer.domElement.style.top = '0';
+                css3DRenderer.domElement.style.userSelect = 'none';
+                css3DRenderer.domElement.style.pointerEvents = 'none';
+                const renderEveryFrame = () => {
+                    const requestAnimationFrameId = requestAnimationFrame(renderEveryFrame);
+                    stateMode.requestAnimationFrameId = requestAnimationFrameId;
+                    css3DRenderer.render(scene, five.camera);
+                };
+                return () => {
+                    var _a;
+                    scene.add(css3DObject);
+                    (_a = resizeObserver === null || resizeObserver === void 0 ? void 0 : resizeObserver.observe) === null || _a === void 0 ? void 0 : _a.call(resizeObserver);
+                    renderEveryFrame();
+                    if (mode === 'behind' && mesh) {
+                        five.scene.add(mesh);
+                        disposers.push(() => mesh && five.scene.remove(mesh));
+                    }
+                };
+            }
+            else {
+                return () => {
+                    scene.add(css3DObject);
+                };
+            }
+        })();
+        if (frontModeUnInited) {
+            const wrapper = fiveElement.parentElement || document.body;
+            wrapper.appendChild(css3DRenderer.domElement);
+        }
+        if (behindModeUnInited) {
+            const wrapper = behindFiveContainer;
+            wrapper.appendChild(css3DRenderer.domElement);
+        }
+        // ======= INIT END =======
+        const dispose = () => {
+            var _a;
+            disposers.forEach((d) => d === null || d === void 0 ? void 0 : d());
+            scene.remove(css3DObject);
+            if (scene.children.length === 0) {
+                if (typeof stateMode.requestAnimationFrameId === 'number') {
+                    cancelAnimationFrame(stateMode.requestAnimationFrameId);
+                }
+                css3DRenderer.domElement.remove();
+                if (mode === 'front')
+                    state.frontMode = undefined;
+                if (mode === 'behind')
+                    state.behindMode = undefined;
+                if (!state.behindMode && !state.frontMode) {
+                    (_a = resizeObserver === null || resizeObserver === void 0 ? void 0 : resizeObserver.unobserve) === null || _a === void 0 ? void 0 : _a.call(resizeObserver);
+                }
+            }
+            return true;
+        };
+        const idx = state.disposeCallbacks.findIndex((item) => item === dispose);
+        if (idx !== -1) {
+            state.disposeCallbacks.splice(idx, 1);
+        }
+        else {
+            state.disposeCallbacks.push(dispose);
+        }
+        if (autoRender)
+            render();
+        return { container, dispose, css3DObject, render: autoRender ? undefined : render };
+    };
+    const createObject = (points, config) => {
+        const { ratio, dpr, container: element, mode } = config;
+        const planeWidth = points[0].distanceTo(points[1]);
+        const planeHeight = points[1].distanceTo(points[2]);
+        const domWidthPx = evenNumber((planeWidth / ratio) * dpr);
+        const domHeightPx = evenNumber((planeHeight / ratio) * dpr);
+        const css3DObject = new CSS3DRenderer.CSS3DObject(element);
+        css3DObject.scale.set(ratio, ratio, ratio);
+        element.style.width = domWidthPx + 'px';
+        element.style.height = domHeightPx + 'px';
+        element.style.pointerEvents = 'none';
+        const centerPosition = centerPoint(points[0], points[2]);
+        const vector01 = points[1].clone().sub(points[0]); // 点0 -> 点1 的向量
+        const vector12 = points[2].clone().sub(points[1]); // 点1 -> 点2 的向量
+        // 旋转
+        const rotateXAngle = new THREE.Vector3(0, 1, 0).angleTo(new THREE.Vector3(0, vector12.y, vector12.z));
+        const rotateYAngle = new THREE.Vector3(1, 0, 0).angleTo(new THREE.Vector3(vector01.x, 0, vector01.z));
+        const rotateZAngle = vector01.angleTo(new THREE.Vector3(vector01.x, 0, vector01.z));
+        /**
+         * [0,1,0] => [0,0,1]  为rotate Worldx正方向
+         * [0,0,1] => [0,1,0]  为rotate Worldy正方向
+         * [0,1,1] => [-1,0,0] 为rotate Worldz正方向
+         */
+        const rotateX = (vector12.z > 0 ? -1 : 1) * rotateXAngle;
+        const rotateY = (vector01.z < 0 ? 1 : -1) * rotateYAngle;
+        const rotateZ = ((vector01.x > 0 && vector01.y < 0) || (vector01.x < 0 && vector01.y > 0) ? -1 : 1) * rotateZAngle;
+        css3DObject.rotateOnWorldAxis(new THREE.Vector3(1, 0, 0), rotateX); // x
+        css3DObject.rotateOnWorldAxis(new THREE.Vector3(0, 1, 0), rotateY); // y
+        css3DObject.rotateOnWorldAxis(new THREE.Vector3(0, 0, 1), rotateZ); // z
+        css3DObject.position.set(centerPosition.x, centerPosition.y, centerPosition.z);
+        let mesh;
+        if (mode === 'behind') {
+            const material = new THREE__namespace.MeshBasicMaterial({
+                opacity: 0,
+                transparent: false,
+                side: THREE__namespace.DoubleSide,
+            });
+            const geometry = new THREE__namespace.PlaneGeometry(domWidthPx, domHeightPx);
+            mesh = new THREE__namespace.Mesh(geometry, material);
+            mesh.name = 'CSS3DRenderPlugin-mesh';
+            mesh.position.copy(css3DObject.position);
+            mesh.rotation.copy(css3DObject.rotation);
+            mesh.scale.copy(css3DObject.scale);
+        }
+        return { css3DObject, mesh };
+    };
+    return {
+        create3DDomContainer,
+        disposeAll: () => {
+            state.disposeCallbacks.forEach((d) => d === null || d === void 0 ? void 0 : d());
+            state.disposeCallbacks = [];
+        },
+    };
+};
+
+exports.CSS3DRenderPlugin = CSS3DRenderPlugin;
+exports["default"] = CSS3DRenderPlugin;

package/dist/CSS3DRenderPlugin/utils/createResizeObserver.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @description: 究极简陋的 ResizeObserver polyfill
+ */
+export default function createResizeObserver(func: () => any, element?: HTMLElement): {
+    observe: () => void;
+    unobserve: () => void;
+};

package/dist/CameraMovementPlugin/index.d.ts

@@ -0,0 +1,7 @@
+import type { FivePlugin } from '@realsee/five';
+import { CameraMovementPluginExportType, CameraMovementPluginParameterType } from './typing';
+/**
+ * **运镜插件** 模拟类似于电影运镜效果。
+ */
+export declare const CameraMovementPlugin: FivePlugin<CameraMovementPluginParameterType, CameraMovementPluginExportType>;
+export default CameraMovementPlugin;