API 参考

您正在查看最新版本（V2.2.1）的文档。如果您想查阅其他版本的文档，可以点击页面右上角“切换版本”按钮进行切换。

■ 如果您不确定当前使用的产品是哪个版本，请随时联系梅卡曼德技术支持。

Mech-Vision SDK 提供以下核心类，用于管理视觉方案、工程和步骤的完整生命周期。

核心类概览

类名说明

类名	说明
`Solution`	管理视觉方案的生命周期，包括打开、关闭、保存、重命名方案，以及获取方案信息、工程信息、相机信息、通信配置等。
`Project`	管理视觉工程，包括保存工程、运行/停止工程、获取输出数据、固定步骤输出端口等，并支持注册运行状态和采集完成回调。
`Step`	管理视觉工程中的单个步骤，包括获取步骤信息、读取/写入步骤参数（JSON 格式）、独立执行步骤、获取步骤输出数据等。
`ErrorStatus`	统一的错误状态结构，包含操作结果的错误码（`code`）和描述信息（`description`），并提供 `ok()` 方法判断是否成功。

Solution

管理视觉方案的生命周期，包括打开、关闭、保存、重命名方案，以及获取方案信息、工程信息、相机信息、通信配置等。

Project

管理视觉工程，包括保存工程、运行/停止工程、获取输出数据、固定步骤输出端口等，并支持注册运行状态和采集完成回调。

Step

管理视觉工程中的单个步骤，包括获取步骤信息、读取/写入步骤参数（JSON 格式）、独立执行步骤、获取步骤输出数据等。

ErrorStatus

统一的错误状态结构，包含操作结果的错误码（code）和描述信息（description），并提供 ok() 方法判断是否成功。

Solution 类

常用方法

方法签名返回值说明

方法签名	返回值	说明
`open(path, username, password)`	`ErrorStatus`	打开指定路径的方案。`username` 和 `password` 为可选参数（无访问控制时留空）。
`close(discardChanges=true)`	`ErrorStatus`	关闭已打开的方案。`discardChanges=true` 时强制关闭并丢弃未保存的更改。
`save()`	`ErrorStatus`	保存当前方案。
`rename(name)`	`ErrorStatus`	重命名方案（同时重命名方案目录）。重命名操作之间需间隔一段时间。
`getInfo(info)`	`ErrorStatus`	获取方案基本信息，输出至 `SolutionInfo` 结构体。
`getAllProjectInfos(projectInfos)`	`ErrorStatus`	获取方案中所有工程的信息列表，输出至 `vector<ProjectInfo>`。

open(path, username, password)

ErrorStatus

打开指定路径的方案。username 和 password 为可选参数（无访问控制时留空）。

close(discardChanges=true)

ErrorStatus

关闭已打开的方案。discardChanges=true 时强制关闭并丢弃未保存的更改。

save()

ErrorStatus

保存当前方案。

rename(name)

ErrorStatus

重命名方案（同时重命名方案目录）。重命名操作之间需间隔一段时间。

getInfo(info)

ErrorStatus

获取方案基本信息，输出至 SolutionInfo 结构体。

getAllProjectInfos(projectInfos)

ErrorStatus

获取方案中所有工程的信息列表，输出至 vector<ProjectInfo>。

SolutionInfo 结构体

struct SolutionInfo {
    std::string name;       // Solution name
    std::string path;       // Absolute path of the solution directory
    std::string version;    // Solution version
    bool hasChanges;        // Whether there are unsaved changes
    bool isRunning;         // Whether it is currently running
};

Project 类

常用方法

方法签名返回值说明

