@ray-js/robot-map-sdk 0.0.17-beta.1 → 0.0.17-beta.3

package/dist/constant/methods.js

@@ -1 +1 @@
-const e=["areRoomsAdjacent","getForbiddenSweepZones","getForbiddenMopZones","getCleanZones","getVirtualWalls","getThresholds","getSpots","getRoomAnchors","getWayPoints","getViewportCenterPoint","getMapCenterPoint","getWallPointsByViewportCenter","getForbiddenSweepZonePointsByViewportCenter","getForbiddenMopZonePointsByViewportCenter","getCleanZonePointsByViewportCenter","getSpotPointByViewportCenter","getEffectiveDividerPoints","getDividerEndPoints","isNearChargerOrRobot","isPointInAnyRoom","isWallIntersectsAnyRoom","isZoneIntersectsAnyRoom","resetPanZoom","snapshot","snapshotByData","getCustomCarpets","forceEndGesture","getFurniturePointsByViewportCenter","getCustomCarpetPointsByViewportCenter","getRectPointsByCenter","getFurnitures","drawCustomZones","getCustomZones","clearCustomZones","setEditingCustomZones"],o=["onMapFirstDrawed","onMapDrawed","onPathDrawed","onRoomPropertiesDrawed","onRoomsDrawed","onClickRoom","onClickRoomProperties","onRemoveForbiddenSweepZone","onRemoveForbiddenMopZone","onRemoveCleanZone","onRemoveVirtualWall","onRemoveThreshold","onUpdateForbiddenSweepZone","onUpdateForbiddenMopZone","onUpdateCleanZone","onUpdateVirtualWall","onUpdateThreshold","onUpdateSpot","onUpdateRoomAnchor","onUpdateWayPoint","onUpdateDivider","onClickForbiddenSweepZone","onClickForbiddenMopZone","onClickCleanZone","onClickVirtualWall","onClickThreshold","onClickSpot","onClickRoomAnchor","onClickWayPoint","onClickDetectedObject","onClickCustomElement","onClickMap","onClickCarpet","onDeleteCarpet","onUpdateCustomCarpet","onDeleteCustomCarpet","onGestureStart","onGestureEnd","onClickRobot","onClickChargingStation","onRemoveFurniture","onUpdateFurniture","onClickFurniture","onRemoveCustomZone","onUpdateCustomZone","onClickCustomZone"];export{e as MAP_API_METHODS,o as MAP_CALLBACK_METHODS};
+const e=["areRoomsAdjacent","getForbiddenSweepZones","getForbiddenMopZones","getCleanZones","getVirtualWalls","getThresholds","getSpots","getRoomAnchors","getWayPoints","getViewportCenterPoint","getMapCenterPoint","getWallPointsByViewportCenter","getForbiddenSweepZonePointsByViewportCenter","getForbiddenMopZonePointsByViewportCenter","getCleanZonePointsByViewportCenter","getThresholdPointsByViewportCenter","getSpotPointByViewportCenter","getEffectiveDividerPoints","getDividerEndPoints","isNearChargerOrRobot","isPointInAnyRoom","isWallIntersectsAnyRoom","isZoneIntersectsAnyRoom","resetPanZoom","snapshot","snapshotByData","getCustomCarpets","forceEndGesture","getFurniturePointsByViewportCenter","getCustomCarpetPointsByViewportCenter","getRectPointsByCenter","getFurnitures","drawCustomZones","getCustomZones","clearCustomZones","setEditingCustomZones"],o=["onMapFirstDrawed","onMapDrawed","onPathDrawed","onRoomPropertiesDrawed","onRoomsDrawed","onClickRoom","onClickRoomProperties","onRemoveForbiddenSweepZone","onRemoveForbiddenMopZone","onRemoveCleanZone","onRemoveVirtualWall","onRemoveThreshold","onUpdateForbiddenSweepZone","onUpdateForbiddenMopZone","onUpdateCleanZone","onUpdateVirtualWall","onUpdateThreshold","onUpdateSpot","onUpdateRoomAnchor","onUpdateWayPoint","onUpdateDivider","onClickForbiddenSweepZone","onClickForbiddenMopZone","onClickCleanZone","onClickVirtualWall","onClickThreshold","onClickSpot","onClickRoomAnchor","onClickWayPoint","onClickDetectedObject","onClickCustomElement","onClickMap","onClickCarpet","onDeleteCarpet","onUpdateCustomCarpet","onDeleteCustomCarpet","onGestureStart","onGestureEnd","onClickRobot","onClickChargingStation","onRemoveFurniture","onUpdateFurniture","onClickFurniture","onRemoveCustomZone","onUpdateCustomZone","onClickCustomZone"];export{e as MAP_API_METHODS,o as MAP_CALLBACK_METHODS};

