@bitalltech-maplibre/core 1.0.2 → 1.0.3

package/dist/types/effects/low-altitude/shared.d.ts

@@ -0,0 +1,67 @@
+import { type Map, type CanvasSourceSpecification, type CircleLayerSpecification, type FillLayerSpecification, type LineLayerSpecification, type RasterLayerSpecification, type SymbolLayerSpecification } from "maplibre-gl";
+import type { LngLatTuple } from "../geometry";
+export type EffectFeatureCollection = GeoJSON.FeatureCollection<GeoJSON.Geometry, GeoJSON.GeoJsonProperties>;
+export type EffectLayerSpecification = (Omit<FillLayerSpecification, "id" | "source"> & {
+    id: string;
+    type: "fill";
+}) | (Omit<LineLayerSpecification, "id" | "source"> & {
+    id: string;
+    type: "line";
+}) | (Omit<CircleLayerSpecification, "id" | "source"> & {
+    id: string;
+    type: "circle";
+}) | (Omit<SymbolLayerSpecification, "id" | "source"> & {
+    id: string;
+    type: "symbol";
+}) | (Omit<RasterLayerSpecification, "id" | "source"> & {
+    id: string;
+    type: "raster";
+});
+/** Canvas 渐变这类非 GeoJSON 渲染需要额外挂载的 source。 */
+export interface EffectCanvasSource {
+    id: string;
+    source: CanvasSourceSpecification;
+}
+export interface BaseEffectOptions {
+    /** 特效 id；会派生出 sourceId 和多个 layerId。 */
+    id: string;
+    /** 特效中心点，经纬度。 */
+    center: LngLatTuple;
+    /** 插入到指定图层之前。 */
+    beforeId?: string;
+    /** 初始是否可见，默认可见。 */
+    visible?: boolean;
+}
+/** 每种特效渲染函数的输出：GeoJSON 数据、图层配置和可选动画启动器。 */
+export interface EffectRenderResult<Options> {
+    data: EffectFeatureCollection;
+    layers: EffectLayerSpecification[];
+    canvasSources?: EffectCanvasSource[];
+    startAnimation?: (context: EffectAnimationContext<Options>) => (() => void) | void;
+}
+export interface EffectAnimationContext<Options> {
+    /** 获取最新 options，动画过程中 update 后会立即读取到新配置。 */
+    getOptions: () => Options;
+    /** 写回 GeoJSON source 数据，动画每帧只需要替换特效数据。 */
+    setData: (data: EffectFeatureCollection) => void;
+}
+/** addXxxEffect 返回的控制器，用于更新、显隐和移除特效。 */
+export interface MapEffectController<Options> {
+    /** 特效 id。 */
+    id: string;
+    /** 更新特效配置。内部会重建 source/layer 或刷新动画数据。 */
+    update: (options: Partial<Omit<Options, "id">>) => void;
+    /** 显示全部相关图层，不重新创建 source。 */
+    show: () => void;
+    /** 隐藏全部相关图层，source 数据仍保留。 */
+    hide: () => void;
+    /** 移除图层、source 和动画。调用后控制器不可再恢复。 */
+    remove: () => void;
+}
+export declare const createFeature: <Geometry extends GeoJSON.Geometry>(geometry: Geometry, properties: GeoJSON.GeoJsonProperties) => GeoJSON.Feature<Geometry>;
+export declare const createFeatureCollection: (features: GeoJSON.Feature[]) => EffectFeatureCollection;
+export declare const removeLayerIfExists: (map: Map, id: string) => void;
+export declare const removeSourceIfExists: (map: Map, id: string) => void;
+export declare const setLayersVisibility: (map: Map, layerIds: string[], visible: boolean) => void;
+export declare const isStyleNotReadyError: (error: unknown) => boolean;
+export declare const createManagedEffect: <Options extends BaseEffectOptions>(map: Map, initialOptions: Options, renderEffect: (options: Options) => EffectRenderResult<Options>) => MapEffectController<Options>;

package/dist/types/effects/low-altitude/target-lock.d.ts

