VR Workshop DevKit

基于Owlly的通用离线标注工具集

起步

安装

# npm
$ npm i -S @aibee/vr-workshop-devkit

# yarn
$ yarn add @aibee/vr-workshop-devkit

使用

main.js

import VRLabelingTool from '@aibee/vr-workshop-devkit';
Vue.use(VRLabelingTool);

<template lang="html">
  <VRLabelingTool
    ref="labelingTool"
    :model-path="modelPath"
    :panorama-data="panoData"
    :initial-view-direction="initialViewDirection"
    :current-panorama-id.sync="currentPid"
    :show-map.sync="showMap"
    :svg-path="svgPath"
    :svg-align-params="svgAlignParams"
    :custom-content-types="customContentTypes"
    :panorama-videos="panoramaVideos"
    @stageInited="onStageInited"
    @eventEmitted="onEventEmitted">
    <template #transitionSelector>
      <el-cascader
        v-model="selectedTransitionTarget"
        class="dialog-cascader"
        :options="transitionOptions"
        size="mini"
        @change="onTransitionSelectedTargetChanged">
      </el-cascader>
    </template>
  </VRLabelingTool>
</template>

API 文档

参数

快速参考表格

复杂数据结构将在表格下方复杂数据小节说明

参数	必填	说明	类型	可选值	默认值
model-path	✅	所标注VR场景的模型数据URI	string	-	-
panorama-data	✅	所标注VR场景的全景图数据	array(详见下方说明)	-	-
initial-view-direction	✅	所标注VR场景的默认视线方向, 数据为(x, y, z)组成的方向向量数组	[number, number, number]	-	-
current-panorama-id	✅	当前全景点位id, 数据双向绑定	number	-	-
show-map		是否显示地图, 数据双向绑定	boolean	-	false
svg-path		地图对应svg的URI	string	-	-
svg-align-params		地图与模型的对齐数据	object(详见下方说明)	-	-
custom-content-types		自定义内容数据	array(详见下方说明)	-	-
panorama-videos		全景视频数据	array(详见下方说明)	-	-

复杂数据说明

panorama-data

type PanoramaData = {
    pid: number, // 必填, 点位id
    visible: boolean, // 必填, 全景点可见性
    position: number[], // 必填, 全景点点位坐标, 格式为 [x, y, z]
    quaternion: number[], // 必填, 全景点姿态四元数, 格式为 [x, y, z, w]
    neighbourPanoramaIDs: number[], // 必填, 临近全景点可见性数组, 数组元素为可见点位的点位id
    textureURLs: string[], // 必填, 低清全景图图片URI数组
    useLowTextureURLsOnly: boolean, // 可选, 仅使用低清全景图, 默认为false
    highTextureURLs: string[], // 可选, 高清全景图图片URI数组, 默认为null
}[];

svg-align-params

type SvgAlignParams = {
    img_height: number, // 地图svg高度,
    img_width: number, // 地图svg宽度,
    transformMatrices: {
        upTrans: number[], // svg坐标空间与模型坐标空间的对齐映射矩阵, 数组为16个元素, 描述一个4*4的矩阵
    },
};

custom-content-types

type CustomContentTypes = {
    value: number, // 类型id, 注意: 0为无类型值, 请勿使用
    thumb: string, // 缩略图URI, 用于在选择器内展示
    title: string, // 类型名称, 用于在选择器等位置展示
    component: VueComponentClass, // 编辑组件, 用于填充内容标签页的编辑内容, 传入类定义而不是实例,
    default: any, // 默认值, 若使用该字段, 默认值会传入组件的data属性内
};

panorama-videos

type PanoramaVideos = {
    pid: number, // 必填, 点位id
    src: string, // 必填, 全景视频链接
    name: string, // 必填, 视频名称
}[];

插槽

transitionSelector

过渡选择对话框内左上角所需填充的选择器组件, 需用户自行定义

接口

侧边栏设置

omitTools(toolnames: string | Array)

筛选掉不需要的工具。

switchTool(toolname)

设置默认选中工具。可选项有 viewingAngle、pointVisibility、hotspot、imgTextLabel、signLabel、ruler

视角设置

setPerspective(perspectiveData: object)

设置视角数据