package/dist/index.d.ts

@@ -61,6 +61,35 @@ export declare type AppConfig = {
         freeColor: ColorSource
         /** 地图自适应时的偏移量（像素) */
         autoFitOffset?: { x: number; y: number }
+        /**
+         * 地图美化（Beautify）参数，配合 `runtime.enableBeautify` 使用。
+         *
+         * 只暴露开发者能凭直觉调整的旋钮：外壳描边样式（`borderWidth` /
+         * `shellLightenRatio`）与墙线吸附强度（`wallSnapTolerance`）。RDP 简化容差、
+         * 凹凸抹平尺寸、回退膨胀阈值属于算法内部标定参数，已下沉为内部常量、不再
+         * 暴露为配置（2026-07-23 收窄）。门口推断（Doorway inference）同理——随美化
+         * 自动运行，参数为内部常量（原 `doorway` 子开关已于 2026-07-22 移除）。
+         */
+        beautify: {
+            /**
+             * 外壳规整档：`'faithful'`（缺省）外壳紧贴原始轮廓，未测绘到的空洞原样
+             * 保留；`'boxy'` 花掉一份面积预算换更少的边，房间趋向规整的矩形 / L 形
+             * （空洞被浅色外壳盖住）。两档都只加不减，绝不削掉设备测绘到的区域；
+             * 别的房间已测绘的区域也不会被外壳盖住（渲染分层保证，几何上贴身档的
+             * 外壳仍可能与邻居交叠）。档位映射到的化简预算是内部标定常量。
+             */
+            level: 'faithful' | 'boxy'
+            /** 外壳边框宽度（像素），边框颜色复用 `map.obstacleColor` */
+            borderWidth: number
+            /** 外壳浅色调的提亮比例（0 为房间原色，1 为纯白） */
+            shellLightenRatio: number
+            /**
+             * 墙线吸附（wall-snap）容差（地图像素）：在原始数据里相邻的房间对，其近平行
+             * 外壳边垂直间距不超过此值时吸附到同一条墙线，使相邻外壳零缝隙贴合。
+             * 缺省 7；`0` 关闭 wall-snap。相邻性判定复用 `map.adjacencyThreshold`。
+             */
+            wallSnapTolerance: number
+        }
     }
 
     /** 热力图配置 */
