菜单

fixSharedMemoryDll — API 参考

作者: JT下载

fixSharedMemoryDll — API 参考

纯 C 接口，与 FIX 检测软件通过共享内存通信。支持同步/异步两种模式。

当前版本：2.1.0。2.1 新增“体数据 + ROI/config JSON”接口，旧导出保持 ABI 兼容。

工作流程、返回格式、configJson 参数等业务层说明见 fixSDK_README.md。

环境要求

Windows x64
FIX 检测软件已启动
编译：#include "fixSharedMemory_api.h"，链接 fixSharedMemoryDll.lib
运行：fixSharedMemoryDll.dll 放在 exe 同目录

数据类型

FSImageTypeC — 像素类型

值	常量	每像素字节	对应 OpenCV
1	`FS_IMAGE_C_GRAY8`	1	CV_8UC1
2	`FS_IMAGE_C_GRAY16U`	2	CV_16UC1
3	`FS_IMAGE_C_GRAY16S`	2	CV_16SC1
4	`FS_IMAGE_C_FLOAT32`	4	CV_32FC1
5	`FS_IMAGE_C_RGB24`	3	CV_8UC3
6	`FS_IMAGE_C_RGBA32`	4	CV_8UC4

FSTaskStatusC — 任务状态码

值	常量	说明
100	`FS_TASK_C_STARTED`	任务已开始
101	`FS_TASK_C_PROGRESS`	进度更新
200	`FS_TASK_C_COMPLETED`	完成，有数据返回
201	`FS_TASK_C_COMPLETED_NODATA`	完成，无数据返回
400	`FS_TASK_C_FAILED`	处理失败
401	`FS_TASK_C_CANCELLED`	被取消
408	`FS_TASK_C_TIMEOUT`	等待超时

FSApiError — API 返回码

值	常量	说明
0	`FS_API_OK`	成功
-1	`FS_API_ERROR_INVALID_HANDLE`	无效句柄 (NULL)
-2	`FS_API_ERROR_NOT_CONNECTED`	未连接到服务端
-3	`FS_API_ERROR_INVALID_PARAM`	参数无效 (NULL 数据或零维度)
-4	`FS_API_ERROR_SEND_FAILED`	发送失败
-5	`FS_API_ERROR_TIMEOUT`	等待超时
-6	`FS_API_ERROR_INTERNAL`	内部错误
-7	`FS_API_ERROR_VERSION_MISMATCH`	协议版本不匹配

FSResultC — 同步调用结果

c 复制代码

typedef struct FSResultC {
    uint32_t taskStatus;   /* FSTaskStatusC */
    uint32_t requestId;
    double   progress;
    int64_t  elapsedMs;
} FSResultC;

FSVolumeInfoC — 体数据信息

c 复制代码

typedef struct FSVolumeInfoC {
    uint32_t width, height, depth;
    int      imageType;    /* FSImageTypeC */
    double   voxelSizeX, voxelSizeY, voxelSizeZ;  /* mm */
    size_t   dataSize;     /* 体数据字节数 */
} FSVolumeInfoC;

回调函数类型

c 复制代码

/* 进度回调 */
typedef void (*FSProgressFunc)(uint32_t requestId, const char* dataName,
                               double progress, const char* message,
                               void* userData);

/* 完成回调 */
typedef void (*FSCompletionFunc)(uint32_t requestId, const char* dataName,
                                uint32_t taskStatus, const char* message,
                                int64_t elapsedMs, void* userData);

/* 体数据回调 */
typedef void (*FSVolumeDataFunc)(uint32_t requestId, const char* dataName,
                                 const void* volumeData,
                                 const FSVolumeInfoC* volumeInfo,
                                 void* userData);

所有回调在 DLL 内部线程触发，回调内不要进行耗时操作。dataName 是发送时传入的数据名称，方便回调中识别是哪个数据的结果。体数据指针仅在回调期间有效，如需保留请在回调内复制。

API 函数

生命周期

`fsChannelCreate`

c 复制代码

FSChannelHandle fsChannelCreate(const char* serverName);

创建通道并连接到 FIX 服务端。失败返回 NULL（如 FIX 未运行）。

serverName：共享内存名称，传 NULL 使用默认值 "FIXSharedMemory"
重连方式：fsChannelDestroy 后重新 fsChannelCreate

`fsChannelDestroy`

c 复制代码

