别再打字搜图了，用姿势搜索图片：Pose-Search 开源工具完整上手指南

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

你有没有过这样的经历：脑子里有一张"人跳起来、身体后仰、双手张开"的画面，却怎么也想不起来是哪张照片，只好在搜索引擎里反复输入"跳跃 后仰 双手张开"，结果翻了几十页也没找到想要的。问题不在于你描述得不够好，而在于用文字描述人体动作，本身就天然低效。

这个困扰其实有解——Pose-Search就是这样一款专为"姿势搜索"打造的开源工具。它通过 AI 识别图片中的人物骨骼关键点，让你直接用一张照片当"搜索条件"，去图片库里找出所有姿势相似的照片。本文会用一套完整的实操流程，带你从零跑通这个项目。

先看它长什么样：一个滑雪板照片带来的直觉感受

下面这张图是项目仓库里的真实界面截图editor.jpg，一眼就能看懂它的设计思路：

Pose-Search 编辑器界面：左侧原图上叠加了红色骨骼骨架，中间有简化骨架与三维骨骼模型，右侧管理照片元数据、标签与性别信息。

画面里是一个滑雪板运动员腾空瞬间的照片。左侧大图被叠加上红色线条组成的人体骨骼骨架，中间区域同时展示了简化版的 2D 骨架和半透明的 3D 骨骼模型，右侧则是照片的 ID、作者、尺寸、性别和标签等信息。

这其实揭示了 Pose-Search 的两大能力：它能把任意照片"翻译"成骨骼数据，然后以骨骼数据为索引进行姿势匹配。用骨骼代替文字，就是它和其他图片工具最大的不同。

三个让人眼前一亮的独特设计

初次体验这个项目，有三处细节最打动我，它们也是理解整个项目灵魂的关键。

1. 33 个关键点，把身体变成一串"数字密码"

Pose-Search 基于 MediaPipe Pose 方案，会在每张人像照片上检测出33 个人体关键点（面部、肩膀、手肘、手腕、髋部、膝盖、脚踝等），每个点不仅记录二维坐标，还带有三维空间坐标和可见性置信度。

关键数据存放在src/utils/detect-pose.ts中，由NUM_OF_LANDMARKS = 33定义；而为了不阻塞界面，检测被放到了 public/worker/detect-pose.worker.js 这个 Web Worker 里后台执行。你在界面上看到红色骨架瞬间生成，背后就是这套流水线在工作。

2. 分部位匹配器：你可以只搜"左手肘"的姿势

这是最让我惊喜的功能。大多数姿势搜索工具是"整张图算一个相似度"，而 Pose-Search 把身体拆成了Face、Chest、左右 Shoulder、左右 Elbow、Crotch、左右 Hip、左右 Knee等多个部位，每个部位都对应一个独立的匹配器，统一注册在 src/Search/Search.ts 的matchers表里。

更妙的是，在三维骨骼模型上点击某个骨骼节点，系统会自动帮你选中对应部位的匹配器——想搜"左膝弯曲 90 度"的人，点一下左膝节点就行，完全不用记英文选项。

3. "视角无关"匹配模式：同一个动作，换个角度也能找到

拍照片的人不可能每次都在同一角度，为此项目为多数部位都实现了一对匹配器：普通版MatchShoulder和MatchShoulderCameraUnrelated（视角无关版）。后者把身体动作映射到"以躯干为基准的局部坐标系"里，从而摆脱相机拍摄角度的影响。

这个设计在 src/Search/impl/ 目录下体现得淋漓尽致——每个部位都有MatchXxx.ts和MatchXxxCameraUnrelated.ts两个实现文件。搜索时只需切换界面上的一个开关，就能在"考虑拍摄角度"和"忽略拍摄角度"之间自由切换。

动手实操：从克隆到第一次搜索的完整流程

纸上谈兵不如动手一试。整个过程大约五分钟，跟着做即可。

第一步：克隆项目并安装依赖

在终端执行以下三条命令（这也是仓库 README 提供的标准流程）：

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

项目使用 Vue 3 与 Vite 构建，依赖安装通常在一分钟内完成。如果你网络较慢，可以配置镜像源后重试。

第二步：启动开发服务器

继续执行：

npm run dev

