openzi-vue

OpenZI是一套高性能的三维可视化引擎，专为Web端打造。openzi-vue是其Vue集成包，提供了在Vue应用中快速集成OpenZI功能的能力。

功能特性

• 高性能WebRTC实时渲染，支持低延迟交互
• 丰富的场景API支持，包括关卡加载、坐标转换、相机控制等
• 便捷的Vue组件集成，支持Vue 3
• 完善的事件机制，便于业务层扩展
• 跨平台兼容性，支持主流浏览器
• 提供视频站、POI点、镜头漫游等高级功能

安装

npm install openzi-vue
# 或
yarn add openzi-vue

快速入门

API 文档

在线文档

您可以直接访问在线API文档：OpenZI Vue API 文档

本地文档

注意：npm平台不支持直接在线查看包内的HTML文件。

查看详细的API文档，请在安装包后打开本地的 api-docs.html 文件。

安装后，可以通过以下方式访问API文档：

1. 找到您项目中安装的openzi-vue包目录
2. 在该目录下直接打开 api-docs.html 文件查看完整的API文档和组件说明

组件内使用

以下是基于vue的完整使用示例，包含组件初始化、场景配置、关卡加载和API操作等功能：

<template>
  <div class="container">
    <!-- 配置区域 -->
    <div class="config-panel">
      <div class="config-item">
        <label for="ueIp">UE服务器IP：</label>
        <input id="ueIp" v-model="config.ueIp" type="text" placeholder="输入UE服务器IP">
      </div>
      <button class="tech-btn primary" @click="applyConfig">应用配置</button>
    </div>

    <!-- 组件展示区域 -->
    <div class="component-container" v-if="showComponent">
      <open-z-i-viewer  @mapLoaded="onMapLoaded" />
    </div>

    <!-- API操作区域 -->
    <div class="api-panel">
      <div class="api-section">
        <h3>关卡管理</h3>
        <div class="button-group">
          <button class="tech-btn primary" @click="loadSingleLevel('耳闸', '耳闸-入口-中景')" :disabled="!apiReady">加载耳闸关卡</button>
          <button class="tech-btn secondary" @click="loadSingleLevel('二道闸','二道闸-上游-近景')" :disabled="!apiReady">加载二道闸关卡</button>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref, reactive } from 'vue';
// 从openzi-vue包导入OpenZIViewer sceneApi和levelUtils
import { sceneApi, levelUtils, OpenZIViewer } from 'openzi-vue';
// 解构levelUtils工具方法
const { fetchCameraData, fetchLevelData, findLevelByName, findCameraConfig, loadLevelWithChildren } = levelUtils;

// 组件配置
const config = reactive({
  ueIp: '192.168.18.224',
  levelConfigUrl: '/configs/map/levelData.json'
});

// 状态变量
const showComponent = ref(false);
const apiReady = ref(false);
let OpenZIAPI = null;

// 应用配置
function applyConfig() {
  if (!config.ueIp) {
    console.error('请输入有效的UE服务器IP地址');
    return;
  }
  window.ueIp = config.ueIp; // 将UE服务器IP赋值给全局变量
  showComponent.value = false;
  setTimeout(() => {
    showComponent.value = true;
  }, 100);
}