参数

名称	说明
perspectiveData	标签数据数组, 数组元素数据结构参考"事件"部分viewing-angle``update中data的结构

漫游热点

setHotspots(hotspotData: object[] || {short: object[], content: object[]})

设置热点数据.

参数

名称	说明
hotspotData	热点数据数组或者对象。假设传入数组, 工具归类热点数据都为快捷导航热点。数据元素数据结构参考"事件"部分hotspot``create中data的结构

createHotspot(hotspotData: object)

新增热点

名称	说明
hotspotData	热点数据结构如下

type hotspotData = {
    img: string, // 热点封面, 应该为base64格式的图片
    pid: number, // currentPid, 当前所在点位
    quaternion: {}, // 四元数
    type: string // 类型, 当前可选 content, short
};

updateHotspot(id: number, hotspotData: object)

更新热点

名称	说明
id	标签id
hotspotData	热点数据

deleteHotspot(id: number, type?: short)

删除目标id的热点数据

参数

名称	说明
id	热点id

标签标注

set2DLabels(labelData: object[])

设置标签标注数据, 该操作将替换所有标签.

参数

名称	说明
labelData	标签数据数组, 数组元素数据结构参考"事件"部分2d-label``create中labelData的结构

add2DLabel(labelData: object)

在当前点位添加2D标签, 使用labelData作为模板.

参数

名称	说明
labelData	标签数据, 数据结构参考"事件"部分2d-label``create中labelData的结构

update2DLabel(id: number, labelData: object)

更新目标id的标签数据

参数

名称	说明
id	标签id
labelData	标签数据, 数据结构参考"事件"部分2d-label``create中labelData的结构

delete2DLabel(id: number)

删除目标id的标签数据

参数

名称	说明
id	标签id

set2DTemplateLabels(templateData: object[])

设置标签标注标签库(模板)数据.

参数

名称	说明
templateData	标签数据数组, 数组元素数据结构参考"事件"部分2d-label``create中labelData的结构

set2DShortcuts(shortcutData: object[])

设置标签标注快速添加(模板)数据.

参数

名称	说明
shortcutData	标签数据数组, 数组元素数据结构参考"事件"部分2d-label``create中labelData的结构

add2DShortcut(labelData: object)

添加快速添加标签数据, 使用labelData作为模板.

参数

名称	说明
labelData	标签数据, 数据结构参考"事件"部分2d-label``create中labelData的结构

delete2DShortcut(labelData: object)

删除快速添加标签数据

参数

名称	说明
labelData	标签数据, 数据结构参考"事件"部分2d-label``create中labelData的结构

标牌标注

set3DLabels(labelData: object[])

设置3D标牌数据, 该操作将替换所有标牌.

参数

名称	说明
labelData	标签数据数组, 数组元素数据结构参考"事件"部分3d-label``create中labelData的结构

create3DLabel(labelData: object)

新建3D标牌并且自动选中该3D标牌. 完成后可在组件内通过 label-3d-created 监听到并进行自定义操作

参数

名称	说明
labelData	3D标牌数据, 数组元素数据结构参考"事件"部分3d-label``create中labelData的结构。新建时可不含id / transition / content

update3DLabel(id: number, labelData: object)

更新3D标牌. 完成后可在组件内通过 label-3d-updated 监听到并进行自定义操作

参数

名称	说明
id	标牌id
labelData	3D标牌数据, 数组元素数据结构参考"事件"部分3d-label``create中labelData的结构。

delete3DLabel(id: number)

删除3D标牌。完成后可在组件内通过 label-3d-deleted 监听到并进行自定义操作

参数

名称	说明
id	标牌id

可见性

setPointVisibilities(pointsVisibility: object[])

设置点位可见性。

参数

名称	说明
pointsVisibility	可见性数组。数组元素数据结构参考"事件"部分point-visibility``current-update中pointVisibility的结构。

setCurrentPointVisibility(pointVisibility: object)

设置当前点位可见性。

参数

名称	说明
pointVisibility	可见性对象。数组元素数据结构参考"事件"部分point-visibility``current-update中pointVisibility的结构。

setCurrentPointNeighborVisibility(neighborPid: number, neighborVisible: boolean)