void fsChannelDestroy(FSChannelHandle handle);

销毁通道，释放所有资源。传 NULL 安全无操作。

`fsChannelIsConnected`

c 复制代码

int fsChannelIsConnected(FSChannelHandle handle);

返回 1 已连接，0 未连接。

同步 API

`fsChannelSendVolumeAndWait`

c 复制代码

int fsChannelSendVolumeAndWait(
    FSChannelHandle handle,
    const void* data,          /* 体数据指针 */
    const char* dataName,      /* 数据名称标识 */
    const char* teachingFile,  /* 教学文件 (NULL = 无) */
    const char* resultPath,    /* 结果保存路径 */
    uint32_t width, uint32_t height, uint32_t depth,
    int imageType,             /* FSImageTypeC */
    double voxelSizeX, double voxelSizeY, double voxelSizeZ,  /* mm */
    uint32_t timeoutMs,        /* 超时毫秒 (0 = 默认 60000) */
    FSResultC* outResult,      /* [out] 可 NULL */
    char* outMsg, size_t msgBufSize  /* [out] 消息缓冲, 可 NULL */
);

发送已重建的体数据并阻塞等待 FIX 检测完成。返回 FS_API_OK / 负数错误码。

`fsChannelSendVolumeWithConfigAndWait`（2.1）

c 复制代码

int fsChannelSendVolumeWithConfigAndWait(
    FSChannelHandle handle,
    const void* data,
    const char* dataName,
    const char* teachingFile,  /* 例如 PCBTraining，不带 .fixt */
    const char* resultPath,
    const char* configJson,    /* 检测 ROI / drilling depth / _metadata */
    uint32_t width, uint32_t height, uint32_t depth,
    int imageType,
    double voxelSizeX, double voxelSizeY, double voxelSizeZ,
    uint32_t timeoutMs,
    FSResultC* outResult,
    char* outMsg, size_t msgBufSize
);

用于“客户传入已重建体 + 模型教学文件 + 本次检测 ROI”。configJson 与投影接口使用同一 ROI/config 格式。NULL 保持旧 Volume 路径；DLL 会严格校验 JSON object（含 UTF-8、转义、嵌套结构及有限数值范围），非法或非 object JSON 返回 FS_API_ERROR_INVALID_PARAM。outMsg 必须容纳本次配置选择的公共响应；returnJsonReport=true 时即为完整检测 JSON。缓冲区不足返回 FS_API_ERROR_INTERNAL，不能把截断内容当成有效 JSON。

`fsChannelSendProjectionAndWait`

c 复制代码

int fsChannelSendProjectionAndWait(
    FSChannelHandle handle,
    const void* data,
    const char* dataName,
    const char* teachingFile,
    const char* resultPath,
    const char* reconConfigJson,   /* 重建配置 JSON (NULL = 无) */
    uint32_t width, uint32_t height, uint32_t depth,
    int imageType,
    double voxelSizeX, double voxelSizeY, double voxelSizeZ,
    uint32_t timeoutMs,            /* 0 = 默认 120000 */
    FSResultC* outResult,
    char* outMsg, size_t msgBufSize,
    void* outVolumeData,           /* [out] 体数据缓冲 (NULL = 不需要) */
    size_t outVolumeSize,          /* 缓冲区大小 */
    FSVolumeInfoC* outVolumeInfo   /* [out] 体数据信息, 可 NULL */
);

发送投影数据（用于 CT 重建）并阻塞等待完成。

接收重建后的体数据需要先调用 fsChannelEnableVolumeReceiver，然后传入 outVolumeData 缓冲区。

PCBHole3D 的 reconConfig 契约

投影接口的 reconConfigJson 与体数据接口的 configJson 使用同一份 PCBHole3D ROI 契约。教学文件可以写入根对象的 _metadata.teachingFile：

json 复制代码

{
  "_metadata": {
    "teachingFile": "PCBTraining"
  },
  "pcbHole3D": {
    "schemaVersion": 1,
    "output": {
      "returnJsonReport": false,
      "saveJsonReport": true
    }
  },
  "coordinateUnit": "pixel",
  "roi": [
    {
      "id": 1,
      "name": "Hole_1",
      "centerX": 120.5,
      "centerY": 84.0,
      "sizeX": 32.0,
      "sizeY": 32.0,
	      "functions": ["ReconROI", "StubROI"],
	      "drillSides": ["Top"],
	      "drillingDepthUnit": "mil",
      "topDrillingDepth": 8.0,
      "bottomDrillingDepth": 0.0,
      "drillingDepthTolerance": 1.0
    }
  ]
}

