@vsleem-realsee-viewer/realsee-plugin 2.1.3 → 2.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.internal.md +373 -12
  2. package/dist/index.mjs +1991 -1993
  3. package/dist/index.umd.js +24 -24
  4. package/package.json +3 -3
package/README.internal.md CHANGED
@@ -6,6 +6,20 @@
6
6
 
7
7
  依赖@vsleem-realsee-viewer/shared（共享类）
8
8
 
9
+ ## 目录
10
+
11
+ - [1. Realsee全景组件](#1-realsee全景组件)
12
+ - [2. Viewer 视图组件](#2-viewer-视图组件)
13
+ - [3. Marker 标记组件](#3-marker-标记组件)
14
+ - [4. Map 小地图组件](#4-map-小地图组件)
15
+ - [5. 核心类说明](#5-核心类说明)
16
+ - [6. 枚举类型](#6-枚举类型)
17
+ - [7. 数据模型类型](#7-数据模型类型)
18
+ - [8. 配置常量](#8-配置常量)
19
+ - [9. 工具函数](#9-工具函数)
20
+ - [10. 导出的类型声明对象](#10-导出的类型声明对象)
21
+ - [11. 示例](#11-示例)
22
+
9
23
  ## 1.2 RealseeProps 参数说明
10
24
 
11
25
  | 参数名 | 类型 | 默认值 | 说明 |
@@ -185,14 +199,38 @@ type slot= {
185
199
  currentPointMarkers: TrackMarker[] | undefined;
186
200
  currentMarker: TrackMarker | undefined;
187
201
  }
202
+ ```
203
+
204
+ ### RealseeStore 方法说明
205
+
206
+ | 方法 | 类型签名 | 说明 |
207
+ | --------------------- | --------------------------------------------------------- | -------------------- |
208
+ | `reload` | `(searchInfo: SearchInfo) => Promise<void>` | 重新加载数据 |
209
+ | `fetchRecord` | `(patrolId: string) => Promise<TrackRecord \| undefined>` | 获取单条巡检记录 |
210
+ | `selectModel` | `(coordinate: Partial<Coordinate>) => void` | 选择模型坐标系 |
211
+ | `selectRecord` | `(record: Partial<TrackRecord>) => void` | 选择巡检记录 |
212
+ | `selectPoint` | `(point: Partial<TrackPoint>) => void` | 选择轨迹点 |
213
+ | `selectMarker` | `(marker?: Partial<TrackMarker>) => void` | 选择问题标记 |
214
+ | `setReferPoint` | `(current: TrackPoint, options: PanoOptions) => void` | 设置参考点 |
215
+ | `addMarker` | `(marker: TrackMarker) => void` | 添加问题标记 |
216
+ | `removeMarker` | `(marker: Partial<TrackMarker>) => void` | 移除问题标记 |
217
+ | `updateMarker` | `(marker: Partial<TrackMarker>) => void` | 更新问题标记 |
218
+ | `hasRecord` | `(id: string) => boolean` | 检查是否存在指定记录 |
219
+ | `getRecord` | `(id: string) => TrackRecord \| undefined` | 获取指定记录 |
220
+ | `addRecord` | `(id: string) => Promise<TrackRecord \| undefined>` | 添加新记录 |
221
+ | `batchAddRecords` | `(ids: string[]) => Promise<void>` | 批量添加巡检记录 |
222
+ | `removeRecord` | `(id: string) => boolean` | 移除记录 |
223
+ | `updateRecord` | `(record: TrackRecord) => Promise<void>` | 更新记录数据 |
224
+ | `findClosestBIMModel` | `() => Coordinate \| undefined` | 查找最近的BIM模型 |
188
225
 
189
226
  type mapSlot = slot & {
190
- state: Required<Partial<MapProps>>;
227
+ state: Required<Partial<MapProps>>;
191
228
  }
192
229
 
193
230
  type playbarSlot = slot & {
194
- state: Required<Partial<PlaybarProps>>;
231
+ state: Required<Partial<PlaybarProps>>;
195
232
  }
233
+
196
234
  ```
197
235
 
198
236
  # 2. Viewer 视图组件
@@ -212,8 +250,10 @@ type playbarSlot = slot & {
212
250
  | `loadingPh` | `boolean` | false | 是否加载占位图 |
213
251
 
214
252
  ```
253
+
215
254
  type ReadonlyViewerConfig = 'container' | 'panorama' | 'keyboard' | 'keyboardActions';
216
255
  type ViewerProps = Omit<ViewerConfig, ReadonlyViewerConfig>;
256
+
217
257
  ```
218
258
 
219
259
  ## 2.3 ViewerElement 实例对象
@@ -272,12 +312,14 @@ type ViewerProps = Omit<ViewerConfig, ReadonlyViewerConfig>;
272
312
  | `handlePathMarkerFn?` | `(marker: MarkerOptions) => MarkerOptions` | - | 处理路径标记 |
273
313
 
274
314
  ```
315
+
275
316
  type MarkerProps = MarkersPluginConfig & {
276
- onPointChange?: (e: events.SelectMarkerEvent) => Promise<any>;
277
- onMarkerChange?: (e: events.SelectMarkerEvent) => Promise<any>;
278
- handleViolationMarkerFn?: (marker: MarkerOptions) => MarkerOptions;
279
- handlePathMarkerFn?: (marker: MarkerOptions) => MarkerOptions;
317
+ onPointChange?: (e: events.SelectMarkerEvent) => Promise<any>;
318
+ onMarkerChange?: (e: events.SelectMarkerEvent) => Promise<any>;
319
+ handleViolationMarkerFn?: (marker: MarkerOptions) => MarkerOptions;
320
+ handlePathMarkerFn?: (marker: MarkerOptions) => MarkerOptions;
280
321
  };
322
+
281
323
  ```
282
324
 
283
325
  ## 2.6 MarkerElement 实例对象
@@ -289,8 +331,10 @@ type MarkerProps = MarkersPluginConfig & {
289
331
  | `...MarkersPlugin` | `...MarkersPlugin` | 请查看Marker默认配置 | 视图配置 |
290
332
 
291
333
  ```
334
+
292
335
  type MarkerElement = MarkersPlugin
293
- ```
336
+
337
+ ````
294
338
 
295
339
  # 3. Playbar 播放器组件
296
340
 
@@ -364,7 +408,7 @@ type slot= {
364
408
  currentMarker: TrackMarker | undefined;
365
409
  state: Required<Partial<PlaybarProps>>;
366
410
  }
367
- ```
411
+ ````
368
412
 
369
413
  # 4. Map 小地图组件
370
414
 
@@ -438,7 +482,323 @@ type slot= {
438
482
  }
439
483
  ```
440
484
 
441
- # 5. 导出的类型声明对象
485
+ # 5. 核心类说明
486
+
487
+ ## 5.1 TrackPoint 轨迹点类
488
+
489
+ 用于表示巡检轨迹中的单个点位。
490
+
491
+ ### 属性说明
492
+
493
+ | 属性 | 类型 | 说明 |
494
+ | ---------------- | ------------ | ---------------------- |
495
+ | `id` | `string` | 点ID |
496
+ | `img` | `string` | 全景图地址 |
497
+ | `patrolId` | `string` | 巡检记录ID |
498
+ | `coordinate` | `Coordinate` | 源坐标系 |
499
+ | `point` | `Point` | 在源坐标系上的坐标点 |
500
+ | `position` | `Point` | 在空间坐标系上的坐标点 |
501
+ | `placeholderImg` | `string` | 占位全景图 |
502
+ | `uxTime` | `string` | 创建时间 |
503
+ | `panorama` | `any` | 全景图地址（组件使用） |
504
+ | `color` | `string` | 轨迹颜色 |
505
+ | `index` | `number` | 点的下标 |
506
+ | `rawIndex` | `number` | 点的原始下标 |
507
+
508
+ ### 方法说明
509
+
510
+ | 方法 | 类型 | 说明 |
511
+ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
512
+ | `constructor` | `(options?: Partial<TrackPoint>) => TrackPoint` | 构造函数 |
513
+ | `parsedModel` | `(point: Partial<TrackPointModel>, coordinate: Coordinate, panoramaSize?: PanoramaSize, appSetting?: AppSetting) => Partial<TrackPoint>` | 解析轨迹点字段 |
514
+ | `toSphericalCoord` | `(p1: Point, p2: Point) => { d: number, yaw: number, pitch: number }` | 计算球面坐标位置 |
515
+ | `projection` | `(r1: TrackCoordinateRelation, r2: TrackCoordinateRelation) => Point \| undefined` | 坐标投影转换 |
516
+
517
+ ## 5.2 TrackMarker 问题标记类
518
+
519
+ 用于表示全景图中的问题标记点。
520
+
521
+ ### 属性说明
522
+
523
+ | 属性 | 类型 | 说明 |
524
+ | ------------------ | ------------ | -------------------- |
525
+ | `id` | `string` | 问题标记ID |
526
+ | `pointId` | `string` | 轨迹点ID |
527
+ | `patrolId` | `string` | 巡检记录ID |
528
+ | `coordinateId` | `number` | 原始源坐标系ID |
529
+ | `coordinate` | `Coordinate` | 源坐标系 |
530
+ | `point` | `Point` | 在源坐标系上的坐标点 |
531
+ | `relativePosition` | `string` | 原始坐标映射关系 |
532
+ | `perspective` | `Position` | 在球面的位置 |
533
+ | `photoTime` | `string` | 拍照时间 |
534
+ | `panorama` | `string` | 全景图 |
535
+ | `markerIcon` | `any` | 标记图标 |
536
+ | `markerType` | `string` | 标记类型 |
537
+ | `data` | `any` | 自定义数据 |
538
+
539
+ ### 方法说明
540
+
541
+ | 方法 | 类型 | 说明 |
542
+ | ------------- | ------------------------------------------------------------------------------------------ | ---------------- |
543
+ | `constructor` | `(options?: Partial<TrackMarker>) => TrackMarker` | 构造函数 |
544
+ | `parsedModel` | `(marker: Partial<TrackMarkerModel>, coordinateTree?: Coordinate) => Partial<TrackMarker>` | 解析问题标记字段 |
545
+ | `projection` | `(dstCoordinate: Coordinate) => TrackMarker \| undefined` | 坐标投影转换 |
546
+
547
+ ## 5.3 TrackRecord 巡检记录类
548
+
549
+ 用于表示一条完整的巡检记录。
550
+
551
+ ### 属性说明
552
+
553
+ | 属性 | 类型 | 说明 |
554
+ | ------------------ | -------------------------- | ---------------- |
555
+ | `id` | `string` | 记录唯一标识 |
556
+ | `coordinateId` | `number` | 原始源坐标系ID |
557
+ | `coordinate` | `Coordinate` | 轨迹点坐标系 |
558
+ | `trackPoints` | `Map<string, TrackPoint>` | 轨迹点集合 |
559
+ | `trackMarkers` | `Map<string, TrackMarker>` | 标记点集合 |
560
+ | `relativePosition` | `string` | 原始坐标映射关系 |
561
+ | `projectId` | `number` | 关联的项目ID |
562
+ | `createTime` | `number` | 创建时间戳 |
563
+ | `color` | `string` | 显示颜色 |
564
+ | `type` | `number` | 记录类型 |
565
+ | `panoramaSize` | `PanoramaSize` | 全景图尺寸信息 |
566
+ | `realseeSetting` | `RealseeSetting` | 全景设置 |
567
+ | `data` | `any` | 第三方附加数据 |
568
+
569
+ ### 方法说明
570
+
571
+ | 方法 | 类型 | 说明 |
572
+ | ------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------- |
573
+ | `constructor` | `(options?: Partial<TrackRecord>) => TrackRecord` | 构造函数 |
574
+ | `parsedModel` | `(record: TrackRecordModel, coordinateTree?: Coordinate, appSetting?: AppSetting) => Promise<Partial<TrackRecord>>` | 解析原始记录数据 |
575
+
576
+ ---
577
+
578
+ # 6. 枚举类型
579
+
580
+ ## 6.1 TrackRecordTypeEnum 巡检记录类型
581
+
582
+ | 值 | 说明 |
583
+ | --------------- | -------------- |
584
+ | `Manual` | 手动巡检 (0) |
585
+ | `Intelligent` | 智能巡检 (1) |
586
+ | `RTK` | RTK (2) |
587
+ | `RealTimeTrack` | 实时轨迹 (3) |
588
+ | `Drone` | 无人机巡检 (4) |
589
+
590
+ ## 6.2 PointTypeEnum 路径点展示模式
591
+
592
+ | 值 | 说明 |
593
+ | ---------- | -------- |
594
+ | `NUMBER` | 点位模式 |
595
+ | `DISTANCE` | 距离模式 |
596
+
597
+ ## 6.3 MarkerTypeEnum 标记类型
598
+
599
+ | 值 | 说明 |
600
+ | ----- | -------- |
601
+ | `pin` | 方向标记 |
602
+
603
+ ## 6.4 DirectionMoveEnum 移动方向
604
+
605
+ | 值 | 说明 |
606
+ | ------------ | --------- |
607
+ | `Forward` | 前进 (1) |
608
+ | `Stationary` | 静止 (0) |
609
+ | `Backward` | 后退 (-1) |
610
+
611
+ ## 6.5 ViewModeEnum 视图预览模式
612
+
613
+ | 值 | 说明 |
614
+ | ------------ | ---------------------------------------------------------- |
615
+ | `Auto` | 自由播放视角（不做任何限定） |
616
+ | `FollowRoad` | 播放视角跟随轨迹自动调整 |
617
+ | `FollowView` | 播放视角跟随每帧的主视角（再现巡检过程中巡检人员的主视角） |
618
+
619
+ ---
620
+
621
+ # 7. 数据模型类型
622
+
623
+ ## 7.1 TrackPointModel 轨迹点模型
624
+
625
+ | 属性 | 类型 | 说明 |
626
+ | ------------ | -------- | ------------------------------- |
627
+ | `id` | `string` | 唯一标识ID |
628
+ | `img` | `string` | 全景图地址 |
629
+ | `patroIndex` | `string` | 算法点下标 |
630
+ | `patrolId` | `string` | 巡检记录ID |
631
+ | `uxTime` | `string` | 格式化时间(YYYY-MM-DD HH:mm:ss) |
632
+ | `color` | `string` | 颜色 |
633
+ | `p` | `string` | 点位偏移量 |
634
+ | `alt` | `string` | 海拔 |
635
+ | `lat` | `string` | 纬度 |
636
+ | `lon` | `string` | 经度 |
637
+ | `x` | `string` | 在源坐标系的X坐标 |
638
+ | `y` | `string` | 在源坐标系的Y坐标 |
639
+ | `z` | `string` | 在源坐标系的Z坐标 |
640
+ | `data` | `any` | 自定义数据 |
641
+
642
+ ## 7.2 TrackMarkerModel 问题标记模型
643
+
644
+ | 属性 | 类型 | 说明 |
645
+ | ------------------ | -------- | ------------------ |
646
+ | `id` | `string` | 问题ID |
647
+ | `pointId` | `string` | 轨迹点ID |
648
+ | `coordinateId` | `number` | 源坐标系ID |
649
+ | `patrolId` | `string` | 巡检记录ID |
650
+ | `point` | `string` | 在源坐标系的坐标点 |
651
+ | `relativePosition` | `string` | 坐标映射关系 |
652
+ | `perspective` | `string` | 在球面的位置 |
653
+ | `photoTime` | `string` | 拍照时间 |
654
+ | `panorama` | `string` | 全景图 |
655
+ | `markerIcon` | `any` | 标记图标 |
656
+ | `markerType` | `string` | 标记类型 |
657
+ | `data` | `any` | 自定义数据 |
658
+
659
+ ## 7.3 TrackRecordModel 巡检记录模型
660
+
661
+ | 属性 | 类型 | 说明 |
662
+ | ------------------ | -------------------- | ---------------- |
663
+ | `id` | `string` | 巡检ID |
664
+ | `coordinateId` | `number` | 源坐标系ID |
665
+ | `relativePosition` | `string` | 坐标映射关系 |
666
+ | `trackList` | `TrackPointModel[]` | 源坐标系轨迹列表 |
667
+ | `markerList` | `TrackMarkerModel[]` | 问题标记列表 |
668
+ | `projectId` | `number` | 项目ID |
669
+ | `createTime` | `number` | 创建日期 |
670
+ | `type` | `number` | 巡检记录类型 |
671
+ | `color` | `string` | 颜色 |
672
+ | `realseeSetting` | `string` | 全景设置 |
673
+ | `data` | `any` | 自定义数据 |
674
+
675
+ ## 7.4 TrackCoordinateRelation 坐标系关系
676
+
677
+ | 属性 | 类型 | 说明 |
678
+ | --------------------- | ------------- | ------------ |
679
+ | `srcToDstRelativeMap` | `RelativeMap` | 源到目标映射 |
680
+ | `srcCoordinate` | `Coordinate` | 源坐标系 |
681
+ | `dstCoordinate` | `Coordinate` | 目标坐标系 |
682
+
683
+ ---
684
+
685
+ # 8. 配置常量
686
+
687
+ ## 8.1 APP_SETTING 全局默认配置
688
+
689
+ ```typescript
690
+ {
691
+ baseUrl: 'https://vsleem.com/api',
692
+ authorizeCode: '',
693
+ obsType: 'hs'
694
+ }
695
+ ```
696
+
697
+ ## 8.2 REALSEE_SETTING 全景默认设置
698
+
699
+ ```typescript
700
+ {
701
+ pointLax: 0, // 轨迹点稀疏距离（毫米单位）
702
+ pointType: 0, // 路径点展示模式 0=点位模式，1=距离模式
703
+ pointNumber: 5, // 路径展示前后多少个点
704
+ pointDistance: 5000, // 路径展示距离范围内的点（毫米单位）
705
+ preloadStep: 5, // 预加载步长
706
+ trackColorRange: [ // 轨迹颜色范围
707
+ '#3CDE99', '#DE3CB9', '#683CDE', '#3CA0DE',
708
+ '#D8DE3C', '#DEA03C', '#DE3C3C'
709
+ ],
710
+ pathPin: pinIcon, // 路径图钉图标
711
+ pathRedPin: redPinIcon // 红色路径图钉图标
712
+ }
713
+ ```
714
+
715
+ ## 8.3 VIEWER_CONFIG 视图默认配置
716
+
717
+ ```typescript
718
+ {
719
+ viewMode: 1, // 视图预览模式
720
+ navbar: false, // 是否显示导航栏
721
+ defaultYaw: 0, // 默认偏航角
722
+ defaultPitch: 0, // 默认俯仰角
723
+ defaultZoomLvl: 30, // 默认缩放级别
724
+ defaultTransition: { speed: 900, rotation: true },
725
+ moveInertia: false, // 是否启用移动惯性
726
+ moveThresh: 0, // 移动旋转阈值
727
+ minFov: 20, // 最小视野角度
728
+ maxFov: 120, // 最大视野角度
729
+ loadingImg: '', // 加载图片
730
+ loadingTxt: 'Loading...',
731
+ size: { width: '100%', height: '100%' }
732
+ }
733
+ ```
734
+
735
+ ## 8.4 MAP_CONFIG 小地图默认配置
736
+
737
+ 包含小地图的样式、尺寸、位置等默认配置。
738
+
739
+ ## 8.5 MAP_GEO_OPTIONS 地理地图选项
740
+
741
+ ```typescript
742
+ {
743
+ center: [31.3016935, 120.5810725], // 地图初始化经纬度
744
+ zoom: 17, // 地图初始化缩放等级
745
+ attributionControl: true, // 是否显示版权控件
746
+ zoomControl: false // 是否显示缩放控件
747
+ }
748
+ ```
749
+
750
+ ## 8.6 TILE_LAYERS 地图瓦片图层配置
751
+
752
+ 默认天地图瓦片图层配置，包含矢量底图和标注图层。
753
+
754
+ ## 8.7 TRACK_COLOR_LIST 轨迹颜色列表
755
+
756
+ 预定义的7种轨迹颜色。
757
+
758
+ ---
759
+
760
+ # 9. 工具函数
761
+
762
+ ## 9.1 panoramaCrop 全景图切片
763
+
764
+ 用于对全景图进行切片处理，支持华为云、阿里云、火山引擎等对象存储服务。
765
+
766
+ | 参数 | 类型 | 说明 |
767
+ | -------------- | -------------- | ------------ |
768
+ | `url` | `string` | 全景图片地址 |
769
+ | `panoramaSize` | `PanoramaSize` | 全景图的尺寸 |
770
+ | `appSetting` | `AppSetting` | App配置 |
771
+
772
+ **返回值**: `{ width: number, cols: number, rows: number, baseUrl: string, tileUrl: (col: number, row: number) => string }`
773
+
774
+ ## 9.2 RadarMarker 雷达标记
775
+
776
+ 用于在地图上显示雷达扫描效果的标记类。
777
+
778
+ | 属性 | 类型 | 默认值 | 说明 |
779
+ | ----------- | ---------- | ---------------------- | ------------------------- |
780
+ | `latLng` | `L.LatLng` | - | 经纬度 |
781
+ | `radius` | `number` | 30 | 半径（米） |
782
+ | `color` | `string` | '#108ee9' | CSS颜色值 |
783
+ | `hFov` | `number` | 90 | 扇形水平视野角（0-360度） |
784
+ | `angle` | `number` | 0 | 方向角度（0-360度） |
785
+ | `className` | `string` | 'leaflet-radar-marker' | 自定义CSS类名 |
786
+
787
+ ## 9.3 useResizeObserver 尺寸观察
788
+
789
+ 用于监听元素尺寸变化的 Vue 组合式函数。
790
+
791
+ | 参数 | 类型 | 说明 |
792
+ | ---------- | -------------------------------------------- | -------- |
793
+ | `target` | `MaybeRef<HTMLElement \| null \| undefined>` | 目标元素 |
794
+ | `callback` | `(entries: ResizeObserverEntry[]) => void` | 回调函数 |
795
+ | `options` | `UseResizeObserverOptions` | 选项 |
796
+
797
+ **返回值**: `{ width: Ref<number>, height: Ref<number>, stop: () => void }`
798
+
799
+ ---
800
+
801
+ # 10. 导出的类型声明对象
442
802
 
443
803
  ```js
444
804
  import '@photo-sphere-viewer/core/index.css';
@@ -459,6 +819,7 @@ export type {
459
819
  TrackMarkerModel /** 轨迹标记模型 */,
460
820
  TrackPointModel /** 轨迹点模型 */,
461
821
  TrackRecordModel /** 轨迹记录模型 */,
822
+ TrackCoordinateRelation /** 坐标系关系 */,
462
823
  } from '@vsleem-realsee-viewer/realsee-plugin';
463
824
 
464
825
  /** 配置相关类型导出 */
@@ -523,17 +884,17 @@ export {
523
884
 
524
885
  ```
525
886
 
526
- # 6. 示例
887
+ # 11. 示例
527
888
 
528
889
  通过以下方式来注册组件
529
890
 
530
- ## 6.1 安装
891
+ ## 11.1 安装
531
892
 
532
893
  `npm install @vsleem-realsee-viewer/realsee-plugin @vsleem-realsee-viewer/shared`
533
894
 
534
895
  `pnpm add @vsleem-realsee-viewer/realsee-plugin @vsleem-realsee-viewer/shared`
535
896
 
536
- ## 6.2 例子
897
+ ## 11.2 例子
537
898
 
538
899
  `vsleem-realsee-demo仓库下的views/realsee`
539
900