@@ -102,6 +131,14 @@ export declare type AppConfig = {
             inactive: string[]
             /** 普通状态颜色（非选择模式下使用） */
             normal?: string[]
+            /**
+             * 美化外壳（Shell）填充色的显式覆盖调色板，按四色索引取用（可选）。
+             * 未配置时外壳色由房间基础色向白色按 `map.beautify.shellLightenRatio`
+             * 推导（随选择状态变化）；配置后外壳直接使用该调色板对应索引的颜色，
+             * 覆盖自动推导。仅在 `runtime.enableBeautify` 开启时生效，足迹层始终用
+             * 房间基础色，选择态反馈不受影响。修改此项会实时重新着色两层。
+             */
+            shell?: string[]
             /** 房间名称颜色 */
             name: string[]
             /** 房间名称非激活状态颜色 */
@@ -1093,7 +1130,7 @@ export declare type LoggerPayload = {
     ts: number
 }
 
-export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getThresholds", "getSpots", "getRoomAnchors", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData", "getCustomCarpets", "forceEndGesture", "getFurniturePointsByViewportCenter", "getCustomCarpetPointsByViewportCenter", "getRectPointsByCenter", "getFurnitures", "drawCustomZones", "getCustomZones", "clearCustomZones", "setEditingCustomZones"];
+export declare const MAP_API_METHODS: readonly ["areRoomsAdjacent", "getForbiddenSweepZones", "getForbiddenMopZones", "getCleanZones", "getVirtualWalls", "getThresholds", "getSpots", "getRoomAnchors", "getWayPoints", "getViewportCenterPoint", "getMapCenterPoint", "getWallPointsByViewportCenter", "getForbiddenSweepZonePointsByViewportCenter", "getForbiddenMopZonePointsByViewportCenter", "getCleanZonePointsByViewportCenter", "getThresholdPointsByViewportCenter", "getSpotPointByViewportCenter", "getEffectiveDividerPoints", "getDividerEndPoints", "isNearChargerOrRobot", "isPointInAnyRoom", "isWallIntersectsAnyRoom", "isZoneIntersectsAnyRoom", "resetPanZoom", "snapshot", "snapshotByData", "getCustomCarpets", "forceEndGesture", "getFurniturePointsByViewportCenter", "getCustomCarpetPointsByViewportCenter", "getRectPointsByCenter", "getFurnitures", "drawCustomZones", "getCustomZones", "clearCustomZones", "setEditingCustomZones"];
 
 export declare const MAP_CALLBACK_METHODS: readonly ["onMapFirstDrawed", "onMapDrawed", "onPathDrawed", "onRoomPropertiesDrawed", "onRoomsDrawed", "onClickRoom", "onClickRoomProperties", "onRemoveForbiddenSweepZone", "onRemoveForbiddenMopZone", "onRemoveCleanZone", "onRemoveVirtualWall", "onRemoveThreshold", "onUpdateForbiddenSweepZone", "onUpdateForbiddenMopZone", "onUpdateCleanZone", "onUpdateVirtualWall", "onUpdateThreshold", "onUpdateSpot", "onUpdateRoomAnchor", "onUpdateWayPoint", "onUpdateDivider", "onClickForbiddenSweepZone", "onClickForbiddenMopZone", "onClickCleanZone", "onClickVirtualWall", "onClickThreshold", "onClickSpot", "onClickRoomAnchor", "onClickWayPoint", "onClickDetectedObject", "onClickCustomElement", "onClickMap", "onClickCarpet", "onDeleteCarpet", "onUpdateCustomCarpet", "onDeleteCustomCarpet", "onGestureStart", "onGestureEnd", "onClickRobot", "onClickChargingStation", "onRemoveFurniture", "onUpdateFurniture", "onClickFurniture", "onRemoveCustomZone", "onUpdateCustomZone", "onClickCustomZone"];
 
@@ -1404,6 +1441,28 @@ export declare interface MapApi {
         offsetX?: number;
         offsetY?: number;
     }): Point[];
