OpenPose C API 开发指南从 Wrapper 封装到自定义输入输出的实战教程【免费下载链接】openposeOpenPose: Real-time multi-person keypoint detection library for body, face, hands, and foot estimation项目地址: https://gitcode.com/gh_mirrors/op/openposeOpenPose 的 C API 是官方提供的面向应用集成的核心接口它通过op::Wrapper将底层多线程流水线、模型推理、渲染与 GUI 封装为简洁调用让开发者能以接近原生 C 的性能读取任意输入、插入自定义后处理并接管显示与保存。本文以 doc/04_cpp_api.md 为骨架结合 examples/tutorial_api_cpp 与 examples/user_code 中的完整示例和 CMake 配置系统讲解 C API 的使用时机、Wrapper 生命周期、四种线程模式、op::Datum数据载体以及如何快速搭建属于自己的 OpenPose 应用。什么时候应该使用 C / Python API官方文档明确指出是否使用 C API 取决于你的集成需求如果你只是想跑通官方 Demo、用命令行参数完成推理请直接使用 OpenPose Demo如果你需要读取特定的输入源例如自己的图像目录、多路相机、自定义数据格式追加自定义后处理函数或者实现自己的显示与保存逻辑就应该转向 Python API 或 C API在阅读 C 示例之前你应当先熟悉 OpenPose Demo 及其主要命令行 flags否则 API 示例中的大量 flag 会难以理解。C 与 Python API 的能力边界基本一致差别在于运行环境与性能敏感度Python 版通过 Pybind11 将op::Arrayfloat和cv::Mat自动转换为 NumPy 数组适合快速原型而 C API 直接操作op::Datum与op::Matrix零解释开销更适合性能敏感的生产级集成。快速起步复制示例文件并接入 CMake官方推荐的快速原型方法是从 examples/tutorial_api_cpp 中复制并重命名任意示例文件放入 examples/user_code 文件夹然后把新文件的名字登记到该目录下的 CMakeLists.txt 中CMake 就会将它与整个 OpenPose 项目一同编译。具体步骤如下详见 examples/user_code/README.md按常规方式安装/编译 OpenPose将你的自定义.cpp/.hpp文件放入examples/user_code/建议先从 examples/openpose/openpose.cppOpenPoseDemo 主程序或任意 examples/tutorial_api_cpp 示例拷贝在 examples/user_code/CMakeLists.txt 顶部取消注释并填入你的文件名单重新运行 CMakeConfigure和Generate修改你的代码然后重新编译Ubuntucd build/ make -j\nprocMaccd build/ make -j\sysctl -n hw.logicalcpuWindows在 Visual Studio 中编译F5、F7 或绿色运行按钮每次修改代码后都要重复第 5 步。运行你的自定义程序./build/examples/user_code/{your_custom_file_name}在 Linux/macOS 上CMake 会把可执行文件命名为源文件名加.bin后缀Windows 上则统一命名为UserCustomCode。user_code 的 CMake 机制源码解析从 examples/user_code/CMakeLists.txt 的源码可以看出该目录通过遍历USER_CODE_FILES变量自动生成可执行目标每个源文件被编译为独立可执行文件Linux/macOS 下命名规则为${SOURCE_NAME}.binWindows 下为UserCustomCode通过target_link_libraries(${EXE_NAME} openpose ${examples_3rdparty_libraries})链接 OpenPose 主库及其第三方依赖gflags、OpenCV 等Windows 下额外配置了 Release/Debug 输出目录RUNTIME_OUTPUT_DIRECTORY_RELEASE/DEBUG保证 DLL 查找路径正确。这意味着你完全不需要维护独立的 CMake 工程把自定义代码丢进examples/user_code即可获得与官方示例一致的构建环境这也是快速迭代的最小成本路径。教程示例全景18 个由浅入深的 C 示例examples/tutorial_api_cpp/CMakeLists.txt 中注册了 18 个官方示例每个示例聚焦一个具体能力点编号文件核心主题0101_body_from_image_default.cpp读取单张图像输出身体关键点并显示0202_whole_body_from_image_default.cpp全身身体脸手关键点0303_keypoints_from_image.cpp完整配置 Wrapper 后获取关键点0404_keypoints_from_images.cpp遍历图像目录0505_keypoints_from_images_multi_gpu.cpp多 GPU 推理0606_face_from_image.cpp仅人脸关键点0707_hand_from_image.cpp仅手部关键点0808_heatmaps_from_image.cpp输出热力图0909_keypoints_from_heatmaps.cpp用自定义热力图代替网络输出跑贪心连接算法1010_asynchronous_custom_input.cpp异步模式 自定义输入1111_asynchronous_custom_input_multi_camera.cpp异步多相机输入1212_asynchronous_custom_output.cpp异步模式 自定义输出1313_asynchronous_custom_input_output_and_datum.cpp异步自定义输入输出 Datum1414_synchronous_custom_input.cpp同步模式 自定义输入1515_synchronous_custom_preprocessing.cpp同步自定义预处理1616_synchronous_custom_postprocessing.cpp同步自定义后处理1717_synchronous_custom_output.cpp同步自定义输出1818_synchronous_custom_all_and_datum.cpp同步全流程 Datum最简示例从单张图像获取身体关键点以 01_body_from_image_default.cpp 为例整个流程只有三步核心调用op::Wrapper opWrapper{op::ThreadManagerMode::Asynchronous}; opWrapper.start(); const cv::Mat cvImageToProcess cv::imread(FLAGS_image_path); const op::Matrix imageToProcess OP_CV2OPCONSTMAT(cvImageToProcess); auto datumProcessed opWrapper.emplaceAndPop(imageToProcess);用op::ThreadManagerMode::Asynchronous模式构造 Wrapper然后在op::Datum中读取poseKeypointsop::Arrayfloat形状为[人数, 关键点, 3]第三维为 x、y、置信度通过toString()打印或按poseKeypoints[{person, bodyPart, xyscore}]逐个访问渲染结果位于datum.cvOutputData通过OP_OP2CVCONSTMAT转回cv::Mat后用cv::imshow显示图像输入输出统一使用op::MatrixOpenPose 自研的与 OpenCV 兼容的矩阵封装跨库边界用OP_CV2OPCONSTMAT/OP_OP2CVCONSTMAT宏转换。Wrapper 核心 API 与四种线程模式从 include/openpose/wrapper/wrapper.hpp 的接口定义可以梳理出 Wrapper 的核心生命周期构造explicit WrapperT(const ThreadManagerMode threadManagerMode ThreadManagerMode::Synchronous)。Synchronous模式下一切都在 Wrapper 内部运行SynchronousIn/Out则把输入帧生产者和/或输出交给用户线程配置configure(wrapperStructPose / Face / Hand / Extra / Output / Gui)与setWorker(op::WorkerType::Input, wUserInput, workerInputOnNewThread)运行start()启动线程系统exec()阻塞当前线程直到全部帧处理完毕同步模式常用stop()停止线程系统数据进出waitAndEmplace推入输入只对 Asynchronous/AsynchronousIn 有效、waitAndPop取出输出只对 Asynchronous/AsynchronousOut 有效、emplaceAndPop两者合一的便捷方法。官方文档对线程模式的选型建议可从示例注释中直接读取异步模式Asynchronous适合快速原型性能不是首要考虑如示例 10 的注释 ideal for fast prototyping同步模式Synchronous适合生产环境集成示例 14 的注释 provides the fastest results with respect to runtime performance。此外disableMultiThreading()可将流水线切为单线程顺序处理便于调试与降低延迟。自定义输入异步与同步两种实现范式异步自定义输入10_asynchronous_custom_input.cpp不需要继承任何基类只需提供两个方法createDatum()读取下一张图像填入std::shared_ptrstd::vectorstd::shared_ptrop::Datum用op::getFilesOnDirectory(directoryPath, op::Extensions::Images)枚举目录内全部图片读到末尾或空帧时返回nullptr表示结束isFinished()查询是否已结束。主循环中调用opWrapper.waitAndEmplace(datumToProcess)将帧推入队列处理完成后opWrapper.stop()。其内部实现wrapper.hpp 中waitAndEmplace针对单相机与多视角multiview分别调度多视角场景会逐路调用waitAndEmplace。同步自定义输入14_synchronous_custom_input.cpp则要求继承op::WorkerProducer...并实现workProducer()以及可空的initializationOnThread()然后通过opWrapper.setWorker(op::WorkerType::Input, wUserInput, true)注册为输入 Worker最后调用opWrapper.exec()阻塞运行。workProducer()返回nullptr或调用this-stop()都能终止流水线。两种范式共享同一套configureWrapper()模式先用op::flagsToPoint、op::flagsToPoseMode、op::flagsToPoseModel、op::flagsToScaleMode、op::flagsToHeatMaps、op::flagsToDetector等转换函数把 gflags 命令行参数翻译为 C 结构体字段再依次configure六个WrapperStruct*Pose、Face、Hand、Extra、Output、Gui。例如--net_resolution默认-1x36816 的倍数增大可提升精度但会降低速度、--model_pose默认BODY_25这些默认值都定义在 include/openpose/flags.hpp 中。特殊玩法从自定义热力图生成关键点09_keypoints_from_heatmaps.cpp 展示了 C API 的深度定制能力设置FLAGS_body 2关闭内部姿态估计网络把自定义热力图填入datumPtr-poseNetOutputOpenPose 只运行后端的贪心连接greedy connection算法来生成关键点。需要注意热力图尺寸必须与内部网络输出尺寸一致否则会导致 core dumped段错误可借助--net_resolution、--scale_number等 flag 对齐维度。该示例同时演示了如何在同一个进程内起第二个op::Wrapper实例获取热力图再把热力图喂给主 Wrapper 的完整数据流。常见问题与注意事项先跑通 Demo 再碰 APIAPI 示例大量复用 Demo 的 gflags 参数体系--model_folder、--write_json、--display、--net_resolution等建议先阅读 doc/01_demo.md 与 include/openpose/flags.hpp 中的 flags 注释废弃 flag--write_keypoint已标记为废弃deprecated示例 10 中会打印提示改用--write_json输出保存op::WrapperStructOutput支持--write_jsonbody/hand/face 关键点 JSON、--write_coco_jsonCOCO 格式、--write_images、--write_video、--write_heatmaps等相关实现在 src/openpose/filestream 目录GUI通过op::WrapperStructGui配置--no_gui_verbose、--fullscreen等 flag 可控制显示行为空指针检查所有处理函数都应先判断datumsPtr ! nullptr !datumsPtr-empty()这是官方示例的统一防御性写法编译期链接Windows 下需在 Visual Studio 中编译整个解决方案仅按绿色运行按钮不会编译全部目标。总结OpenPose C API 的核心价值在于它把底层多线程推理流水线封装进op::Wrapper同时通过op::Datum、op::Arrayfloat、op::Matrix与WorkerProducer等抽象保留了对输入、预处理、后处理、输出和显示的完全控制权。18 个 教程示例 覆盖了从读取一张图到自定义输入输出 Datum的全部进阶路径examples/user_code 则提供了一条零成本接入项目构建体系的快速迭代通道。对于需要将姿态估计嵌入自有系统的开发者C API 是兼顾性能与灵活性的推荐入口。【免费下载链接】openposeOpenPose: Real-time multi-person keypoint detection library for body, face, hands, and foot estimation项目地址: https://gitcode.com/gh_mirrors/op/openpose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考