方法签名	返回值	说明
`Project(name)`	—	构造函数，传入工程名称。
`getInfo(info)`	`ErrorStatus`	获取工程基本信息，输出至 `ProjectInfo` 结构体。
`save()`	`ErrorStatus`	保存工程。
`run(state, requestId, projectResult)`	`ErrorStatus`	运行工程。`state` 可为 `OutputFinished`（等待输出步骤完成）或 `Finished`（等待整个工程完成）。
`stopRun()`	`ErrorStatus`	停止正在运行的工程。
`getOutput(outputJson)`	`ErrorStatus`	获取工程的输出数据（JSON 字符串）。
`pinStepOutput(stepPorts)`	`ErrorStatus`	固定指定步骤的输出端口数据，防止工程运行结束后数据被丢弃。
`setRunningChangedCallback(cb)`	`void`	注册工程运行状态变化回调（工程开始/结束时触发）。
`setCaptureFinishedCallback(cb)`	`void`	注册工程采集完成回调（所有采集步骤执行完成后触发）。

Project(name)

—

构造函数，传入工程名称。

getInfo(info)

ErrorStatus

获取工程基本信息，输出至 ProjectInfo 结构体。

save()

ErrorStatus

保存工程。

run(state, requestId, projectResult)

ErrorStatus

运行工程。state 可为 OutputFinished（等待输出步骤完成）或 Finished（等待整个工程完成）。

stopRun()

ErrorStatus

停止正在运行的工程。

getOutput(outputJson)

ErrorStatus

获取工程的输出数据（JSON 字符串）。

pinStepOutput(stepPorts)

ErrorStatus

固定指定步骤的输出端口数据，防止工程运行结束后数据被丢弃。

setRunningChangedCallback(cb)

void

注册工程运行状态变化回调（工程开始/结束时触发）。

setCaptureFinishedCallback(cb)

void

注册工程采集完成回调（所有采集步骤执行完成后触发）。

ProjectInfo 结构体

struct ProjectInfo {
    int id;               // Unique project ID
    std::string name;     // Project name
    std::string path;     // Absolute path of the project file
    bool hasChanges;      // Whether there are unsaved changes
    bool isRegistered;    // Whether it is registered
    bool isRunning;       // Whether it is currently running
};

ProjectResult 结构体

struct ProjectResult {
    std::string projectName; // Project name
    std::string requestId;   // Unique identifier for this run
    int64_t jobId;           // Project run task ID
    std::string outputJson;  // Output data in JSON format (pick point pose and so on)
};

Step 类

常用方法

方法签名返回值说明

方法签名	返回值	说明
`Step(name, projectName)`	—	构造函数，传入步骤名称和所属工程名称。
`getInfo(info)`	`ErrorStatus`	获取步骤基本信息，输出至 `StepInfo` 结构体。
`getPropertiesJson(namesJson, propsJson)`	`ErrorStatus`	根据参数名 JSON 数组获取步骤参数。`namesJson` 格式如 `["threshold"]`。
`setPropertiesJson(propsJson)`	`ErrorStatus`	通过 JSON 字符串批量设置步骤参数。
`run(requestId, stepResult)`	`ErrorStatus`	独立执行该步骤（从头运行至此步骤）。
`getOutput(portIndex, stepOutput)`	`ErrorStatus`	获取指定端口的步骤输出数据（需先调用 `Project::pinStepOutput()` 固定端口）。

Step(name, projectName)

—

构造函数，传入步骤名称和所属工程名称。

getInfo(info)

ErrorStatus

获取步骤基本信息，输出至 StepInfo 结构体。

getPropertiesJson(namesJson, propsJson)

ErrorStatus

根据参数名 JSON 数组获取步骤参数。namesJson 格式如 ["threshold"]。

setPropertiesJson(propsJson)

ErrorStatus

通过 JSON 字符串批量设置步骤参数。

run(requestId, stepResult)

ErrorStatus

独立执行该步骤（从头运行至此步骤）。

getOutput(portIndex, stepOutput)

ErrorStatus

获取指定端口的步骤输出数据（需先调用 Project::pinStepOutput() 固定端口）。

StepInfo 结构体

struct StepInfo {
    std::string guid; // Step GUID
    std::string name; // Step name
};

ErrorStatus 结构体

