人体姿势检索实战指南：用 Pose-Search 三步从海量图片中找出指定动作

【免费下载链接】pose-searchx6ud.github.io/pose-search项目地址: https://gitcode.com/gh_mirrors/po/pose-search

本次文章采用"动手实战式"结构：以一次真实的"找动作图片"经历开场引出项目，随后依次讲解姿势识别原理、环境搭建、完整检索体验、匹配机制拆解和扩展方向，章节顺序与原文完全不同，叙述视角改为第一人称体验视角。

先说一个让人抓狂的场景

做运动类内容的朋友大概都有过这种经历：素材库里有几千张图片，想找一张"左腿抬起、右臂向后摆"的照片，却只能一张张翻。翻到最后眼睛都快花了，还得不到满意的结果。想用文字搜？"右腿弯曲45度、身体前倾30度"这种描述，搜索引擎根本听不懂。

这就是 Pose-Search 想解决的问题——它是一款基于骨骼关键点的人体姿势检索引擎，让你像"拖拽一个3D小人摆动作"那样定义目标姿势，然后从图片库里自动筛出最接近的照片。这套人体姿势检索方案，把"只能靠肉眼和关键词"的活儿，变成了一个可计算的数学问题。

别被"计算机视觉"吓到，原理其实很直白

你可能会问：图片又不是文字，机器怎么知道我摆的是什么动作？

答案藏在每个画面里的"骨架"上。Pose-Search 借助 Google 的 MediaPipe Pose 模型，对每张图片做一次"透视"：把人体的肩、肘、腕、髋、膝、踝等关节位置统统定位出来，一共提取33 个骨骼关键点。每个关键点不仅有平面坐标，还带着深度信息和可见度评分，相当于给每个人体建了一张三维"数字名片"。

这一步对应源码里的src/utils/detect-pose.ts。它把检测结果分成两套数据：一套是归一化后的画面坐标（对应你在图上看到的红点标注），另一套是真实空间中的世界坐标（对应三维信息）。两套数据都被存进landmarks.dat，配合photos.json里的图片元数据，就构成了一个"骨骼点+图片"的检索数据库。

说白了，检索的本质不再是"看图"，而是"比骨架"。动作像不像，取决于两组骨骼点之间的几何关系接近不接近。

三步完成环境搭建，跟着做就能跑起来

别急，部署这套姿势检索工具比你想象的简单，不需要懂模型训练，只需要 Node.js 环境。

第一步：拉取仓库并安装依赖

git clone https://gitcode.com/gh_mirrors/po/pose-search cd pose-search npm install

第二步：启动开发服务

npm run dev

浏览器打开本地地址就能进入界面。如果想打包成生产版本，执行npm run build即可，构建过程会自动做类型检查并压缩资源。

第三步：导入你的图片数据

系统默认图片来自 Unsplash。你只需到 Unsplash 开放平台申请一个应用密钥（App Key），然后访问/#/editor编辑器页面，把密钥粘贴到弹出的输入框里，系统就会自动拉取图片并完成骨骼关键点标注。整个标注过程由 MediaPipe 在浏览器本地完成，所有检测结果会写回landmarks.dat和photos.json，下次启动直接读取，不需要重复计算。

效果最直观的姿势检索方式：拖拽3D小人

环境跑起来之后，就到了最有意思的环节。编辑器界面里会有一个可拖拽的 3D 人体模型——这就是你的"姿势模板"。你可以用鼠标转动视角、扳动各个关节，把它摆成你想要的姿势，比如让滑板运动员做一个腾空抓板动作。

摆好姿势后，从下拉框里选择要匹配的身体部位，比如"Left Elbow"或"Right Knee"，再点一下搜索按钮，系统就会遍历整个图片库，按相似度从高到低返回前 100 个结果（这个数量上限可以在配置里改）。点击任意一张缩略图还能放大查看原图，验证匹配效果。

这里有个很贴心的细节：搜索结果左上角会带翻转标记。因为人体动作天然有左右对称性，系统遇到"左手动作但图片里是右手完成"的情况，会通过水平翻转来处理，保证"左叉腰"也能匹配到"右叉腰"的照片。