// 地图加载完成回调
async function onMapLoaded(data) {
  console.log('地图加载完成');

  // 获取OpenZIAPI实例
  OpenZIAPI = data?.OpenZIAPI;

  if (OpenZIAPI) {
    apiReady.value = true;
    // 初始化场景通用工具API
    sceneApi.init(OpenZIAPI);
    
    try {
      // 1 设置默认坐标系
      await sceneApi.changeCoodinate({
        "coordinateOrigin": "117.4572,39.021101,140.402447",
        "projectionCoordinateSystem": "EPSG:4326",
        "planetShape": 1,
        "GISType": 0,
        "originOffset": "0,0,0",
        "scale": 100
      });

      // 2 设置默认帧率
      sceneApi.changeFps(30);

      // 3 加载基础关卡
      await loadLevels();

      // 4 设置默认视角
      setDefaultCameraView();

    } catch (error) {
      console.error(`初始化设置出错: ${error.message}`);
    }
  }

  // 加载基础关卡函数
  async function loadLevels() {
    try {
      // 加载主要关卡
      await sceneApi.loadLevel('TJ01_46', true);
      // 加载天空场景
      await sceneApi.loadLevel('LV_skycreator', false);
      // 加载特效
      sceneApi.loadLevel('BP_TEXIAO', false);
    } catch (error) {
      console.error(`加载关卡时出错: ${error.message}`);
    }
  }

  // 设置默认视角函数
  function setDefaultCameraView() {
    try {
      // 设置RTS模式的默认视角
      const cameraInfo = {
        "cameraMode": "rts",
        "redirectionOrigin": false,
        "gisType": 0,
        "coordinates": {"X": 117.20377616700722, "Y": 39.136763510147595, "Z": 48.32056263554841},
        "pitch": -79.25000000000016,
        "pitchRange": {"X": -90, "Y": -5},
        "yaw": 179.99999999999966,
        "yawRange": {"X": -180, "Y": 180},
        "moveSpeed": 100,
        "rotationSpeed": 180,
        "zoomSpeed": 100
      };

      // 调用设置相机信息的API
      sceneApi.changeCamera(cameraInfo)
        .then(() => {
          console.log('默认视角设置完成');
        })
        .catch(error => {
          console.error(`默认视角设置失败: ${error.message}`);
        });
    } catch (error) {
      console.error(`设置默认视角时出错: ${error.message}`);
    }
  }
}

// 加载单关卡并设置指定视角
async function loadSingleLevel(name, cameraName = '默认', weaterName = 'Weather_Clear_02', time = 17) {
  try {
    // 0 检查参数是否有效
    if (!name) {
      console.error('加载单关卡时缺少必要参数');
      return;
    }

    console.log(`开始加载关卡: ${name}`);

    // 1 修改天气
    sceneApi.changeWeather(weaterName);
    console.log(`天气已设置为: ${weaterName}`);

    // 2 修改时间
    sceneApi.changeHour(time);
    console.log(`时间已设置为: ${time}时`);

    // 3 动态获取关卡配置数据
    const levelData = await fetchLevelData();
    const targetLevel = findLevelByName(levelData, name);

    if (!targetLevel) {
      console.warn(`未找到关卡${name}的配置信息`);
      // 尝试直接使用提供的名称加载
      try {
        await sceneApi.loadLevel(name, false);
        console.log(`关卡${name}加载完成`);
      } catch (error) {
        console.error(`加载关卡${name}失败: ${error.message}`);
      }
      return;
    }

    // 4 加载指定关卡及其子节点
    try {
      await loadLevelWithChildren(targetLevel);
      console.log(`关卡${targetLevel.title}加载完成`);
    } catch (error) {
      console.error(`加载关卡${targetLevel.title}失败: ${error.message}`);
      return;
    }

    // 5 动态获取相机配置数据并应用
    if (cameraName) {
      const cameraData = await fetchCameraData();
      const targetCameraInfo = findCameraConfig(cameraData, name, cameraName);

      if (!targetCameraInfo) {
        console.warn(`未找到关卡${name}对应的相机配置${cameraName || ''}，使用默认视角`);
      } else {
        // 应用相机视角设置
        try {
          await sceneApi.changeCamera(targetCameraInfo);
          console.log(`视角${cameraName}设置完成`);
        } catch (error) {
          console.error(`设置视角失败: ${error.message}`);
        }
      }
    }

  } catch (error) {
    console.error(`加载关卡${name}时出错: ${error.message}`);
  }
}
</script>

<style scoped>
.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 20px;
}

.component-container {
  width: 100%;
  height: 600px;
  border: 1px solid #ddd;
  overflow: hidden;
  background-color: #000;
}

/* 确保open-z-i-viewer组件适应容器尺寸 */
.component-container >>> open-z-i-viewer {
  width: 100%;
  height: 100%;
  display: block;
}

/* 其他样式省略 */
</style>

核心组件说明

OpenZIViewer 组件

OpenZIViewer 是整个库的核心组件，负责与OpenZI引擎建立连接并渲染3D场景。

组件属性

| 属性名 | 类型 | 默认值 | 说明 | |-------|------|-------|------| | ueIp | String | 无 | UE服务器IP地址，必填项 | | uePort | Number | 8080 | UE服务器端口 | | peerConnectionOptions | Object | {} | WebRTC连接配置选项 | | startVideoMuted | Boolean | false | 是否静音启动视频 | | autoPlayAudio | Boolean | true | 是否自动播放音频 |

