@zhangdali1996/lr-map-viewer 0.0.13 → 0.0.15

package/README.md

@@ -298,14 +298,6 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 - `get3dInstance()`
 - `resize()`
 - `refreshScene()`
-- `saveView()`
-- `restoreView(viewState)`
-- `initializeDemoPerson()`
-- `startDemoPersonMotion(x, y, z)`
-- `stopDemoPersonMotion()`
-- `toggleDemoPersonMotion(x, y, z)`
-- `focusDemoPerson()`
-- `moveView(x, y, z)`
 - `registerModelInfoQuery(callback)`
 
 说明：
@@ -313,12 +305,93 @@ createApp(App).use(LrMapViewerPlugin).mount('#app')
 - `switchMode(mode)` 支持在 `2d / 3d` 间切换当前显示引擎。
 - `get2dInstance()` 返回当前二维 adapter 实例，其中包含 `map`、`options`、`behavior`、`layerTree` 等信息。
 - `refreshScene()` 仅对三维场景有效。
-- `saveView()` 用于保存当前三维视角快照，返回结果可直接交给 `restoreView(viewState)` 复原。
-- `initializeDemoPerson()`、`startDemoPersonMotion()`、`stopDemoPersonMotion()`、`toggleDemoPersonMotion()`、`focusDemoPerson()` 仅对三维场景有效，用于控制示例人员对象。
-- `moveView(x, y, z)` 传入的是绝对三维坐标，组件内部会自动换算成相对 `basePoint` 坐标后调用聚焦接口。
 - `registerModelInfoQuery(callback)` 会在用户点击三维中的模型对象时触发回调。
 - 模型信息查询返回 4 个字段：`id`、`name`、`layerName`、`position`。
 
+## 监测点模块
+
+监测点相关能力通过组件实例提供，适合业务侧自己实现外部按钮、列表和联动逻辑。
+
+监测点模块 expose：
+
+- `initMonitorPoints()`
+- `queryMonitorPointList()`
+- `reloadMonitorPoints()`
+- `focusMonitorPoint(target)`
+- `focusPerson(target)`
+- `movePerson(target)`
+
+说明：
+
+- `initMonitorPoints()` 用于初始化监测点，组件会查询监测点数据并加载显示到三维场景中。
+- `queryMonitorPointList()` 会重新查询最新监测点数据，并返回列表结果，但不会把结果重新加载到地图上。
+- `reloadMonitorPoints()` 会先清空当前场景中已加载的监测点，再重新查询并加载，避免重复添加。
+- `focusMonitorPoint(target)` 会将视口移动到指定监测点，并打开该监测点的信息弹窗；`target` 支持传监测点 `id` 或监测点对象。
+- `focusPerson(target)` 用于聚焦指定人员定位对象；`target` 支持传人员 `sceneId`、人员名称或人员对象，不传时默认聚焦第一名人员。
+- `movePerson(target)` 用于触发指定人员的轨迹移动；`target` 的传参规则与 `focusPerson(target)` 保持一致。
+
+## 视角控制模块
+
+视角控制相关能力同样通过组件实例提供，便于业务侧自己实现“视角列表 + 当前视口保存恢复”。
+
+视角控制模块 expose：
+
+- `getViewPointList()`
+- `switchToViewPoint(target)`
+- `getCurrentViewInfo()`
+- `applyViewInfo(viewInfo)`
+
+说明：
+
+- `getViewPointList()` 返回当前预设视角列表，列表项包含 `key`、`name`、`cameraPos`、`viewCenter`。
+- `switchToViewPoint(target)` 用于切换到指定预设视角；`target` 支持传预设视角 `key`、视角名称或视角对象。
+- `getCurrentViewInfo()` 用于读取当前视口的视角信息，返回结果可直接作为 `applyViewInfo(viewInfo)` 的入参。
+- `applyViewInfo(viewInfo)` 用于按传入的视角参数恢复视口位置和视角中心。
+
+## 其他 3D 方法
+
+以下方法继续保留，主要用于兼容现有接入方式或演示人员联动：
+
+- `initializeDemoPerson()`
+- `startDemoPersonMotion(x, y, z)`
+- `stopDemoPersonMotion()`
+- `toggleDemoPersonMotion(x, y, z)`
+- `focusDemoPerson()`
+- `moveView(x, y, z)`
+
+说明：
+
+- `initializeDemoPerson()` 用于初始化人员演示对象或人员轨迹对象。
+- `startDemoPersonMotion()`、`stopDemoPersonMotion()`、`toggleDemoPersonMotion()` 为旧的人员演示控制方法。
+- `focusDemoPerson()` 用于聚焦当前主人员对象。
+- `moveView(x, y, z)` 用于按绝对坐标快速聚焦目标点。
+
+## 范围选点模块
+
+范围选点相关能力单独通过组件实例提供，适合外部业务系统自己实现按钮、面板和联动逻辑，而不是依赖组件内部调试面板。
+
+范围选点模块 expose：
+
+- `startRangeSelection(options)`
+- `cancelRangeSelection(options)`
+- `setRangeSelection(center, options)`
+- `setRangeSelectionRadius(radius)`
+- `clearRangeSelection()`
+- `getRangeSelectionResult()`
+- `registerRangeSelectionChange(callback)`
+- `focusMonitorPoint(target)`
+
+说明：
+
+- `startRangeSelection(options)` 用于启动范围选点，支持通过 `options.radius` 指定初始半径。
+- `cancelRangeSelection(options)` 用于取消当前范围选点，可通过 `options.preserveCurrentResult` 控制是否保留当前结果。
+- `setRangeSelection(center, options)` 用于直接传入三维坐标生成球形范围，适合业务系统通过外部坐标直接驱动范围选点。
+- `setRangeSelectionRadius(radius)` 用于更新当前范围半径；如果当前已完成选点，会同步更新球体和范围内测点。
+- `clearRangeSelection()` 用于清除当前范围球、选点标记和测点过滤结果。
+- `getRangeSelectionResult()` 返回当前范围选点结果，包含状态、半径、球心坐标、当前巷道信息和范围内测点列表。
+- `registerRangeSelectionChange(callback)` 会在开始选点、选点完成、半径变化、取消、清除时触发回调。
+- `focusMonitorPoint(target)` 用于定位并打开指定测点的信息窗，支持传测点 `id` 或测点对象。
+
 ## 二维图纸配置说明
 
 推荐写法：