浏览器会自动打开开发地址。搜索主界面默认就能直接使用，因为项目仓库自带了一份照片数据集（public/photos.json记录照片信息，public/landmarks.dat存放全部骨骼关键点），开箱即用。

第三步：完成一次姿势搜索

进入搜索界面后，按这个顺序操作：

1. 选择部位：从下拉框中选择"Left Elbow"（左肘）或"Right Knee"（右膝）等任意部位；
2. 设定条件：可选按性别筛选（男/女/不区分），以及是否开启"视角无关"匹配；
3. 点击搜索：系统遍历整个数据集，为每张照片计算相似度分数，按从高到低排序返回。

结果以缩略图网格展示，点击任意结果会弹出大图查看器，同步显示原图和姿势骨架的对比。

第四步：扩展自己的图片库

如果你想把自己的照片加入数据库，需要进入/#/editor编辑器页面。这里有一个小坑提前告诉你：编辑器依赖 Unsplash 的 API Key 来批量拉取图片，你需要在 Unsplash 官网申请一个免费的应用密钥，粘贴到编辑器顶部的输入框中。

拿到密钥后，编辑器的工作流是：搜索或上传照片 → 点击Run Model让 MediaPipe 自动生成骨架 → 手动补全性别和标签 → 点击Add Record写入数据集 → 最后点击Save data.db保存。

进阶技巧与避坑经验

跑通流程只是开始，想让姿势搜索更顺手，这几个经验值得收藏。

配置参数速查表

项目的核心参数集中在 src/config.ts，只有三行，非常好改：

三个容易踩的坑

1. 照片太糊匹配不到：MediaPipe 对低分辨率、强逆光、严重遮挡的照片识别率很低。尽量用人物占画面 60% 以上、光线充足的正面或侧面照；
2. 别忽略"视角无关"开关：搜"同一动作不同角度"记得打开它；但如果你就是想找特定朝向的姿势，请保持关闭，否则结果会偏宽泛；
3. 性别筛选是弱约束：性别是靠照片标签自动推断的，并非百分百准确。对结果要求严格时，别只依赖它筛选。

数据存储的小秘密

你可能会好奇landmarks.dat到底存了什么。打开 src/utils/PhotoDataset.ts 会发现，每张照片的 33 个关键点被紧凑编码成33 × 7个浮点数（2D 坐标 3 个 + 3D 坐标 3 个 + 可见性 1 个），全部照片拼成一个二进制大数组。这正是搜索能在浏览器本地飞快完成的原因——无需任何后端服务，纯前端即可跑完整套检索。

想定制自己的匹配算法？接口只要求两个方法

如果你对技术感兴趣，Pose-Search 的扩展点设计得非常清爽。打开 src/Search/impl/search.ts，可以看到匹配器的统一接口PoseMatcher只要求实现两个方法：

interface PoseMatcher { prepare(model: SkeletonModel): void; // 用当前选中的姿势初始化参考数据 match(photo: Photo): MatchResult | null; // 逐张照片打分，返回分数或 null }

只要实现这两个方法，再把它注册进matchers表，一个新部位（比如"脖子""脚踝"）的搜索能力就诞生了。以 MatchElbow.ts 为参照，你能看到真实的打分逻辑：同时比较肘部弯曲角度、手臂在屏幕上的朝向、以及手臂在躯干局部坐标系中的方向，多个误差项相乘得到最终分数。

这种"一处接口、多处实现"的结构，让整个项目就像搭积木一样可以自由扩充。

从"搜一张图"到"收藏一类动作"

回过头看开头那个找图的困扰：以前你只能靠文字碰运气，现在你可以直接拿一张心仪的动作照片作为搜索条件，几秒内翻出整个库里所有同款姿势。不管是整理动作参考素材、分析运动姿态，还是给照片库做智能归档，Pose-Search 都提供了一种完全不同的、更接近直觉的搜索方式。

这个项目基于 MIT 协议开源，你可以放心使用、修改，甚至把它移植到自己的项目里。想立刻体验，就按上面四步操作：克隆仓库 → 安装依赖 → 启动服务 → 选一个部位点下搜索。

下一次当你再为某个动作画面翻遍整个图片库时，不妨让姿势本身替你说话——动作是最好的关键词，而 Pose-Search 就是听懂动作的那个翻译官。

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