教学文件选择规则为：API 的 teachingFile 参数非空时优先使用；API 参数为空或 NULL 时，使用 _metadata.teachingFile。两处都未提供时只执行原有无教学文件流程。API 指定的文件无效时会按 API 错误处理，不会回退到配置中的文件。

pcbHole3D.schemaVersion 仍为整数 1。output.returnJsonReport 和
output.saveJsonReport 必须是 JSON boolean，默认分别为 false 和 true：

`returnJsonReport`	`saveJsonReport`	公共响应	磁盘
`false`	`true`	`_metadata`（含 `jsonReportPath`）+ `roi: []`	完整 `_metadata + roi` 报告
`true`	`true`	`_metadata`（含 `jsonReportPath`）+ 完整 `roi`	完整 `_metadata + roi` 报告
`true`	`false`	`_metadata` + 完整 `roi`	不写报告
`false`	`false`	`_metadata` + `roi: []`	不写报告

报告原子提交成功后，公共响应的 _metadata.jsonReportPath 才会出现。它是 FIX
运行主机视角的绝对路径；异机调用应使用双方可访问的 UNC/共享目录，或自行传输文件。
保存失败会使任务以 JSON_REPORT_WRITE_FAILED 失败，并且不返回
jsonReportPath。详细路径选择和报告字段见
../docs/PCBHole3D_上位机JSON对接说明.md。

drillSides 是可选但权威的检测方向字段，值为非空数组，可包含 "Top"、"Bottom" 或两者。字段存在时，null、空数组、重复项、未知值和非字符串项都属于无效请求；某侧钻深非零时，drillSides 必须同时包含该侧。钻深用于搜索窗口/先验，不再承担方向开关。

仅当 drillSides 缺省时，才按旧版钻深契约推导方向：

`topDrillingDepth`	`bottomDrillingDepth`	检测方向
`> 0`	`0`	Top
`0`	`> 0`	Bottom
`> 0`	`> 0`	Top + Bottom
`0`	`0`	单侧组模型使用唯一已训练侧；否则兼容 Top AutoModel

公开 ROI 契约不包含目标线路层成员。旧版配置中的此类成员会被兼容接收并静默忽略，不会改变检测方向或结果；新配置不要再生成它们。

异步 API

`fsChannelSetProgressCallback`

c 复制代码

void fsChannelSetProgressCallback(FSChannelHandle handle,
                                  FSProgressFunc callback, void* userData);

`fsChannelSetCompletionCallback`

c 复制代码

void fsChannelSetCompletionCallback(FSChannelHandle handle,
                                    FSCompletionFunc callback, void* userData);

`fsChannelSendVolumeAsync`

c 复制代码

uint32_t fsChannelSendVolumeAsync(
    FSChannelHandle handle,
    const void* data,
    const char* dataName,
    const char* teachingFile,
    const char* resultPath,
    uint32_t width, uint32_t height, uint32_t depth,
    int imageType,
    double voxelSizeX, double voxelSizeY, double voxelSizeZ
);

返回 requestId（>0 成功，0 失败）。结果通过 completion callback 返回。

`fsChannelSendVolumeWithConfigAsync`（2.1）

c 复制代码

uint32_t fsChannelSendVolumeWithConfigAsync(
    FSChannelHandle handle,
    const void* data,
    const char* dataName,
    const char* teachingFile,
    const char* resultPath,
    const char* configJson,
    uint32_t width, uint32_t height, uint32_t depth,
    int imageType,
    double voxelSizeX, double voxelSizeY, double voxelSizeZ
);

返回 requestId（>0 成功，0 参数/JSON/发送失败）。同一 handle 可由多个线程调用；DLL 会原子绑定 requestId 与数据包，completion callback 仍可能来自内部线程。

`fsChannelSendProjectionAsync`

c 复制代码

uint32_t fsChannelSendProjectionAsync(
    FSChannelHandle handle,
    const void* data,
    const char* dataName,
    const char* teachingFile,
    const char* resultPath,
    const char* reconConfigJson,
    uint32_t width, uint32_t height, uint32_t depth,
    int imageType,
    double voxelSizeX, double voxelSizeY, double voxelSizeZ
);