@@ -388,6 +461,93 @@ const map2dConfig = {
 
 推荐通过 `ref` 调用组件实例方法：
 
+### 监测点模块示例
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const viewerRef = ref(null)
+
+async function handleInitMonitorPoints() {
+  await viewerRef.value?.initMonitorPoints?.()
+}
+
+async function handleReloadMonitorPoints() {
+  await viewerRef.value?.reloadMonitorPoints?.()
+}
+
+async function handleQueryMonitorPoints() {
+  const list = await viewerRef.value?.queryMonitorPointList?.()
+  console.log('monitor points', list)
+}
+
+function handleFocusMonitorPoint() {
+  viewerRef.value?.focusMonitorPoint?.('mock-monitor-point-1')
+}
+
+function handleFocusPerson() {
+  viewerRef.value?.focusPerson?.()
+}
+
+function handleMovePerson() {
+  viewerRef.value?.movePerson?.()
+}
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <button type="button" @click="handleInitMonitorPoints">初始化监测点</button>
+    <button type="button" @click="handleReloadMonitorPoints">重新加载监测点</button>
+    <button type="button" @click="handleQueryMonitorPoints">查询监测点</button>
+    <button type="button" @click="handleFocusMonitorPoint">聚焦监测点</button>
+    <button type="button" @click="handleFocusPerson">聚焦人员</button>
+    <button type="button" @click="handleMovePerson">人员移动</button>
+    <LrMapViewer ref="viewerRef" :lr3d-config="lr3dConfig" />
+  </div>
+</template>
+```
+
+### 视角控制模块示例
+
+```vue
+<script setup>
+import { ref } from 'vue'
+import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
+
+const viewerRef = ref(null)
+const currentViewInfo = ref(null)
+
+function handleSwitchViewPoint() {
+  viewerRef.value?.switchToViewPoint?.('井口')
+}
+
+function handleCaptureViewInfo() {
+  currentViewInfo.value = viewerRef.value?.getCurrentViewInfo?.() ?? null
+}
+
+function handleRestoreViewInfo() {
+  if (currentViewInfo.value) {
+    viewerRef.value?.applyViewInfo?.(currentViewInfo.value)
+  }
+}
+</script>
+
+<template>
+  <div style="height: 100vh;">
+    <button type="button" @click="handleSwitchViewPoint">切换到井口视角</button>
+    <button type="button" @click="handleCaptureViewInfo">读取当前视口</button>
+    <button type="button" @click="handleRestoreViewInfo">按视角参数恢复</button>
+    <LrMapViewer ref="viewerRef" :lr3d-config="lr3dConfig" />
+  </div>
+</template>
+```
+
+### 范围选点模块示例
+
+如果你需要通过组件实例控制范围选点：
+
 ```vue
 <script setup>
 import { ref, watch } from 'vue'
@@ -395,27 +555,34 @@ import { LrMapViewer } from '@zhangdali1996/lr-map-viewer'
 
 const viewerRef = ref(null)
 
-function handleMoveView() {
-  viewerRef.value?.moveView?.(
-    // x 坐标（绝对坐标）
-    37515326.469929,
-    // y 坐标（绝对坐标）
-    4412734.214238,
-    // z 坐标（绝对坐标）
-    1311.15,
-  )
+function startRangeSelection() {
+  viewerRef.value?.startRangeSelection?.({
+    radius: 500,
+  })
+}
+
+function clearRangeSelection() {
+  viewerRef.value?.clearRangeSelection?.()
+}
+
+function focusFirstMonitorPoint() {
+  const result = viewerRef.value?.getRangeSelectionResult?.()
+  const firstMonitorPoint = result?.monitorPoints?.[0]
+
+  if (firstMonitorPoint) {
+    viewerRef.value?.focusMonitorPoint?.(firstMonitorPoint)
+  }
 }
 
 watch(
   viewerRef,
   (viewer) => {
-    if (!viewer?.registerModelInfoQuery) {
+    if (!viewer?.registerRangeSelectionChange) {
       return
     }
 
-    viewer.registerModelInfoQuery((payload) => {
-      // payload 为点击模型后返回的模型信息
-      console.log('model info', payload)
+    viewer.registerRangeSelectionChange((payload) => {
+      console.log('range selection', payload)
     })
   },
   { immediate: true },
@@ -424,7 +591,9 @@ watch(
 
 <template>
   <div style="height: 100vh;">
-    <button type="button" @click="handleMoveView">移动视角</button>
+    <button type="button" @click="startRangeSelection">开始范围选点</button>
+    <button type="button" @click="clearRangeSelection">清除范围</button>
+    <button type="button" @click="focusFirstMonitorPoint">定位首个测点</button>
     <LrMapViewer ref="viewerRef" :lr3d-config="lr3dConfig" />
   </div>
 </template>