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

package/dist/index.d.ts

@@ -61,6 +61,34 @@ 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 +130,14 @@ export declare type AppConfig = {
             inactive: string[]
             /** 普通状态颜色（非选择模式下使用） */
             normal?: string[]
+            /**
+             * 美化外壳（Shell）填充色的显式覆盖调色板，按四色索引取用（可选）。
+             * 未配置时外壳色由房间基础色向白色按 `map.beautify.shellLightenRatio`
+             * 推导（随选择状态变化）；配置后外壳直接使用该调色板对应索引的颜色，
+             * 覆盖自动推导。仅在 `runtime.enableBeautify` 开启时生效，足迹层始终用
+             * 房间基础色，选择态反馈不受影响。修改此项会实时重新着色两层。
+             */
+            shell?: string[]
             /** 房间名称颜色 */
             name: string[]
             /** 房间名称非激活状态颜色 */
@@ -2166,6 +2202,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 +2279,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 +2511,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
 }
 
 /** 定点清扫配置 */