返回 requestId（>0 成功，0 失败）。

`fsChannelCancelRequest`

c 复制代码

void fsChannelCancelRequest(FSChannelHandle handle, uint32_t requestId);

取消等待中的异步请求（仅客户端侧取消，不通知服务端）。

体数据接收器

用于接收 FIX 重建后的体数据。调用一次后对后续所有投影请求生效。

`fsChannelEnableVolumeReceiver`

c 复制代码

int fsChannelEnableVolumeReceiver(FSChannelHandle handle, size_t volumeDataSize);

volumeDataSize：预期体数据字节数（如 512*512*512*2），DLL 自动加上协议开销。传 0 关闭并释放接收器。

`fsChannelSetVolumeCallback`

c 复制代码

void fsChannelSetVolumeCallback(FSChannelHandle handle,
                                FSVolumeDataFunc callback, void* userData);

设置异步模式下的体数据回调。传 NULL 清除。

状态查询

`fsChannelGetLastError`

c 复制代码

const char* fsChannelGetLastError(FSChannelHandle handle);

返回最近一次错误消息。线程安全。返回的指针在下次 API 调用后可能失效，需尽快复制。

`fsChannelPendingCount`

c 复制代码

size_t fsChannelPendingCount(FSChannelHandle handle);

当前等待中的异步请求数。

`fsGetVersion`

c 复制代码

const char* fsGetVersion(void);

DLL 版本号字符串（当前为 "2.1.0"）。

代码示例

同步发送体数据

c 复制代码

FSChannelHandle ch = fsChannelCreate(NULL);
if (!ch) { /* FIX 未运行 */ return; }

FSResultC result = {0};
char msg[512] = {0};

int ret = fsChannelSendVolumeAndWait(
    ch, volumeData, "my_volume", "PCB1.tch", "C:\\Results",
    512, 512, 100, FS_IMAGE_C_GRAY16U,
    0.05, 0.05, 0.05,
    60000, &result, msg, sizeof(msg));

if (ret == FS_API_OK)
    printf("完成, 耗时 %lld ms, 消息: %s\n", result.elapsedMs, msg);

fsChannelDestroy(ch);

同步发送体数据 + PCB Hole 3D 检测 ROI

c 复制代码

FSChannelHandle ch = fsChannelCreate(NULL);
FSResultC result = {0};

/* 默认只返回元数据、报告路径和 roi:[]。
 * 若配置 returnJsonReport=true，应按最大 ROI 数预留足够空间。 */
char* resultJson = (char*)malloc(1024 * 1024);
int ret = fsChannelSendVolumeWithConfigAndWait(
    ch, volumeData, "board_001", "PCBTraining", NULL,
    roiConfigJson,
    2400, 2400, 710, FS_IMAGE_C_GRAY16U,
    0.01, 0.01, 0.01,
    300000, &result, resultJson, 1024 * 1024);

if (resultJson[0] != '\0') {
    /* 即使 ret 是任务失败码，也应先严格解析 JSON 并读取 _metadata。 */
    printf("%s\n", resultJson);
}
free(resultJson);
fsChannelDestroy(ch);

PCB Hole 3D 的公共响应根级固定只有 _metadata 和 roi。默认
returnJsonReport=false、saveJsonReport=true，因此成功响应只返回元数据、完整
报告路径和空 ROI：

json 复制代码

{
  "_metadata": {
    "application": "FIX Inspection",
    "dataName": "board_001",
    "teachingFile": "PCBTraining",
    "elapsedMs": 1234,
    "status": "OK",
    "jsonReportPath": "D:/results/board_001-pcbhole3d-report-r42-a1b2c3d4.json"
  },
  "roi": []
}

空 roi 是默认行为，不表示没有完成检测。jsonReportPath 指向的磁盘文件包含完整
_metadata 和 roi；它是 FIX 主机视角的绝对路径，异机客户端需要使用约定的
UNC/共享目录或自行传输。完整报告中的 roi[] 与请求顺序一致，先回填公开 ROI
字段（包括客户提交的 id），再为每个 ROI 增加 result。设置
returnJsonReport=true 时，下列完整结构也会在公共响应中内联：

json 复制代码

