feat: resize image utils (#1078)

Co-authored-by: MistEO <mistereo@hotmail.com>

Author: neko-para

docs/en_us/2.2-IntegratedInterfaceOverview.md

@@ -13,6 +13,7 @@ Different language bindings may have different naming conventions and are wrappe
 | MaaControllerPostClick(ctrl_handle, x, y)         | controller.post_click(x, y)       | ctrl.post_click(x, y)             |
 | MaaTaskerInited(tasker_handle)                    | tasker.inited                     | tasker.inited                     |
 | MaaTaskerPostTask(tasker_handle, entry, override) | tasker.post_task(entry, override) | tasker.post_task(entry, override) |
+| MaaImageBufferResize(image_handle, width, height) | ImageBuffer.resize(width, height) | Global.resize_image(image, width, height) |
 
 ## MaaUtility.h
 
@@ -51,6 +52,16 @@ Set global options. Will be split into specific options in bindings.
 
 Load plugin. Can use full path or name only. When using name only, will search in system directory and current directory. Can also recursively search for plugins in a directory.
 
+## MaaBuffer.h
+
+### MaaImageBufferResize
+
+- `handle`: Image buffer
+- `width`: Target width, pass 0 to scale by height
+- `height`: Target height, pass 0 to scale by width
+
+Resize the image data in `handle` with aspect ratio preserved. `width` and `height` cannot both be 0.
+
 ## MaaResource.h
 
 ### MaaResourceCreate

docs/zh_cn/2.2-集成接口一览.md

@@ -13,6 +13,7 @@
 | MaaControllerPostClick(ctrl_handle, x, y)         | controller.post_click(x, y)       | ctrl.post_click(x, y)             |
 | MaaTaskerInited(tasker_handle)                    | tasker.inited                     | tasker.inited                     |
 | MaaTaskerPostTask(tasker_handle, entry, override) | tasker.post_task(entry, override) | tasker.post_task(entry, override) |
+| MaaImageBufferResize(image_handle, width, height) | ImageBuffer.resize(width, height) | Global.resize_image(image, width, height) |
 
 ## MaaUtility.h
 
@@ -51,6 +52,16 @@
 
 加载插件。可以使用完整路径或仅使用名称，仅使用名称时会在系统目录和当前目录中搜索。也可以递归搜索目录中的插件
 
+## MaaBuffer.h
+
+### MaaImageBufferResize
+
+- `handle`: 图像缓冲区
+- `width`: 目标宽度，传 0 表示按高度等比缩放
+- `height`: 目标高度，传 0 表示按宽度等比缩放
+
+按比例缩放 `handle` 中的图像数据，修改原缓冲区。`width` 与 `height` 不能同时为 0。
+
 ## MaaResource.h
 
 ### MaaResourceCreate

include/MaaFramework/Utility/MaaBuffer.h

@@ -54,6 +54,7 @@ extern "C"
     MAA_FRAMEWORK_API int32_t MaaImageBufferType(const MaaImageBuffer* handle);
     MAA_FRAMEWORK_API MaaBool
         MaaImageBufferSetRawData(MaaImageBuffer* handle, MaaImageRawData data, int32_t width, int32_t height, int32_t type);
+    MAA_FRAMEWORK_API MaaBool MaaImageBufferResize(MaaImageBuffer* handle, int32_t width, int32_t height);
 
     typedef uint8_t* MaaImageEncodedData;
     MAA_FRAMEWORK_API MaaImageEncodedData MaaImageBufferGetEncoded(const MaaImageBuffer* handle);

source/Common/MaaBuffer.cpp

@@ -4,6 +4,7 @@
 #include "MaaUtils/Buffer/ListBuffer.hpp"
 #include "MaaUtils/Buffer/StringBuffer.hpp"
 #include "MaaUtils/Logger.h"
+#include "MaaUtils/NoWarningCV.hpp"
 
 MaaStringBuffer* MaaStringBufferCreate()
 {
@@ -272,6 +273,16 @@ MaaBool MaaImageBufferSetRawData(MaaImageBuffer* handle, MaaImageRawData data, i
     return true;
 }
 
+MaaBool MaaImageBufferResize(MaaImageBuffer* handle, int32_t width, int32_t height)
+{
+    if (!handle) {
+        LogError << "handle is null";
+        return 0;
+    }
+
+    return handle->resize(width, height);
+}
+
 MaaImageEncodedData MaaImageBufferGetEncoded(const MaaImageBuffer* handle)
 {
     if (!handle) {

source/binding/NodeJS/src/apis/global.cpp

@@ -4,6 +4,7 @@
 #include <MaaToolkit/MaaToolkitAPI.h>
 
 #include "../foundation/spec.h"
+#include "buffer.h"
 
 std::string version_from_macro()
 {
@@ -100,6 +101,16 @@ void config_init_option(std::string user_path, maajs::OptionalParam<std::string>
     }
 }
 
+maajs::ArrayBufferType resize_image(maajs::ArrayBufferType src, int32_t width, int32_t height)
+{
+    ImageBuffer buf;
+    buf.set(src);
+    if (!MaaImageBufferResize(buf, width, height)) {
+        throw maajs::MaaError { "Global resize_image failed" };
+    }
+    return buf.data(src.Env());
+}
+
 maajs::ObjectType load_global(maajs::EnvType env)
 {
     auto globalObject = maajs::ObjectType::New(env);
@@ -114,6 +125,7 @@ maajs::ObjectType load_global(maajs::EnvType env)
     MAA_BIND_SETTER(globalObject, "draw_quality", set_draw_quality);
     MAA_BIND_SETTER(globalObject, "reco_image_cache_limit", set_reco_image_cache_limit);
     MAA_BIND_FUNC(globalObject, "config_init_option", config_init_option);
+    MAA_BIND_FUNC(globalObject, "resize_image", resize_image);
 
     return globalObject;
 }

source/binding/NodeJS/src/apis/global.d.ts

@@ -13,6 +13,8 @@ declare global {
             set draw_quality(value: number)
             set reco_image_cache_limit(value: number)
             config_init_option(user_path: string, default_json?: string): void
+
+            resize_image(image: ArrayBuffer, width: number, height: number): ArrayBuffer
         }
     }
 }

source/binding/Python/maa/buffer.py

@@ -334,6 +334,20 @@ def set(self, value: numpy.ndarray) -> bool:
             )
         )
 