+    /**
+     * 基于视口中心生成门槛的四个角点坐标
+     *
+     * 缺省尺寸 1m × 0.15m（长 × 厚）—— 「新建门槛」的初始尺寸，不是配置项；
+     * 需要别的初始尺寸就传 `width` / `height`。传入值会被钳制到
+     * `controls.threshold` 的 `minLength`/`maxLength` 与 `minHeight`/`maxHeight`
+     * （米）区间内。
+     *
+     * @param options - 配置选项
+     * @param options.width - 门槛长度，单位米，默认 1
+     * @param options.height - 门槛厚度，单位米，默认 0.15
+     * @param options.offsetX - X方向像素偏移，支持负数，默认为 0
+     * @param options.offsetY - Y方向像素偏移，支持负数，默认为 0
+     * @returns 四个角点坐标，顺时针顺序：[左上, 右上, 右下, 左下]（0→1 为长度
+     *   方向，0→3 为厚度方向），可直接作为 `ThresholdParam.points`
+     */
+    getThresholdPointsByViewportCenter(options?: {
+        width?: number;
+        height?: number;
+        offsetX?: number;
+        offsetY?: number;
+    }): Point[];
     /**
      * 基于任意中心点生成矩形的四个顶点坐标
      *
@@ -2166,6 +2225,24 @@ export declare type ProcessedRasterData = {
     totalPixels: number
 }
 
+/**
+ * 栅格房间的美化几何（仅 `runtime.enableBeautify` 开启时由 MapManager 计算，
+ * 随 `ProcessedRasterData` 一并交给渲染层）。
+ *
+ * 由像素掩膜描环（`traceRoomRing`）后经既有美化管线得到，坐标在像素**角点格**
+ * 坐标系（像素 `(x, y)` 占据 `[x, x+1] × [y, y+1]`），渲染时不做 +0.5 居中偏移
+ * ——描环多边形本就与逐像素矩形逐字节对齐。只有拿到可渲染外壳的房间才有此
+ * 记录；描环失败 / 管线回退的房间与特殊房间保持逐像素原样渲染（ADR 0003/0004）。
+ */
+export declare type RasterBeautifiedRoom = {
+    /** 美化外壳（Shell）顶点（闭合环，不重复首点），严格包含描环足迹 */
+    shell: Point[]
+    /** 美化足迹（Footprint）顶点：无损阶梯描环本身（逐像素原样，不简化） */
+    footprint: Point[]
+    /** 推断出的门口开口段，落在该房间外壳边上（可选，见 Room.doorways） */
+    doorways?: { start: Point; end: Point }[]
+}
+
 /**
  * 点阵房间数据
  */
@@ -2225,6 +2302,27 @@ export declare type Room = {
     centerPoint: Point
     /** 颜色索引（用于四色算法） */
     colorIndex?: number
+    /**
+     * 美化外壳（Shell）顶点，仅在 `runtime.enableBeautify` 开启时由
+     * MapManager 写入绘制数据；`roomGeometryMap` 中的原始几何不携带该字段
+     * （原始数据保持数据层权威，见 ADR 0003）
+     */
+    shell?: Point[]
+    /**
+     * 美化足迹（Footprint）顶点：房间原始轮廓的轻度简化环，仅在美化开启且该
+     * 房间携带 `shell` 时由 MapManager 一并写入。渲染层用房间基础色把它填入
+     * 外壳内部并裁剪到外壳，呈现设备实际测绘区域（见 ADR 0003）。与 `shell`
+     * 同样不写回 `roomGeometryMap`。
+     */
+    footprint?: Point[]
+    /**
+     * 推断出的门口开口段（Doorway），落在该房间自身外壳边上。门口推断是美化管线的
+     * 内建默认步骤：仅在 `runtime.enableBeautify` 开启、且该房间共享墙上推断出开口时
+     * 由 MapManager 写入（随美化自动运行，不再需要配置或 runtime 子开关）。渲染层据此
+     * 在这些位置打断外壳边框。门口是派生视觉开口，不是门槛（Threshold），绝不影响门槛
+     * 渲染 / 编辑（见 CONTEXT.md §Beautification、ADR 0003）。
+     */
+    doorways?: { start: Point; end: Point }[]
 }
 
 /**
@@ -2436,6 +2534,17 @@ export declare type RuntimeConfig = {
     showRobotPulseCircle: boolean
     /** 选中的地毯ID列表 */
     selectedCarpetIds: string[]
+    /**
+     * 是否启用地图美化（Beautify）
+     *
+     * 开启后地图以规整外壳（Shell）展示房间：外壳填充为房间色的浅色调，
+     * 边框使用 `config.map.obstacleColor`。结构化地图上障碍点与自由区域点云
+     * 隐藏，未知房间（id >= 255）不参与美化、按原样渲染；栅格地图上房间
+     * 像素掩膜先描成轮廓再走同一条美化管线（2026-07-28），特殊房间与描环 /
+     * 直角化失败的房间保持逐像素原样渲染。切换开关会从缓存的地图数据重新
+     * 处理并立即重绘。样式与算法参数见 `config.map.beautify`。
+     */
+    enableBeautify: boolean
 }
 
 /** 定点清扫配置 */
