OpenPose Demo 命令行实战指南从图像、视频到 3D 重建的完整上手指南【免费下载链接】openposeOpenPose: Real-time multi-person keypoint detection library for body, face, hands, and foot estimation项目地址: https://gitcode.com/gh_mirrors/op/openposeOpenPose 是面向人体、人脸、手部与脚部关键点检测的实时多人姿态估计库。本文以仓库 doc/01_demo.md 为骨架完整讲解如何直接运行官方 Demo无需改动任何源码覆盖图像目录、视频、摄像头、IP 摄像头等多输入源的切换JSON/图片/视频/界面多种输出方式多 GPU 并行、最高精度配置、3D 重建与帧间跟踪以及内存不足等常见问题的排查方案。读完本文你将能够独立使用openpose.binWindows 下为OpenPoseDemo.exe跑通任意输入源并依据业务场景自由组合参数。准备工作可执行程序与示例素材官方 Demo 的启动方式有三种任选其一即可Windows 便携版直接使用bin\OpenPoseDemo.exe详见 doc/installation/0_index.md 中的 Windows Portable Demo 小节无需编译源码编译产物在项目根目录执行 CMake 构建后使用build/examples/openpose/openpose.binWindows 下为build\x64\Release\OpenPoseDemo.exeVisual Studio 调试运行若使用 Visual Studio 构建需要先把bin/*.dll拷贝到最终的 DLL 输出目录见 doc/installation/0_index.md 的 Windows 小节或直接修改 include/openpose/flags.hpp 中的默认 flag 值。运行任何命令时请务必确认当前处于项目根目录即 OpenPose 文件夹本身而不是build/、windows/或bin/。仓库自带的示例素材已就绪examples/media/video.avi示例视频与examples/media/约 20 张示例图片因此无需修改任何代码即可直接体验。从源码层面看Demo 的程序入口在 examples/openpose/openpose.cppmain()首先调用gflags::ParseCommandLineFlags解析命令行 flag随后进入openPoseDemo()由 configureWrapper 把全部 flag 依次映射到WrapperStructPose、WrapperStructFace、WrapperStructHand、WrapperStructExtra、WrapperStructInput、WrapperStructOutput、WrapperStructGui等配置结构体最终通过opWrapper.exec()启动线程流水线。快速开始跑通第一个 Demo在项目根目录执行以下命令预期可视化结果与 doc/02_output.md 的 UI and Visual Output 小节展示的效果一致# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin --video examples/media/video.avi:: Windows - Portable Demo bin\OpenPoseDemo.exe --video examples/media/video.avi如果你使用 Visual Studio 构建并已正确拷贝 DLL则可以这样运行:: Windows - Library - 前提已按 doc/installation/0_index.md#windows 小节拷贝 DLL build\x64\Release\OpenPoseDemo.exe --video examples/media/video.avi如果运行失败按以下顺序排查报错为内存不足out of memory时参见后文「改善内存与速度牺牲精度」小节使用 Mac 时先确认「Mac OSX 附加步骤」小节其余错误先查阅 doc/05_faq.md 中的 FAQ。切换输入源图像目录、视频与摄像头OpenPose 支持三种最常见的输入源对应三个互斥的输入 flag。图像目录--image_dir {目录路径}# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin --image_dir examples/media/:: Windows - Portable Demo bin\OpenPoseDemo.exe --image_dir examples/media/视频文件--video {视频路径}# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin --video examples/media/video.avi:: Windows - Portable Demo bin\OpenPoseDemo.exe --video examples/media/video.avi摄像头默认输入源不指定--image_dir或--video时默认使用摄像头机器上有多台摄像头时用--camera {编号}指定# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin ./build/examples/openpose/openpose.bin --camera 0 ./build/examples/openpose/openpose.bin --camera 1:: Windows - Portable Demo bin\OpenPoseDemo.exe bin\OpenPoseDemo.exe --camera 0 bin\OpenPoseDemo.exe --camera 1此外include/openpose/flags.hpp 中还有--ip_camera用于读取支持 RTSP / HTTP 协议的流媒体摄像头。输入源的选择逻辑集中在 examples/openpose/openpose.cppflagsToProducer会依据--image_dir、--video、--ip_camera、--camera、--flir_camera的组合决定最终的ProducerType。摄像头分辨率由--camera_resolution控制默认-1x-1即使用 OpenCV 的默认 1280x720。一键开启人脸与手部关键点检测在任意命令后追加--face和/或--hand即可# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin --image_dir examples/media/ --face --hand ./build/examples/openpose/openpose.bin --video examples/media/video.avi --face --hand ./build/examples/openpose/openpose.bin --face --hand:: Windows - Portable Demo bin\OpenPoseDemo.exe --image_dir examples/media/ --face --hand bin\OpenPoseDemo.exe --video examples/media/video.avi --face --hand bin\OpenPoseDemo.exe --face --hand源码层面的对应关系--face与--hand分别控制 examples/openpose/openpose.cpp 中的WrapperStructFace与WrapperStructHand。开启后人脸与手部网络会共享--model_folder指定的模型目录对应仓库中的models/face/pose_deploy.prototxt与models/hand/pose_deploy.prototxt。需要留意的是开启后人脸/手部检测速度与图中人数强相关人数越多越慢手部网络的分辨率由--hand_net_resolution默认368x368需为 16 的倍数且为正方形控制官方实测--hand_scale_number 6 --hand_scale_range 0.4组合精度最佳人脸网络分辨率由--face_net_resolution默认368x368控制多人脸场景下320x320通常可在几乎不掉精度的前提下显著提速。输出配置JSON、图片、视频与界面可以自由组合OpenPose 的各类输出相互独立、互补叠加是否在界面显示骨架与是否把结果写入磁盘互不影响。保存 JSON 关键点数据--write_json {输出目录}JSON 格式说明见 doc/02_output.md# Ubuntu 和 MacWindows 下 flag 相同 ./build/examples/openpose/openpose.bin --image_dir examples/media/ --write_json output_jsons/ ./build/examples/openpose/openpose.bin --video examples/media/video.avi --write_json output_jsons/ ./build/examples/openpose/openpose.bin --write_json output_jsons/每个 JSON 文件对应一帧画面包含people数组每人包含pose_keypoints_2d、face_keypoints_2d、hand_left_keypoints_2d、hand_right_keypoints_2d以及开启--3d后的*_keypoints_3d格式为x,y,z,c还可在开启--part_candidates时额外输出组装为人体之前的部位候选。具体字段样例见 doc/02_output.md 的 JSON Output Format 小节。坐标的归一化范围由--keypoint_scale决定0原始输入分辨率1网络输出分辨率2最终输出分辨率3[0,1]4[-1,1]。把带骨架的渲染结果保存为视频或图片--write_video {视频路径}/--write_images {输出目录}# Ubuntu 和 MacWindows 下 flag 相同 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --write_video output/result.avi ./build/examples/openpose/openpose.bin --image_dir examples/media/ --write_video output/result.avi ./build/examples/openpose/openpose.bin --video examples/media/video.avi --write_images output_images/ ./build/examples/openpose/openpose.bin --video examples/media/video.avi --write_images output_images/ --write_images_format jpg ./build/examples/openpose/openpose.bin --image_dir examples/media/ --write_images output_images/ ./build/examples/openpose/openpose.bin --image_dir examples/media/ --write_images output_images/ --write_images_format jpg--write_images_format默认png可改为jpg、bmp等 OpenCVcv::imwrite支持的扩展名--write_video内部使用cv::VideoWriter输出路径必须以.avi结尾motion JPEG 编码。关闭 GUI 窗口--display 0适合服务器环境或轻微提速。但注意关闭显示后必须指定至少一种磁盘输出--write_json、--write_video、--write_images三选一否则程序无输出可写# Ubuntu 和 MacWindows 下 flag 相同 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --write_images output_images/ --display 0进一步提速--display 0且不使用--write_video/--write_images时可追加--render_pose 0跳过骨架叠加渲染节省渲染开销# Ubuntu 和 MacWindows 下 flag 相同 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --write_json output_jsons/ --display 0 --render_pose 0另外提醒--write_keypoint已被官方标记为废弃源码 include/openpose/flags.hpp 中注明 Deprecated, usewrite_jsonexamples/openpose/openpose.cpp 在检测到该 flag 时也会打印弃用警告新项目请一律使用--write_json。纯骨架渲染去掉背景图像追加--disable_blending后渲染结果骨架或热力图将绘制在纯黑背景上而不是叠加到原始图像# Ubuntu 和 MacWindows 下 flag 相同 # 仅人体骨架 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --disable_blending该 flag 的定义见 include/openpose/flags.hpp与--part_to_show、--alpha_pose、--alpha_heatmap相互关联--part_to_show选择可视化通道0全部部位1背景热力图2热力图叠加3PAF 叠加之后依次为各部位热力图与各部位对 PAF--alpha_pose与--alpha_heatmap控制 GPU 渲染下的混合透明度。多 GPU 并行控制使用哪些显卡默认情况下 OpenPose 会使用机器上所有可用 GPU。--num_gpu指定使用的 GPU 总数--num_gpu_start指定起始 GPU 编号。例如--num_gpu 2 --num_gpu_start 1表示使用 GPU ID 1 和 2、跳过 GPU ID 0需机器至少有 3 块 GPU:: Windows - Portable DemoUbuntu 和 Mac 下 flag 相同 bin\OpenPoseDemo.exe --video examples/media/video.avi --num_gpu 2 --num_gpu_start 1对应源码 include/openpose/flags.hpp--num_gpu为负数时自动使用全部 GPU--num_gpu_start默认 0。最高精度配置以下命令是目前官方在人体、手部、人脸关键点检测上能达到的最高精度配置# Ubuntu 和 Mac仅人体 ./build/examples/openpose/openpose.bin --net_resolution 1312x736 --scale_number 4 --scale_gap 0.25 # Ubuntu 和 Mac人体 手 人脸 ./build/examples/openpose/openpose.bin --net_resolution 1312x736 --scale_number 4 --scale_gap 0.25 --hand --hand_scale_number 6 --hand_scale_range 0.4 --face:: Windows - Portable Demo仅人体 bin\OpenPoseDemo.exe --net_resolution 1312x736 --scale_number 4 --scale_gap 0.25 :: Windows - Portable Demo人体 手 人脸 bin\OpenPoseDemo.exe --net_resolution 1312x736 --scale_number 4 --scale_gap 0.25 --hand --hand_scale_number 6 --hand_scale_range 0.4 --face硬件与模型硬性要求必须使用BODY_25默认模型定义于 include/openpose/flags.hppCOCO精度略低但仍可用MPI不支持该配置精度与速度都会下降需要至少 16 GB 显存的 Nvidia GPU具体分档如下BODY_25人体 脚默认模型约 10.5 GB如 Titan X(P)、部分 Quadro、P100、V100BODY_25 人脸 手约 16 GB如 V100COCO人体 人脸 手约 6.7 GB如 2070、2080CPU / OpenCL 模式无法运行该配置唯一替代方案是手动裁剪每个人、缩放后喂入默认 OpenPose。补充信息官方文档记载该配置在 Titan X 上约 2 FPSBODY_25COCO约 1 FPS盲目增大--net_resolution会大幅降低速度且不保证精度提升因此官方建议只使用这里给出的确切 flag 与取值--maximize_positives不推荐风险自负会降低人体候选的接受阈值牺牲视觉/定性精度以换取 COCO 挑战的数值精度。其底层实现在 src/openpose/pose/poseParameters.cpp开启后 NMS 阈值由 0.05 降至 0.02、连接筛选阈值由 0.95 降至 0.75、部位连接阈值由 0.05 降至 0.01、最小子集数量由 3 降至 2、最小子集得分由 0.4 降至 0.05直观表现是同时增加假阳性与真阳性最大化平均召回率、可能损害平均精度视觉上明显变差但挑战数值提升Ubuntu 用户可查看官方用于精度测试的实验脚本非官方支持可能随时变动scripts/tests/pose_accuracy_coco_test_dev.sh与scripts/tests/pose_accuracy_coco_val.sh。附加模型更高精度BODY_25B官方论文中的精度数字与默认模型并不一致——论文发布时释放的是当时的最佳模型之后又找到了更好的模型。如需更高精度的BODY_25B预训练模型可从 OpenPose 训练仓库下载「Option 1最大精度、较慢」版本。该模型精度更高但更慢、占用更多显存且必须使用 Nvidia GPU 版本。附加模型更少假阳性BODY_25B若需要假阳性更少、但运行性能与显存要求不变的模型可从 OpenPose 训练仓库下载BODY_25B预训练模型的「Option 2推荐」版本。同样必须使用 Nvidia GPU 版本。3D 重建多视角立体视觉实战3D 重建依赖多相机系统如 FLIR/Point-Grey 立体相机并把同一人体的关键点在多个视角间三角化。以下按官方文档的五个步骤展开。1. 实时 3D Demo# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin --flir_camera --3d --number_people_max 1 # 带人脸与手部 ./build/examples/openpose/openpose.bin --flir_camera --3d --number_people_max 1 --face --hand:: Windows - Portable Demo bin\OpenPoseDemo.exe --flir_camera --3d --number_people_max 1 :: 带人脸与手部 bin\OpenPoseDemo.exe --flir_camera --3d --number_people_max 1 --face --hand注意--3d模式只显示 1 个人画面中存在多人时会失败因此必须搭配--number_people_max 1。该模式对应 examples/openpose/openpose.cpp 中WrapperStructExtra的--3d与--3d_min_views配置。2. 保存 3D 关键点与视频# Ubuntu 和 MacWindows 下 flag 相同 ./build/examples/openpose/openpose.bin --flir_camera --3d --number_people_max 1 --write_json output_folder_path/ --write_video_3d output_folder_path/video_3d.avi--write_json会把 3D 关键点以x,y,z,c形式写入 JSONc为 1 或 0 表示 3D 重建是否成功--write_video_3d保存 3D 可视化结果视频对应 flag 定义见 include/openpose/flags.hpp。3. 快速保存立体相机原始图像不做关键点检测供后续离线处理# Ubuntu 和 MacWindows 下 flag 相同 # 保存视频注意保存 PNG 相比 JPG 画质更好但会降低 FPS具体取决于硬盘写入速度与相机数量 ./build/examples/openpose/openpose.bin --flir_camera --num_gpu 0 --write_video output_folder_path/video.avi --write_video_fps 5 # 保存图片注意保存 PNG 相比 JPG 画质更好但会降低 FPS具体取决于硬盘写入速度与相机数量 ./build/examples/openpose/openpose.bin --flir_camera --num_gpu 0 --write_images output_folder_path/ --write_images_format jpg这里--num_gpu 0表示完全跳过关键点检测网络仅做采集与存储。4. 读取并处理之前保存的立体相机图像# Ubuntu 和 MacWindows 下 flag 相同 # 可选追加 --face 和/或 --hand 以包含人脸与手部 # 假设有 3 台相机 # 注意强烈建议降低 --output_resolution。例如 3 台相机以 1920x1080 录制时拼接后图像为 (3x1920)x1080建议设为如 640x360缩小 3 倍 # 视频 ./build/examples/openpose/openpose.bin --video output_folder_path/video.avi --3d_views 3 --3d --number_people_max 1 --output_resolution {desired_output_resolution} # 图片 ./build/examples/openpose/openpose.bin --image_dir output_folder_path/ --3d_views 3 --3d --number_people_max 1 --output_resolution {desired_output_resolution}--3d_views是--image_dir/--video的补充选项每轮读取多张图像用于立体处理如--3d。使用时必须设置--camera_parameter_path默认models/cameraParameters/flir/仓库示例见models/cameraParameters/flir/17012332.xml.example且该目录下必须恰好存在与视角数相同的 XML 相机参数文件。5. 关键点在至少 x 个视角可见时才进行重建# Ubuntu 和 MacWindows 下 flag 相同 # 关键点至少在 2 个视角可见时重建假设 n 2 ./build/examples/openpose/openpose.bin --flir_camera --3d --number_people_max 1 --3d_min_views 2 --output_resolution {desired_output_resolution} # 关键点至少在 max(2, min(4, n-1)) 个视角可见时重建默认规则 ./build/examples/openpose/openpose.bin --flir_camera --3d --number_people_max 1 --output_resolution {desired_output_resolution}--3d_min_views默认-1等价于max(2, min(4, #cameras-1))见 include/openpose/flags.hpp。帧间跟踪Tracking实验性--tracking用于在帧间跟踪人体官方标注为实验性功能。取值含义-1默认禁用正整数表示每隔 N 帧运行一次 OpenPose 关键点检测、其余帧用跟踪结果填补0表示每帧同时运行检测与跟踪无提速/减速但平滑性更好。以下三种用法覆盖不同诉求:: Windows - Portable DemoUbuntu 和 Mac 下 flag 相同 :: 1. 大幅提速牺牲精度OpenPose 每 1 帧检测后续约 5 帧用跟踪结果 bin\OpenPoseDemo.exe --tracking 5 --number_people_max 1 :: 2. 提速同时保留大部分精度OpenPose 每 1 帧检测另 1 帧跟踪 bin\OpenPoseDemo.exe --tracking 1 --number_people_max 1 :: 3. 视觉平滑每帧同时运行 OpenPose 与跟踪无提速/减速 bin\OpenPoseDemo.exe --tracking 0 --number_people_max 1--number_people_max默认-1保留全部检测到的人设定正整数后OpenPose 会按「人体面积、部位得分、部位间连接得分」保留得分最高的前 N 人可用于剔除假阳性前提是场景中的人都被检出但也可能把过小或严重遮挡的人当作假阴性删掉。将 Kinect 2.0 用作 Windows 10 摄像头自 Windows 10 Anniversary 更新起Kinect 2.0 可被当作普通网络摄像头读取。步骤打开「设备管理器」展开kinect sensor devices选项卡右键WDF kinectSensor Interface并更新驱动程序。若已有其他摄像头请先断开它或使用--camera 2指定 Kinect 的设备编号。常用 Flags 一览以下是官方文档列出的最常用 flag完整列表与全部说明见 doc/advanced/demo_advanced.mdFlag作用--face开启人脸关键点检测--hand开启手部关键点检测--video input.mp4读取视频文件input.mp4--camera 3读取 3 号摄像头--image_dir path_with_images/处理目录path_with_images/下的图像--ip_camera URL处理流媒体 IP 摄像头URL 支持 RTSP 与 HTTP 协议--write_video path.avi把处理后的图像保存为视频--write_images folder_path把处理后的图像保存到文件夹--write_keypoint path/输出包含人体姿态数据的 JSON / XML / YML 文件已废弃请改用--write_json--process_real_time视频处理时可能跳帧以保持实时播放--disable_blending在黑色背景上渲染结果骨架或热力图不显示原图。相关 flagpart_to_show、alpha_pose、alpha_pose--part_to_show选择要可视化的预测通道--display 0不打开显示窗口适合服务器场景或轻微提速--num_gpu 2 --num_gpu_start 1从指定设备 ID 开始并行使用指定数量的 GPU默认使用全部可用 GPU--model_pose MPI选择模型影响关键点数量、速度与精度--logging_level 3日志输出阈值取值范围 [0,255]0 输出所有消息255 全部不输出当前消息位于 [1,4]1 为低优先级、4 为高优先级其中--logging_level、--model_pose的取值在 examples/openpose/openpose.cpp 中有运行时校验logging_level超出 [0,255] 会直接报错--model_pose支持BODY_25、COCO、MPI、MPI_4_layers以及BODY_19、BODY_25B等字符串到枚举的映射见 src/openpose/utilities/flagsToOpenPose.cpp。--model_pose对应的模型定义文件位于仓库 models/pose 下body_25/pose_deploy.prototxt、coco/pose_deploy_linevec.prototxt、mpi/pose_deploy_linevec.prototxt与mpi/pose_deploy_linevec_faster_4_stages.prototxt预训练权重可通过 models/getModels.shWindows 为models/getModels.bat下载。进阶快速开始更多进阶 flag如--output_resolution、--keypoint_scale、--heatmaps_add_parts、--write_heatmaps、--part_candidates、--disable_multi_thread、--body、--face_detector、--hand_detector等请阅读 doc/advanced/demo_advanced.md。也可以随时运行--help查看全部可用 flag——只需关注输出中Flags from examples/openpose/openpose.cpp:一节的条目即可# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin --help:: Windows - Portable Demo bin\OpenPoseDemo.exe --helpBug 排查内存不足、速度过慢与平台差异改善内存占用与速度代价是精度下降如果你的 Nvidia GPU 运行时不报内存不足请直接跳过本小节--net_resolution需要谨慎使用当 GPU 显存不足或没有 Nvidia GPU 时可以降低该值以提升速度并减少显存占用但精度也会明显下降——分辨率越低速度越快、显存越省精度越低# Ubuntu 和 Mac ./build/examples/openpose/openpose.bin --video examples/media/video.avi --net_resolution -1x320 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --net_resolution -1x256 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --net_resolution -1x196 ./build/examples/openpose/openpose.bin --video examples/media/video.avi --net_resolution -1x128:: Windows - Portable Demo bin\OpenPoseDemo.exe --video examples/media/video.avi --net_resolution -1x320 bin\OpenPoseDemo.exe --video examples/media/video.avi --net_resolution -1x256 bin\OpenPoseDemo.exe --video examples/media/video.avi --net_resolution -1x196 bin\OpenPoseDemo.exe --video examples/media/video.avi --net_resolution -1x128补充要点均与 include/openpose/flags.hpp 中的定义一致默认网络分辨率为-1x368任何更小的分辨率都能提升速度-1表示该维度自动适配以保持输入源的宽高比。例如-1x368、656x-1、656x368对 720p 和 1080p 输入会得到完全相同的结果分辨率处理视频时推荐使用-1让 OpenPose 自动选择理想分辨率处理不同尺寸混合的图像目录时若不用-1且图像宽高比差异极大可能触发内存不足。例如目录里有100x11040和10000x368两张图默认-1x368会分别得到网络输出分辨率3x368和10000x368后者显然会内存溢出进阶辅助--net_resolution_dynamic仅对图像/自定义输入生效默认 1可在使用-1时把网络宽度裁剪到「该值 × 默认 16:9 宽度368 高对应 656 宽」以内小显存 GPU 建议设 1大显存 GPU 建议设 0 以追求最大精度与速度。Mac OSX 附加步骤仅 OPENCL 模式如果你不用 Mac或使用的是CPU_only的 Mac可以跳过本节。若你的 Mac 启用了OPENCL支持且带有 AMD 独立显卡机器上会存在两块不兼容的 GPUAMD 与 Intel。此时需要手动选择其中一块AMD 通常更强。先用clinfo查看设备编号——AMD 设备大概率是设备 2clinfo随后在任意 OpenPose 命令中追加以下两个 flag指定使用 AMD 显卡加速num_gpu_start填上面查到的设备 ID./build/examples/openpose/openpose.bin --num_gpu 1 --num_gpu_start 2如果只有 Intel 核显则它大概率是设备 1请始终追加./build/examples/openpose/openpose.bin --num_gpu 1 --num_gpu_start 1FAQ其余错误、问题与顾虑请查阅 doc/05_faq.md。小结OpenPose Demo 的价值在于「零改动即可体验完整的多人姿态估计流水线」通过 examples/openpose/openpose.cpp 这一薄封装--image_dir/--video/ 摄像头 / IP 摄像头 / FLIR 立体相机等多输入源、--write_json/--write_video/--write_images等输出通道、--net_resolution/--scale_number/--num_gpu等精度与性能旋钮全部以命令行 flag 形式开放。建议的组合思路是先按本文「快速开始」跑通默认流程再按输入源需求挑选对应 flag最后在「最高精度」与「降低--net_resolution」两个方向之间根据 GPU 显存与帧率要求做权衡并借助--help与 doc/advanced/demo_advanced.md 探索更多高级参数。【免费下载链接】openposeOpenPose: Real-time multi-person keypoint detection library for body, face, hands, and foot estimation项目地址: https://gitcode.com/gh_mirrors/op/openpose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考