scene-3d

src/npm 是楼层 3D 预览/展示模块，基于 Three.js 渲染编辑器保存的楼层数据。模块支持底图面、墙体、房间标签、业务图标、设备、通行设施和路径渲染，并提供运行时新增图标、替换设备图标、移动设备、相机飞行等能力。

快速开始

import { createScene3D } from '@/npm/index.js'

const scene3d = createScene3D(containerEl, floorData, {
  resourceBaseUrl: '/resource/',  // 图片资源路径在public下：public/resource/
  showAreaLabels: true,
  showIconSprites: true,
  showPassageSprites: true,
  showDeviceSprites: true
})

scene3d.on('click', (object, feature) => {
  console.log(object, feature)
})

销毁时释放 Three.js 资源：

scene3d.dispose()

创建场景

配置

createScene3D(container: HTMLElement, data?: EditorData | FeatureCollection, options?: SceneOptions): TDScene

| 选项 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | container | HTMLElement | √ | 3D 场景容器。 | | data | EditorData | FeatureCollection | | 初始化数据。支持编辑器保存结构或普通 GeoJSON。 | | options | SceneOptions | | 场景配置。 |

SceneOptions

| 选项 | 类型 | 必选 | 描述 | | --- | --- | --- |--------------------------| | targetSize | number | | 投影后的目标尺寸参考值，默认 0。 | | areaHeight | number | | 面区域高度，默认 0.08。 | | wallHeight | number | | 墙体高度，默认 2.5。 | | areaLabelHeight | number | | 房间文字高度，默认 2。 | | spriteY | number | | 业务图标统一高度；未传时按墙体高度计算。 | | showAreaLabels | boolean | | 是否显示房间标签，默认启用。 | | showIconSprites | boolean | | 是否显示普通图标，默认启用。 | | showPassageSprites | boolean | | 是否显示通行设施图标，默认启用。 | | showDeviceSprites | boolean | | 是否显示设备图标，默认启用。 | | showPaths | boolean | | 是否显示路径线，默认关闭。 | | background | number | | 场景背景色，默认 0xf7fafc。 | | resourceBaseUrl | string | | 图片资源根路径，默认 /resource/。 | | resourceExtension | string | | 资源默认扩展名，默认 png。 | | resourceFolders | Record<string, string> | | 不同业务图层的资源目录映射。 | | resolveResourcePath | function | | 自定义资源路径解析函数。 |

数据结构

模块支持两类输入：

| 类型 | 描述 | | --- | --- | | EditorData | 编辑器保存结构，包含 baseMap 和 business。 | | FeatureCollection | 普通 GeoJSON，会作为底图数据处理。 |

推荐结构：

{
  schemaVersion: 'rt-gis-editor.v1',
  coordinateSystem: {
    metersPerUnit: 1
  },
  baseMap: {
    type: 'FeatureCollection',
    features: []
  },
  business: {
    type: 'FeatureCollection',
    features: []
  }
}

业务点位通过 properties.layerType 区分：

| layerType | 描述 | 常用字段 | | --- | --- | --- | | icon | 普通图标 | iconName、iconUrl、markerUrl、color | | device | 设备 | categoryName、categoryIconUrl、deviceCode、markerUrl | | passage | 通行设施 | passageType、passageName、facilityIconUrl、markerUrl |

示例：

{
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [lng, lat]
  },
  properties: {
    layerType: 'device',
    deviceCode: 'code-1',
    categoryName: '监控'
  }
}

图标资源

资源解析

resolveResourceIconUrl(feature: Feature, options?: ResourceOptions): string

| 选项 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | feature | Feature | √ | 业务点位 Feature。 | | options.resourceBaseUrl | string | | 资源根路径。 | | options.resourceExtension | string | | 默认资源扩展名。 | | options.resourceFolders | Record<string, string> | | 资源目录映射。 | | options.resolveResourcePath | function | | 自定义资源路径函数。 |

默认会根据 layerType 和名称字段拼接资源路径：

| layerType | 名称字段 | 默认目录 | | --- | --- | --- | | device | categoryName | 设备 | | passage / facility | passageType 或 passageName | 直梯 | | icon | iconName | 图标 |

markerUrl

properties.markerUrl 表示已经生成好的图片资源，会直接作为 Sprite 贴图渲染，不再走默认 marker 画布生成。

{
  properties: {
    layerType: 'device',
    markerUrl: '/resource/device/camera-marker.png'
  }
}

运行时图标

createIcon

scene3d.createIcon(image: IconImage, coordinate: RuntimePosition, info?: object, options?: CreateIconOptions): THREE.Sprite | null

新增一个运行时业务图标。

| 参数 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | image | IconImage | √ | 图片资源。会直接作为 Sprite 贴图，不走资源名称解析或默认 marker 画布生成。 | | coordinate | RuntimePosition | √ | 图标坐标。支持地图坐标、Three 世界坐标和 THREE.Vector3。 | | info | object | | 写入 feature.properties 的业务信息。 | | options | CreateIconOptions | | 创建选项。 |

IconImage

| 类型 | 示例 | 描述 | | --- | --- | --- | | string | '/resource/device/camera.png' | 图片 URL。 | | object | { image: '/resource/device/camera.png' } | 从 markerUrl、image、iconUrl、url、icon、src、href 中读取图片资源。 | | HTMLImageElement | imageEl | 图片元素。 | | HTMLCanvasElement | canvasEl | Canvas 资源。 | | THREE.Texture | texture | Three.js 贴图。 |

RuntimePosition

