插件开发示例

本页面展示了如何为 NIVIOBIM 图形引擎开发自定义插件，包括插件基础结构、事件处理、UI集成等。

基础插件开发

1. 简单插件示例

javascript

/**
 * @fileoverview NIVIOBIM天空盒功能模块
 * 
 * 该文件为NIVIOBIM天空盒功能的主要模块，提供3D场景的天空盒背景功能。
 * 支持立方体贴图天空盒，为3D场景提供环境背景和雾效。
 * 
 * 主要特性：
 * - 立方体贴图天空盒：支持6张图片组成的立方体贴图天空盒
 * - 雾效支持：为场景添加雾效，增强视觉深度
 * - 动态加载：异步加载天空盒纹理
 * - 场景集成：与3D场景无缝集成
 * - 资源管理：自动管理天空盒资源的加载和释放
 * 
 * @author NIVIOBIM Team
 * @version 1.0.0
 * @since 2023
 */
import PluginPackage from './plugins/PluginPackage@2.1.0.module.js';
const Plugin = PluginPackage.Plugin;
const {
    CubeTextureLoader,
    Fog,
} = THREE;

let _$skyBoxUrls = null;

/**
 * 天空盒插件类
 *
 * NIVIOBIM天空盒功能的主插件类，继承自Plugin。
 * 提供3D场景的天空盒背景功能，支持立方体贴图和雾效。
 *
 * 主要功能包括：
 * - 天空盒设置：设置6张图片组成的立方体贴图天空盒
 * - 雾效管理：为场景添加和移除雾效
 * - 异步加载：异步加载天空盒纹理资源
 * - 场景集成：与3D场景无缝集成
 * - 资源管理：自动管理天空盒资源的加载和释放
 *
 * @class SkyBox
 * @extends Plugin
 * @example
 * // 创建天空盒插件
 * const skyBox = new SkyBox(viewer3D, {
 *     name: 'SkyBox'
 * });
 * 
 * // 设置天空盒图片
 * skyBox.setSkyBoxUrls([
 *     'px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg'
 * ]);
 * 
 * // 启用天空盒
 * skyBox.enabled = true;
 */
class SkyBox extends Plugin{

    /**
     * 创建天空盒插件实例
     * 
     * 初始化天空盒插件，设置场景管理器和立方体贴图加载器。
     * 
     * @param {Viewer3D} viewer3D - Viewer3D实例，提供场景管理器访问
     * @param {Object} options - 插件配置选项
     * @example
     * // 创建天空盒插件
     * const skyBox = new SkyBox(viewer3D, {
     *     name: 'SkyBox'
     * });
     */
    constructor(viewer3D,options) {
        super(viewer3D,options);
        this.sceneManager = viewer3D.sceneManager;
        this.scene = viewer3D.sceneManager.geometryScene;
        this.cubeTextureLoader = new CubeTextureLoader();
    }
    /**
     * 设置天空盒的6个图片地址
     * 
     * 设置立方体贴图天空盒的6张图片地址，按照Three.js的约定顺序：
     * [px, nx, py, ny, pz, nz] 分别对应右、左、上、下、前、后六个面。
     * 
     * @param {Array<string>} urls - 6张图片的URL地址数组
     * @example
     * // 设置天空盒图片
     * skyBox.setSkyBoxUrls([
     *     'right.jpg',   // px - 右面
     *     'left.jpg',    // nx - 左面
     *     'top.jpg',     // py - 上面
     *     'bottom.jpg',  // ny - 下面
     *     'front.jpg',   // pz - 前面
     *     'back.jpg'     // nz - 后面
     * ]);
     */
    setSkyBoxUrls(urls){
        if(!Array.isArray(urls) || urls.length !== 6) {
            return console.error("the urls must be an array of 6 image urls for the skybox");
        }
        _$skyBoxUrls = urls;
    }

    set enabled(boolean){
        super.enabled = boolean;
        if(boolean === true) {
            this.__init();
        }else{
            this.__recover()
        }
    }

    /**
     * 初始化天空盒
     * 
     * 异步加载天空盒纹理，设置场景背景和雾效。
     * 这是一个私有方法，由enabled属性自动调用。
     * 
     * @private
     * @async
     * @example
     * // 此方法由enabled属性自动调用
     * skyBox.enabled = true; // 会自动调用__init()
     */
    async __init(){
        const textures = await this.cubeTextureLoader.loadAsync(_$skyBoxUrls);
        this.scene.background = textures;
        this.scene.fog = new Fog(0xC0C0C0, 10, 1000000);
        this.dispatchEvent({type:'render'});
    }

    /**
     * 恢复天空盒
     * 
     * 移除场景背景和雾效，恢复场景到默认状态。
     * 这是一个私有方法，由enabled属性自动调用。
     * 
     * @private
     * @example
     * // 此方法由enabled属性自动调用
     * skyBox.enabled = false; // 会自动调用__recover()
     */
    __recover(){
        this.scene.background = null;
        this.scene.fog = null;
        this.dispatchEvent({type:'render'});
    }

    /**
     * 销毁天空盒插件
     * 
     * 清理插件资源，移除天空盒背景和雾效，调用父类的销毁方法。
     * 
     * @example
     * // 销毁天空盒插件
     * skyBox.dispose();
     */
    dispose() {
        this.__recover();
        super.dispose();
    }
}
export {
    SkyBox
}

2.使用插件

javascript


const extensionManager  = viewer3D.extensionManager;
//修改成你自己的地址
const urls = ['./images/skyboxs/px.jpg', './images/skyboxs/nx.jpg', './images/skyboxs/py.jpg', './images/skyboxs/ny.jpg', './images/skyboxs/pz.jpg', './images/skyboxs/nz.jpg'];

const skyBox = new PluginPackage.SkyBox(viewer3D,{});
skyBox.addEventListener('render',()=>{
    viewer3D.allRender();
})

skyBox.setSkyBoxUrls(urls);
skyBox.enabled = true;
extensionManager.addPlugin('skybox',skybox,false);

插件开发示例 ​

基础插件开发 ​

1. 简单插件示例 ​

2.使用插件 ​

相关链接 ​

插件开发示例

基础插件开发

1. 简单插件示例

2.使用插件

相关链接