控件与轨迹工具

Overview

继承 ol/control/OverviewMap。getOverviewMap / setCollapsed / getCollapsed / setMap 等基类方法可用。

鹰眼控件，默认复制主图底图。

import { Overview } from 'geoverse';
map.addControl(new Overview({ map, show: false }));

构造选项 OverviewOptions（继承 ol/control/OverviewMap 的 Options），新增：

字段	类型	默认	说明
map	Map	—	主地图（用于复制底图到鹰眼）
onlyBase	boolean	true	仅显示底图图层
show	boolean	false	初始是否展开

方法	说明
open() / close()	展开 / 收起鹰眼

底图切换后鹰眼的同步由 GMap.resetOverview() 负责（switchBase 内部已调用）。

cloneBaseLayers —— cloneBaseLayers(layers: BaseLayer[]) => BaseLayer[]，复制底图图层（鹰眼不能与主图共享图层实例）。

---

PathSimplifier

轨迹回放工具。轨迹线/起终点/轨迹点/动画通过线分层渲染（整体挂在 LayerGroup）；视图缩放时用 simplify-js 抽稀渲染节点；支持 animation（平滑，按长度推进）与 skip（按节点跳跃）两种播放模式。

import { PathSimplifier } from 'geoverse';

const track = new PathSimplifier({
  mapObj: map,
  path: [{ longitude: 118.1, latitude: 24.4, gnssTime: '12:00' } /* ... */],
  showTracePoint: true,
  tracePointsModePlay: 'animation',
});
track.setFitView(true);
track.on('move', (evt) => console.log(evt.data));
track.start();

构造选项 PathSimplifierOptions：

字段	类型	默认	说明
mapObj	GMap	—	地图实例
bubble	boolean	false	事件是否只取最上层要素
showTracePoint	boolean	false	是否显示轨迹点
tracePointsModePlay	'animation' | 'skip'	'animation'	播放模式
path	TrackNodeInfo[]	[]	轨迹点集合
options	TrackStyleOptions	—	样式参数

TrackNodeInfo：longitude / latitude（经纬度）、gnssTime、speed、mileage、status、direction 等业务字段（沿轨迹数据约定）。 TrackStyleOptions：carIcon? / startIcon? / endIcon?、speed?（animation 速度）、timeStep?（skip 步长秒）、arrowPixel?。

播放控制

方法	签名	说明
start	(moveIdx?: number)	开始播放（可指定起始节点索引）
stop / pause / resume	()	停止复位 / 暂停 / 继续
setFitView	(flag: boolean)	视野适配整条轨迹
getSpeed / setSpeed		速度读写
getSpeedUp / setSpeedUp		倍速读写
getPercentnum / setPercentnum		播放进度（0~1）

数据与样式

方法	签名	说明
getPaths / setPaths	() => TrackNodeInfo[] / (arr)	轨迹数据读写（setPaths 重建）
clearPaths	()	清空轨迹数据
nodeVisible / arrowVisible	(flag: boolean)	轨迹点 / 箭头显隐
labelVisible	(flag, style?)	时间标签显隐（基于 NameLayer 文字避让）
setTraceLineStyle / setPassLineStyle / setTraceNodeStyle	(opts)	轨迹线 / 通过线 / 节点样式
destroy	()	停止动画、清空数据、回收全部监听与图层组

事件

通过 on(type, cb) / once / un 订阅。type 取值：move、nodeClick、nodeMouseover、nodeMouseout、pathClick、pathMouseover、pathMouseout。回调收到 TrackEvent，载荷在 evt.data（move 事件的 data 为 TrackMoveInfo：index / status / position / lngLat / passNode / length）。

TrackEvent 继承 ol/events/Event，含 data: unknown 载荷。

---

NameLayer experimental

继承 GVectorLayer（→ ol/layer/Vector）。

文字避让标注图层（四方向碰撞避让）。

experimental

该实现保持原有避让算法行为（避让在密集场景仍有已知瑕疵），已修复监听泄漏；API 可能在后续版本调整。

import { NameLayer } from 'geoverse';
const labels = new NameLayer({
  map,
  pointsArr: [{ position: [118.18, 24.49], text: '厦门' }],
  zoom: 10,
});
map.addLayer(labels);

构造选项 NameLayerOptions：

字段	类型	默认	说明
map	GMap	必填	地图实例
pointsArr	NamePoint[]	[]	标注点（{ position, text }，position 为 WGS-84）
zoom	number	8	低于该层级不显示
styleOptions	Partial<NameLayerStyle>		标签样式
zIndex	number

NameLayerStyle：fillColor / strokeColor / textColor / fontCss / boxWidth（0 时按文字实测宽度）。

方法	签名	说明
setPoints	(points: NamePoint[])	更新标注点并重绘
drawText	()	重绘全部标签（带避让）
textVisibility	(text: string, visible: boolean)	控制指定标签显隐（跨重绘保持）
getObjectByText	(text) => TextComponent[]	按文字全匹配获取标签组合
listenMoveEnd	(flag: boolean)	开关 moveend 自动重绘

---

轨迹抽稀（纯算法）

距离 + 角度/垂距 + Douglas-Peucker + 平滑的组合抽稀，无副作用。

import { compressLine } from 'geoverse';
const result = compressLine(points, { thinTarget: 75, smoothTarget: 20 });

函数	签名	说明
compressLine	(points: TrackPoint[], options?: CompressLineOptions) => TrackPoint[] | undefined	主流程，满足抽稀率/平滑率目标返回带 iDel 标记的点集，否则 undefined
douglasPeucker	(points: TrackPoint[], threshold: number) => TrackPoint[]	DP 抽稀
perpendicularDistance	(start, center, end) => number	点到线垂距
pixelDistance	(a: TrackPoint, b: TrackPoint) => number	两像素点距离

TrackPoint：{ lon, lat, pixel: [number, number], iDel: number }（iDel：0 允许抽稀 / 1 保留 / -1 可删除）。 CompressLineOptions：lengthThreshold?(0.0007) / angleThreshold?(120) / verticalThreshold?(5) / dpThreshold?(300) / smoothAngle?(120) / smoothLength?(0.0005) / thinTarget?(75) / smoothTarget?(20)。