OLA 文档中心

主题

2026-06-18

生成鼠标渐开线随机移动轨迹 - GenerateInvoluteMouseTrajectory ​

函数简介 ​

以指定坐标为 中心点，在半径范围内生成 渐开线式随机游走 轨迹点数组，模拟人在区域内自然晃动的鼠标路径，供二次开发预览、分析或自行按点回放。

与 GenerateMouseTrajectory 的区别：GenerateMouseTrajectory 生成 起点到终点 的定向轨迹，并受 SetConfig 中真实鼠标轨迹配置控制；本接口以 中心 + 半径 生成 区域内随机游走，曲率与扰动由调用参数直接指定，不依赖 EnableRealMouse 等配置项。

与 MoveTo 的关系：本接口只 生成数据、不移动鼠标。回放时需自行逐步调用 MoveToWithoutSimulator 或 MoveR，详见下文 回放轨迹数据。

返回数据结构（JSON 数组，每个元素为一个轨迹点）：

json
[
  {"x": 512, "y": 398},
  {"x": 518, "y": 405},
  {"x": 521, "y": 412}
]
字段名类型说明
x整数该点绝对 X 坐标。
y整数该点绝对 Y 坐标。

接口名称 ​

GenerateInvoluteMouseTrajectory

DLL调用 ​

c
long GenerateInvoluteMouseTrajectory(long ola, int startX, int startY, int radius, int stepDistance, double curvature, double noiseAmplitude);

参数说明 ​

参数名类型说明
ola长整数型OLAPlug对象的指针，由 CreateCOLAPlugInterFace 接口生成。
startX整数型起点X坐标（中心点）。
startY整数型起点Y坐标（中心点）。
radius整数型移动半径范围（像素）。
stepDistance整数型轨迹点之间的距离（像素，建议3-10，0表示自动计算为5）。
curvature双精度浮点数曲率系数（0.5-2.0，越大越弯曲，默认1.0）。
noiseAmplitude双精度浮点数随机扰动幅度（0-5像素，默认2.0）。

参数详细说明 ​

stepDistance（步距）：

  • 精细模式：3-5像素，轨迹平滑但点数多。
  • 标准模式：5-8像素，平衡性能和效果。
  • 快速模式：8-10像素，点数少但可能不够平滑。
  • 传入0时自动使用默认值5像素。

curvature（曲率系数）：

  • 0.5：轻微弯曲，接近直线。
  • 1.0：标准弯曲（推荐）。
  • 1.5-2.0：高度弯曲，更自然随机。

noiseAmplitude（扰动幅度）：

  • 0-1.0：轻微抖动。
  • 1.0-3.0：标准抖动，模拟人手（推荐）。
  • 3.0-5.0：明显抖动。

如何设置轨迹参数 ​

本接口参数在 调用时直接传入，无需通过 SetConfig 配置。可按场景选用下列组合：

标准模式（推荐） ​

以按钮中心 (500, 400) 为圆心，在半径 120 像素内自然晃动，步距 5、标准曲率与扰动：

python
# 中心 (500,400)，半径 120，步距 5，曲率 1.0，扰动 2.0
result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0)

精细模式 ​

需要更平滑、点更密时，减小步距并降低扰动：

csharp
// 步距 3、轻微曲率与抖动，适合小控件悬停
var result = ola.GenerateInvoluteMouseTrajectory(500, 400, 80, 3, 0.8, 1.0);

快速模式 ​

点数较少、移动更快时，增大步距：

python
# 步距 8、步距传 0 时内部默认 5
result = ola.GenerateInvoluteMouseTrajectory(500, 400, 150, 8, 1.0, 2.0)

高随机模式 ​

需要路径更弯曲、抖动更明显时：

csharp
var result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.8, 3.5);

示例 ​

SDK 调用 ​

cpp
#include "OLAPlugServer.h"

OLAPlugServer ola;
// 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
auto result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0);
csharp
using OLAPlug;

var ola = new OLAPlugServer();
// 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
var result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0);
python
from OLAPlugServer import OLAPlugServer

ola = OLAPlugServer()
# 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0)
java
import com.olaplug.OLAPlugServer;