| 类型 | 示例 | 描述 | | --- | --- | --- | | [lng, lat] | [113.1, 23.1] | 地图坐标。 | | [x, y, z] | [10, 3, 20] | Three 世界坐标。 | | object | { lng, lat } | 地图坐标对象。 | | object | { x, y, z } | Three 世界坐标对象。 | | THREE.Vector3 | new THREE.Vector3(x, y, z) | Three 世界坐标。 |

CreateIconOptions

| 选项 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | id | string | | Feature ID；未传时自动生成。 | | layerType | string | | 图层类型，默认读取 info.layerType，再默认 icon。 | | y | number | | 图标高度。 |

示例：

scene3d.createIcon('/resource/device/camera.png', [lng, lat], {
  layerType: 'device',
  deviceCode: 'code-1',
  deviceName: '监控 1'
})

别名：

scene3d.addIcon(...args)

replaceDeviceIcon

scene3d.replaceDeviceIcon(image: IconImage, deviceCode: string, info?: object): boolean

替换已有设备图标。

| 参数 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | image | IconImage | √ | 新图片资源。会直接作为 Sprite 贴图。 | | deviceCode | string | √ | 设备标识。 | | info | object | | 合并到原设备 feature.properties 的业务信息。 |

设备查找会匹配以下字段：

| 字段 | | --- | | properties.deviceCode | | properties.deviceId | | properties.deviceNo | | properties.code | | properties.id | | feature.id |

示例：

scene3d.replaceDeviceIcon('/resource/device/offline.png', 'code-1', {
  status: 'offline'
})

别名：

scene3d.replaceIcon(...args)

运行时标签

createLabel

scene3d.createLabel(component: Component, props?: object | (() => object), scale?: number): CSS3DSprite

创建一个基于 Vue 组件的 CSS3D 标签。

| 参数 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | component | Component | √ | Vue 组件。 | | props | object | (() => object) | | 传给 Vue 组件的属性；支持对象或返回对象的函数。 | | scale | number | | CSS3DSprite 缩放比例。 |

返回值为 THREE 的 CSS3DSprite，方法只负责创建标签对象，不会自动加入场景。调用方需要设置位置并添加到对应场景或分组。

示例：

import DeviceLabel from './DeviceLabel.vue'

const label = scene3d.createLabel(DeviceLabel, {
  name: '监控 1',
  status: '在线'
}, 0.02)

label.position.set(x, y, z)
scene3d.scene.add(label)

设备移动

moveDeviceIcon

scene3d.moveDeviceIcon(deviceCode: string, endPosition: RuntimePosition, options?: MoveOptions): boolean

| 参数 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | deviceCode | string | √ | 设备标识。 | | endPosition | RuntimePosition | √ | 目标位置。 | | options | MoveOptions | | 移动配置。 |

MoveOptions

| 选项 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | duration | number | | 动画时长，单位毫秒，默认 800。 | | follow | boolean | | 是否让相机跟随移动目标。 | | followOptions | object | | 相机飞行配置。 |

示例：

scene3d.moveDeviceIcon('code-1', [endLng, endLat], {
  duration: 1000,
  follow: true,
  followOptions: {
    distance: 10,
    duration: 1000
  }
})

别名：

scene3d.moveIcon(...args)

设备状态

setDeviceAlarm

scene3d.setDeviceAlarm(deviceCode: string): boolean

将设备渲染为告警状态。

setDeviceOffline

scene3d.setDeviceOffline(deviceCode: string): boolean

将设备渲染为离线状态。

| 参数 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | deviceCode | string | √ | 设备标识。 |

相机

followDevice

scene3d.followDevice(deviceCode: string, options?: CameraFlyOptions): boolean

从当前视角平滑飞到目标设备近景。

别名：

scene3d.cameraFollowDevice(...args)
scene3d.trackDevice(...args)

stopFollowDevice

scene3d.stopFollowDevice(): void

取消当前相机飞行动画。

CameraFlyOptions

| 选项 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | distance | number | | 相机和目标的距离。 | | height | number | | 相机高度。 | | duration | number | | 动画时长，单位毫秒。 | | target | THREE.Vector3 | | 自定义目标点。 |

事件

on

const cleanup = scene3d.on(type: 'click', callback: (object: THREE.Object3D, feature: Feature) => void): Function

| 参数 | 类型 | 必选 | 描述 | | --- | --- | --- | --- | | type | 'click' | √ | 当前支持业务点位点击事件。 | | callback | function | √ | 点击回调。 |

off

scene3d.off(type: 'click'): void

取消指定事件。

坐标转换

mapCoordinateToWorld

scene3d.mapCoordinateToWorld(coordinate: [number, number]): THREE.Vector3 | null

地图坐标转 Three 世界坐标。

worldToMapCoordinate

scene3d.worldToMapCoordinate(x: number, z: number): [number, number] | null

Three 世界坐标转地图坐标。

数据切换

setData

scene3d.setData(data: EditorData | FeatureCollection, options?: SceneOptions): void

清空当前场景并重新渲染。

switchMap

scene3d.switchMap(data: EditorData | FeatureCollection, options?: SceneOptions): void

setData 的语义化别名。

底层方法

TDMethods 导出底层工具方法，适合需要自定义渲染或独立处理数据时使用。

| 方法 | 描述 | | --- | --- | | normalizeEditorData | 归一化编辑器数据。 | | createProjection | 创建坐标投影函数。 | | createBusinessSprite | 创建业务点位 Sprite。 | | createMarkerSprite | 创建默认 marker Sprite。 | | createTextureSprite | 使用图片资源创建贴图 Sprite。 | | createPathLine | 创建路径线。 | | createRaycaster | 创建点击射线检测。 | | disposeObject | 释放单个 Three 对象资源。 | | disposeChildren | 释放 Group 下所有子对象资源。 |