凭什么匹配得准？拆开匹配器给你看

搜索准不准，全靠src/Search/impl/目录下那一排"专用匹配器"。

每个匹配器都实现同一个PoseMatcher接口，只有两个核心方法：prepare()负责读取你摆好的 3D 模板姿势，算出它的角度特征；match()负责拿这些特征去和图片库里的每张照片逐一比对，算出相似度分数，分数越高越靠前。

为什么拆成这么多个文件？因为"局部匹配"比"整体匹配"聪明得多。全身一起比，头发、衣服、背景都会干扰判断；而单独比较肘部弯曲角度、肩部旋转方向、膝盖的夹角，每个部位都能用最合适的几何算法，误差自然更小。比如MatchElbow会同时比较上臂和前臂的朝向角、肘部弯折角、以及手臂相对躯干的方位，多个角度误差相乘得到总分——只要某一项差太多，总分就会迅速拉低，保证不滥竽充数。

更妙的是"相机无关"匹配器（MatchShoulderCameraUnrelated这类文件）。普通的 2D 角度会受拍摄角度影响：同一个动作，从正面拍和从侧面拍，画面里的夹角完全不同。这类匹配器只用世界坐标计算"关节相对躯干的方向"，把拍摄视角的影响抹掉，这就是系统宣传的视角无关能力。

另外，每个匹配器都很"自觉"：如果某张照片里目标部位的可见度太低（低于配置里的LANDMARK_VISIBILITY_ACCEPTABLE_THRESHOLD，默认 0.4），它直接返回空结果，宁可不出现在列表里，也不拿噪音数据凑数。

除了搜图，它还能用在哪儿

把检索能力搭好之后，应用场景其实比想象中宽：

• 体育训练分析：教练把标准技术动作存进库里，运动员想练"手臂完全伸展、身体成直线"的空中姿态，直接拖 3D 模型搜出参考图。
• 康复动作核对：治疗师可以检索"膝关节弯曲 90~120 度"的示范图，让患者照着标准执行，方便又直观。
• 动画制作找参考：动画师需要"奔跑中左腿前摆、右腿后蹬"的中间帧，过去翻素材库半小时，现在几秒钟出结果。
• 行为异常监测：建立一个正常姿态基准库，凡是偏离基准太多的姿势都会被标记出来，可用于特定场景的安防辅助。

如果以后想接入自己的图片数据源，也留好了口子：PhotoDataset负责数据读写，图片库里每一张图的元数据和骨骼点都能通过它增删改查，替换数据源不需要动匹配逻辑。

给想动代码的人留的几条路

这套项目最大的优点就是模块化，想改哪里都很清楚：

• 新增一个身体部位的匹配器：在src/Search/impl/下新建类，实现PoseMatcher接口，再在Search.ts的匹配器注册表里登记一下，界面上立刻多一个可选项。
• 自定义3D可视化：src/components/SkeletonModelCanvas/里加载了头部、躯干、四肢等一组 OBJ 模型文件，可以替换成你自己的骨骼模型。
• 调整检索体验：src/config.ts里MAX_NUM_OF_SEARCH_RESULTS控制返回数量，LANDMARK_VISIBILITY_ACCEPTABLE_THRESHOLD控制关键点可信度门槛，改这两个数就能在"召回更多"和"结果更准"之间找平衡。

现在该轮到你动手了

回顾一下：Pose-Search 用 33 个骨骼关键点把"姿势"变成可计算的数据，用分部位匹配器和视角无关算法保证精度，再用 3D 模型拖拽提供最直观的姿势定义方式——整套流程环环相扣，却只靠浏览器就能跑起来。

与其对着这篇文章想象，不如现在就git clone下来，npm install之后去编辑器里拖两下 3D 小人，搜一把自己最想要的那个动作。你会发现，找一张"姿势对的图"，从来没这么痛快过。

【免费下载链接】pose-searchx6ud.github.io/pose-search项目地址: https://gitcode.com/gh_mirrors/po/pose-search