OLAPlugServer ola = new OLAPlugServer();
// 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
var result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0);
cpp
var ola = com("OlaPlug.OlaSoft")
var result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0)
vbscript
Set ola = CreateObject("OlaPlug.OlaSoft")
result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0)
text
.局部变量 ola, OLAPlug
ola.创建 ()
result ＝ ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0)
aardio
import OLAPlugServer;
var ola = OLAPlugServer();
var result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0);
text
变量 ola <类型 = OLAPlugServer>
ola = 新建 OLAPlugServer
自动 result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0)
cpp
#include "OLAPlugServer.h"

OLAPlugServer ola;
// 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
auto result = ola.GenerateInvoluteMouseTrajectory(500, 400, 120, 5, 1.0, 2.0);

原生 DLL 调用 ​

cpp
long instance = CreateCOLAPlugInterFace();
// 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
long ptr = GenerateInvoluteMouseTrajectory(instance, 500, 400, 120, 5, 1.0, 2.0);
if (ptr != 0) {
    char buffer[512] = {0};
    GetStringFromPtr(ptr, buffer, sizeof(buffer));
    FreeStringPtr(ptr);
}
csharp
using System.Runtime.InteropServices;
using System.Text;

[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern long CreateCOLAPlugInterFace();
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int GetStringFromPtr(long ptr, StringBuilder lpString, int size);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int FreeStringPtr(long ptr);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int GetStringSize(long ptr);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern long GenerateInvoluteMouseTrajectory(long ola, int startX, int startY, int radius, int stepDistance, double curvature, double noiseAmplitude);

long instance = CreateCOLAPlugInterFace();
// 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
long ptr = GenerateInvoluteMouseTrajectory(instance, 500, 400, 120, 5, 1.0, 2.0);
if (ptr != 0) {
    StringBuilder sb = new StringBuilder(GetStringSize(ptr) + 1);
    GetStringFromPtr(ptr, sb, sb.Capacity);
    FreeStringPtr(ptr);
    string result = sb.ToString();
}
python
from ctypes import CDLL, c_int, c_int64, c_double, create_string_buffer

ola = CDLL("OLAPlug_x64.dll")
ola.CreateCOLAPlugInterFace.restype = c_int64
ola.GenerateInvoluteMouseTrajectory.argtypes = [c_int64, c_int, c_int, c_int, c_int, c_double, c_double]
instance = ola.CreateCOLAPlugInterFace()
# 以 (500, 400) 为中心，半径 120 像素内生成渐开线随机轨迹
ptr = ola.GenerateInvoluteMouseTrajectory(instance, 500, 400, 120, 5, 1.0, 2.0)
if ptr:
    buf = create_string_buffer(ola.GetStringSize(ptr) + 1)
    ola.GetStringFromPtr(ptr, buf, len(buf))
    ola.FreeStringPtr(ptr)
    result = buf.value.decode("utf-8")

回放轨迹数据 ​

生成结果为 JSON 字符串（SDK 直接返回字符串；原生 DLL 需先用 GetStringFromPtr 读取）。与 GenerateMouseTrajectory 不同，本接口返回的点 仅含 x、y，不含 time 字段，回放时需自行控制步间延时。

回放要点：

  1. 先关闭内置轨迹：回放时若仍开启 EnableRealMouse，每步 MoveTo 会再次生成轨迹，导致路径变形。建议回放前 SetConfigByKey("EnableRealMouse", "False")，或逐步使用 MoveToWithoutSimulator / MoveR。
  2. 自行设置步间延时：可用固定间隔（如 8～15 毫秒）调用 Delay，模拟自然移动节奏；步距越小、延时越短，移动越流畅。
  3. 两种回放方式：
    • 绝对坐标：用每点的 x、y 定位（MoveToWithoutSimulator）。
    • 相对偏移：根据相邻两点坐标差计算 deltaX、deltaY，逐步调用 MoveR（调用前光标应在轨迹起点附近）。
python
import json
from OLAPlugServer import OLAPlugServer

ola = OLAPlugServer()
ola.SetConfigByKey("EnableRealMouse", "False")  # 回放时关闭内置轨迹

center_x, center_y = 500, 400
json_str = ola.GenerateInvoluteMouseTrajectory(center_x, center_y, 120, 5, 1.0, 2.0)
points = json.loads(json_str)

delay_ms = 10  # 步间延时，可按需调整

# 方式一：绝对坐标 + MoveToWithoutSimulator
for pt in points:
    ola.MoveToWithoutSimulator(pt["x"], pt["y"])
    ola.Delay(delay_ms)

# 方式二：相对偏移 + MoveR（调用前光标应在 center_x, center_y 附近）
# prev_x, prev_y = center_x, center_y
# for pt in points:
#     ola.MoveR(pt["x"] - prev_x, pt["y"] - prev_y)
#     prev_x, prev_y = pt["x"], pt["y"]
#     ola.Delay(delay_ms)
csharp
using System.Text.Json;
using OLAPlug;

var ola = new OLAPlugServer();
ola.SetConfigByKey("EnableRealMouse", "False");

int centerX = 500, centerY = 400;
var json = ola.GenerateInvoluteMouseTrajectory(centerX, centerY, 120, 5, 1.0, 2.0);
using var doc = JsonDocument.Parse(json);

const int delayMs = 10;
foreach (var pt in doc.RootElement.EnumerateArray())
{
    ola.MoveToWithoutSimulator(pt.GetProperty("x").GetInt32(), pt.GetProperty("y").GetInt32());
    ola.Delay(delayMs);
}
cpp
#include "OLAPlugServer.h"
#include <nlohmann/json.hpp>  // 或任意 JSON 库

OLAPlugServer ola;
ola.SetConfigByKey("EnableRealMouse", "False");

const int centerX = 500, centerY = 400;
auto jsonStr = ola.GenerateInvoluteMouseTrajectory(centerX, centerY, 120, 5, 1.0, 2.0);
auto points = nlohmann::json::parse(jsonStr);

const int delayMs = 10;
for (const auto& pt : points) {
    ola.MoveToWithoutSimulator(pt["x"], pt["y"]);
    ola.Delay(delayMs);
}
python
import json
from ctypes import CDLL, c_int, c_int64, c_double, create_string_buffer

ola = CDLL("OLAPlug_x64.dll")
ola.CreateCOLAPlugInterFace.restype = c_int64
ola.GenerateInvoluteMouseTrajectory.argtypes = [c_int64, c_int, c_int, c_int, c_int, c_double, c_double]
instance = ola.CreateCOLAPlugInterFace()

ptr = ola.GenerateInvoluteMouseTrajectory(instance, 500, 400, 120, 5, 1.0, 2.0)
buf = create_string_buffer(ola.GetStringSize(ptr) + 1)
ola.GetStringFromPtr(ptr, buf, len(buf))
ola.FreeStringPtr(ptr)
points = json.loads(buf.value.decode("utf-8"))

ola.SetConfigByKey(instance, "EnableRealMouse", "False")
for pt in points:
    ola.MoveToWithoutSimulator(instance, pt["x"], pt["y"])
    ola.Delay(instance, 10)

典型场景：在按钮或图标附近 悬停晃动 若干秒后再点击，可循环调用本接口生成新轨迹并回放，每次路径均不同，拟人效果更好。

若只需 直接移动到目标点，可跳过本接口，使用 MoveTo（内置轨迹）或 MoveToWithoutSimulator（瞬移）。

返回值 ​

返回值说明
（返回值）字符串指针地址，包含JSON格式的轨迹点数组数据。返回 0 表示失败。

注意事项 ​

项目说明
释放内存DLL调用返回字符串指针地址，需要调用 FreeStringPtr 接口释放内存。
随机性每次调用生成的路径 不同（含随机扰动），适合模拟悬停晃动；需要可复现路径时请自行保存 JSON 结果。
中心与半径startX、startY 为游走区域的 中心点，radius 为最大偏移范围（像素）；轨迹点会分布在该圆形区域内。
与 SetConfig 无关曲率、步距、扰动由本接口参数控制，不受 EnableRealMouse、RealMouseMode 等配置影响。
回放时关闭内置轨迹按点回放前建议将 EnableRealMouse 设为 false，或使用 MoveToWithoutSimulator / MoveR，避免每步再次生成轨迹。