请输入
菜单

fixSharedMemoryDll — API 参考

作者: JT下载

fixSharedMemoryDll — API 参考

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

工作流程、返回格式、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 / 负数错误码。

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 缓冲区。

异步 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 返回。

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.0.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);

异步发送 + 回调

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
infer.* 模型推理（输入图 → 输出图 + JSON） infer.yolo / infer.seg（接入中）
teach.* 教学文件检测 teach.detect（接入中）
meta.* 元命令（不需要图像） meta.list_commands / meta.gpu_info

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 快速档（先下采样再 ×4 forward）；"scale4"=×4 上采样
filter.sr.blendRatio float 1.0 Soft↔Hard 混合比例 [0,1]；0=Soft（柔和/去噪），1=Hard（锐利）
filter.sr.tileSize int 1024 内部 tile 尺寸（>=64）
filter.sr.tileOverlap int 32 tile 重叠像素
filter.sr.batchHint int 1 一次 forward 前向的 tile 数（真 GPU batch，OOM 自动减半）

GPU-only：filter.sr 必须 GPU。如 GPU 不可用返回 FS_PROC_C_GPU_UNAVAIL。

batchHint 语义：N 张 tile 堆成 [N,3,H,W] 单次 forward。8 GB 显卡 scale1 推荐
4~8，scale4 推荐 2~4（×4 输出激活更大）。OOM 时 fiSRTiler 自动 batchSize/=2 重试，
最坏退化到 batch=1。该改造仅影响共享内存通道（fiSRTiler）；WL 控件中的 FIX SR 路径未变。

通用选项开关（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.tileOverlap\":32,\"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);

处理模型

  • 服务端 串行处理：所有图像处理任务进入同一队列，按到达先后逐个执行（避免 GPU 资源争抢）
  • 进度回调 注册即生效：调用 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 GPU 不可用
-104 OOM
-105 客户端取消
-106 超时
-200 内部错误（详见 errorMsg）

FAQ

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

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

Q: reconConfigJson 填什么？
A: JSON 字符串，包含重建参数和 _metadata 控制参数。详见 fixSDK_README.md 的 configJson 章节。

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

上一个
FIX SDK
下一个
FIX 共享内存使用说明 V2
最近修改: 2026-05-05Powered by