设置位于当前点位的时候, 相邻点位对于当前点位是否可见。

名称	说明
neighborPid	相邻点位pid
neighborVisible	相邻点位对于当前点位是否可见

过渡相关

openTransitionDialog()

开启过渡选择对话框

setTransitionDialogVrData(panoData: object[], modelPath: string, pid: number, direction: number[])

设置过渡选择对话框内的VR场景数据

参数

名称	说明
panoData	全景数据, 数据结构参考"参数"部分中PanoramaData的结构
modelPath	模型数据URI
pid	点位id
direction	方向, 结构为[x, y, z]数组

setTransitionInfo(info: object)

设置当前的过渡信息

参数

名称	说明
info	标签数据, 数据结构参考`getCurrentTransitionInfo()`返回值

getCurrentTransitionInfo(): object

获取当前的过渡信息

返回值: 过渡信息, 结构如下

{
    pid: number, // 点位id
    text: string, // 过渡提示信息文字
    thumb: string, // 过渡缩略图
    direction: number[], // 朝向方向向量
}

事件

目前标注工具仅使用一个事件接口进行广播, 但使用参数进行工具与类型的区分. 通用事件结构如下:

通用事件接口

事件名: @stageInited stage初始化完成后的生命周期。可在这个事件里执行自定义操作和工具侧边栏相关。

参数结构实例:

function onStageInited() {
    // ...
}

事件名: @eventEmitted

参数结构实例:

function onEventEmitted({
    tool: string, // 广播事件的工具名称
    type: string, // 事件的类型
    data: any, // 事件所包含的数据
}) {
    // ...
}

工具类型

名称	说明
viewing-angle	视角设置
hotspot	漫游热点
label-2d	标签标注
label-3d	标牌标注
point-visibility	点位可见性

各工具事件

viewing-angle 视角设置

update

初始视角更新

data结构:

{
    defaultFov: number, // 初始FOV
    fovRange: [number, number], // FOV范围
    initPid: number, // 初始点位id
    direction: [number, number, number], // 初始视角方向
    indicatorUrl: string, // 点位地面图标URI
    indicatorSize: number, // 点位地面图片尺寸, 以厘米为单位
    northPoint: number, // 指北方向角度
}

create

初始视角新建, 会在短期内移除该事件.

data结构参考update事件.

north-update

指北角更新, 会在短期内移除该事件.

data结构参考update事件.

north-create

指北角新建, 会在短期内移除该事件.

data结构参考update事件.

hotspot 漫游热点

create

热点新建

data结构:

{
    img: string, // 热点缩略图, 格式为Base64字符串
    pid: number, // 热点点位id
    quaternion: { // 方向四元数
        _x: number,
        _y: number,
        _z: number,
        _w: number,
    },
}

update

热点更新

data结构:

{
    img: string, // 热点缩略图, 格式为Base64字符串或URI
    pid: number, // 热点点位id
    quaternion: { // 方向四元数
        _x: number,
        _y: number,
        _z: number,
        _w: number,
    },
    sort: number, // 排序值
    text: string, // 热点名称
}

delete

热点删除

data结构:

{
    id: number, // 热点id
}

sort

热点排序

data结构:

{
  params: {
    target_sort: number, // 需要变更的排序值
    next_sort: number, // 变更后的排序值
  },
  type: string  // 热点所属类型
}

label-2d 标签标注

create

标签新建, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构:

{
    labelData: {
        id: number,  // 标签id (create事件不返回该值)
        position: [number, number, number], // 标签位置
        pid: number, // 标签所在点位id
        visible: boolean, // 可见性
        image: {
            src: string, // 图片URI
            height: number, // 高度
            width: number, // 宽度
            anchor: string, // 锚点位置
            offsetX: number, // X轴偏移量
            offsetY: number, // Y轴偏移量
            visible: boolean, // 可见性
        },
        text: {
            content: string, // 文字内容
            anchor: string, // 锚点位置
            offsetX: number, // X轴偏移量
            offsetY: number, // Y轴偏移量
            visible: boolean, // 可见性
            color: string, // 颜色 (CSS颜色)
            fontSize: number, // 字号
            align: string, // 文字(段落)对齐
            backgroundColor: string, // 背景颜色 (CSS颜色)
            borderColor: string, // 描边颜色 (CSS颜色)
            borderWidth: number, // 描边宽度
            borderRadius: number, // 圆角半径
        },
        transition: {
            // 暂时不记录VR id, 后期会增加
            pid: number, // 点位id
            text: string, // 过渡说明文字
            thumb: string, // 过渡缩略图, Base64 或 URI
            direction: { // 朝向方向向量
                x: number,
                y: number,
                z: number,
            },
        },
        content: {
            type: number, // 内容类型
            triggerType: number, // 触发类型,
            data: any, // 内容数据
        },
    }
}

