feat(Pipeline): roi 和 target 字段支持负数坐标和尺寸 (#1093)

Author: MistEO

docs/en_us/3.1-PipelineProtocol.md

@@ -426,9 +426,11 @@ Template matching, also known as "find image."
 
 This algorithm property requires additional fields:
 
-- `roi`: *array<int, 4>* | *string*  
+- `roi`: *array<int, 4>* | *array<int, 2>* | *string*  
     Recognition area coordinates. Optional, default [0, 0, 0, 0], i.e. full screen.
-  - *array<int, 4>*: Recognition area coordinates, [x, y, w, h], if you want full screen, you can set it to [0, 0, 0, 0].
+  - *array<int, 4>*: Recognition area coordinates, [x, y, w, h], if you want full screen, you can set it to [0, 0, 0, 0].  
+    Supports negative values: negative x or y means calculating from the right or bottom edge of the image; w or h of 0 means extending to the edge, negative means taking absolute value and treating (x, y) as the bottom-right corner instead of top-left. For example, `[-100, -100, 0, 0]` represents the area from the bottom-right corner 100 pixels inward to the edge; `[200, 200, -100, -50]` represents a 100x50 area with (200, 200) as bottom-right corner, i.e., `[100, 150, 100, 50]`.
+  - *array<int, 2>*: Fixed coordinate point `[x, y]`. Supports negative values with the same meaning as above.
   - *string*: Fill in the node name, and identify within the target range identified by a previously executed node.
 
 - `roi_offset`: *array<int, 4>*  
@@ -801,8 +803,8 @@ Additional properties for this action:
     The position of the click target. Optional, default is true.  
   - *true*: The target is the position just recognized in this node (i.e., itself).
   - *string*: Enter the node name, as the target, to use the position recognized by a previously executed node.
-  - *array<int, 2>*: Fixed coordinate point `[x, y]`.
-  - *array<int, 4>*: Fixed coordinate area `[x, y, w, h]`. A point is sampled inside the rectangle with higher probability near the center and lower probability near the edges. To target the entire screen, set it to [0, 0, 0, 0].
+  - *array<int, 2>*: Fixed coordinate point `[x, y]`. Supports negative values, meaning calculating from the right or bottom edge of the image. For example, `[-100, -100]` represents a position 100 pixels from the bottom-right corner.
+  - *array<int, 4>*: Fixed coordinate area `[x, y, w, h]`. A point is sampled inside the rectangle with higher probability near the center and lower probability near the edges. To target the entire screen, set it to [0, 0, 0, 0]. Supports negative values: negative x or y means calculating from the right or bottom edge of the image; w or h of 0 means extending to the edge, negative means taking absolute value and treating (x, y) as the bottom-right corner.
 
 - `target_offset`: *array<int, 4>*  
     Additional movement from the `target` before clicking, where the four values are added together. Optional, default is [0, 0, 0, 0].

docs/zh_cn/3.1-任务流水线协议.md

@@ -431,9 +431,11 @@ MaaResourcePostPath(resource, "resource/debug");  // debug 节点使用 rate_lim
 
 该算法属性需额外部分字段：
 
-- `roi`: *array<int, 4>* | *string*  
+- `roi`: *array<int, 4>* | *array<int, 2>* | *string*  
     识别区域坐标。可选，默认 [0, 0, 0, 0] ，即全屏。  
-  - *array<int, 4>*: 识别区域坐标，[x, y, w, h]，若希望全屏可设为 [0, 0, 0, 0] 。
+  - *array<int, 4>*: 识别区域坐标，[x, y, w, h]，若希望全屏可设为 [0, 0, 0, 0] 。  
+    支持负数：x 或 y 为负数时表示从图像右边缘或下边缘反向计算；w 或 h 为 0 时表示延伸至边缘，为负数时取绝对值并将 (x, y) 视为右下角而非左上角。例如 `[-100, -100, 0, 0]` 表示右下角 100x100 位置到边缘的范围；`[200, 200, -100, -50]` 表示以 (200, 200) 为右下角的 100x50 区域，即 `[100, 150, 100, 50]`。
+  - *array<int, 2>*: 固定坐标点 `[x, y]`。支持负数，含义同上。
   - *string*: 填写节点名，在之前执行过的某节点识别到的目标范围内识别。  
 
 - `roi_offset`: *array<int, 4>*  
@@ -809,8 +811,8 @@ Pipeline v2 时，将这些字段放到 `recognition.param` 中即可。
     点击目标的位置。可选，默认 true 。  
   - *true*: 目标为本节点中刚刚识别到的位置（即自身）。  
   - *string*: 填写节点名，目标为之前执行过的某节点识别到的位置。  
-  - *array<int, 2>*: 固定坐标点 `[x, y]`。  
-  - *array<int, 4>*: 固定坐标区域 `[x, y, w, h]`，会在矩形内随机选取一点（越靠近中心概率越高，边缘概率相对较低），若希望全屏可设为 [0, 0, 0, 0] 。
+  - *array<int, 2>*: 固定坐标点 `[x, y]`。支持负数，表示从图像右边缘或下边缘反向计算。例如 `[-100, -100]` 表示右下角距离边缘 100 像素的位置。  
+  - *array<int, 4>*: 固定坐标区域 `[x, y, w, h]`，会在矩形内随机选取一点（越靠近中心概率越高，边缘概率相对较低），若希望全屏可设为 [0, 0, 0, 0] 。支持负数：x 或 y 为负数时表示从图像右边缘或下边缘反向计算；w 或 h 为 0 时表示延伸至边缘，为负数时取绝对值并将 (x, y) 视为右下角。
 
 - `target_offset`: *array<int, 4>*  
     在 `target` 的基础上额外移动再作为点击目标，四个值分别相加。可选，默认 [0, 0, 0, 0] 。

source/MaaFramework/Task/Component/Actuator.cpp

@@ -6,6 +6,7 @@
 #include "MaaUtils/JsonExt.hpp"
 #include "MaaUtils/Logger.h"
 #include "Vision/TemplateComparator.h"
+#include "Vision/VisionUtils.hpp"
 
 MAA_TASK_NS_BEGIN
 
@@ -725,6 +726,11 @@ cv::Rect Actuator::get_target_rect(const MAA_RES_NS::Action::Target target, cons
 
     auto image = controller()->cached_image();
 
+    // Region 类型支持负数坐标和尺寸
+    if (target.type == Target::Type::Region) {
+        raw = MAA_VISION_NS::normalize_rect(raw, image.cols, image.rows);
+    }
+
     int x = std::clamp(raw.x + target.offset.x, 0, image.cols);
     int y = std::clamp(raw.y + target.offset.y, 0, image.rows);
     int width = std::clamp(raw.width + target.offset.width, 0, image.cols - x);

source/MaaFramework/Vision/VisionUtils.hpp

@@ -295,17 +295,50 @@ inline static std::vector<float> image_to_tensor(const cv::Mat& image)
     return tensor;
 }
 
+// 将支持负数的矩形转换为标准矩形：
+// - x/y 负数表示从右/下边缘反向计算
+// - w/h 负数表示取绝对值并将 (x,y) 视为右下角
+// - w/h 为 0 表示延伸至边缘
+inline cv::Rect normalize_rect(const cv::Rect& rect, int image_width, int image_height)
+{
+    cv::Rect res = rect;
+
+    if (res.x < 0) {
+        res.x = image_width + res.x;
+    }
+    if (res.y < 0) {
+        res.y = image_height + res.y;
+    }
+
+    if (res.width < 0) {
+        res.width = -res.width;
+        res.x -= res.width;
+    }
+    if (res.height < 0) {
+        res.height = -res.height;
+        res.y -= res.height;
+    }
+
+    if (res.width == 0) {
+        res.width = image_width - res.x;
+    }
+    if (res.height == 0) {
+        res.height = image_height - res.y;
+    }
+
+    return res;
+}
+
 inline cv::Rect correct_roi(const cv::Rect& roi, const cv::Mat& image)
 {
     if (image.empty()) {
         LogError << "image is empty" << VAR(image.size());
         return roi;
     }
-    if (roi.empty()) {
-        return { 0, 0, image.cols, image.rows };
-    }
 
-    cv::Rect res = roi;
+    cv::Rect res = normalize_rect(roi, image.cols, image.rows);
+
+    // 边界检查和修正
     if (image.cols < res.x) {
         LogError << "roi is out of range" << VAR(image.size()) << VAR(res);
         res.x = image.cols - res.width;

test/python/pipeline_test.py

@@ -935,6 +935,135 @@ def test_repeat_params(context: Context):
     print("  PASS: repeat params")
 
 
+# ============================================================================
+# 负数 roi 和 target 参数测试
+# ============================================================================
+
+
+def test_negative_roi_and_target(context: Context):
+    """测试负数 roi 和 target 参数的解析"""
+    print("\n=== test_negative_roi_and_target ===")
+
+    new_ctx = context.clone()
+
+    # 测试负数 roi 坐标（从边缘反向计算）
+    new_ctx.override_pipeline(
+        {
+            "NegativeRoiCoord": {
+                "recognition": "TemplateMatch",
+                "template": ["test.png"],
+                "roi": [-100, -100, 50, 50],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeRoiCoord")
+    assert_eq(obj.recognition.param.roi, [-100, -100, 50, 50], "negative roi coords")
+
+    # 测试负数 roi 宽高（xy 作为右下角）
+    new_ctx.override_pipeline(
+        {
+            "NegativeRoiSize": {
+                "recognition": "TemplateMatch",
+                "template": ["test.png"],
+                "roi": [200, 200, -100, -50],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeRoiSize")
+    assert_eq(obj.recognition.param.roi, [200, 200, -100, -50], "negative roi size")
+
+    # 测试 roi 宽高为 0（延伸至边缘）
+    new_ctx.override_pipeline(
+        {
+            "ZeroRoiSize": {
+                "recognition": "TemplateMatch",
+                "template": ["test.png"],
+                "roi": [100, 100, 0, 0],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("ZeroRoiSize")
+    assert_eq(obj.recognition.param.roi, [100, 100, 0, 0], "zero roi size")
+
+    # 测试组合：负数坐标 + 零宽高（右下角到边缘）
+    new_ctx.override_pipeline(
+        {
+            "NegativeRoiCombo": {
+                "recognition": "TemplateMatch",
+                "template": ["test.png"],
+                "roi": [-100, -100, 0, 0],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeRoiCombo")
+    assert_eq(obj.recognition.param.roi, [-100, -100, 0, 0], "negative roi combo")
+
+    # 测试 2 元素数组的负数坐标
+    new_ctx.override_pipeline(
+        {
+            "NegativeRoi2Elem": {
+                "recognition": "TemplateMatch",
+                "template": ["test.png"],
+                "roi": [-50, -50],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeRoi2Elem")
+    assert_eq(obj.recognition.param.roi, [-50, -50, 0, 0], "negative roi 2-element")
+
+    # 测试负数 target 坐标
+    new_ctx.override_pipeline(
+        {
+            "NegativeTargetCoord": {
+                "action": "Click",
+                "target": [-100, -100, 50, 50],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeTargetCoord")
+    assert_eq(obj.action.param.target, [-100, -100, 50, 50], "negative target coords")
+
+    # 测试负数 target 宽高
+    new_ctx.override_pipeline(
+        {
+            "NegativeTargetSize": {
+                "action": "Click",
+                "target": [300, 300, -100, -100],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeTargetSize")
+    assert_eq(obj.action.param.target, [300, 300, -100, -100], "negative target size")
+
+    # 测试 2 元素数组的负数 target
+    new_ctx.override_pipeline(
+        {
+            "NegativeTarget2Elem": {
+                "action": "Click",
+                "target": [-50, -50],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeTarget2Elem")
+    assert_eq(obj.action.param.target, [-50, -50, 0, 0], "negative target 2-element")
+
+    # 测试 Swipe 的负数坐标
+    new_ctx.override_pipeline(
+        {
+            "NegativeSwipe": {
+                "action": "Swipe",
+                "begin": [-100, -100, 50, 50],
+                "end": [-50, -50],
+            }
+        }
+    )
+    obj = new_ctx.get_node_object("NegativeSwipe")
+    assert_eq(obj.action.param.begin, [-100, -100, 50, 50], "negative swipe begin")
+    assert_eq(obj.action.param.end[0], [-50, -50, 0, 0], "negative swipe end")
+
+    print("  PASS: negative roi and target")
+
+
 # ============================================================================
 # 主测试流程
 # ============================================================================
@@ -1033,6 +1162,7 @@ class AdditionalTestReco(CustomRecognition):
             def analyze(self, context, argv):
                 test_wait_freezes(context)
                 test_repeat_params(context)
+                test_negative_roi_and_target(context)
                 return CustomRecognition.AnalyzeResult(
                     box=(0, 0, 10, 10), detail="done"
                 )