@ray-js/robot-map-sdk 0.0.17-beta.2 → 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

@@ -74,8 +74,9 @@ export declare type AppConfig = {
             /**
              * 外壳规整档：`'faithful'`（缺省）外壳紧贴原始轮廓，未测绘到的空洞原样
              * 保留；`'boxy'` 花掉一份面积预算换更少的边，房间趋向规整的矩形 / L 形
-             * （空洞被浅色外壳盖住）。两档都只加不减，绝不削掉设备测绘到的区域，
-             * 也绝不吞掉别的房间已测绘的区域。档位映射到的化简预算是内部标定常量。
+             * （空洞被浅色外壳盖住）。两档都只加不减，绝不削掉设备测绘到的区域；
+             * 别的房间已测绘的区域也不会被外壳盖住（渲染分层保证，几何上贴身档的
+             * 外壳仍可能与邻居交叠）。档位映射到的化简预算是内部标定常量。
              */
             level: 'faithful' | 'boxy'
             /** 外壳边框宽度（像素），边框颜色复用 `map.obstacleColor` */
@@ -1129,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"];
 
@@ -1440,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[];
     /**
      * 基于任意中心点生成矩形的四个顶点坐标
      *
@@ -2630,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
     /**
@@ -2672,7 +2724,7 @@ export declare type ThresholdConfig = {
     outlineDashArray: [number, number]
     /** 编辑态轮廓填充颜色 */
     outlineFillColor: ColorSource
-    /** 尺寸标签（长×高）文本颜色（编辑态显示） */
+    /** 尺寸标签（长×厚）文本颜色（编辑态显示） */
     textColor: ColorSource
     /** 尺寸标签相对轮廓边缘向外的偏移（屏幕像素） */
     textOffset: number
@@ -2681,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
 }
@@ -2717,8 +2772,8 @@ export declare type ThresholdStyle = {
 /**
  * 门槛类型。
  *
- * - `'passable'`：可通行门槛，机器人可尝试跨越，默认渲染为绿色斜纹条带
- * - `'impassable'`：不可通行门槛，机器人不得跨越，默认渲染为红色斜纹条带
+ * - `'passable'`：可通行门槛，机器人可尝试跨越，默认渲染为蓝白斜纹条带
+ * - `'impassable'`：不可通行门槛，机器人不得跨越，默认渲染为红白斜纹条带
  */
 export declare type ThresholdType = 'passable' | 'impassable'