所有 SDK 方法均返回 ErrorStatus，包含以下字段：

struct ErrorStatus {
    std::string code;        // Error code (for example, "SUCCESS" or "-E_FILE_IO_ERROR")
    std::string description; // Error description

    bool ok() const;         // Whether successful (code == "SUCCESS")
};

常用错误码

错误码含义

错误码	含义
`E_SUCCESS`	操作成功
`E_INTERNAL`	内部错误（工程服务未注册等）
`E_FILEIO`	文件 I/O 错误（路径不存在、保存失败等）
`E_INVALID_PARAM`	非法参数（参数为空或格式不正确）
`E_NOT_COMPATIBLE`	版本不兼容
`E_PERMISSION_DENIED`	权限不足
`E_SOLUTION_NOT_FOUND`	方案未打开
`E_SOLUTION_LOGIN_FAILED`	方案用户名或密码错误
`E_PROJECT_NOT_FOUND`	工程未找到
`E_PROJECT_RUNNING`	工程正在运行，无法执行该操作
`E_PROJECT_EXEC_INSTANCE_OVERFLOW`	运行中的工程任务数超出上限
`E_STEP_NOT_FOUND`	步骤不存在
`E_STEP_INVALID_PROPERTY`	步骤参数名不存在或参数值类型不匹配
`E_RECIPE_NAME_NOT_FOUND`	指定的参数配方名称不存在
`E_GLOBAL_VARIABLE_NOT_FOUND`	全局变量不存在
`E_GLOBAL_VARIABLE_TYPE_MISMATCH`	全局变量类型不匹配

E_SUCCESS

操作成功

E_INTERNAL

内部错误（工程服务未注册等）

E_FILEIO

文件 I/O 错误（路径不存在、保存失败等）

E_INVALID_PARAM

非法参数（参数为空或格式不正确）

E_NOT_COMPATIBLE

版本不兼容

E_PERMISSION_DENIED

权限不足

E_SOLUTION_NOT_FOUND

方案未打开

E_SOLUTION_LOGIN_FAILED

方案用户名或密码错误

E_PROJECT_NOT_FOUND

工程未找到

E_PROJECT_RUNNING

工程正在运行，无法执行该操作

E_PROJECT_EXEC_INSTANCE_OVERFLOW

运行中的工程任务数超出上限

E_STEP_NOT_FOUND

步骤不存在

E_STEP_INVALID_PROPERTY

步骤参数名不存在或参数值类型不匹配

E_RECIPE_NAME_NOT_FOUND

指定的参数配方名称不存在

E_GLOBAL_VARIABLE_NOT_FOUND

全局变量不存在

E_GLOBAL_VARIABLE_TYPE_MISMATCH

全局变量类型不匹配

全局函数

函数签名说明

函数签名	说明
`void initialize(configFilePath={})`	初始化 SDK。可传入 JSON 配置文件路径；不传则使用默认配置。程序启动时必须首先调用。
`void uninitialize()`	反初始化 SDK，释放所有资源。程序退出前必须调用。
`bool startServer(serverPath={})`	通过 SDK 启动Mech-Vision。
`bool closeServer()`	关闭通过 SDK 启动的Mech-Vision。

void initialize(configFilePath={})

初始化 SDK。可传入 JSON 配置文件路径；不传则使用默认配置。程序启动时必须首先调用。

void uninitialize()

反初始化 SDK，释放所有资源。程序退出前必须调用。

bool startServer(serverPath={})

通过 SDK 启动Mech-Vision。

bool closeServer()

关闭通过 SDK 启动的Mech-Vision。

该页面是否有帮助？

我要反馈

感谢您的支持！

可以通过以下方式反馈意见：

我们重视您的隐私

我们使用 cookie 为您在我们的网站上提供最佳体验。继续使用该网站即表示您同意使用 cookie。如果您拒绝，将使用一个单独的 cookie 来确保您在访问本网站时不会被跟踪或记住。

同意

不同意