组件事件

| 事件名 | 参数 | 说明 | |-------|------|------| | mapLoaded | data: { OpenZIAPI } | 地图加载完成时触发，返回OpenZIAPI实例 | | onConnected | 无 | 连接成功时触发 | | onDisconnected | 无 | 断开连接时触发 | | onError | error: Error | 发生错误时触发 |

场景API (sceneApi) 详解

sceneApi 提供了一系列操作3D场景的方法，以下是主要API的详细说明：

初始化与基础操作

init(api)

初始化场景API，必须在使用其他API前调用。

• 参数: api - OpenZIAPI实例
• 返回值: 无

import { sceneApi } from 'openzi-vue'

// 地图加载完成后初始化
function onMapLoaded(data) {
  const OpenZIAPI = data?.OpenZIAPI
  if (OpenZIAPI) {
    sceneApi.init(OpenZIAPI)
  }
}

changeCoodinate(jsondata)

切换场景坐标系。

• 参数: jsondata - 坐标系配置对象
• 返回值: Promise

await sceneApi.changeCoodinate({
  "coordinateOrigin": "117.4572,39.021101,140.402447",
  "projectionCoordinateSystem": "EPSG:4326",
  "planetShape": 1,
  "GISType": 0,
  "originOffset": "0,0,0",
  "scale": 100
})

loadLevel(levelName, removeOthersLevel, bHidden)

加载指定关卡。

• 参数:
  • levelName - 关卡名称
  • removeOthersLevel - 是否移除其他关卡
  • bHidden - 是否隐藏关卡
• 返回值: Promise

// 加载主要关卡并移除其他关卡
await sceneApi.loadLevel('TJ01_46', true)

// 加载天空场景但不移除其他关卡
await sceneApi.loadLevel('LV_skycreator', false)

相机控制

getCameraInfo()

获取当前相机信息。

• 参数: 无
• 返回值: Promise，解析为相机信息对象

sceneApi.getCameraInfo().then(cameraInfo => {
  console.log('当前相机信息:', cameraInfo)
})

changeCamera(cameraInfo)

设置相机位置和角度。

• 参数: cameraInfo - 相机信息对象
• 返回值: Promise

sceneApi.changeCamera({
  "cameraMode": "rts",
  "redirectionOrigin": false,
  "gisType": 0,
  "coordinates": {"X": 117.203776, "Y": 39.136764, "Z": 48.320563},
  "pitch": -79.25,
  "yaw": 180,
  "moveSpeed": 100,
  "rotationSpeed": 180,
  "zoomSpeed": 100
})

视频站与POI管理

addVideos()

添加视频站。

• 参数: 无
• 返回值: Promise

sceneApi.addVideos().then(result => {
  console.log('添加视频站成功:', result)
})

clearPOI()

清除所有POI点。

• 参数: 无
• 返回值: Promise

sceneApi.clearPOI().then(result => {
  console.log('清除POI成功:', result)
})

镜头漫游

addCameraPlay()

添加镜头漫游。

• 参数: 无
• 返回值: Promise

sceneApi.addCameraPlay().then(result => {
  console.log('添加镜头漫游成功:', result)
})

startCameraPlay()

开始镜头漫游。

• 参数: 无
• 返回值: Promise

sceneApi.startCameraPlay().then(result => {
  console.log('开始漫游成功:', result)
})

pauseCameraPlay()

暂停镜头漫游。

• 参数: 无
• 返回值: Promise

sceneApi.pauseCameraPlay().then(result => {
  console.log('暂停漫游成功:', result)
})

性能控制

changeFps(fps)

修改帧率。

• 参数: fps - 目标帧率
• 返回值: Promise

// 设置为30帧
sceneApi.changeFps(30)

showFps()

显示当前帧率。

• 参数: 无
• 返回值: Promise

sceneApi.showFps().then(result => {
  console.log('显示帧率信息:', result)
})

开发指南

克隆仓库

git clone https://github.com/yourusername/openzi-vue.git
cd openzi-vue

安装依赖

npm install

开发模式

npm run dev

构建生产版本

npm run build

预览生产版本

npm run preview

兼容性

• 支持Chrome 80+、Firefox 78+、Safari 14+等现代浏览器
• 需要支持WebRTC的浏览器环境
• 推荐使用Chrome浏览器以获得最佳性能

License

MIT