{
  "_metadata": {
    "application": "FIX Inspection",
    "dataName": "board_001",
    "teachingFile": "PCBTraining",
    "elapsedMs": 1234,
    "status": "OK"
  },
  "roi": [
    {
      "id": 101,
      "name": "H1",
      "coordinateUnit": "pixel",
      "centerX": 120.5,
      "centerY": 84.0,
      "sizeX": 32.0,
      "sizeY": 32.0,
      "functions": ["ReconROI", "StubROI"],
      "drillingDepthUnit": "mil",
      "topDrillingDepth": 8.0,
      "bottomDrillingDepth": 0.0,
      "result": {
        "status": "OK",
        "direction": "top",
        "top": {
          "stubMax": {
            "value": 3.8,
            "unit": "mil",
            "ngThreshold": { "operator": ">", "value": 5.0, "unit": "mil" },
            "status": "OK"
          },
          "stubMin": { "value": 3.4, "unit": "mil", "ngThreshold": { "operator": ">", "value": 5.0, "unit": "mil" }, "status": "OK" },
          "stubHeight": { "value": 0.4, "unit": "mil", "ngThreshold": { "operator": ">", "value": 1.0, "unit": "mil" }, "status": "OK" },
          "drillingDepthMax": { "value": 8.1, "unit": "mil", "ngThreshold": { "operator": ">", "value": 10.0, "unit": "mil" }, "status": "OK" },
          "drillingDepthMin": { "value": 7.8, "unit": "mil", "ngThreshold": { "operator": ">", "value": 10.0, "unit": "mil" }, "status": "OK" },
          "remainingLengthMax": { "value": 25.0, "unit": "mil", "ngThreshold": { "operator": ">", "value": 30.0, "unit": "mil" }, "status": "OK" },
          "remainingLengthMin": { "value": 24.6, "unit": "mil", "ngThreshold": { "operator": ">", "value": 30.0, "unit": "mil" }, "status": "OK" },
          "wallMin": { "value": 0.85, "unit": "mil", "ngThreshold": { "operator": "<", "value": 0.8, "unit": "mil" }, "status": "OK" },
          "circuit": { "value": "Signal 3", "status": "OK" },
          "layer": { "value": 127, "status": "OK" },
          "confidence": { "value": 0.93, "status": "OK" },
          "tailHeight": { "value": null, "unit": "mil", "ngThreshold": { "operator": "<", "value": 5.0, "unit": "mil" }, "status": "NOT_APPLICABLE" }
        },
        "bottom": {
          "stubMax": { "value": null, "unit": "mil", "ngThreshold": { "operator": ">", "value": 5.0, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "stubMin": { "value": null, "unit": "mil", "ngThreshold": { "operator": ">", "value": 5.0, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "stubHeight": { "value": null, "unit": "mil", "ngThreshold": { "operator": ">", "value": 1.0, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "drillingDepthMax": { "value": null, "unit": "mil", "ngThreshold": { "operator": ">", "value": 10.0, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "drillingDepthMin": { "value": null, "unit": "mil", "ngThreshold": { "operator": ">", "value": 10.0, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "remainingLengthMax": { "value": null, "unit": "mil", "ngThreshold": { "operator": ">", "value": 30.0, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "remainingLengthMin": { "value": null, "unit": "mil", "ngThreshold": { "operator": ">", "value": 30.0, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "wallMin": { "value": null, "unit": "mil", "ngThreshold": { "operator": "<", "value": 0.8, "unit": "mil" }, "status": "NOT_APPLICABLE" },
          "circuit": { "value": null, "status": "NOT_APPLICABLE" },
          "layer": { "value": null, "status": "NOT_APPLICABLE" },
          "confidence": { "value": null, "status": "NOT_APPLICABLE" },
          "tailHeight": { "value": 12.0, "unit": "mil", "ngThreshold": { "operator": "<", "value": 5.0, "unit": "mil" }, "status": "OK" }
        }
      }
    }
  ]
}

result.status 为 OK、NG 或 ERROR。量测完成但超限为 NG；定位或量测未完成为
ERROR，详情位于该 ROI 的 result.errors[]。top、bottom 固定包含 Inspection 表的
Stub Max/Min/Height、Depth Max/Min、Rem Max/Min、Wall Min、Circuit、Layer、Conf. 和
Tail Height；不适用或未测字段分别使用 NOT_APPLICABLE、NOT_MEASURED。

长度值及 ngThreshold 使用该 ROI 的 drillingDepthUnit（mil 或允许小数的 slice）。
ngThreshold.operator 表示使该字段成为 NG 的比较条件；未启用阈值时为 null。
Wall Min 在 slice 模式下表示按 Z 层距换算的等效长度，不是电路层数量；layer 始终是
1-based 层号且没有长度单位。双向孔的 Rem Max/Min 会在两侧回填同一数值并标记
shared: true。任务级失败信息位于 _metadata.errorCode 和 _metadata.message。
请求保存完整报告但写入失败时，错误码为 JSON_REPORT_WRITE_FAILED，且不返回
_metadata.jsonReportPath。NCC 定位过程、分割、模型健康和逐切层轨迹等工程诊断
不会进入客户报告。
_metadata.status="OK" 表示任务正常完成，并不表示所有 ROI 的 result.status 都是 OK。

异步发送 + 回调

c 复制代码

void onDone(uint32_t reqId, const char* dataName, uint32_t status,
            const char* msg, int64_t ms, void* ud) {
    *(int*)ud = 1;
    printf("[%s] 请求 #%u 完成, 状态=%u, 耗时=%lld ms\n", dataName, reqId, status, ms);
}

FSChannelHandle ch = fsChannelCreate(NULL);
volatile int done = 0;
fsChannelSetCompletionCallback(ch, onDone, (void*)&done);

uint32_t reqId = fsChannelSendVolumeAsync(
    ch, volumeData, "my_volume", "PCB1.tch", "C:\\Results",
    512, 512, 100, FS_IMAGE_C_GRAY16U, 0.05, 0.05, 0.05);

while (!done) Sleep(100);  /* 主线程可做其他事 */
fsChannelDestroy(ch);

发送投影 + 接收重建体数据

c 复制代码

FSChannelHandle ch = fsChannelCreate(NULL);

/* 启用体数据接收器 */
fsChannelEnableVolumeReceiver(ch, 512*512*512*2);

/* 分配接收缓冲区 */
void* volBuf = malloc(512*512*512*2);
FSVolumeInfoC volInfo = {0};
FSResultC result = {0};
char msg[512] = {0};

int ret = fsChannelSendProjectionAndWait(
    ch, projData, "proj1", NULL, "C:\\Results",
    reconConfigJson,
    512, 512, 360, FS_IMAGE_C_GRAY16U, 0.1, 0.1, 1.0,
    120000, &result, msg, sizeof(msg),
    volBuf, 512*512*512*2, &volInfo);

if (ret == FS_API_OK && volInfo.dataSize > 0)
    printf("收到体数据: %ux%ux%u\n", volInfo.width, volInfo.height, volInfo.depth);

free(volBuf);
fsChannelDestroy(ch);

重连

c 复制代码

FSChannelHandle ch = fsChannelCreate(NULL);
if (!ch) {
    /* 等待 FIX 启动后重试 */
    Sleep(3000);
    ch = fsChannelCreate(NULL);
}
/* ... 使用 ch ... */
fsChannelDestroy(ch);

完整示例代码见 example.cpp。

注意事项

NULL 安全：所有 API 传 NULL 句柄不会崩溃，会返回错误码或空值
线程安全：所有 API 可在任意线程调用；回调在 DLL 内部线程触发
异步自动过期：异步请求如果 5 分钟内未收到 FIX 响应，自动标记为 FS_TASK_C_TIMEOUT 并触发 completion callback
体数据指针生命周期：回调中的 volumeData 指针仅在回调执行期间有效，需要保留请在回调内复制
数据内存布局：体数据为行优先连续存储，data[z * height * width + y * width + x]

通用 2D 图像处理通道（filter / infer / teach / meta）

提供单图入、单图出 + 结构化结果 JSON 的通用接口。一对协议承载所有 2D 图像处理任务，命令通过字符串前缀区分（filter.* / infer.* / teach.* / meta.*），新增命令对协议透明，客户端无需升级。

命令清单

前缀	含义	示例
`filter.*`	像素级处理（输入图 → 输出图）	`filter.{sr,sm,um,rl,pnp,clahe,hef,edgeEnhance,anisoDiffusion,gamma,exposure,bc,shadowHighlight,levels,enhance,gauss}` 单 filter + `filter.applyEffect`（直接吃 FIX 存的 .json，一次复现 UI 整套效果） —— 共 17 个，完整列表见 filter README
`infer.*`	模型推理（输入图 → 输出图 + JSON）	`infer.yolo` / `infer.seg`（接入中）
`teach.*`	教学文件检测	`teach.detect`（接入中）
`meta.*`	元命令（不需要图像）	`meta.list_commands`

paramsJson 键命名约定

为避免一个 paramsJson 同时携带多命令参数时键冲突，命令私有参数键名全部带命令前缀：

类别	命名规则	示例
命令私有参数	`<command>.<key>`	`filter.sr.scaleMode`、`filter.sr.batchHint`
通用选项开关	`option.<key>`	`option.returnImage`（与命令无关，所有 image-proc 命令共用）
channel 注入	顶层短键	`responseChannel`、`imageProcReturnChannel`（DLL 自动注入，用户无需写）

📘 filter.* 命令族完整接口手册：参见 fixSharedMemory_dll_filter_README.md（含 filter.sr 的完整 API、JSON 字段、调用示例、性能数据）。下文仅保留快速概览。

filter.sr 参数（JSON）

字段	类型	默认	说明
`filter.sr.scaleMode`	string	`"scale4"`	`"scale1"`=同尺寸增强；`"scale2"`=×2 快速档；`"scale3"`=×3 上采样；`"scale4"`=×4 上采样
`filter.sr.blendRatio`	float	1.0	Soft↔Hard 混合比例 [0,1]；0=Soft（柔和/去噪），1=Hard（锐利）
`filter.sr.tileSize`	int	1024	tile 尺寸（≥ 1024，小于该值自动提升）
`filter.sr.batchHint`	int	1	一次处理的 tile 数；服务端内存吃紧时会自动减半到 1

环境不可用：filter.sr 不可用时返回 FS_PROC_C_GPU_UNAVAIL。

batchHint 调优：scale1 推荐 4~8，scale4 推荐 2~4（×4 输出更大）；服务端内存不足时会自动减半重试，最坏退化到 batch=1。

通用选项开关（option.*）

字段	类型	默认	说明
`option.returnImage`	bool	`true`	`false` = 跳过 SHM 像素回传，仅返回 JSON 结果（适合检测/分类等不需要输出图的命令；与 `FSImageProcParamsC::resultPath` 落盘可独立或叠加）

客户端 API

c 复制代码

/* 1. 启用结果接收器（一次性）—— 大小按预期最大输出图字节数估 */
size_t maxResultBytes = 1ULL * 1024 * 1024 * 1024;  /* 1 GB；scale4 大图建议 ≥ 8 GB */
fsChannelEnableImageProcReceiver(handle, maxResultBytes);

/* 2. 同步调用（不传字段=用服务端默认：scale4 / blendRatio=1.0 / batchHint=1） */
FSImageProcParamsC params = {0};
params.command     = "filter.sr";
params.paramsJson  = "{\"filter.sr.scaleMode\":\"scale4\",\"filter.sr.blendRatio\":1.0,"
                     "\"filter.sr.tileSize\":1024,\"filter.sr.batchHint\":1}";
params.timeoutMs   = 600000;

FSImageProcResultC result = {0};
int rc = fsChannelSendImageProcAndWait(handle, &params,
    inputBgr, rows, cols, 3, FS_IMAGE_C_RGB24, rowStride, &result);

if (rc == FS_API_OK && result.procStatus == FS_PROC_C_OK) {
    /* result.outImage / outRows / outCols / outStride 已填充 */
    saveImage(result.outImage, result.outRows, result.outStride);
}
fsChannelFreeImageProcResult(&result);   /* 必须释放 */

/* 3. 异步 + 进度 */
fsChannelSetImageProcProgressCallback(handle, onProgress, userData);
fsChannelSetImageProcCompleteCallback(handle, onComplete, userData);
uint32_t reqId = fsChannelSendImageProcAsync(handle, &params,
    inputBgr, rows, cols, 3, FS_IMAGE_C_RGB24, rowStride);

处理模型

服务端 串行处理：所有图像处理任务进入同一队列，按到达先后逐个执行（避免资源争抢）
进度回调 注册即生效：调用 fsChannelSetImageProcProgressCallback 后，长任务（如 SR 分块）会持续推送 stepDone/stepTotal
取消语义：异步模式下可调 fsChannelCancelRequest(handle, reqId)；服务端在下次 progress 检查点中止任务

共享内存推荐配置

输入图像走主共享内存（sd_EC_SharedMemoryX/Y/Z），输出图像走独立的 image-proc 接收通道（由 fsChannelEnableImageProcReceiver(maxResultBytes) 创建）。

命令	输入	输出	主共享内存推荐	接收器推荐
filter.sr / scale1 / 15360×10997 BGR	483 MB	483 MB	≥ 1 GB	≥ 600 MB
filter.sr / scale2 / 15360×10997 BGR	483 MB	1.93 GB	≥ 1 GB	≥ 2 GB
filter.sr / scale4 / 15360×10997 BGR	483 MB	7.7 GB	≥ 1 GB	≥ 8 GB

主共享内存通过 fiSettings 中 sd_EC_SharedMemoryX/Y/Z 配置；不够时返回 FS_ERROR_SIZE_TOO_LARGE。

状态码（FSProcStatusC）

值	含义
0	OK
-100	未知命令
-101	JSON 参数错误
-102	图像类型/尺寸不支持
-103	`filter.sr` 服务端能力不可用（仅 filter.sr 触发）
-104	服务端内存耗尽
-105	客户端取消
-106	超时
-200	内部错误（详见 errorMsg）

FAQ

Q: FIX 重启后需要重连吗？
A: 需要。fsChannelDestroy 后重新 fsChannelCreate。

Q: 可以同时发送多个请求吗？
A: 异步模式下可以。同步模式天然是一个一个等待的。

Q: reconConfigJson 填什么？
A: JSON 字符串，包含重建参数、ROI 和 _metadata 控制参数。PCBHole3D 可在 _metadata.teachingFile 提供教学文件，API 的 teachingFile 参数优先；精简示例见上文。其他参数详见 fixSDK_README.md 的 configJson 章节。

Q: 支持哪些语言？
A: 任何能调用 C DLL 的语言：C/C++、C#（P/Invoke）、Python（ctypes/cffi）等。

上一个

FIX SDK

下一个

fixSharedMemoryDll 异步发送 API —— 返回值与错误处理对接说明

最近修改: 2026-07-23Powered by

fixSharedMemoryDll — API 参考

fixSharedMemoryDll — API 参考

环境要求

数据类型

FSImageTypeC — 像素类型

FSTaskStatusC — 任务状态码

FSApiError — API 返回码

FSResultC — 同步调用结果

FSVolumeInfoC — 体数据信息

回调函数类型

API 函数

生命周期

fsChannelCreate

fsChannelDestroy

fsChannelIsConnected

同步 API

fsChannelSendVolumeAndWait

fsChannelSendVolumeWithConfigAndWait（2.1）

fsChannelSendProjectionAndWait

PCBHole3D 的 reconConfig 契约

异步 API

fsChannelSetProgressCallback

fsChannelSetCompletionCallback

fsChannelSendVolumeAsync

fsChannelSendVolumeWithConfigAsync（2.1）

fsChannelSendProjectionAsync

fsChannelCancelRequest

体数据接收器

fsChannelEnableVolumeReceiver

fsChannelSetVolumeCallback

状态查询

fsChannelGetLastError

fsChannelPendingCount

fsGetVersion

代码示例

同步发送体数据

同步发送体数据 + PCB Hole 3D 检测 ROI

异步发送 + 回调

发送投影 + 接收重建体数据

重连

注意事项

通用 2D 图像处理通道（filter / infer / teach / meta）

命令清单

paramsJson 键命名约定

filter.sr 参数（JSON）

通用选项开关（option.*）

客户端 API

处理模型

共享内存推荐配置

状态码（FSProcStatusC）

FAQ

`fsChannelCreate`

`fsChannelDestroy`

`fsChannelIsConnected`

`fsChannelSendVolumeAndWait`

`fsChannelSendVolumeWithConfigAndWait`（2.1）

`fsChannelSendProjectionAndWait`

`fsChannelSetProgressCallback`

`fsChannelSetCompletionCallback`

`fsChannelSendVolumeAsync`

`fsChannelSendVolumeWithConfigAsync`（2.1）

`fsChannelSendProjectionAsync`

`fsChannelCancelRequest`

`fsChannelEnableVolumeReceiver`

`fsChannelSetVolumeCallback`

`fsChannelGetLastError`

`fsChannelPendingCount`

`fsGetVersion`