+    def resize(self, width: int = 0, height: int = 0) -> bool:
+        """调整图像尺寸 / Resize image
+
+        Args:
+            width: 目标宽度，0 表示按高度等比缩放 / Target width, 0 to scale by height
+            height: 目标高度，0 表示按宽度等比缩放 / Target height, 0 to scale by width
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
+        return bool(
+            Library.framework().MaaImageBufferResize(self._handle, width, height)
+        )
+
     @property
     def empty(self) -> bool:
         """判断缓冲区是否为空 / Check if buffer is empty
@@ -389,6 +403,13 @@ def _set_api_properties():
             ctypes.c_int32,
         ]
 
+        Library.framework().MaaImageBufferResize.restype = MaaBool
+        Library.framework().MaaImageBufferResize.argtypes = [
+            MaaImageBufferHandle,
+            ctypes.c_int32,
+            ctypes.c_int32,
+        ]
+
         Library.framework().MaaImageBufferIsEmpty.restype = MaaBool
         Library.framework().MaaImageBufferIsEmpty.argtypes = [MaaImageBufferHandle]
 

source/modules/MaaFramework.cppm

@@ -268,6 +268,7 @@ export using ::MaaImageBufferHeight;
 export using ::MaaImageBufferChannels;
 export using ::MaaImageBufferType;
 export using ::MaaImageBufferSetRawData;
+export using ::MaaImageBufferResize;
 export using ::MaaImageBufferGetEncoded;
 export using ::MaaImageBufferGetEncodedSize;
 export using ::MaaImageBufferSetEncoded;

test/python/binding_test.py

@@ -45,6 +45,7 @@
 from maa.toolkit import Toolkit
 from maa.custom_action import CustomAction
 from maa.custom_recognition import CustomRecognition
+from maa.buffer import ImageBuffer
 from maa.define import MaaDbgControllerTypeEnum, LoggingLevelEnum
 from maa.context import Context, ContextEventSink
 from maa.event_sink import EventSink
@@ -408,6 +409,28 @@ def test_controller_api():
     return dbg_controller
 
 
+# ============================================================================
+# Buffer API 测试
+# ============================================================================
+
+
+def test_buffer_api():
+    print("\n=== test_buffer_api ===")
+
+    buf = ImageBuffer()
+    src = numpy.zeros((100, 200, 3), dtype=numpy.uint8)
+    assert buf.set(src), "set should succeed"
+
+    # 仅指定宽度，按比例缩放高度
+    assert buf.resize(50, 0), "resize should succeed"
+    resized = buf.get()
+    print(f"  resized shape: {resized.shape}")
+    assert resized.shape[1] == 50, "width should be 50"
+    assert resized.shape[0] == 25, "height should keep aspect ratio"
+
+    print("  PASS: buffer API")
+
+
 # ============================================================================
 # Tasker API 测试
 # ============================================================================
@@ -688,6 +711,7 @@ def test_toolkit():
     # 测试各模块 API
     resource = test_resource_api()
     controller = test_controller_api()
+    test_buffer_api()
     tasker = test_tasker_api(resource, controller)
 
     # 验证自定义识别和动作被调用