added

标签已添加后广播.

data结构参考create事件.

update

标签更新前广播, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构参考create事件.

updated

标签更新后广播.

data结构参考create事件.

delete

标签删除前广播, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构参考create事件.

deleted

标签删除后广播.

data结构参考create事件.

shortcut-create

快捷添加新建前广播, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构参考create事件.

shortcut-created

快捷添加新建后广播.

data结构参考create事件.

shortcut-delete

快捷添加删除前广播, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构参考create事件.

shortcut-deleted

快捷添加删除后广播.

data结构参考create事件.

open-transition-dialog

用户打开点位跳转选择器对话框时广播, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构: 无

clear-transition-info

用户清空点位跳转信息时广播

data结构: 无

transition-selection-confirmed

用户确认跳转信息时广播

data结构:

{
    pid: number, // 点位id
    image: string, // 过渡缩略图, Base64
    direction: number[], // 朝向方向向量
}

transition-selection-cancelled

用户取消确认跳转信息时广播

data结构: 无

label-3d 标牌标注

create

标牌新建, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构:

{
    id: number,  // 标牌id (create事件不返回该值)
    position: [number, number, number], // 标牌位置
    pose: [number, number, number, number], // 标牌姿态
    poseType: 0 | 1, // 标牌姿态类型, 0为朝向镜头, 1为自由姿态
    srcType: 'image' | 'video' | 'model, // 资源类型, image为图片, video为视频, model为模型
    imgUrl: string, // 图片URI
    videoUrl: string, // 视频URI（srcType为model时，模型URI也使用此字段）
    videoRatio: number, // 视频比例, 只读属性, SDK不会对该数值进行任何改动, 数值为 宽度 / 高度 的结果
    imgHeight: number, // 高度
    imgWidth: number, // 宽度（模型缩放也使用此字段）
    visible: boolean, // 可见性
    title: string, // 标牌名称
    visibleDist: number, // 可见范围距离
    visiblePoints: number[], // 标牌可见点位id数组
    transitionId: number, // transitionId (create事件不返回该值, 没有transition时候标注工具默认 transitionId 为 -1)
    transition: {  // 过度 （create事件不返回该值）
        // 暂时不记录VR id, 后期会增加
        pid: number, // 点位id
        text: string, // 过渡说明文字
        thumb: string, // 过渡缩略图, Base64 或 URI
        direction: { // 朝向方向向量
            x: number,
            y: number,
            z: number,
        },
    },
    contentId: number, // contentId (create事件不返回该值, 没有content时候标注工具默认 contentId 为 -1)
    content: { // 内容 (cerate 事件不返回该值)
        type: number, // 内容类型
        triggerType: number, // 触发类型,
        data: any, // 内容数据
    },
}

created

标牌新建完成后广播

update

标牌更新前广播, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构参考create事件.

updated

标牌更新后广播

delete

标牌删除前广播, 该事件在用户执行动作时广播, 工具会仅执行事件广播而不会进行其他操作

data结构参考create事件.

deleted

标牌删除后广播

open-transition-dialog

clear-transition-info

transition-selection-confirmed

transition-selection-cancelled

与label-2d同名事件相同

point-visibility 点位可见性编辑

current-update

当前点位可见性更新

data结构:

{
    pid: number,
    visible: boolean, // 当前点位是否可见
    invisibleNeighbors: [...pids] // 位于当前点位不可见的neighborPids
}

neighbor-update

当前点位可见的相邻点更新

data结构:

{
    neighborPid: number, // 相邻点位pid
    neighborVisible: boolean, // 相邻点位相对当前点位是否可见
}