@@ -0,0 +1,4 @@
+import { type Map } from "maplibre-gl";
+import type { MapEffectController } from "./shared";
+import type { TargetLockOptions } from "./types";
+export declare const addTargetLock: (map: Map, initialOptions: TargetLockOptions) => MapEffectController<TargetLockOptions>;

package/dist/types/effects/low-altitude/types.d.ts

@@ -0,0 +1,333 @@
+import type { LngLatTuple } from "../geometry";
+import type { BaseEffectOptions } from "./shared";
+/** 单点扩散脉冲：适合告警点、事件点、目标点高亮。 */
+export interface PulseMarkerOptions extends BaseEffectOptions {
+    /** 中心实心区域半径，单位米。 */
+    radius?: number;
+    /** 脉冲最大扩散半径，单位米。 */
+    maxRadius?: number;
+    /** 主颜色。 */
+    color?: string;
+    /** 中心填充色，默认跟随 color。 */
+    fillColor?: string;
+    /** 中心填充透明度。 */
+    fillOpacity?: number;
+    /** 脉冲环透明度。 */
+    pulseOpacity?: number;
+    /** 脉冲环线宽。 */
+    lineWidth?: number;
+    /** 同时存在的脉冲环数量。 */
+    pulseCount?: number;
+    /** 一轮扩散动画时长，单位毫秒。 */
+    duration?: number;
+}
+/** 多环脉冲：比普通脉冲更强调中心和外扩环。 */
+export interface RingPulseMarkerOptions extends BaseEffectOptions {
+    /** 核心半径，单位米。 */
+    radius?: number;
+    /** 外环最大半径，单位米。 */
+    maxRadius?: number;
+    /** 外扩环数量。 */
+    ringCount?: number;
+    /** 主颜色。 */
+    color?: string;
+    /** 核心填充色。 */
+    fillColor?: string;
+    /** 核心填充透明度。设为 0 可隐藏填充。 */
+    fillOpacity?: number;
+    /** 核心描边线及外扩同心环的线透明度。 */
+    lineOpacity?: number;
+    /** 环线宽度。 */
+    lineWidth?: number;
+    /** 一轮动画时长，单位毫秒。 */
+    duration?: number;
+    /** 核心呼吸缩放幅度。 */
+    pulseScale?: number;
+}
+/** 呼吸圆：适合叠在图标、设备点或目标点后面做柔和背景高亮。 */
+export interface BreathingCircleOptions extends BaseEffectOptions {
+    /** 基础半径，单位米。 */
+    radius?: number;
+    /** 呼吸最小半径，单位米；不传时根据 radius 自动计算。 */
+    minRadius?: number;
+    /** 呼吸最大半径，单位米；不传时根据 radius 自动计算。 */
+    maxRadius?: number;
+    /** 主颜色。 */
+    color?: string;
+    /** 填充色，默认跟随 color。 */
+    fillColor?: string;
+    /** 最亮时填充透明度。 */
+    fillOpacity?: number;
+    /** 最暗时填充透明度。 */
+    minFillOpacity?: number;
+    /** 描边颜色，默认跟随 color。 */
+    strokeColor?: string;
+    /** 最亮时描边透明度。 */
+    strokeOpacity?: number;
+    /** 最暗时描边透明度。 */
+    minStrokeOpacity?: number;
+    /** 描边宽度，单位像素。设为 0 可隐藏描边。 */
+    strokeWidth?: number;
+    /** 一轮呼吸动画时长，单位毫秒。 */
+    duration?: number;
+}
+/** 扇形扫描渐变配置。colors 在扇形扫描效果中会从圆心沿半径方向过渡到外缘。在雷达扫描中，centerOpacity 会从圆心开始，edgeOpacity 会从外缘开始。 */
+export interface SectorScanGradientOptions {
+    colors?: string[];
+    opacity?: number;
+    /** 圆心附近透明度；不传时使用基础透明度的 25%。 */
+    centerOpacity?: number;
+    /** 外缘透明度；不传时使用基础透明度。 */
+    edgeOpacity?: number;
+}
+/** 扇形扫描：给定起止角度，可选旋转速度和分段渐变。 */
+export interface SectorScanOptions extends BaseEffectOptions {
+    /** 扇形半径，单位米。 */
+    radius: number;
+    /** 起始方位角，0 表示正北，顺时针增加。 */
+    startAngle: number;
+    /** 结束方位角，0 表示正北，顺时针增加。 */
+    endAngle: number;
+    /** 纯色填充颜色；未传 gradient.colors 时使用。 */
+    color?: string;
+    /** 纯色填充透明度，或渐变默认透明度。 */
+    opacity?: number;
+    /** 径向渐变配置；colors 至少两个颜色时启用 Canvas 渐变。 */
+    gradient?: SectorScanGradientOptions;
+    /** 扇形两条边线颜色。 */
+    outlineColor?: string;
+    /** 扇形边线透明度。 */
+    outlineOpacity?: number;
+    /** 扇形边线宽度。 */
+    outlineWidth?: number;
+    /** 旋转速度，单位度/秒；不传或为 0 时静止。 */
+    rotationSpeed?: number;
+}
+/** 定向脉冲：一组沿指定方向推进的弧线。 */
+export interface DirectionalPulseOptions extends BaseEffectOptions {
+    /** 最大脉冲半径，单位米。 */
+    radius: number;
+    /** 中心方向角，0 表示正北。 */
+    direction?: number;
+    /** 扇形展开角度。 */
+    spread?: number;
+    /** 主颜色。 */
+    color?: string;
+    /** 线透明度。 */
+    opacity?: number;
+    /** 线宽。 */
+    lineWidth?: number;
+    /** 同屏弧线数量。 */
+    lineCount?: number;
+    /** 弧线间距，单位米。 */
+    lineSpacing?: number;
+    /** 推进速度，单位米/秒；不传时静止。 */
+    speed?: number;
+    /** 内侧起始半径，单位米。 */
+    innerRadius?: number;
+}
+/** 雷达扫描：距离环、十字线、距离文字和旋转扫描尾迹。 */
+export interface RadarSweepOptions extends BaseEffectOptions {
+    /** 雷达半径，单位米。 */
+    radius: number;
+    /** 扫描主色。 */
+    color?: string;
+    /** 扫描面默认透明度。 */
+    opacity?: number;
+    /** 单个扫描扇形角度。 */
+    sweepAngle?: number;
+    /** 初始扫描起始角度。 */
+    sweepStartAngle?: number;
+    /** 旋转速度，单位度/秒。 */
+    rotationSpeed?: number;
+    /** 距离环数量。 */
+    ringCount?: number;
+    /** 距离环颜色。 */
+    ringColor?: string;
+    /** 距离环透明度。 */
+    ringOpacity?: number;
+    /** 距离环线宽。 */
+    ringWidth?: number;
+    /** 尾部透明度（渐变模式控制扫描起始边透明度）。 */
+    tailOpacity?: number;
+    /** 头部透明度（渐变模式控制扫描结束边透明度）。 */
+    headOpacity?: number;
+    /** 是否显示十字线。 */
+    showCrosshair?: boolean;
+    /** 十字线颜色。 */
+    crosshairColor?: string;
+    /** 十字线透明度。 */
+    crosshairOpacity?: number;
+    /** 十字线宽度。 */
+    crosshairWidth?: number;
+    /** 中心核心半径，单位米。 */
+    coreRadius?: number;
+    /** 中心核心颜色。 */
+    coreColor?: string;
+    /** 是否显示距离文字。 */
+    showDistanceLabels?: boolean;
+    /** 距离文字颜色。 */
+    distanceLabelColor?: string;
+    /** 距离文字 halo 颜色。 */
+    distanceLabelHaloColor?: string;
+    /** 距离文字透明度。 */
+    distanceLabelOpacity?: number;
+    /** 距离文字字号。 */
+    distanceLabelSize?: number;
+    /** 自定义距离文字格式化。 */
+    distanceLabelFormatter?: (distance: number, index: number) => string;
+    /** 径向渐变配置；colors 至少两个颜色时启用 Canvas 渐变渲染扫描区域。 */
+    gradient?: SectorScanGradientOptions;
+}
+/** 防御圆：静态地理圆，内部淡色填充经径向渐变过渡到边缘光晕，最外层叠加实心边框线，适合标识设备覆盖范围或防御区域。 */
+export interface DefenceCircleOptions extends BaseEffectOptions {
+    /** 防御半径，单位米。 */
+    radius: number;
+    /** 主颜色。fillColor 和 borderColor 不传时默认跟随此值。 */
+    color?: string;
+    /** 内部填充色，不传时跟随 color。 */
+    fillColor?: string;
+    /** 内部填充透明度（渐变起始值）。 */
+    fillOpacity?: number;
+    /** 边框颜色，不传时跟随 color。 */
+    borderColor?: string;
+    /** 边框线宽，单位像素。 */
+    borderWidth?: number;
+    /** 边框线透明度（最外层实心边框）。 */
+    borderOpacity?: number;
+}
+/** 目标锁定：固定像素尺寸的四角锁定框和中心准星，适合跟随移动目标。 */
+export interface TargetLockOptions extends BaseEffectOptions {
+    /** 锁定框颜色。 */
+    color?: string;
+    /** 锁定框尺寸，单位像素。 */
+    size?: number;
+    /** 线宽，单位像素。 */
+    lineWidth?: number;
+    /** 四角线段长度，单位像素。 */
+    cornerLength?: number;
+    /** 是否显示中心准星，默认 true。 */
+    showCrosshair?: boolean;
+    /** 中心准星单侧长度，单位像素。 */
+    crosshairLength?: number;
+    /** 准星与中心点之间的留白，单位像素。 */
+    crosshairGap?: number;
+    /** 是否旋转锁定框，默认 true。 */
+    rotate?: boolean;
+    /** 旋转一周时长，单位毫秒。 */
+    rotationDuration?: number;
+    /** 整体透明度。 */
+    opacity?: number;
+}
+/** 定向反制光束：由设备指向目标的收窄能量通道、粒子流和目标震荡环。 */
+export interface CountermeasureBeamOptions extends BaseEffectOptions {
+    /** 反制目标经纬度。 */
+    target: LngLatTuple;
+    /** 反制模式。驱离时震荡环向外扩散，迫降时向目标收缩。 */
+    mode?: "expulsion" | "forcedLanding";
+    /** 主颜色。 */
+    color?: string;
+    /** 能量通道填充颜色，默认跟随 color。 */
+    channelColor?: string;
+    /** 能量通道透明度。 */
+    channelOpacity?: number;
+    /** 设备端通道宽度，单位米。 */
+    sourceWidth?: number;
+    /** 目标端通道宽度，单位米。 */
+    targetWidth?: number;
+    /** 中心束线颜色，默认使用偏亮的紫红色。 */
+    lineColor?: string;
+    /** 中心束线宽度，单位像素。 */
+    lineWidth?: number;
+    /** 中心束线透明度。 */
+    lineOpacity?: number;
+    /** 推进粒子颜色，默认跟随 lineColor。 */
+    particleColor?: string;
+    /** 同时显示的推进粒子数量；设为 0 可关闭。 */
+    particleCount?: number;
+    /** 粒子基础半径，单位像素。 */
+    particleRadius?: number;
+    /** 粒子从设备移动到目标所需时间，单位毫秒。 */
+    particleDuration?: number;
+    /** 是否显示目标端震荡环。 */
+    targetRipple?: boolean;
+    /** 目标端震荡环最大半径，单位米。 */
+    targetRippleRadius?: number;
+    /** 同时显示的震荡环数量。 */
+    targetRippleCount?: number;
+    /** 单轮震荡时长，单位毫秒。 */
+    targetRippleDuration?: number;
+    /** 震荡环线宽，单位像素。 */
+    targetRippleWidth?: number;
+}
+export type CoordinationLinkType = "detection" | "command" | "countermeasure";
+export interface CoordinationLink {
+    /** 链路起点。 */
+    from: LngLatTuple;
+    /** 链路终点。 */
+    to: LngLatTuple;
+    /** 探测、指挥或反制链路。 */
+    type: CoordinationLinkType;
+    /** 覆盖该链路的默认颜色。 */
+    color?: string;
+}
+/** 多设备协同反制：展示探测、指挥和反制链路及其数据流向。 */
+export interface CoordinatedCountermeasureOptions extends BaseEffectOptions {
+    /** 协同链路集合。center 表示当前处置目标位置。 */
+    links: CoordinationLink[];
+    /** 链路线宽，单位像素。 */
+    lineWidth?: number;
+    /** 链路透明度。 */
+    lineOpacity?: number;
+    /** 每条链路同时显示的流动粒子数量。 */
+    particleCount?: number;
+    /** 流动粒子半径，单位像素。 */
+    particleRadius?: number;
+    /** 粒子走完整条链路的时长，单位毫秒。 */
+    particleDuration?: number;
+    /** 是否显示链路端点。 */
+    showNodes?: boolean;
+    /** 链路端点半径，单位像素。 */
+    nodeRadius?: number;
+    /** 是否显示目标协同状态环。 */
+    targetRipple?: boolean;
+    /** 目标状态环最大半径，单位米。 */
+    targetRippleRadius?: number;
+    /** 目标状态环动画时长，单位毫秒。 */
+    targetRippleDuration?: number;
+}
+/** 导航诱骗：展示目标真实位置到诱导位置的偏移关系和诱导流向。 */
+export interface NavigationSpoofingOptions extends BaseEffectOptions {
+    /** 后端或业务算法给出的诱导位置。center 表示目标真实位置。 */
+    spoofedPosition: LngLatTuple;
+    /** 主颜色。 */
+    color?: string;
+    /** 偏移虚线颜色，默认跟随 color。 */
+    lineColor?: string;
+    /** 偏移虚线宽度，单位像素。 */
+    lineWidth?: number;
+    /** 偏移虚线透明度。 */
+    lineOpacity?: number;
+    /** 诱导方向流动粒子数量。 */
+    particleCount?: number;
+    /** 粒子半径，单位像素。 */
+    particleRadius?: number;
+    /** 粒子从真实位置移动到诱导位置的时长，单位毫秒。 */
+    particleDuration?: number;
+    /** 是否显示真实位置点。 */
+    showTruePosition?: boolean;
+    /** 是否显示诱导位置虚影。 */
+    showSpoofedPosition?: boolean;
+    /** 诱导位置虚影半径，单位像素。 */
+    ghostRadius?: number;
+    /** 诱导位置虚影透明度。 */
+    ghostOpacity?: number;
+    /** 是否显示诱导位置脉冲环。 */
+    ripple?: boolean;
+    /** 诱导位置脉冲环最大半径，单位米。 */
+    rippleRadius?: number;
+    /** 同时显示的脉冲环数量。 */
+    rippleCount?: number;
+    /** 单轮脉冲动画时长，单位毫秒。 */
+    rippleDuration?: number;
+}

package/dist/types/effects/low-altitude/visual.d.ts

@@ -0,0 +1,15 @@
+export type RgbColor = [number, number, number];
+export declare const clamp: (value: number, min: number, max: number) => number;
+export declare const parseColor: (color: string) => RgbColor | undefined;
+export declare const normalizeCanvasAngle: (angle: number) => number;
+/** Canvas arc 使用数学角度，这里把方位角转换成顺时针扫过角度。 */
+export declare const getClockwiseSweep: (startAngle: number, endAngle: number) => number;
+export declare const getCanvasArcAngle: (bearing: number) => number;
+/** 将 #hex/rgb 颜色和透明度合成 rgba；解析不了时原样返回。 */
+export declare const toRgbaColor: (color: string, opacity: number) => string;
+/** 二次缓出函数，让颜色过渡前快后慢更自然。 */
+export declare const easeOutQuad: (t: number) => number;
+/** 在两个 rgb 颜色之间线性插值。 */
+export declare const lerpRgb: (a: RgbColor, b: RgbColor, t: number) => RgbColor;
+/** 在颜色数组中按浮点索引做纯色插值，返回 "rgb(r,g,b)" 格式。 */
+export declare const lerpColorArray: (colors: string[], t: number) => string;