@@ -2544,28 +2653,57 @@ export declare type SpotParam = {
 
 /** 门槛配置 */
 export declare type ThresholdConfig = {
-    /** 条纹线宽（屏幕像素，不随地图缩放变化） */
+    /**
+     * 条纹线宽，垂直于斜纹方向度量（斜纹角度见 {@link ThresholdConfig.stripeAngle}）。
+     *
+     * **单位是条带厚度的比例，不是像素**（0.3 表示线宽为条带厚度的 30%）。
+     * 于是整套纹路跟着条带一起缩放：跨条带的条纹根数、疏密、着色比例在任何
+     * 地图缩放下都不变，薄门槛与厚门槛看起来也是同一张贴纸。
+     */
     stripeWidth: number
-    /** 相邻条纹间距（屏幕像素） */
+    /**
+     * 相邻条纹间距，沿条带长度方向度量。**单位同样是条带厚度的比例。**
+     *
+     * 步距 `stripeWidth + stripeGap` 决定疏密：取 0.7 时，一根斜纹横穿条带的
+     * 水平距离约为步距的 `1 / (0.7 × tan(stripeAngle))` 倍。
+     *
+     * 两者不同轴：`stripeWidth` 是垂直于斜纹的线宽，同一根斜纹沿长度方向占
+     * `stripeWidth / sin(stripeAngle)`（45° 时为 `× √2`），所以着色比例约为
+     * `stripeWidth / sin(stripeAngle) / (stripeWidth + stripeGap)`——默认值下
+     * 约 55%。调陡 `stripeAngle` 会让条带变淡，需同步放大 `stripeWidth`。
+     */
     stripeGap: number
+    /**
+     * 斜纹倾斜方向：`'forward'` 为 `/`（沿长度方向向右上），`'backward'` 为
+     * `\`（向右下）。缺省 `'forward'`。厂商之间惯例不一，两种都保留。
+     */
+    stripeDirection: 'forward' | 'backward'
+    /**
+     * 斜纹与条带长度方向的夹角（度）。`45` 是常见的危险胶带角度，`90` 为垂直
+     * 于条带的竖条纹；取值钳制在 `[10, 90]`。
+     *
+     * 注意角度会连带改变疏密与着色：斜纹越陡，横穿条带需要的水平距离越短
+     * （`厚度 / tan(角度)`），同样的步距下穿过条带的条纹越少；同时一根斜纹沿
+     * 长度方向只占 `stripeWidth / sin(角度)`，所以着色比例也会下降。改陡以后
+     * 想维持观感，需要同步调小 `stripeGap`。
+     */
+    stripeAngle: number
     /** 条带边框线宽（屏幕像素） */
     borderWidth: number
     /** 条带圆角半径（屏幕像素，自动不超过条带半厚 / 半长） */
     cornerRadius: number
-    /** 可通行门槛样式（默认绿色斜纹） */
+    /** 可通行门槛样式（默认蓝白斜纹） */
     passable: ThresholdStyle
-    /** 不可通行门槛样式（默认红色斜纹） */
+    /** 不可通行门槛样式（默认红白斜纹） */
     impassable: ThresholdStyle
-    /** 最小长度 (米)，绘制与缩放时长度被钳制到不小于该值 */
+    /** 最小长度 (米)，绘制与缩放时长边（顶点 0→1）被钳制到不小于该值 */
     minLength: number
     /** 最大长度 (米)，可选。缺省或 ≤ minLength 时不限制。 */
     maxLength?: number
-    /** 最小高度 (米)，绘制与缩放时条带高度被钳制到不小于该值 */
+    /** 最小厚度 (米)，绘制与缩放时厚度边（顶点 0→3）被钳制到不小于该值 */
     minHeight: number
-    /** 最大高度 (米)，可选。缺省或 ≤ minHeight 时不限制。 */
+    /** 最大厚度 (米)，可选。缺省或 ≤ minHeight 时不限制。 */
     maxHeight?: number
-    /** 数据未携带 height 时的默认条带高度 (米) */
-    defaultHeight: number
     /** 四角控制按钮图标容器填充颜色（编辑态显示） */
     iconWrapperFillColor: ColorSource
     /**
@@ -2586,7 +2724,7 @@ export declare type ThresholdConfig = {
     outlineDashArray: [number, number]
     /** 编辑态轮廓填充颜色 */
     outlineFillColor: ColorSource
-    /** 尺寸标签（长×高）文本颜色（编辑态显示） */
+    /** 尺寸标签（长×厚）文本颜色（编辑态显示） */
     textColor: ColorSource
     /** 尺寸标签相对轮廓边缘向外的偏移（屏幕像素） */
     textOffset: number
@@ -2595,27 +2733,30 @@ export declare type ThresholdConfig = {
 /**
  * 门槛参数。
  *
- * 门槛是「中心线 + 高度」的矩形条带元素，用可通行 / 不可通行两种类型标记
- * 机器人能否跨越的通道，渲染为斜纹条带（可通行绿色 / 不可通行红色）。条带
- * 为真实世界尺寸：长度由两端点决定，厚度由 `height` 决定，随地图缩放。
+ * 门槛是四角坐标描述的矩形条带元素，用可通行 / 不可通行两种类型标记机器人
+ * 能否跨越的通道，渲染为白底斜纹条带（可通行蓝白 / 不可通行红白）。条带为真实
+ * 世界尺寸（长度与厚度都由四角坐标决定，随地图缩放）。数据形态与禁区 /
+ * 家具等四边形元素一致 —— 与主流厂商的门槛协议对齐（见 ADR 0005）。
  *
  * 交互由运行时 `editingThresholdIds` 门控：列入的门槛显示编辑控件（虚线
  * 轮廓、尺寸标签与删除 / 旋转 / 缩放 / 移动按钮，与禁区等四边形元素同一套
- * 编辑面），长与高在缩放时各自钳制到 `minLength`/`maxLength` 与
+ * 编辑面），长与厚在缩放时各自钳制到 `minLength`/`maxLength` 与
  * `minHeight`/`maxHeight`（米）区间。编辑结束触发 `onUpdateThreshold`，
  * 点击触发 `onClickThreshold`，删除按钮触发 `onRemoveThreshold`。
  */
 export declare type ThresholdParam = {
     /** 门槛ID */
     id: string
-    /** 中心线两端点坐标（起点、终点），与其他元素同为地图像素坐标系 */
-    points: [Point, Point]
     /**
-     * 条带高度（厚度），单位与 points 相同（地图像素）。缺省时取
-     * `controls.threshold.defaultHeight`（米）换算；绘制与缩放时被钳制在
-     * `minHeight` / `maxHeight`（米）区间内。
+     * 四角坐标（地图像素坐标系），顺时针 左上→右上→右下→左下，与家具 /
+     * 禁区等四边形元素同序：顶点 0→1 为长度方向，0→3 为厚度方向。
+     *
+     * 入口处会归一化：绕向纠正为顺时针、较长的一条边规范到 0→1、长与厚
+     * 分别钳制到 `minLength`/`maxLength` 与 `minHeight`/`maxHeight`（米）区间，
+     * 再拉直成标准矩形（保留旋转角与中心）。因此 `getThresholds()` 回吐的
+     * 点集是归一化后的结果，不一定与传入的原始点逐字相同。
      */
-    height?: number
+    points: Point[]
     /** 门槛类型（可通行 / 不可通行）。缺省为 `passable`（可通行）。 */
     type?: ThresholdType
 }
@@ -2631,8 +2772,8 @@ export declare type ThresholdStyle = {
 /**
  * 门槛类型。
  *
- * - `'passable'`：可通行门槛，机器人可尝试跨越，默认渲染为绿色斜纹条带
- * - `'impassable'`：不可通行门槛，机器人不得跨越，默认渲染为红色斜纹条带
+ * - `'passable'`：可通行门槛，机器人可尝试跨越，默认渲染为蓝白斜纹条带
+ * - `'impassable'`：不可通行门槛，机器人不得跨越，默认渲染为红白斜纹条带
  */
 export declare type ThresholdType = 'passable' | 'impassable'