The OpenBiomechanics Project — 全球最大公开精英棒球动捕数据集

INFOBOX — OpenBiomechanics 一屏速览

维度	内容
本质	一家棒球训练机构把自家运动员的动捕评估库开源出来的项目——不是一次科研采集，而是既有评估数据的二次释放
官方名	The OpenBiomechanics Project（OBP），官网 openbiomechanics.org
主办	Driveline Baseball Research & Development（美国）
首发	2022 年 12 月：先 100 名投手，约一周后补 98 名打者
投球	411 次快球试投 / 100 名投手；球速中位 85.3 mph（69.5–94.4）
击球	677 次挥棒 / 98 名打者；出球速度中位 91.0 mph（48.8–107.0）
体能	1,934 次力台评估 / 1,162 名运动员（2024-07 新增）
硬件	光学标记点多相机系统；投球 3 块、击球 4 块测力台；标记点 360 Hz、力台 1,080 Hz
三层数据	Raw C3D 轨迹｜Full signal 全信号 CSV｜POI 每次一行汇总
许可	数据 CC BY-NC-SA 4.0（禁止商用，专业体育组织关联人员另禁）｜代码 MIT（2026-07 起）
体量	投球 + 击球全量压缩约 1.1 GB（GitHub Releases）
论文	无同行评审数据论文；引用为 2022 年 misc 条目，无 DOI
库内互链	UL-RED（rid 1162）、REHAB（1163）、GaitND（232）、gaitpdb（242）、LIVE-GaitNeuroKids（1055）
一句话定位	目前公开可得的最大规模精英棒球动捕数据集——但只覆盖快球，且许可是非商业

OpenBiomechanics 是一个判断"开源数据集能长什么样"的好样本，但它身上有两处让人意外的地方，值得先说清楚。

第一处是它的出身。绝大多数公开运动数据集来自实验室的专项采集：招募几十名受试者、设计几个动作、跑一遍伦理审批、写一篇数据描述论文。OBP 不是。它是 Driveline Baseball——一家商业化棒球训练机构——把日常评估业务里已经积累下来的动捕记录，脱敏后整批释放。这意味着数据不是"为发表而采集"的，而是"为训练决策而采集"的：动作更接近真实训练情境，但受试者群体天然偏斜（客户以大学球员为主），采集协议也随业务演进而非随实验设计固定。理解这一点，比记住任何数字都重要。

第二处是它的元数据形态。它没有 DOI，没有统一的"数据集版本号"，没有标准划分，甚至在 2026 年 7 月做了一次 git 历史重写——旧的克隆和旧文献里引用的路径全都失效。它的可信度不来自一篇论文，而来自一份持续维护的仓库、一份 DATASHEET.md、一套逐资产校验的下载脚本，以及一批第三方研究者用它发表的论文。

导语读法三则：

1. 只想拿数据建模：直奔 §5 获取路径与 §6 坑点清单。特别注意许可：这不是一个可以随手丢进商业产品的东西。
2. 关心怎么用它做研究：§4 讲三层数据结构与事件定义，§7 讲第三方研究已经拿它做了什么、以及做错了什么。
3. 关心它和临床/康复数据的关系：§9 给出库内五个同族条目的对照，以及"竞技动作"与"临床动作"两种采集范式的差别。

§0 导读：这个数据集解决什么问题

§0.0 先看三个数字

在展开任何讨论之前，先给三个能让人立刻形成印象的数字：

411 与 100。 411 次快球试投，来自 100 名投手。这组数字说明数据是"少人多试"的结构——不是一百个人各投一次，而是一百个人各投四次上下。这个结构决定了后续所有统计的分母。

677 与 98。 677 次挥棒，来自 98 名打者，其中 604 次有 HitTrax 记录的球路结果。这组数字说明击球模块比投球模块"试次更多、人更少"，平均每人近 7 次挥棒。

1,934 与 1,162。 1,934 次力台体能评估，来自 1,162 名运动员。这组数字与前两组不在一个量级上，因为体能评估是"一人一次、多种测试"的结构，不需要多次试投来稳定测量。

三个数字并排看，能读出一个设计逻辑：动作类数据靠多次试投降低测量噪声，体能类数据靠扩大人数提高人群覆盖。这个逻辑是对的，但它也意味着两类数据的人群构成不同，不能简单合并。

§0.1 一个长期存在的结构性稀缺

棒球投球是运动生物力学里被研究得最透的动作之一，但"透"和"开放"是两回事。肘部尺侧副韧带（UCL）损伤、肩关节内旋力矩过高、髋肩分离不足——这些概念在运动医学文献里讨论了三十多年，可是支撑它们的原始数据，绝大多数锁在职业球队的私有数据库里、锁在实验室的硬盘里、或者以"联系作者索取"的形式存在。一个在马来西亚读本科的学生、一个在阿根廷做康复研究的治疗师、一个想验证自己的无标记动捕算法是否可靠的工程师，拿不到这批数据。

后果是双重的。其一是可复现性：论文报告了"投球者肘内翻力矩平均为某值"之类的数字，但没有人能拿同一批原始数据重跑一遍。其二是基准缺失：任何新的姿态估计算法、任何新的逆动力学流程，都没有一个公认的"金标准"数据可以对照。

§0.2 OBP 的回答

OBP 的回答很直接：把一训练机构自己已经在用的数据放出来。具体做了三件事。

第一，给出三层表示，覆盖不同起点的人。 想要从零开始自己算的，拿 C3D——里面是原始标记点三维轨迹和测力台的模拟信号，配一份静态模型文件，任何支持 C3D 的软件都能打开。想要直接做统计的，拿 POI 表——每次试投一行，列是球速、肘内翻力矩、髋肩分离等几十个指标。想要做时间序列建模的，拿 full signal 表——按 360 Hz 与 1,080 Hz 输出关节角度、角速度、力矩、能量流。

第二，把约定写清楚。 运动学与动力学用右手定则算完之后，作者又做了一批"让教练和球员看得懂"的调整：左右手对称化、符号取反、加减 90 度。这些东西如果不写出来，使用者算出来的数会对不上。仓库的 README 逐关节列出了每个轴的正负方向，这是这份数据集最被低估的部分。

第三，把许可写清楚，也把禁区写清楚。 数据是 CC BY-NC-SA 4.0，非商业；外加一条针对"专业体育组织与金融分析公司关联人员"的排除条款。这条排除条款在开源数据集里极为罕见，但它恰恰说明了数据来源：这是一家商业机构的资产。

§0.3 它不解决什么

必须坦白：OBP 不是一个"基准数据集"。它没有排行榜、没有基线模型、没有标准划分，也没有一篇说明"这个数据集该被怎么评测"的论文。它是一堆高质量的原料。原料的价值取决于使用者的手艺，这一点在使用前必须认清。

§0.4 一个具体的判断：它算不算"数据基础设施"

用"基础设施"的标准衡量 OBP，会得到一个有意思的结论。

基础设施通常有四个特征：被多方依赖、有稳定的公共接口、有长期维护承诺、有独立于单一机构的存档。OBP 在前两条上表现良好——大量第三方论文依赖它，接口（C3D / CSV / obp 包）稳定且文档清晰；在后两条上有明显欠缺——维护依赖 Driveline 一家机构的持续意愿，存档依赖 GitHub 一个平台，没有 Zenodo 之类的独立存档副本，也没有 DOI 锚定版本。

这个判断有实际后果。如果你打算把 OBP 作为一项长期研究的基础数据（例如构建一个持续更新的运动损伤队列模型），就必须自己承担"未来某天仓库变动"的风险：定期做本地镜像、记录每次使用的 commit、在论文中写明数据获取日期。这不是过度谨慎——2026 年 7 月的历史重写已经证明，这个仓库确实会做破坏性变更。

§0.5 本文的写作立场

最后交代一下这份条目的写法，方便读者判断哪些内容可信到什么程度。

凡是官方三源能直接读到的数字，本文照录并注明口径；凡是官方未给、而二手资料常给的数字（如相机台数），本文写"未公开"；凡是需要推断的（如 time 列零点），本文明确标注为推断。所有关键数字在附录 C 里有一张证据链表，标注了是"两处一致"还是"单一来源"。

这样做的原因很简单：OBP 是一个没有论文背书的资源，任何转述都可能在转述中失真。读者需要一个能自己回查的路径，而不是一段看起来权威的叙述。

§0 读法三则：

1. 本文所有数字均出自官方三源（官网、仓库 README、DATASHEET.md）与已发表的第三方论文，逐条在附录 C 列出处；凡三源未给的（如相机台数、标记点总数），本文一律写"未公开"而不是补一个看起来合理的数字。
2. OBP 的数字有"人数"与"试次数"两套口径，混用是最高频的误读。411 是试投数，100 才是人数（坑 2）。
3. 这是一份"活"的数据集。2026 年 7 月的重写让所有旧链接失效，读任何二手资料前先回仓库确认现状（坑 4）。

§1 数据集速览：十三问十三答

Q1：OpenBiomechanics 到底是一个数据集还是一个项目？

是一个项目，旗下有四个模块。三个是数据模块：Baseball Pitching（投球）、Baseball Hitting（击球）、High Performance（测力台体能评估）；第四个是 Computer Vision（OBP-CV），放的是同步 genlock 视频与多相机标定，属于工具与素材性质。检索时把"OBP"当成一个数据集名字来搜，会漏掉模块级文档。

Q2：谁做的，为什么做？

Driveline Baseball 的研发部门。动机在首发博客里写得很直白：创始人 Kyle Boddy 十多年前就提议开源生物力学数据，“开源投球物理数据曾经从根本上改变了棒球”，如果开源动捕数据能有同样影响的一小部分，就能再改变一次。博客里还列了两个更具体的目标：让经济条件或科研条件较差的学生能做出有竞争力的项目申请；以及把它当作招聘时的作品筛选材料。

Q3：数据从哪来？

Driveline 运动员的动作捕捉评估档案。运动员到机构做评估，投手在投手丘上投若干颗比赛强度快球，打者在打击区对着投球机挥棒，同时被光学动捕系统与埋在地下的测力台记录。这些记录原本用于制定训练处方，现在被脱敏后成批公开。

Q4：有多大？

投球模块 411 次试投、100 名投手；击球模块 677 次挥棒、98 名打者，其中 604 行有 HitTrax 击球结果配对；High Performance 模块 1,934 次评估、1,162 名运动员。投球加击球的全量压缩包约 1.1 GB。

Q5：采集规格是什么？

标记点衍生信号 360 Hz，测力台 1,080 Hz。投球用 3 块力台埋于投手丘草皮下，击球用 4 块力台置于打击区，外加一个 10 标记点的球棒刚体。全信号经 4 阶 Butterworth 低通滤波：运动学与动力学 20 Hz 截止，地面反作用力 40 Hz 截止。相机型号与台数官方未公开。

Q6：有什么标签？

没有标签。它是一个无监督/自监督场景，或者更准确地说，是一个"你要预测什么就自己造标签"的场景。常见标签是球速、出球速度、以及肘内翻力矩这类损伤风险代理指标。

Q7：许可能不能商用？

不能。数据与文档是 CC BY-NC-SA 4.0，非商业。而且有一条超出标准 CC 的排除条款：受雇于、关联于或为专业体育组织、金融分析公司的重要股东人员，无论何种用途都被禁止，除非单独取得书面商业许可。代码（2026 年 7 月起）是 MIT，可以随便用。教学用途免费到 2030 年 12 月 31 日，个人科研永久免费。

Q8：有配套论文吗？

没有同行评审的数据描述论文。官方给定的引用是 2022 年的一条 misc 条目（Wasserberger 等），DOI 字段为空。所以它在学术引用体系里的地位，弱于一本 Scientific Data 论文所描述的数据集——尽管它的实际使用量可能更高。

Q9：它和 OpenCap、OpenSim 是什么关系？

OpenCap 是 Stanford 开发的无标记动捕工具链，OpenSim 是肌肉骨骼建模平台，ezc3d 是读 C3D 的 Python 库。OBP 不是这三者的替代品，而是它们的输入或验证对象：你可以用 OpenCap 拍同样的动作再和 OBP 的标记点数据对照，也可以用 OpenSim 加载 OBP 的标记点轨迹重算逆动力学。三者是上下游，不是竞品（§9）。

Q10：一句话结论，值不值得用？

如果你要研究棒球投球或挥棒的生物力学，且用途非商业，它是目前公开可得的、规模最大、保真度最高的选择，没有第二家能比。如果你要的是"带标签、有划分、有基线"的机器学习基准，它不合格，得自己动手造。如果你是职业球队或金融公司的人，先读许可。

Q11：数据里有没有"球种"和"握法"信息？

只有球种一列，且 411 次全是 FF（快球）。握法（四缝/二缝）在 DATASHEET 中未见字段说明，POI 表是否另有细分未在文档中列出。若要研究握法差异，需自行查看元数据列清单，且很可能无此信息。这是一个常被误以为"应该有"的字段。

Q12：能不能用它做投球数量（workload）或疲劳研究？

不能。数据是单次评估中的若干次试投，没有跨天、跨周的时间序列，也没有投球计数、休息天数、比赛记录。所有关于工作量与损伤的经典问题（如"单场投球数上限"），在这份数据里都无法回答。这是竞技数据集与流行病学队列之间的一道硬边界。

Q13：为什么说它"没有论文"却不影响学术使用？

学术使用不要求数据有论文，只要求可引用。OBP 提供了官方引用格式（2022 年 misc 条目）与 CITATION.cff，第三方论文也普遍引用它。缺论文的真实影响是：没有权威的"设计意图说明"，使用者需要自己从 README 与 DATASHEET 拼出设计逻辑；也没有同行评审的质量背书，可信度要靠使用者自己核验。

§1.1 十三问之外，还有三个"不重要但常被问"的问题

“能商用吗？” 已在 Q7 答过，这里只补一条实务建议：如果你的场景处在灰色地带（例如大学实验室接了职业球队的横向课题），不要自行解释许可，直接发邮件问 Driveline 的 sportsscience 邮箱。许可是写死的文本，解释权在许可人。

“有没有中文文档？” 没有。官方文档全部英文，且术语密集（layback、double-dipped kinetics、hip-shoulder separation）。阅读时建议先建立术语表（本文附录 A），再逐段读各模块 README。

“为什么 GitHub 上和官网上的人数数字看起来不一致？” 因为官网只提投手与打者人数，GitHub README 提试投数与人数，两者口径不同但数值互补。这不是矛盾，是不同粒度的概括（附录 C 逐条存照）。

§1.2 如果你只有五分钟

读三个地方就够：本文 §10.3 的一页速查卡（全部硬数字）、§6 的坑 2 与坑 8（人数口径、许可禁区）、§10.2 的决策卡（能不能用）。其余章节是在你需要回答"为什么"的时候再回来查的。

一个补充的"五分钟变十分钟"建议：把 §2.2、§2.3、§2.4 三张表抄下来，贴在你的分析脚本开头当注释。这样每次跑代码，你都会看到"411 次 / 100 人"“677 次 / 98 人”"1,934 次 / 1,162 人"这三组对应关系，口径错误会在发生前被拦下。这不是玩笑——本库历史上有过多起"人数与试次数混用"导致结论作废的案例。

§1.3 术语先行：五个不懂就会读错的词

OBP 的文档用了一批棒球与生物力学的专用词，中文语境里没有完全对应的常译。读之前先建立这五个词的映射，能省下大量查词时间。

layback：投球蓄力末端肩关节外旋达到极值的姿态，官方在事件定义里把它与 maximum external rotation（MER）并列，是同一个时刻的两种叫法。中文宜写"最大外旋（layback）"。

hip-shoulder separation：髋肩分离，指骨盆与躯干在横断面上的相对旋转角。它在官方数据结构里不是一个独立字段，而是"躯干-骨盆"相对节段的 Z 轴值（§4.2）。这个词在教练语境里用得很泛，在数据里必须按节段的定义用。

double-dipped kinetics：官方文档的原文表述，指肩与髋同时给出按近端与远端解析的两套动力学解（§2.7）。没有通用中译，本文写作"双解析动力学"。

varus moment：内翻力矩，肘关节在投球末段承受的主要力矩方向，常被用作 UCL 负荷的代理指标。注意它是内力矩，不是韧带应力（§7.2）。

point of interest（POI）：不是"兴趣点"，而是"每次试投一行的汇总指标表"（§2.5）。这个缩写在本库其他条目里也有不同含义，读别处文献时要按上下文判断。

§1.4 数据集的"五个第一眼"

如果只能从全文摘出五个"第一眼就该知道"的事实，我会选这五个。它们覆盖了身份、规模、结构、限制、许可五个维度，任何其他细节都是在它们之上的展开。

第一眼：它不是论文数据集，是机构数据的公开化。 这决定了它的规模优势（无须为发表而精简）与文献弱势（无设计意图说明），也决定了它的许可必然带有商业机构的痕迹。

第二眼：投球 411 次 / 100 人，击球 677 次 / 98 人。 两个模块都以"少人多试"为结构，任何"独立样本"的假设都需先按人聚合。

第三眼：三层表示（C3D / 全信号 / POI）覆盖了从原始到汇总的完整链条。 这是它最有工程价值的设计，也是它"比很多学术数据集更实用"的原因。

第四眼：只有快球、无肌电、无变化球、无纵向随访。 四个"无"划定了它能回答的问题边界：快球投掷的机制、挥棒的机制，以及它们与身体能力的关系；不包括球种比较、肌肉激活、损伤预测。

第五眼：许可比标准 CC 更窄。 非商业之外，还有职业体育与金融分析的排除条款。这是使用前必须跨过的第一道门。

把这五个"第一眼"记住，再读后面的章节时，很多细节会自动归位——例如为什么官方要强调"公开的是更大数据集的样本"（对应第一条）、为什么 DATASHEET 把运动员泄漏列为第一条局限（对应第二条）、为什么 CV 模块要反复标注"临时性"（对应第三、四条）。

§2 数据构成与规格

§2.1 四个模块的分工

OBP 仓库按"研究问题"而不是"文件类型"分目录，这是理解它的第一个关键。

模块	目录	解决的问题	仓库内直接可读	需下载
棒球投球	baseball_pitching/	投手从抬腿到球出手再到最大内旋的完整动力学	POI 表、元数据表	C3D、全信号 CSV
棒球击球	baseball_hitting/	打者从启动到触球的动力学，含球棒与来球结果	POI 表、元数据表、HitTrax 表	C3D、全信号 CSV
高表现	high_performance/	同一批运动员的测力台体能评估	完整评估表	无（表直接在仓库）
计算机视觉	computer_vision/	多机位同步视频与临时性多相机标定	标定脚本、测试、文档	cv_media.zip

这个分法有一个隐含的好处：POI 与元数据表留在 git 里，克隆一次就能做统计；只有 C3D 和全信号要另下。对于只想做"球速和什么运动学变量相关"这类问题的人，28 MB 的克隆就够了，不必碰那 1.1 GB。

§2.2 投球模块的硬数字

411 次试投全部来自 100 名投手、100 个 session。也就是说，一名投手一次评估可能贡献多次试投（首发博客的说法是"每位至少 2 颗比赛强度快球，取决于处理并上传了多少"），但每人只在一个 session 里出现。

维度	数值
试投数	411
投手数	100
球种	全部为快球（FF），411/411
右投 / 左投	328 / 83
球速 min / median / max	69.5 / 85.3 / 94.4 mph
年龄 min / median / max	17.7 / 20.7 / 27.6 岁
水平 College / Independent / High school / MiLB	314 / 42 / 32 / 23

读这张表要注意三件事。第一，“elite” 是一个营销词，不是一个统计口径：中位球速 85.3 mph 在大学棒球里属于合格但不出众的水平，最大值 94.4 mph 离职业平均也还有距离；MiLB 样本只有 23 条。第二，年龄中位 20.7 岁，说明这是"从高中后期到大学毕业"这个窗口的人群，不是职业球员的稳态。第三，411 次全是快球——这意味着所有关于"投变化球时肘部负荷更高"的经典论点，在这份数据里无法直接检验。

还有一层更隐蔽的口径问题：表里的 Independent 指独立联盟（非 MLB 附属的小联盟），与 College、High school 并列时，实际并不构成一个按竞技水平单调排列的序列。做有序变量编码时，如果按"高中 < 大学 < 独立联盟 < MiLB"去赋值，等于预设了一个未经数据支持的等级假设。更稳妥的做法是把它当无序类别，或者另找可量化的水平指标（如球速本身）。

§2.3 击球模块的硬数字

维度	数值
挥棒数	677
打者数	98
右打 / 左打	496 / 181
出球速度 min / median / max	48.8 / 91.0 / 107.0 mph
年龄 min / median / max	17 / 20 / 31 岁
水平 College / High school / MiLB / Independent	517 / 83 / 47 / 30
HitTrax 配对行	604

击球模块有一个投球模块没有的东西：来球的标准化。所有挥棒都打投球机，设定约 65 mph，距本垒约 40 ft。这是为了让打者的动作在可比的刺激下被记录——但代价是，真实比赛中面对 90+ mph 来球和面对变化球时的调整策略，数据里看不到。出球速度最低 48.8 mph 的那批挥棒，大概率是年轻球员的练习挥棒或打空后的弱击，使用时应先看分布再做截断。

HitTrax 604 行与 677 次挥棒之间差 73 次，DATASHEET 没有解释缺配原因（遗留疑点，见附录 C）。

§2.4 High Performance 模块的硬数字

这是 2024 年 7 月才加入的模块，性质与前两个不同：它记录的不是棒球专项动作，而是通用体能测试，用来回答"这些运动员的身体能力如何"。

维度	数值
评估次数	1,934
运动员数	1,162
水平 College / High School / Pro	904 / 816 / 214

测试	缩写	有数据的记录数	覆盖率
反向纵跳	CMJ	1,913	98.9%
蹲跳	SJ	1,827	94.5%
连续跳	HT（Repeated Hop）	1,803	93.2%
等长中位大腿拉	IMTP	1,518	78.5%
爆发俯卧撑	PP（Plyo Pushup）	438	22.6%

Plyo Pushup 只有 438 条，是这份数据里最明显的缺失。使用时不要把它当作"上肢爆发力"的通用变量直接进入全样本回归——那等于用 22.6% 的样本代表全体。除五项测力台测试外，还有胸椎活动度与手持肌力计测量的肩内旋/外旋力量。

High Performance 表以匿名化 UUID（athlete_uid）标识运动员，这一设计意味着同一个人可以跨模块被连接——前提是你能拿到对应关系。官方文档没有提供动捕模块的 user 与体能模块的 athlete_uid 之间的对照表（遗留疑点，见附录 C）。因此实务上，体能模块更适合作为独立的"身体能力分布"研究素材，而不是直接与投球力矩做个体级配对。

§2.5 三层数据表示

Raw 层：C3D 文件。 C3D 是生物力学领域的事实标准二进制格式，内含标记点三维坐标序列、模拟通道（力台六分量）、帧率、事件标记。OBP 的 C3D 是"清洗后"的——原始采集中的明显伪迹已被处理，但软组织伪迹这类生理性误差不可能被清除。每个运动员一个文件夹，另付静态模型文件（用于定义节段）。

早期文件名有一套完整编码：USERid_SESSIONid_HEIGHT_WEIGHT_PITCHNUMBER_PITCHTYPE_PITCHSPEED.c3d。身高以英寸、体重以磅写入，球速保留一位小数但去掉小数点——_905 就是 90.5 mph。这种"把元数据塞进文件名"的做法在 2022 年的初版里很实用，但它有两个问题：文件名一旦被重命名，元数据就丢了；而且它把身高体重暴露在文件名里，虽然数值本身不构成直接标识，但对匿名化是个不必要的风险。2026 年重写后文档改为强调数值型 user/session ID 与 UUID athlete_uid。

Full signal 层：全信号 CSV。 这是把 C3D 里的原始轨迹经逆动力学计算后，按信号类型拆成多张表。投球模块有六张：energy_flow（能量流）、force_plate（力台原始与派生量）、forces_moments（关节力与关节力矩）、joint_angles（关节角度）、joint_velos（关节角速度）、landmarks（标志点位置）。表之间用 session_pitch 与 time 两个键关联。注意 full signal 以 zip 分发（如 joint_angles.zip），需要解压。

POI 层：汇总表。 每次试投或挥棒一行，列是各种"关注点指标"——球速、最大外旋角、肘内翻力矩峰值、髋肩分离最大值等。这一层是多数统计分析的实际入口，也是仓库内直接可读的部分。

§2.6 采样、滤波与坐标系

项目	值	说明
标记点衍生信号采样率	360 Hz	投球与击球一致
测力台采样率	1,080 Hz	恰为 3 倍，便于整倍重采样
运动学/动力学滤波	4 阶 Butterworth 低通，20.0 Hz	全信号
GRF 滤波	4 阶 Butterworth 低通，40.0 Hz	全信号
全局坐标系	+x 二垒→本垒，+y 指向一垒，+z 向上	右手系

3 倍关系不是巧合，是有意设计的：1,080/360 整除，把 GRF 降采样到运动学帧率时不会引入相位错位以外的额外插值误差。但这不等于可以直接合并——两组信号在同一帧率下仍然可能有时间偏移，DATASHEET 明确要求用户谨慎处理。

坐标系的方向也值得说明：+x 从二垒指向本垒，意味着投手面向 -x 方向投球（投手站在本垒的 -x 侧）。这与很多实验室"受试者面向 +x"的惯例相反，从其他来源迁移脚本时必须重新检查符号。

力与力矩是内力/内力矩，默认表达在近端节段坐标系——而不是全局坐标系。这一点在做跨研究比较时最容易出错：文献里报告的"肘内翻力矩"如果是在全局系或不同节段系下算的，数值不可直接比。

§2.7 一个容易被忽略的规格：双解析动力学

DATASHEET 提到肩与髋提供"dual-resolved"（原文写作 “double-dipped”）动力学。通俗地说，就是在某些关节上同时给出按近端节段和按远端节段解析的两套力/力矩。人体是闭链时会过约束，从不同方向做逆动力学得到的解不完全相同；把两套都放出来，等于让使用者自己判断该用哪一套，或者做一致性检验。这是一个相当专业、也相当诚实的处理——多数数据集只给一套，且不说明是按哪一端算的。

§2.8 用一张"数据血缘图"理解三层的关系

若把 OBP 的数据生产链画成一条竖线，自上而下是：

[运动员] → [光学标记点系统 360 Hz] → [原始标记点轨迹]
                    |                          |
             [3/4 块测力台 1,080 Hz] → [原始六分量]
                                               |
                                    [标记点清洗 + 缺失插补]
                                               |
                                    [逆动力学计算（内力矩/能量流）]
                                               |
                          +--------------------+--------------------+
                          |                                         |
                 [Full signal CSV 六表]                    [事件检测 + 峰值提取]
                                                                      |
                                                              [POI 表每次一行]
                                                                      |
                                                          [元数据表 / HitTrax 配对]

这张图有两个用途。

第一，判断你手上的数据处在哪一级。 POI 是链条末端，已经被施加了所有上游选择（清洗规则、滤波截止、事件定义、峰值提取算法）；C3D 是链条前端，只经过清洗。下游数据更省事，但可调整空间更小。如果你的研究问题需要在原始曲线上做自己的峰值检测，就必须回到 C3D。

第二，判断误差会在哪一级被放大。 事件定义用 10% 与 100% 体重阈值，体重来自元数据；如果体重误差 2 kg，阈值就会平移，事件时刻随之移动，峰值提取结果随之改变。链条上最脆弱的一环往往是最上游的那个输入（体重），而不是最复杂的那个算法（逆动力学）。

§2.9 一条数据的完整身份：从文件名到元数据行

以一次投球试投为例，它在不同层的"名字"是这样的：

层级	标识方式	示例形态
C3D 文件	早期编码文件名	USER_SESSION_HEIGHT_WEIGHT_PITCHNO_FF_SPEED.c3d
全信号表	session_pitch + time	一行一个时间采样点
POI 表	与元数据同序的行	一行一次试投
元数据表	user / session / 试投序号	一行一次试投
体能模块	athlete_uid（UUID）	一行一次评估

这张表解释了为什么"连接"在 OBP 里是一件需要小心的事：同一个人的标识在不同模块里可能是数值 ID，也可能是 UUID，而官方没有给出两者的对照。任何"把投球数据和体能数据连起来"的尝试，都要先确认连接键是否存在（见坑 12）。

还有一层：早期文件名里嵌了身高体重，而元数据表里也有身高体重（英寸/磅与米/千克双版本）。如果两者不一致（例如运动员后来重新测量），以哪一份为准？文档未说明。这是又一个"看起来无害、实际会导致复现失败"的细节。

§2.10 OBP 之外：文件格式本身的代价

选择 C3D 是有代价的。它是一个 1980 年代设计的格式，优点是被几乎所有生物力学软件支持、能同时承载点与模拟通道；缺点是：

• 扩展性差，新增变量只能塞进 “parameters” 段，没有统一规范；
• 不同软件写入的 C3D 在单位、坐标系、事件存储方式上存在差异；
• 无法直接流式读取大文件，必须先读头部再定位。

OBP 的应对方式是提供 full signal CSV 作为平行通道——需要精细控制的人用 C3D，需要快速分析的人用 CSV。这种"原始格式 + 派生表格"的双轨设计，是公开运动数据集里比较成熟的一种做法，值得其他项目借鉴。

顺带一提，C3D 的生态在 2020 年后明显好转，ezc3d 提供了干净的 Python 接口，OBP 的官方教程也正是用 ezc3d 讲的。如果你的处理环境只有 Python，这是最省事的路径。

§2.11 关于"清洗后"三个字的追问

DATASHEET 与 README 都强调 C3D 是 “cleaned”。这个词很含糊：清洗包括什么、不包括什么，文档没有逐条列。从上下文可以推断它至少包含：删除明显伪迹帧、处理标记点短时丢失（插补）、统一坐标系。

它显然不包含：软组织伪迹矫正、皮肤移动补偿、测力台与地表面的力传递误差补偿。这些是生物力学的经典系统误差，任何从 OBP 出发的绝对量结论（例如"肘内翻力矩平均多少牛顿米"）都应带上这层不确定性。

“cleaned” 的模糊性带来一个具体的实践风险：使用者会误以为数据已经"干净到可以直接比较不同研究"。实际上，“清洗后"只意味着"OBP 内部一致”，不意味着"与其他实验室的绝对量可比"。

§3 采集协议与同步

3.0 为什么采集协议值得单独一章

对图像数据集，采集协议往往一句话带过（“由放射科医师使用某型号 CT 扫描”），因为扫描仪的参数会写进 DICOM 头，读者自己就能查。运动捕捉不一样：标记点贴在哪儿、相机怎么摆、力台埋多深、事件怎么定义，这些东西不会自动写进数据文件里，只能靠文档说明。

而 OBP 的文档在这些方面恰恰是不完整的。官方给了"3 块力台埋于草皮下、厚约 0.5 英寸"，但没有给相机台数；给了"5 个事件及其阈值"，但没有给事件检测算法的实现细节。这意味着：你无法从零复现 OBP 的采集过程，只能接受它作为一个黑箱输入，然后从输出反推。

这不是批评，而是一种定位。理解"哪些能复现、哪些不能"，决定了你能在 OBP 上做哪一类研究。做"用数据回答问题"的研究，完全够用；做"跨实验室方法学比较"的研究，不够。

3.1 实验室布置

投球场景：三块测力台嵌入投手丘草皮下，草皮平均厚度约 0.5 英寸。这个 0.5 英寸在生物力学里不是小数字——它意味着力台表面与地面之间有约 1.3 cm 的弹性介质，会带来轻微的高频衰减与力传递延迟。作者把厚度写进文档，是想让使用者知道"这不是刚性地面"。

击球场景：四块力台置于打击区草皮下。打者启动时一只脚或双脚踩在后板，落地时前腿踩在前板。四块板的分工设计意味着可以分别捕捉前后脚的支撑相。

力台编号 FP1、FP2、FP3（击球另有第四块）。这里有一个极容易出错的细节：FP1 与 FP3 的 X 轴正方向定义为"制动/后方"，而 FP2 的 X 轴正方向定义为"蹬伸/前方"。也就是说，同一份数据里，不同力台的同一列符号含义相反。任何跨板求和或比较的脚本，第一步必须做符号统一。

从布置可以反推出一个研究问题的边界：三块板覆盖投手丘的前后脚区域，意味着研究可以区分"后腿推进"与"前腿制动"两类力，这恰恰是投球生物力学讨论最久的争议点之一。四块板覆盖打击区则允许更细的左右脚分解。板的数量不是硬件参数，它直接决定了哪些力学分解是可能的。

3.2 相机与标记点

官方文档对相机系统的描述只到"基于标记点的光学动作捕捉"这一层。相机品牌、台数、型号、采集软件、标记点总数，在 DATASHEET 与投球模块 README 中均未给出。

这一点需要特别澄清，因为网上有一种常见的误读：看到 computer_vision 模块里提到"8 路 OptiTrack"，就以为主系统是 8 台 OptiTrack 动捕相机。不是。那 8 路 OptiTrack 是计算机视觉模块的同步视频机位，用于多相机标定与无标记姿态估计实验，与动捕主系统是两套东西。CV 模块标定还用了 4 台 Edgertronic 高速相机与 1 部 iPhone 视频流。

标记点集合在仓库中以正视图与背视图的图片形式给出，没有数字化的清单。文档里明确提到的两个细节值得记下来：

• LIC/RIC（髂嵴标记）已不再使用，部分 C3D 文件中可能缺失。这意味着同一个变量的计算路径在不同年份的试投里可能不同。
• RKNEE2/LKNEE2 在文件中实际标记为 RMKNE/LMKNE。这是命名遗留问题，写解析脚本时按文档名去查找会找不到列。

相机台数的缺失并不意味着精度不可评估。一个间接线索是采样率与滤波设置：标记点 360 Hz、20 Hz 低通，说明系统能捕捉到的最高有效频率远高于投球动作的主要频带（投球动作的功率谱通常在 10 Hz 以下）。换言之，在这份数据的精度预算里，滤波与建模的误差比相机的空间精度更重要——这也是为什么官方把大量文档篇幅花在坐标约定上，而不是硬件参数上。

§3.3 事件定义

事件是 C3D 与全信号数据的"锚点"，也是所有 POI 指标的计算依据。两个模块的事件定义不同，不能混用。

投球（5 个事件）：

事件	判据	含义
Foot contact	前脚 GRF 达 10% 体重	跨步脚刚触地
Foot plant	前脚 GRF 达 100% 体重	跨步脚完全承重
Maximum external rotation（MER / layback）	肩外旋角峰值	蓄力末端，肘部负荷最高的时刻之一
Ball release	球离手	投球动作的最后动力释放
Maximum internal rotation	肩内旋角峰值	随挥阶段的旋转极限

用 10% 与 100% 体重作为阈值是一个经验做法，它的好处是可自动化，坏处是对体重估计误差敏感——而体重是从文件名或元数据里取的，如果元数据有误，阈值判据就会漂移。

击球（3 个事件）：front foot contact、front foot plant、contact（触球）。

§3.4 同步的现实

OBP 没有公开说明标记点系统、力台与视频之间的同步机制（硬件时码、软件触发还是事后对齐）。但从数据结构可以推断：力台与标记点在同一采集系统内（C3D 同时承载两者），所以二者天然同步；视频是另外的系统，CV 模块的标定工作里专门有一套"timing diagnostics"，说明视频与动捕的时间对齐在 OBP-CV 里仍是一个待解决的问题。

对使用者而言，务实的做法是：不要假设 full signal 表里物理量之间的时间零点是精确的。做事件对齐时，先画前脚 GRF 曲线，确认峰值时刻与 C3D 事件标记一致，再做后续计算。

§3.5 同一份数据为什么会有"两个版本的感觉"

OBP 的数据来源是机构日常评估，这意味着不同年份的记录可能来自不同的采集配置。官方做了一件事来缓解这个问题：统一清洗与统一计算。但它没有做、也不可能做的，是抹平采集端的所有差异。

具体表现有三类：

标记点集合的变化。 LIC/RIC 髂嵴标记"已不再使用，部分 C3D 可能缺失"。如果某个衍生指标依赖这些标记，早期与近期的记录就不能直接合并。

命名的不一致。 RKNEE2/LKNEE2 在文件中实际写作 RMKNE/LMKNE。这类不一致通常会被上游软件静默处理（找不到列就跳过），导致某些试投的某几个关节角默默变成缺失，而你不容易察觉。

采集时长与试投数。 有的运动员一次评估贡献 2 颗，有的更多。DATASHEET 说"至少 2 颗，取决于处理并上传了多少"。这意味着"每人试投数"本身是一个与处理流程相关的变量，而不是纯粹的生理变量——把它当作行为特征（例如"投得多说明耐力好"）是危险的。

把这三类放在一起看，会得出一个稍显悲观的结论：OBP 内部并不完全同质。它的 DATASHEET 已经诚实地点出了这些，但点出不等于解决。使用者做合并分析时，最好先按时间或按标记集合做一次敏感性检查。

§3.6 一个被低估的规格：事件阈值的体重依赖

前面提过，foot contact 用 10% 体重、foot plant 用 100% 体重作为阈值。这里再展开一层。

体重从哪来？元数据表（同时给英寸/磅与米/千克两版），以及早期 C3D 文件名里嵌的那一份。如果两处不一致，阈值就会不同，事件时刻就会移动，而移动的方向对整个分析是一致的（全部提前或全部延后），不会在数据里表现出"异常值"，所以很难被发现。

这就是"元数据错误如何静默污染派生数据"的典型链条。它提醒我们：使用 OBP 时，最值得先做的质检不是看关节角的分布，而是核对元数据表里的体重、身高与其他字段是否自洽。

§3.7 事件与动作分期的关系

投球的五个事件把一次投球切成四段：跨步触地到完全承重（接触相）、完全承重到最大外旋（蓄力相）、最大外旋到球出手（加速相）、球出手到最大内旋（随挥相）。这个四段切分在教练与运动医学文献里是通用框架，OBP 的事件定义正好与之一一对应。

分期之所以重要，是因为同一个关节角在不同阶段的含义完全不同。例如肩外旋角在蓄力相增大到峰值是正常机制，如果在加速相仍然增大，则提示动作异常。把全信号数据按事件切段后分析，比用整段均值更有信息量，也更接近教练的判断方式。

击球模块的三个事件切出两段：前脚触地到完全承重（启动相）、完全承重到触球（挥击相）。段数比投球少，这是动作本身的结构决定的，不是数据缺陷。

对做时间序列建模的人，这里有一个实用建议：先用事件把序列切段，再在段内做特征提取，而不是把整段动作丢进一个卷积网络。前者与领域知识对齐，样本效率更高；后者在 411 条样本上几乎必然过拟合。

§3.8 跨模块同步的不可能性

有人会问：能不能把某位运动员的投球动作与他的挥棒动作同步比较？答案是不能。

原因有三：其一，两个模块的 session 是否对应同一时刻未知；其二，两个模块的采集环境不同（投手丘 vs 打击区），布置本身不同；其三，两者的时间零点由各自的事件决定，没有共同参照。

这不是 OBP 的问题，而是所有"多场景动捕"的共性限制。真正想做这类比较，需要专门设计一个"同一 session 内先后完成多动作"的采集方案，公开数据里极少有。

§4 数据结构与字段

§4.1 投球模块的六张全信号表

表名	内容	典型用途
joint_angles	各关节角度时间序列	运动学描述、聚类、动作分期
joint_velos	各关节角速度	加速度、爆发力代理指标
forces_moments	关节力与关节力矩（内力）	肘内翻/外翻力矩、肩内旋力矩
force_plate	测力台六分量与派生量	GRF 曲线、压力中心、冲击衰减
energy_flow	能量流（按官方文件名推断）	动力链研究
landmarks	标志点位置	姿态可视化、与无标记系统对照

六张表都以 session_pitch + time 关联。time 是相对时间（以某个事件为零点），具体以哪个事件为零点，需要在每个模块的 README 中确认——这是一个文档层面的薄弱点。

§4.2 关节与坐标约定

仓库 README 逐关节给出了三个分量（C1/C2/C3，即 _X/_Y/_Z）的物理含义与正负方向。以下为核心关节的摘要，均出自官方文档：

关节	C1	C2	C3
腕	伸展(+)/屈曲(−)	尺偏(+)/桡偏(−)	受约束
肘	屈曲(+)/伸展(−)	受约束	旋前(+)/旋后(−)
肩	水平内收(+)/外展(−)	内收(+)/外展(−)	外旋(+)/内旋(−)
骨盆	前倾(+)/后倾(−)	投掷侧(+)/手套侧(−) 侧屈	朝向本垒(+)/远离(−) 轴向旋转
躯干	屈曲(+)/伸展(−)	手套侧(+)/投掷侧(−) 侧屈	朝向本垒(+)/远离(−) 轴向旋转
躯干-骨盆	伸展(+)/屈曲(−)	手套侧(+)/投掷侧(−) 侧屈	髋肩分离(+)/闭合(−)
髋	伸展(+)/屈曲(−)	内收(+)/外展(−)	外旋(+)/内旋(−)
膝	屈曲(+)/伸展(−)	受约束	受约束
踝	背屈(+)/跖屈(−)	内收(+)/外展(−)	内翻(+)/外翻(−)

这张表里最值得注意的是**髋肩分离（hip-shoulder separation）**的定义：它不是一个独立测量的量，而是"躯干-骨盆"这个相对节段在 Z 轴上的值。做这个变量的研究时，必须确认所有数据的这一列都按同一约定计算，否则跨数据集比较没有意义。

§4.3 力与力矩的方向约定

关节	C1	C2	C3
腕	桡侧(+)/尺侧(−)	前(+)/后(−)	压(+)/牵(−)
肘	桡侧(+)/尺侧(−)	前(+)/后(−)	压(+)/牵(−)
肩	相对上臂（文档原文未完整给出）	同左	同左

肘关节的 C2 轴（前/后）在投球研究中对应的是内翻-外翻力矩，这是 UCL 损伤风险最常被引用的指标。但因为它是内力矩且表达在节段坐标系里，正负号与"内翻/外翻"的对应关系必须按文档核对，不能按直觉。

§4.4 POI 表与元数据表

POI（point of interest）表是"每次试投一行"的汇总，元数据表是"每次试投一行"的身份与情境信息（运动员 ID、session、身高体重、水平、惯用手等）。二者通常按行号或键对齐。

元数据里的 playing_level / highest_playing_level 字段是这份数据里最重要的分层变量：投球模块用 playing_level，击球模块用 highest_playing_level。字段名不同、粒度也不同（击球区分了 MiLB 与 Independent 的顺序），跨模块合并时要做映射。

§4.5 缺失与不一致

DATASHEET 自己列出的缺失与不一致包括：Plyo Pushup 严重缺失（438/1,934）；LIC/RIC 标记部分 C3D 缺失；RKNEE2/LKNEE2 命名不一致；肩与髋的部分力/力矩符号约定"未报告"（convention not reported）。最后一条最麻烦——它意味着在这两个关节上，即使你严格按文档做，也可能算不出与官方 POI 一致的结果。

§4.6 POI 字段的"三类指标"读法

POI 表的列很多，直接一列列读会失去结构。按性质分成三类，理解会快很多：

第一类：表现指标。 球速（投球）、出球速度（击球）。这类指标是"结果"，通常作为因变量。

第二类：峰值/极值指标。 最大外旋角、最大内旋角、髋肩分离峰值、最大骨盆旋转角速度、最大躯干旋转角速度。这类是"动作特征"，常作为自变量。使用时要注意：峰值指标对采样率与滤波截止敏感，20 Hz 低通会削掉高频峰值，不同滤波设置下的峰值不可直接比较。

第三类：动力学负荷指标。 肘内翻力矩峰值、肩内旋力矩峰值、GRF 峰值。这类最受关注，也最容易误用（见 §7.2 的四点）。它们都是内力矩，不是韧带应力。

还有一个跨类的坑：峰值出现的时刻不同。最大外旋角出现在 MER，肘内翻力矩峰值通常也接近 MER 但未必同一帧，GRF 峰值又可能在跨步早期。把几个峰值直接放在一行做相关，等于默认它们描述的是同一个瞬间——实际不是。

§4.7 关于事件截断与时间零点

C3D 与全信号表都携带事件信息，但文档没有逐模块说明 time 列的零点对应哪个事件。这带来一个具体的操作风险：如果你假设 time = 0 是球出手，而实际是跨步脚触地，所有时间窗特征都会整体错位。

稳健的做法是两步核对：先在 C3D 里读出事件帧号，再在对应试投的全信号行里找到同一时刻，比对 time 值。任何基于滑动窗口的特征工程，都应在这一步之后再做。

这一节也解释了为什么本文在 §3.3 把事件定义列得那么细：事件不只是标签，它们是整份数据的时间坐标系统。

§4.8 数据字典的正确用法

2026 年重写后新增的 data_dictionary.csv 与 data_dictionary.json，是查字段的权威来源。changelog 明确说了它做了三件事：修正一个错误条目、补上若干未记录的列、修正 rejc 地标。

这三件事本身就是提示：在 2026-07 之前写的任何解析脚本，都可能因为字段名或含义变化而失效。如果你继承了别人 2023 年写的 OBP 脚本，第一件事不是运行，而是拿数据字典逐列核对。

数据字典的局限也要知道：它给出列名与含义，但不给"该列在哪些模块存在"“该列在哪些年份缺失”。后者仍要靠 DATASHEET 与实际的缺失统计。

§4.9 一张字段核对表：拿到数据先做这六件事

新手拿到 POI 表最常见的反应是"列太多，不知道从哪儿看"。这里给一张六步核对表，半小时能做完，能挡掉后面 80% 的错误。

第一步：核对行数。 投球 POI 应该是 411 行，击球 677 行，体能 1,934 行。行数不对，说明文件拿错了、或者解压了不完整的包。

第二步：核对唯一人数。 投球按 user 去重应为 100，击球应为 98，体能按 athlete_uid 去重应为 1,162。这一步能发现"把两个 session 当成两个人"这类问题。

第三步：核对分类分布。 投球惯用手应为 328 右 + 83 左；击球侧别 496 右 + 181 左；水平分布按 §2.2–§2.4 的表核对。分布对不上，说明筛选或合并出过问题。

第四步：核对极值。 球速 min/max 应为 69.5/94.4 mph，出球速度 48.8/107.0 mph。极值不对，多半是单位问题（mph 与 km/h 混用）。

第五步：核对缺失。 逐列统计缺失率，与 DATASHEET 的描述对照。Plyo Pushup 的 438/1,934 是最可靠的对照点。

第六步：核对时间与事件。 随机抽 3 个试投，在 C3D 里读事件帧号，在全信号表里找对应时刻，确认 time 零点。这一步最费时，但也最能暴露根本性问题。

做完这六步，你就有了一个"可信的工作副本"。之后所有分析都基于它，任何异常都能回溯到某一步。

§4.10 关于"派生指标"的信任边界

POI 表里的指标是官方算好的，用起来省事。但"官方算的"不等于"适合你的问题"。有三类情况需要自己重算：

滤波设置不匹配。 官方用 20 Hz 低通，如果你的研究关注的是冲击类高频成分（例如落地瞬间的力峰值），20 Hz 会把有用的信息滤掉。

事件定义不匹配。 官方用体重阈值定义事件，如果你的分析需要更精确的相位划分（例如按球离手的实际帧），就需要自己重算。

指标口径不匹配。 官方 POI 的"髋肩分离"是躯干-骨盆相对节段的角度，如果你的研究用的是别处定义的分离量（例如标志点连线夹角），两者不可混用。

重算的代价是可能的符号不一致（坑 11）。因此推荐的策略是：能用官方 POI 就用官方 POI，确实需要重算时，先在一小批试投上与官方值做一致性检查，把符号与量级的差异显式记录下来。

§4.11 数据字典里没写、但你一定需要知道的

data_dictionary.csv 给的是列名与含义，但有几类信息它不包含，需要从 DATASHEET 与 README 里拼：

• 单位：多数运动学指标是度或度/秒，动力学指标是牛顿米或牛顿——但具体哪列用哪个单位，要以字典为准逐列确认。
• 坐标系：字典一般写"相对某节段"，但具体是近端还是远端，仍要看 README。
• 缺失编码：是空字符串、NaN，还是某个哨兵值（如 -999），文档未统一说明，导入时建议先 df.isna().sum() 与极值扫描双查。
• 左右手对称化：哪些列已经被对称化处理过，字典中通常不标，需要按 README 的约定推断。

这四条合起来说明一件事：OBP 的文档是"分层"的，模块 README 讲约定、DATASHEET 讲全局、数据字典讲字段，没有一处能单独读完就掌握全貌。使用者的正确姿势是三处对照。

§2.12 模块之间的"人员不重叠"问题

三个数据模块合起来，很容易给人一种印象：这是一套覆盖了 100 名投手 + 98 名打者 + 1,162 名运动员的完整档案。实际不是。

投球模块的 100 人与击球模块的 98 人是否重叠，官方文档没有给出明确说明。从业务场景推断，Driveline 的客户中确实存在"二刀流"（同时投球与击球）的运动员，但重叠比例未公开。因此三个模块的人数不能简单相加——100 + 98 + 1,162 = 1,360 这个数字没有任何意义，因为其中可能有同一人多次计数。

同理，"1,162 名运动员"这个数字也不能与 100 名投手相加。两者的人群定义不同：前者是做过体能评估的人，后者是做过投球动捕的人。一个人可能只做了评估、没做动捕，也可能相反。

这个问题的实践含义是：任何需要"总样本量"的表述，都应该按模块分别写，而不是给一个合计。本文在 INFOBOX 与速查卡里都分开列，就是这个原因。

§2.13 从文件名能读出什么、不能读出什么

早期的 C3D 命名把六项信息编进文件名：用户 ID、session ID、身高、体重、投球序号、球种、球速。这套编码在数据量小的时候很实用，但它引出了三个值得记录的问题。

能读出什么：单看文件名，你就能知道这颗球的球速与球种，不必读元数据。做快速筛选（例如"只看 90 mph 以上"）时，按文件名过滤比读 CSV 还快。

不能读出什么：年龄、水平、惯用手、投球日、当时是否受伤。这四项都不在文件名里，必须查元数据。

带来什么风险：一是元数据与文件名可能不一致（例如运动员补测后体重更新，但文件名未改）；二是把身高体重写进文件名对匿名化是不必要的暴露，虽然数值本身不构成直接标识，但在小群体里（例如某队某年只有一名 6 尺 4 寸的左投）可能间接可识别。2026 年重写后文档改为强调数值 ID 与 UUID，可以看作对这一点的事后修正。

§2.14 一句话总结 §2

如果把 §2 压缩成一句：OBP 是三个规模不同、人群不同、字段不同的模块拼成的数据仓库，每块的数字都要按自己的口径读，任何跨模块的加法都要先问一句"这是同一个人吗"。

§5 获取与上手

§5.0 五个阶段：从"听说"到"能下结论"

在给具体命令之前，先给一张时间地图。多数人在 OBP 上的时间分配大致是"三小时上手、三周才能下结论"，失衡点几乎都在阶段 4。

阶段	典型动作	常见卡点
1 听说	读到 OBP 的名字，打开官网	官网只有投手/打者两个数字，误以为数据很小
2 拿到数据	克隆 + download_data.sh	gh 认证失败、磁盘不够、忘记解压 zip
3 能读出形状	obp.load_poi 打印 shape	以为 import obp 来自 PyPI
4 能解释字段	查 data_dictionary、对符号与单位	力台符号、左右手对称化、时间零点
5 能下结论	分层、防泄漏、报告口径、写外推边界	混淆人数与试次数、把相关当因果

阶段 2 与 3 是纯操作问题，出错了搜错误信息就能解决。阶段 4 与 5 是概念问题，出错了不会报错，只会得出错的结果。本文 §2、§4 与 §6 的全部内容，本质上都是在帮你跨过阶段 4。

§5.2.3 一个常被问到的替代路径

如果只是想快速看一眼数据长什么样，其实有比克隆更轻的办法：直接在浏览器里打开 GitHub 仓库的 baseball_pitching/data/poi/ 目录，点开 CSV 的 Raw 视图。POI 与元数据表都在 git 里，不需要下载任何 release。这对"先判断这份数据适不适合我"的探索阶段足够了。

只有在确认要做分析之后，才值得付出下载 1.1 GB 与配置环境的成本。很多人在还没想清楚研究问题时就先去搭环境，最后卡在下载这一步失去兴趣——这是最可惜的一种浪费。

§5.1 三种需求，三条路径

OBP 的仓库 README 有一张"从哪开始"的表，按目标分流。这个设计很实用，值得原样吸收：

目标	起点	要不要下载大数据
看投球/挥棒汇总指标	examples/01_explore_poi.py + obp 加载包	不需要
看体能评估指标	examples/04_hp_assessment.py	不需要
在浏览器里比较挥棒	swing_visualizer/	需要击球 C3D
读原始标记点轨迹	examples/02_read_c3d.py	需要对应模块 C3D
合并全信号表	examples/03_join_fullsig.py	需要全信号归档
查变量与约定	各模块 README + 数据字典	不需要
做计算机视觉或标定	computer_vision/	部分教程需要媒体

对绝大多数第一次接触的人，正确的路径是 01 → 04 → 03，跳过 02。因为 02 会把你直接丢进 C3D 二进制里，而在你能解释任何一个关节角之前，那份二进制没有意义。

§5.2 环境准备

§5.2.1 先问三个问题，再看命令

在敲任何命令之前，先回答：

1. 你要不要 C3D？ 只要的话，跳到 §5.3 的纪律。不用的，克隆就够。
2. 你所在机构的网络允不允许访问 GitHub Releases？ 不允许的话，需要代理或镜像；OBP 没有官方镜像，这是它相比 HuggingFace 托管数据集的一个劣势。
3. 你的磁盘够不够 5 GB？ 下载的压缩包 1.1 GB、解压后的 C3D 与 CSV 会翻几倍，再加上 Python 环境，5 GB 是保守估计。

这三问看似琐碎，实际上决定了后面半小时会不会白费。特别是在共享集群上做研究的，磁盘配额与小文件数量（C3D 是每人一个文件夹、每颗一文件）都可能成为阻碍。

§5.2.2 最小环境

官方给出的最小路径：

git clone https://github.com/drivelineresearch/openbiomechanics.git
cd openbiomechanics
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

加载器与示例在 Python 3.10 与 3.12 上测试过。obp 是一个仓库内的本地包，不是 PyPI 包，所以必须在仓库根目录运行 Python 或 Jupyter，否则 import obp 会失败。

import obp
pitching_poi = obp.load_poi("pitching")
hitting_metadata = obp.load_metadata("hitting")
hittrax = obp.load_hittrax()
high_performance = obp.load_hp()
print(pitching_poi.shape)
print(pitching_poi[["pitch_speed_mph", "elbow_varus_moment"]].describe())

上面这段就是官方 Quickstart 的原文示例。这里有一个有趣的事实：官方示例第一件事就是看 pitch_speed_mph 与 elbow_varus_moment 的分布——说明作者自己也默认，来用这份数据的人最关心的就是"球速"和"肘内翻力矩"这对关系。

§5.3 下载大数据

scripts/download_data.sh                    # 投球 + 击球全量
scripts/download_data.sh --discipline pitching
scripts/download_data.sh --discipline hitting
scripts/download_data.sh --discipline pitching --with-media
scripts/download_data.sh --skip-data --with-media

Python 侧的等价入口：

import obp
obp.download("pitching")
obp.download(["pitching", "hitting"], media=True)
obp.download(data=False, media=True)   # 只下 CV 媒体

下载器依赖 GitHub CLI（gh）、unzip、Bash，以及 sha256sum 或 shasum。需要先 gh auth login，或在自动化环境里提供 GH_TOKEN。它会对照 scripts/release_checksums.sha256 逐个资产校验后再解压。

这一步有三个坑要提前知道：

1. 数据不在 git 里。2026 年 7 月的重写把所有大二进制从 git 历史中清除，.git 从 2.2 GB 降到约 25 MB，新克隆约 28 MB。C3D 与全信号归档都在 GitHub Releases 的 dataset-v1 标签下。
2. 旧的克隆必须重克隆，不能 git pull。历史被重写过，旧 commit 哈希已不存在。
3. 全信号压缩包不会自动解压。下载器把 zip 留在 data/full_sig/ 下，意图是让你按需解压其中一张表——例如只解 joint_angles.zip。新手常犯的错是以为"下载完就能直接读 CSV"。

cd baseball_pitching/data/full_sig
unzip joint_angles.zip
unzip joint_velos.zip

原始 C3D 则会被解压到各模块的 data/c3d/ 目录。

§5.4 一个最小可用的分析骨架

§5.4.1 先画图，再算数

在跑任何模型之前，先用三张图建立直觉：球速的分布直方图（看是否偏态）、球速与年龄的散点（看人群窗口的形状）、每人试投数的条形图（看"少人多试"有多集中）。这三张图加起来不到十行代码，却能帮你避开后面一半的误判——例如发现球速在 90 mph 以上只有零星几个点，就不会去拟合一条直线然后声称"高速区呈线性关系"。

import obp
poi = obp.load_poi("pitching")
poi["pitch_speed_mph"].hist(bins=30)
poi.plot.scatter(x="age", y="pitch_speed_mph")
poi["user"].value_counts().value_counts().sort_index().plot.bar()

§5.4.2 最小骨架

下面这段不是官方示例，是"用 OBP 回答一个具体问题"的最小骨架，供参考。问题是：投球球速与最大外旋时刻的肩外旋角是否相关？

import obp
import pandas as pd

poi = obp.load_poi("pitching")
cols = [c for c in poi.columns if "pitch_speed" in c or "mer" in c.lower()]
sub = poi[cols].dropna()
print(sub.corr(method="spearman").iloc[0])

# 防运动员泄漏：按 user 分组切分，而不是按行
users = poi["user"].unique()

最后两行是全篇最重要的实践建议。411 条试投来自 100 人，平均一人 4 条；如果按行随机划分训练/测试，同一个人的试投会同时出现在两边，模型学到的是"这个人"而不是"这个动作"，测试集指标会虚高。DATASHEET 专门把"运动员泄漏"列为必须防的问题，官方却没有给标准划分——这不是疏漏，而是有意留白：不同任务需要不同的划分策略。

§6 坑点清单：十二个已经踩过的坑

§6.0 坑点为什么要写成"清单"

坑点清单不是为了"吐槽文档"，而是为了给使用者一份可执行的检查表。每一条坑都对应一个具体的失败动作，写清"做了什么→会发生什么→怎么改"。读的时候建议按你的分析流程对照：如果你的流程里出现了若干条坑里描述的动作，说明分析还没开始就埋了雷。

清单按"数据结构 → 分发 → 计算 → 许可 → 外推"的顺序排列，前面几条是操作层面的，后面几条是判断层面的。后面几条更危险，因为它们不会报错。

坑 1：把"模块"当成"数据集"

OBP 不是一个数据集，是四个模块的集合。检索文献时经常看到"used the OpenBiomechanics dataset"这种含糊表述，实际上有的用的是投球 POI，有的用的是击球 full signal，有的用的是 HP 体能表。复现别人的结论前，先确认他到底用了哪个模块、哪一层表示。三者的采样、人群、变量完全不同，混为一谈会导致"我照着论文做了但结果对不上"。

坑 2：把试投数当人数

411 是试投次数，100 才是人数。677 是挥棒次数，98 才是打者数。这两个数字在二手资料里被混用的频率极高，有的文章写"411 名投手"——这是错的，而且错得很危险：任何以"411 个独立样本"为前提的统计推断都高估了样本量约 4 倍。

坑 3：忽略"投球只有快球"

411 次全部是 fastball。所有关于"变化球更伤肘""曲球改变肘部负荷"的研究问题，无法在这份数据内部检验。如果你的研究设计需要球种对比，OBP 只能提供快球这一端。这一点在二手综述里几乎从不提，因为提了会削弱"精英数据集"的吸引力。

坑 4：用过期的路径与 commit

2026 年 7 月 4 日的 git 历史重写让所有旧 commit 哈希失效，大文件也从 git 迁到 Releases。文献与博客里引用的 baseball_pitching/data/c3d 路径，在新分发里要跑过 download_data.sh 才会生成。任何脚本里硬编码 commit 哈希或假设"克隆即得数据"，都会在 2026-07 之后失效。官方明确要求旧克隆删除重克隆，git pull 无法修复。

坑 5：以为下载完就能读 CSV

全信号归档以 zip 形式留在 data/full_sig/，必须手动解压。这是有意设计（让你只解压需要的表，节省磁盘），但对新手不友好。常见报错是 FileNotFoundError: joint_angles.csv——文件在 zip 里。

坑 6：跨力台直接求和或比较

FP1 与 FP3 的 X 轴正向是"制动/后方"，FP2 的 X 轴正向是"蹬伸/前方"。同一份 CSV 里同一列，在三块板上的符号含义相反。任何"全脚合力""左右脚合计"的计算，必须先做符号统一，否则会算出物理上不可能的结果（例如前脚与后脚的推进分量相互抵消）。

坑 7：按行随机划分训练/测试

见 §5.4。每人多次试投，按行划分必然造成运动员泄漏。DATASHEET 把这条列为已知局限的第一条，官方示例也没有提供划分函数。正确做法至少是 GroupKFold（按 user 分组），更严谨的做法是按 session 或按人分层后再切。

坑 8：把 CC BY-NC-SA 当成普通开源许可

数据许可不止"非商业"这一层。CC BY-NC-SA 4.0 之外，官网额外加了一条排除：受雇于、关联于或为专业体育组织、金融分析公司的重要股东人员，无论何种用途都被禁止，除非取得书面商业许可。这条排除在标准 CC 文本里不存在，是许可人另行声明的。对于在职业球队工作、或在体育博彩/金融分析机构任职的研究者，这是硬性禁区，不能靠"我是做学术研究"来豁免。官网 FAQ 的表述是：这类研究者需要商业许可才能做研究。

坑 9：以为有官方基线或排行榜

没有。没有基线模型、没有标准指标、没有 leaderboard、没有数据描述论文。任何"在 OBP 上 SOTA"的说法，都指的是某个第三方论文自定义的划分与指标，跨论文不可比。做对比实验时，要么复现对方划分，要么在自己的论文里明确定义。

坑 10：把 OBP-CV 的相机当成动捕相机

computer_vision 模块提到 8 路 OptiTrack、4 台 Edgertronic、1 部 iPhone——这些是视频机位，用于多相机标定与无标记姿态实验。动捕主系统的相机品牌与台数官方从未公开。把两者混同，会导致对数据精度来源的错误归因。更细的坑是：CV 模块的标定被明确标注为"临时性、经校验但非最终实验室坐标系"，用它做三维重建得到的坐标，不能直接和动捕数据在同一坐标系里比较。

坑 11：忽略肩与髋的符号约定"未报告"

DATASHEET 明确写：肩与髋的部分力/力矩符号约定 convention not reported。这不是"文档写得不好"，而是一个已知的知识缺口。它意味着：如果你自己从 C3D 重算肩关节力矩，结果可能与官方 POI 符号相反，而你无法从文档判断谁对。务实做法是——直接用官方 POI，不要自己重算；如果必须重算，先在一小批试投上与官方 POI 做符号一致性检查。

坑 12：试图用 HP 模块做个体级配对而不查对照表

High Performance 模块用 UUID athlete_uid，动捕模块用数值型 user/session ID。二者之间是否有公开对照，官方文档未说明。在确认之前，不要假设"能按 id 连起来"。

§6.5 坑点自检表

把上面十二条改写成一张可以贴在工位上的勾选表，按分析流程顺序排列：

阶段	检查项	对应坑
立项	我确认用的是哪个模块、哪一层数据	坑 1
立项	我写的是人数还是试次数，全文口径一致	坑 2
立项	我的问题是否需要变化球；若是，OBP 不够	坑 3
准备	我记录的是当前 release 与 commit，不是旧文献路径	坑 4
准备	全信号 zip 已解压，路径指向解压后的 CSV	坑 5
计算	跨力台求和前已统一 X 轴符号	坑 6
计算	划分按 user 分组，未按行随机	坑 7
计算	自算力矩与官方 POI 做过符号一致性抽检	坑 11
合规	用途非商业，本人及资助方与职业体育/金融分析无关联	坑 8
合规	公开派生数据时以 CC BY-NC-SA 4.0 发布	坑 8
报告	未声称有官方基线或 leaderboard	坑 9
报告	CV 模块与动捕主系统未混为一谈	坑 10
报告	未对 user 与 athlete_uid 做未经验证的连接	坑 12

这张表不能保证分析正确，但能挡掉绝大多数"一上手就错"的情形。做完整分析后，再回头逐条过一遍，通常能发现一两处疏漏。

§7 研究应用与已知结果

§7.0 本章的方法：只读一手，不转述二手

写这一章时有一条自我约束：所有"已知结果"只引自能读到原文的论文，且只写论文摘要与正文里明确表述的内容，不做二次推断。原因是运动科学领域的二手转述失真率很高——一项报告"相关"的研究，经两三层转述后常变成"证明"。

因此本章的结论都带有限定语：X 与 Y 相关（不是 X 导致 Y）；解释了多少方差（不是准确率）；在某个样本里（不是普遍成立）。这些限定语读起来啰嗦，但它们正是判断一条结论能否被采用的关键。

§7.1 第三方研究已经做了什么

OBP 自身没有论文，但它被第三方研究者当作"公共数据源"使用。目前可查的代表性工作有两类。

第一类：用 OBP 回答运动生物力学的本体问题。 Perrett 发表于 Journal of Applied Biomechanics 2024 年第 40 卷第 2 期（98–104 页，doi:10.1123/jab.2023-0045，PMID 37939700）的研究是典型代表：直接使用 OBP 开源数据，评估下肢运动学对球速与挥棒速度的贡献。方法上有两点值得注意——除了对离散运动学变量做相关分析，还用了统计非参数映射（statistical nonparametric mapping），把"慢速组 vs 快速组"的比较扩展到从最大膝高到球出手/触球的整段动作时间序列，而不是只比几个峰值时刻。结论是：后腿旋转与前膝伸展在投手和打者身上都与表现相关。其对实践的含义是，教练应确保运动员具备足够的柔韧性与力量，让后髋与前膝能完成这个动作。

这项工作之所以重要，不只是因为结论，而是因为它证明了 OBP 的可用性：一个独立于 Driveline 的团队，仅凭公开数据，就能做出可发表的运动生物力学研究。这正是开源数据最想达到的效果。

第二类：把 OBP 当作方法学素材。 Journal of Men’s Health 2026 年的一项研究（doi:10.22514/jomh.2026.026）用 OBP 做肩部内旋力矩效率的回归建模，报告 6 个运动学参数合计解释 41.3% 的效率方差，其中跨步脚触地（SFC）时的肩外展角减小与最大外旋时的肩外旋角增大，是区分高低效率组最明显的两个因素。该文的数据可用性声明直接指向 OBP 仓库，伦理声明引用 Western IRB #WB-DLR-115，与 DATASHEET 一致——这是一次漂亮的交叉验证：第三方论文独立确认了伦理批号，说明 OBP 的元数据是可追溯的。

值得注意的是该文自陈的局限：“数据采集早于 2022 年，可能不够新”，且未做事前样本量估计。这恰好点中了 OBP 的一个结构性问题——数据是历史积累，不是为某个问题设计的。用它做假设检验，样本量是否足够、混杂是否可控，全靠研究者自己论证。

§7.2 一个必须正视的效度问题

用 OBP 做损伤风险研究时，"肘内翻力矩"几乎必然出现。但这个指标有几个已知的理论局限，OBP 的用户必须自己承担：

其一，力矩不是负荷，负荷不是损伤。 内力矩是逆动力学的输出，它描述的是关节处的净力矩需求，不是韧带上的应力。同样的力矩，在不同肌肉激活模式下对应不同的韧带负荷。OBP 没有肌电（EMG），所以无法从力矩推断肌肉-韧带分担。

其二，单次最大力矩的重复性有限。 每次试投取峰值，峰值本身受试投间变异影响；411 次试投来自 100 人，意味着每人平均只有 4 次，用 4 次估计一个人的"峰值力矩"噪声很大。

其三，实验室动作与比赛动作不同。 DATASHEET 与第三方论文都提到，实验室环境下投球，运动员的表现会受环境影响。OBP 的数据是"评估场景"下的最大努力快球，不是比赛中的真实投球。

其四，人群窗口窄。 中位年龄 20.7 岁、以大学水平为主，意味着这份数据对"青少年投手损伤"和"职业投手损伤"两个最受关注的问题，都只有间接参考价值。

§7.3 可以把 OBP 用来做什么

反过来，以下方向是 OBP 的强项，值得优先考虑：

• 动作分期的算法研究：五个明确的事件定义 + 360 Hz 标记点数据，是研究"如何自动检测投球分期"的良好素材。
• 无标记动捕的验证：CV 模块提供同步视频，可以用标记点数据当金标准，评估姿态估计算法。
• 动力链与能量流分析：energy_flow 表在多数公开数据集里没有对应物。
• 教学与课程项目：许可明确允许教育用途（免费至 2030-12-31），且数据量适中，适合作为生物力学课程的实战素材。
• 方法学对照：拿 OBP 的 full signal 与你自己的处理流程结果比对，是验证 C3D 处理管线的一种方式。

§7.4 典型失败模式

从公开讨论与文档反推，初学者在 OBP 上最常见的三类失败是：

1. 把 POI 当成"已经清洗好的特征"，直接丢进模型，不检查分布、不检查运动员泄漏、不做分层，最后得到一组无法解释的高 R²。
2. 忽略左右手对称化处理：官方对运动学做了"右手/左手对称化"调整，这意味着投掷臂与手套臂的角度量在约定上已被对齐到同一符号体系。若你自己从 C3D 重算，却不复现这套调整，左右投手混合统计时就会出现与官方 POI 不一致的分布——看起来像"动作差异"，实则是处理流程差异（坑 11 的同一类问题）。
3. 跨模块拼接失败：投球用 playing_level、击球用 highest_playing_level，字段名与粒度都不同，直接 concat 会产生大量缺失。

§7.5 一个具体的分析案例解剖

为了让上面的抽象讨论落地，这里解剖一个小案例。它不引用任何第三方结论，只演示"在 OBP 上做一个诚实的分析"需要走完哪些步骤。

问题设定：在投球模块里，跨步脚触地（foot contact）到球出手（ball release）之间的时长，是否与球速相关？

第一步：确定数据层。 这个问题不需要关节力矩，只需要两个事件的时刻与球速。事件时刻在 C3D 的事件标记里，球速在 POI 表里。最小成本的做法是直接用 POI 表——前提是 POI 里已经有截断时长这一类派生指标；若没有，就要读 C3D 的事件。这一步的教训是：先查 POI 的列清单，再决定要不要动 C3D，官方 Quickstart 之所以从 01 开始，就是这个道理。

第二步：检查分布与缺失。 球速在 69.5 到 94.4 mph 之间，中位 85.3。如果直接做线性相关，高速端只有极少数样本，相关系数会被远端杠杆点主导。合理做法是先画散点、看是否需要秩相关或分段分析。同时要检查 POI 行是否全部有事件标记——早期部分 C3D 缺失 LIC/RIC 标记，虽然不是这些事件的直接依赖，但提示了"不同年份的数据完整度不一"。

第三步：处理人群分层。 水平分四类，大学占 314/411。如果把高中球员（32 条）混进全样本，相关关系可能被"身体成熟度"混杂。务实的做法是报告全样本与大学子样本两个结果，并说明差异。

第四步：防泄漏。 如果这个问题被扩展成一个预测模型（用时长预测球速），必须按 user 分组切分。100 人、411 条，若按行 8:2 划分，测试集里几乎必然包含训练集出现过的投手。

第五步：报告口径。 报告时必须写清：用的是哪个 release、POI 表哪几列、是否做了分布筛选、样本是 411 还是子集、相关系数用的是 Pearson 还是 Spearman。少写任何一项，结论就不可复现。

第六步：外推边界。 即使相关显著，也只能说"在这批以大学水平为主的快球试投中，截断时长与球速存在某某关联"，不能说"延长/缩短截断时长能提高球速"。相关性不是因果，这一点在运动表现领域尤其容易被误读。

这个案例的意义在于说明：OBP 的上手门槛不高（克隆 + 读 CSV 就能开始），但做对分析的门槛不低，而后者完全依赖使用者自己的方法学素养。数据集文档能做的只有提醒（DATASHEET 确实提醒了泄漏与采样率问题），不能替你做决定。

§7.6 关于"精英"与"代表性"的再讨论

前文反复提到人群偏斜，这里把它展开成一个可以带走的方法学观点。

运动生物力学研究长期存在一个取样悖论：越是研究高水平运动员，结论越"有用"，但样本越难获得、越小。OBP 用"机构自有数据批量释放"绕过了获得性问题，代价是接受了机构客户群体的构成（以大学球员为主）。这不是缺陷，而是这个模式的固有特征。

对使用者的实际含义是：OBP 最适合回答"动作机制"层面的问题，最不适合回答"人群水平"层面的问题。前者（如"后腿旋转是否与球速相关"）对人群构成的敏感度较低，因为机制在人群中大体通用；后者（如"职业投手的肘部负荷阈值是多少"）直接依赖人群，用大学球员数据外推必然失准。

同理，时间维度也要小心：数据是 2022 年前后积累的，训练理念与投球策略在这几年持续演变（例如对球速的追求强度上升）。用一个历史窗口的数据讨论"当下"的问题，需要额外的论证。

§7.7 与临床运动医学的接口

虽然 OBP 是竞技数据，它与临床并非无关。运动医学里有一类问题需要"健康运动人群的负荷基线"——例如，康复期的投手什么时候可以恢复到全速投球？判断依据之一是与同龄健康投手的关节力矩分布做比较。OBP 恰好能提供这样一个参照分布（尽管人群偏大学水平）。

用 OBP 做这类基线时，有三条纪律：

1. 只做分布参照，不做个体诊断。OBP 的受试者不是患者，其数据不能用于诊断任何个体。
2. 注意采集情境差异。OBP 是实验室评估场景，康复评估往往在临床环境、不同设备、不同流程下完成，跨环境比较前要先做可比性论证。
3. 注意许可。医疗机构若属商业机构，或在职业体育组织任职，需先解决许可问题（坑 8）。

§7.8 从"数据"到"知识"的最后一公里

一篇使用 OBP 的论文，最终要回答的不是"数据和什么相关"，而是"这对实践意味着什么"。这一步在运动科学里最容易走偏，因为它需要跨越三类不同的证据。

第一类是统计证据：相关显著、回归系数不为零、方差解释比例达到某个水平。这类证据只说明"在这批样本里，两个量同向变化"。

第二类是机制证据：从生物力学第一性原理出发，解释为什么同向变化。例如 Perrett 2024 的结论之所以可被接受，是因为"后腿旋转贡献动量传递"在动力链理论里有明确的机制路径；如果只是统计相关而没有机制，结论的说服力会大打折扣。

第三类是干预证据：改变某个变量后，结果是否改善。这类证据 OBP 完全无法提供——它是横断面观察数据，没有随机化、没有干预、没有随访。

从 OBP 出发的论文，最好明确声明自己停在哪一类。多数第三方研究停在第一类加上第二类的推测，这是诚实且合理的；但如果在摘要里写成"证明某动作可提高球速"，就越过了证据边界。JOMH 2026 那篇在局限里明确写"数据采集早于 2022 年，可能不够新"“未做事前样本量估计”，这种自陈是值得学习的写法。

对读者而言，判断一篇 OBP 论文是否可信，最快的办法是看它的局限段落：如果局限段落把人群、横断面、无干预这三点都点到了，说明作者清楚自己的证据层级；如果局限只写了"样本量有限"，很可能没有认真对待证据边界。

§7.9 一个跨领域的类比

如果把 OBP 比作生物医学领域的某个东西，最接近的不是"某个影像数据集"，而是"某个医院开放的病历队列"：数据量大、来源真实、字段繁杂、没有为研究设计过、许可有特殊限制、治理依赖单一机构。

这个类比能帮我们预判它未来的路径。病历队列走向成熟，通常要经历三步：建立数据字典（OBP 已做）、形成标准变量集（OBP 部分做了，靠 POI 表）、引入外部治理（OBP 尚未做，无独立委员会、无 DOI 存档）。

第三步是最难的，因为外部治理意味着让渡控制权。这也是判断 OBP 能否长期成为"基础设施"的关键：如果它未来引入 Zenodo 存档与 DOI，或者与学术机构共建数据治理委员会，它的学术地位会实质提升；如果一直维持"机构自管 + GitHub 分发"，它会继续被使用，但永远无法成为可被正式引用的数据资产。

§5.5 一个"十分钟验证"流程

如果你对这份数据是否适用于自己的问题仍有疑虑，可以走一遍下面这个十分钟验证流程。它的目标不是得出结论，而是判断"值不值得投入更多时间"。

第 0-2 分钟：看分布。 打开 POI 表的球速列，算中位数与四分位距。如果你的问题涉及 90 mph 以上的高速投球，看一眼有多少条——通常不超过总数的十分之一。样本太薄，说明这个问题在 OBP 上做不深。

第 2-4 分钟：看你要的自变量在不在。 逐列对照 §4.6 的三类指标。如果没有，考虑能否从 C3D 自算（成本高），或换一个数据集。

第 4-6 分钟：看人群。 按水平分层统计你关心的指标。如果某层样本极少（如 MiLB 的 23 条），而你的问题又必须分水平讨论，就要重新考虑。

第 6-8 分钟：看缺失。 统计你要用的列在目标子集里的缺失率。超过 30% 就要谨慎。

第 8-10 分钟：看许可。 对照本文 §6 的许可小节与坑 8，确认你的身份与用途。若处在灰色地带，这十分钟就到此为止，先去问许可。

走完这五步，你会有三种结局之一：明显适合（继续）、明显不适合（换数据）、边界不清（缩小问题范围再试）。三种结局都有价值——最糟的是不验证就开始写代码，两周后才发现数据不支持。

§5.6 关于"要不要用全量"的判断

下载 1.1 GB 全量，还是只拿 POI 与元数据？这个问题取决于三点：

是否需要逐帧信息。 只要统计汇总，POI 够用；要做动作分期、时间序列特征、峰值时刻分析，需要 full signal；要自己重算逆动力学或做无标记对照，需要 C3D。

是否需要试投级 QC。 想检查某条记录是否异常（例如事件时刻错位），必须看曲线，也就必须下 full signal。

磁盘与网络条件。 全量解压后体积远超 1.1 GB，共享环境里要注意配额。

一个务实的折中方案是：先只下 POI 与元数据，用 §5.5 的流程做验证；确定要做之后，再按 --discipline 只下需要的模块，而不是一次下全量。官方的下载脚本支持单模块选择，正是为这个场景设计的。

§5.7 一个提醒：不要把它当"标准答案库"

最后提醒一句容易被忽略的话：OBP 的 POI 值不是"标准答案"，而是"官方处理流程的产物"。

如果有人问你"这位运动员的肘内翻力矩是多少"，正确答案不是"OBP 里那个数"，而是"在 OBP 的处理流程与坐标系约定下，这个数是 X"。换一套滤波、换一个模型、换一个事件定义，这个数会变。

这不是相对主义，而是对"测量"这件事的基本尊重。运动生物力学的多数量都是"在某种约定下的测量值"，约定本身是测量的一部分。OBP 的文档之所以花大量篇幅写约定，就是在提醒这一点。

§8 工程细节与可复现性

§8.0 为什么"工程细节"值得单独一章

多数数据集条目会把"怎么下载、怎么读"压缩成一个段落，因为数据集的身份主要由内容决定。OBP 不一样：它的身份几乎完全由工程实现定义。

理由很直接。它没有论文来锚定版本（没有 DOI，没有"这篇论文描述的是 v1.0"这种说法）；它没有统一的数据集标识符（GitHub 仓库地址是事实上的标识符，但仓库可以被重写、被改名、被归档）；它的内容会随业务积累而增长（新运动员的评估会持续进入内部数据库，是否释放取决于机构决策）。在这些前提下，使用者能依赖的只剩三样东西：仓库的提交历史、release 标签、以及 DATASHEET 的自我陈述。

所以这一章不是"操作指南的附录"，而是理解"这份数据集凭什么可信"的核心章节。同样，§8.1 的时间线也不是史料，而是判断"你现在看到的文档是不是最新版本"的依据。

§8.1 仓库的维护形态

OBP 的可信度很大程度上来自仓库的维护强度，而不是来自某篇论文。从 2022 年 12 月首发到 2026 年 7 月重写，仓库经历了几个阶段：

阶段	时间	关键变化
首发	2022-12	投球 100 人 + 击球 98 人；C3D 与大文件直接提交进 git
教程期	2023-01	加入 ezc3d Python 教程
视觉期	2023-11	OBP-CV 发布，加入同步 genlock 视频
体能期	2024-07	High Performance 模块发布
重写期	2026-07-04	git 历史重写、大文件迁 Releases、双许可拆分、加 obp 加载包与 DATASHEET
标定期	2026-07-19	OBP-CV 多相机标定经交叉验证

这条时间线本身就是一个结论：开源数据集的生命周期远长于一次发布。2022 年那份 README 里没有的 obp 包、数据字典、DATASHEET、CITATION.cff，都是四年后补上的。使用开源数据时，"文档不完善"往往是暂时的，但你必须按当下状态来写代码，并为未来变化留好接口。

§8.2 分发机制的工程选择

先说一个容易被忽略的细节：仓库的 README 在同一段里把 .git 体积写成 “2.2 GB → ~25 MB”，又写"新克隆约 28 MB"。两个数字并不矛盾（前者是 .git 目录、后者是整个克隆的工作树），但它们并置时极易被读成"数据集只有 28 MB"。实际的工作数据量是另一回事：投球 + 击球全量压缩约 1.1 GB，解压后更大。这个"仓库轻、资产重"的结构，是理解 OBP 使用流程的前提。

把 1.1 GB 的压缩数据从 git 里移出去，是 2026 年重写的核心决策。原因在 changelog 里写得很直白：.git 从 2.2 GB 降到约 25 MB（消息里同一句还写成 2.2 GB → ~25 MB、新克隆 ~28 MB 两个数），目的是让克隆变快、让 CI 变可行。代价是：

• 克隆不再等于"拿到数据"，多了一步 download_data.sh；
• 资产要通过 GitHub Releases，依赖 GitHub 平台本身；
• 每次下载要校验 release_checksums.sha256，这是好设计，但也意味着资产一旦重新打包，校验文件必须同步更新。

这种"代码与数据分离"的模式在 2024 年后越来越常见（HuggingFace 数据集、DVC、Git LFS 都是类似思路）。OBP 的选择是"GitHub Releases + 自研下载脚本"，好处是不引入额外依赖，坏处是无法像 HF 那样一行 load_dataset 拿到。

§8.3 代码质量与可复现性

2026 年重写后，仓库的工程化程度明显提高：

• 每个模块有固定的 requirements.txt；
• 加载包 obp 提供 load_poi / load_metadata / load_hittrax / load_hp / download 五个入口；
• 有 data_dictionary.csv 与 data_dictionary.json 两份机器可读数据字典，修正了原先的一个错误条目、补上了若干未记录的列、修正了 rejc 地标；
• 有 DATASHEET.md（按 Gebru 等的 Datasheets for Datasets 框架写）；
• 有 CITATION.cff；
• 移除了受版权保护的教科书 PDF（改为引用文献）；
• 清理了提交历史里的 .DS_Store、硬编码路径与 notebook 中的个人可识别信息。

最后一条值得单独说：在 notebook 里留下硬编码绝对路径与个人信息，是科研代码最常见的隐私泄漏渠道。OBP 在重写时明确处理了这一点，这比多数公开数据集做得更细。

§8.4 CV 模块的成熟度分级

OBP-CV 不是主数据模块，但它的文档对"成熟度"的标注方式，可以作为判断其他开源资源可信度的模板：

组件	官方定级	含义
一般 CV 教程	教学示例	可直接跑通，但不保证科研可用
多相机标定	可复现、已测试，非最终实验室坐标	能复现诊断数字，不能当绝对坐标用
标定测试	使用固定版本依赖	数值工件必须可确定性重建
splat 重建	实验性、单次试投	需独立 CUDA 环境，结果仅供参考
4D 重建	贡献者自报数字	明确声明"不是独立生物力学验证"

这种"把不确定性写在显眼位置"的做法，在开源项目里并不普遍。它降低了误用风险，也提醒使用者：看到一个开源资源时，先找它的"成熟度说明"，再决定能不能拿来做结论。

§8.5 复现一份 OBP 分析的最小清单

给别人（或半年后的自己）留下一份可复现的 OBP 分析，至少要做这几件事：

1. 记录你用的是哪个 release（dataset-v1？其他？）以及克隆到的 commit（注意 2026-07 前的老哈希已失效）；
2. 记录用了哪个模块、哪张表、哪些列，列名以 data_dictionary.csv 为准；
3. 记录数据筛选规则（如"球速 ≥ 80 mph"“剔除 playing_level 为 High school”），并说明原因；
4. 记录划分策略（按 user 分组？按 session？）以及每组人数；
5. 记录是否做了力台符号统一、是否解压了全信号 zip、是否用了官方 POI 而非自算；
6. 记录许可合规声明（非商业、非职业体育组织关联）。

第 6 条不是形式主义。CC BY-NC-SA 要求署名、指明修改、相同方式共享；如果你在论文里修改了数据并公开派生数据，派生物也必须以 CC BY-NC-SA 4.0 发布。

§9 与其他资源的对照

§9.0 为什么要做"对照"而不是"比较"

数据集条目之间最容易写坏的一种段落，是"X 比 Y 更大/更好"。规模、许可、模态都可以比大小，但"好坏"没有意义——它们回答的是不同的问题。所以本章只做三类对照：

• 结构对照：这个资源由哪几层组成，缺哪一层；
• 场景对照：它覆盖的人群与动作是什么；
• 许可对照：能不能用在你的场景里。

不做的对照是"谁的精度更高"。评测精度需要同一批金标准数据、同一套指标，而公开数据集几乎不存在这样的共同基准。强行比较，只会把"采集条件不同"误读成"质量高低"。

§9.1 与库内条目的关系

千方病案医数集里有若干与人体运动、动力学相关的条目，与 OBP 构成"同族不同场景"的关系。以下 rid 均按 status=1 AND del_sign=0 口径核实：

条目	rid	与 OBP 的关系	关键差异
UL-RED（rehab-motion-capture）	1162	同属光学动捕 + 多模态人体运动数据	UL-RED 是 10 人 22 式康复操，临床/康复取向；OBP 是百人级竞技专项动作
REHAB（rehab-wearable-kinematic）	1163	同属人体运动学数据	REHAB 用可穿戴 IMU，120 例卒中患者；OBP 用光学标记 + 测力台，健康年轻运动员
GaitND（gait-in-aging）	232	同属步态/运动动力学	GaitND 面向神经退行性疾病人群，OBP 面向健康运动员
gaitpdb（gait-pd）	242	同属含垂直 GRF 的动力学数据	gaitpdb 是帕金森步态 GRF 曲线，OBP 是投球/挥棒 GRF
LIVE-GaitNeuroKids（live-gaitneurokids）	1055	同属多模态运动采集	该集是 IMU + sEMG + 三视角视频的儿童纵向数据；OBP 无肌电、无纵向随访

从上表能读出一个结构性的空缺：库内在"临床运动"与"竞技运动"两侧都有条目，但含完整逆动力学（关节力矩、能量流）的公开数据集极少。OBP 的价值恰恰在于补上了"力矩"这一层——肌电、步态、视频都不缺，缺的是能把运动学转换为关节负荷的完整动力学链条。

§9.2 与库外生态的关系

OpenCap（Stanford）：智能手机视频驱动的无标记动捕系统。与 OBP 的关系是"验证对象"——OpenCap 的用户可以用 OBP 的标记点数据作为金标准，检验自己的姿态估计与逆动力学结果。需要注意两者的人群与动作不同：OpenCap 的验证多在步态与深蹲上，OBP 是投球与挥棒。

OpenSim：开源肌肉骨骼建模平台。OBP 的 C3D 可以导入 OpenSim 重算逆动力学，但必须注意 OBP 官方用了自己的骨骼约定（含左右手对称化与 ±90 度调整），与 OpenSim 的标准模型不一致。直接用 OpenSim 默认流程处理 OBP 的 C3D，得到的关节角与官方 POI 不可比。

ezc3d：读 C3D 的 Python 库，OBP 官方教程就是用 ezc3d 讲的。这是最低门槛的入口。

AddBiomechanics：自动化的标记点清理与模型缩放工具。与 OBP 是上下游关系，但 OBP 的 C3D 已经"清洗过"，再跑一遍自动清理可能反而引入偏差。

AMASS：大规模人体动作捕捉数据集，主要是日常生活动作，不含力台。OBP 与 AMASS 的差别就是"有力台与无肌电"对"无肌电也无地面反作用力"——前者能做逆动力学，后者只能做运动学。

§9.3 一张选型决策表

你的需求	推荐选择	理由
研究棒球投球/挥棒的关节负荷	OBP	唯一含 3/4 块力台与完整逆动力学的公开棒球数据
研究步态与 GRF	gaitpdb（242）或 GaitND（232）	OBP 的 GRF 是投球/挥棒，不是步行
研究康复动作的动捕	UL-RED（1162）	有临床动作体系与三模态
研究可穿戴 IMU 的运动学	REHAB（1163）	OBP 无 IMU
训练无标记姿态估计算法	OpenCap 配套数据 + OBP 作验证集	OBP 的 CV 模块提供同步视频
需要带标签的基准	都不是	这些数据集均无监督标签

§10 总结与决策卡

§10.1 三句话总结

第一句：它是目前公开可得的、规模最大且保真度最高的精英棒球动捕数据集，没有第二家能比。 411 次快球 + 677 次挥棒 + 1,934 次体能评估，配原始 C3D、全信号与 POI 三层表示，这在棒球领域是空前的。

第二句：它的可信度来自仓库维护而非论文。 无 DOI、无同行评审数据论文、无标准划分、无基线——这些"缺"不是偶然，而是"商业机构放数据"这种模式的必然产物。判断它能不能用，要看 DATASHEET 写得多细、下载校验做得多严、更新时间多近。

第三句：它的许可比标准 CC 更窄。 非商业之外，还有一条针对职业体育组织与金融分析公司关联人员的排除条款。这条不是可以靠"学术用途"豁免的。

把三句话合起来，可以给出一句更实用的判断：OBP 是一份"工程可信、学术弱势、法律受限"的数据集。工程可信，是指数据本身的质量与可复现工具链扎实；学术弱势，是指它在引用体系里没有正式地位；法律受限，是指它的使用边界比一般 CC 数据窄。三条同时成立，使用者要各自应对，不能指望其中一条掩盖另外两条。

§10.1b 三个常见误判及其纠正

误判一：以为"开源"就等于"随便用"。 纠正：开源指代码可获取，不指数据可商用。OBP 的代码 MIT 与数据 CC BY-NC-SA 是两套许可，很多人看到 GitHub 就默认整库开源。

误判二：以为"精英"数据集适合做职业层面的结论。 纠正：人群以大学水平为主，MiLB 样本 23 条。"精英"描述的是采集保真度与动作质量，不是竞技等级。

误判三：以为"有 1,934 条评估"就是大样本。 纠正：体能模块与动捕模块人群不同、字段不同、用途不同，1,934 不能算作投球分析的样本量。真正可用的投球样本是 411 次 / 100 人。

这三条误判在二手讨论中出现频率很高，写出来供读者自查。

§10.2 决策卡：三十秒判断能不能用

问题	是 →	否 →
你的用途是非商业的吗？	继续	停，联系商业许可
你或你的资助方与职业球队/金融分析公司有关联吗？	停，需商业许可	继续
你需要的是棒球投球或挥棒吗？	继续	考虑其他条目（§9.3）
你需要带标签的监督基准吗？	不适合，需自建标签	继续
你能接受"无官方基线、无标准划分"吗？	继续	慎用，或自己做划分并公开
你的分析需要变化球数据吗？	不适合，只有快球	继续
你的分析需要肌电吗？	不适合，OBP 无 EMG	继续
结论要外推到职业球员或青少年吗？	谨慎，人群偏大学水平	继续

§10.3 一页速查卡

项目	值
官方名 / 缩写	The OpenBiomechanics Project / OBP
主办	Driveline Baseball Research & Development
官网 / 仓库	openbiomechanics.org / github.com/drivelineresearch/openbiomechanics
首发	2022-12
引用	Wasserberger KW, Brady AC, Besky DM, Jones BR, Boddy KJ (2022)，无 DOI
伦理	Western IRB # WB-DLR-115
投球	411 次 / 100 人 / 全快球 / 球速 69.5–94.4 mph（中位 85.3）
击球	677 次 / 98 人 / 出球速度 48.8–107.0 mph（中位 91.0）/ HitTrax 604 行
体能	1,934 次 / 1,162 人 / CMJ 1,913、SJ 1,827、HT 1,803、IMTP 1,518、PP 438
采样	标记点 360 Hz；力台 1,080 Hz
滤波	4 阶 Butterworth；运动学/动力学 20 Hz，GRF 40 Hz
力台	投球 3 块；击球 4 块
坐标系	+x 二垒→本垒；+y 向一垒；+z 向上
数据体量	投球+击球约 1.1 GB 压缩
许可	数据 CC BY-NC-SA 4.0；代码 MIT；商用需授权
无	无标签、无划分、无基线、无数据论文、无 EMG、无变化球

§10.4 留给读者的三个开放问题

1. OBP 的相对成功，能否被复制到临床数据上？ 医院与康复机构同样积累了海量动捕与力台数据，但受制于隐私与合规，几乎从不公开。OBP 的"机构自有数据的二次释放"模式，在 HIPAA/GDPR 框架下能否成立，是一个值得认真讨论的问题。
2. "无论文的可信度"可持续吗？ OBP 靠仓库维护赢得了信任，但学术评价体系仍以论文与 DOI 计价。一个没有 DOI 的数据集，在基金申请与职称评审里如何被计入贡献？
3. 许可的排除条款是否是开源数据的新常态？ 商业机构放数据时，倾向保留对竞争对手的排除权。这与 CC 的"不歧视"精神存在张力。未来这类"CC + 附加排除"的混合许可会更多，社区需要一套标准化的处理方式。

§10.5 一个反直觉的结论：数据越多，结论越少

写到这里，值得把全篇的一个深层观察点出来。

OBP 有 411 次试投、677 次挥棒、1,934 次评估，看上去样本充足。但当你真正开始做一个严谨的分析，可用样本会急剧缩水：要排除非快球（无变化球，不缩水）；要排除高中水平（投球剩 356 条）；要要求某一列全非缺失（剩余更少）；要按人分层后每层至少留几个样本（100 人分成四层，最少的 MiLB 层只有 23 条）；要做留一投手交叉验证（每次训练集少一个人）。

最后得到的是一个"看起来很大、用起来很小"的数据集。这不是 OBP 的缺陷，而是几乎所有运动数据集的共同处境——样本量在人群维度上永远不够，因为高水平运动员本来就少。

这个观察的实践含义是：在 OBP 上，样本效率比模型复杂度更重要。用 100 个人训练一个深网络，过拟合风险远高于 100 次试投训练一个三参数线性模型。第三节列举的第三方研究中，Perrett 2024 用的是相关分析与统计非参数映射，JOMH 2026 用的是多元回归——都不是深度学习，这不是偶然。

§10.6 一句话给不同类型的读者

读者	一句话
运动生物力学研究生	选一个事件定义清晰的子问题（如分期时长与球速），先做完一轮完整分析，再谈因果
运动医学/康复研究者	可以把 OBP 当作健康运动员的负荷参照分布，但不要用于个体诊断
计算机视觉工程师	用 CV 模块的同步视频 + 标记点数据做验证，注意标定是临时性的
数据工程师	把它当成"无标签、无划分、无 DOI"的数据源，接口要留好版本号
教练与运动表现分析师	许可限制最多，且数据来自实验室评估，与实战情境有差距
开放数据倡导者	这是一个"机构放数据"的成功样本，也是一份"无 DOI 可信度"的活案例

§10.7 相关条目与建议互链点

本文建议与以下库内条目建立互链（rid 已核实）：

• UL-RED / rehab-motion-capture（rid 1162）：光学动捕 + 康复动作，与 OBP 构成"临床 vs 竞技"对照；
• REHAB / rehab-wearable-kinematic（rid 1163）：可穿戴运动学，与 OBP 的光学标记形成模态对照；
• GaitND / gait-in-aging（rid 232）：步态动力学，与 OBP 共享 GRF/力矩分析语汇；
• gaitpdb / gait-pd（rid 242）：垂直 GRF 步态，与 OBP 的力台数据可直接对比分析范式；
• LIVE-GaitNeuroKids / live-gaitneurokids（rid 1055）：多模态运动采集，补齐 OBP 缺失的肌电与视频维度。

---

附录 A：术语与缩写

缩写/术语	全称	说明
OBP	The OpenBiomechanics Project	本项目
C3D	Coordinate 3D	生物力学通用二进制动作数据格式
POI	Point of Interest	每次试投/挥棒的汇总指标行
Full signal	—	完整时间序列，未经事件截断
GRF	Ground Reaction Force	地面反作用力
MER	Maximum External Rotation	最大外旋（投球蓄力末端）
FF	Fastball	快球
CMJ	Countermovement Jump	反向纵跳
SJ	Squat Jump	蹲跳
HT	Hop Test / Repeated Hop	连续跳
IMTP	Isometric Mid-Thigh Pull	等长中位大腿拉
PP	Plyo Pushup	爆发俯卧撑
UCL	Ulnar Collateral Ligament	肘尺侧副韧带
IRB	Institutional Review Board	机构审查委员会
HitTrax	—	击球结果追踪系统，记录出球速度与击球角度
genlock	Generator Lock	多机位视频帧同步技术
Edgertronic	—	高速摄像机品牌

附录 B0：DAIMS 评分的方法说明

DAIMS 是本库统一的五维评估框架（D 可发现性、A 可获取性、I 可互操作、M 元数据质量、S 可持续性），每维 1-10 分。评分不追求绝对客观，但每一项都要能指向具体证据。

对 OBP 而言，评分时最纠结的是 D 与 S 两项。单看"数据是不是好用"，它可以上 9 分；但看"它在学术体系中是不是一个可引用的实体"，只有 4 分水平。最终给 D 8 分、S 7 分，是把"能否被找到、能否长期存在"与"是否能被规范引用"分开计的结果。若你的研究要求数据集有 DOI，请直接按 4 分看。

I 项给 9 分是罕见的。多数医学数据集在互操作上吃亏，是因为图像格式繁杂、标注体系不统一、缺少机器可读字典。OBP 恰好相反：格式是行业标准（C3D）+ 最简单的表格（CSV）+“两次重写后补上的数据字典”。这是"以工程规范换互操作性"的典型。

附录 B：DAIMS 评估全表

维度	评分（1-10）	依据
D 可发现性	8	官网 + GitHub 双入口，搜索引擎覆盖好，第三方论文引用多；扣分项是无 DOI、无同行评审数据论文，在学术数据库中不可检索为独立数据集记录
A 可获取性	8	公开直链、无需注册、无需 DUA，一键下载脚本 + sha256 校验；扣分项是需 gh CLI 认证、全信号需手动解压、1.1 GB 体量对带宽有限者不友好
I 可互操作	9	C3D 是生物力学事实标准，CSV 全信号可直接进 pandas，POI 表结构简单；扣分项是官方骨骼/坐标约定与 OpenSim 标准模型不一致
M 元数据质量	8	DATASHEET 按 Gebru 框架撰写，含人群、缺失、局限、伦理批号；有机器可读数据字典与 CITATION.cff。扣分项是相机型号/台数、标记点总数、处理软件均未公开，肩髋符号约定"未报告"
S 可持续性	7	依托 GitHub + 官网双备份，机构持续投入（2022→2026 仍在更新）；扣分项是无 DOI、无独立存档机构（如 Zenodo），一旦 GitHub 或机构变动，长期存续无保障
综合评级	8.0/10（优）	互操作性与元数据为最大加分项；学术可引用性与长期存档为最大短板

补充说明：若把"可引用性"单列为一项，OBP 只能得 4 分——它没有 DOI、没有数据描述论文，在正式的数据引用体系里处于边缘。这与它的实际使用量严重不匹配，是本条目最值得记录的一个结构性事实。

附录 C：逐项证据链与双口径存照

关键数字	来源	一致性
100 投手 / 98 打者	官网首屏 + 2022 首发博客	两处一致
411 次试投 / 100 人	GitHub 主 README 快照表 + DATASHEET	两处一致
677 次挥棒 / 98 人 / 604 HitTrax	GitHub 主 README + DATASHEET	两处一致
1,934 评估 / 1,162 人	DATASHEET	单一来源（快照表同值）
328 右投 / 83 左投	DATASHEET	单一来源（合计 411）
496 右打 / 181 左打	DATASHEET	单一来源（合计 677）
球速 69.5 / 85.3 / 94.4	DATASHEET	单一来源
出球速度 48.8 / 91.0 / 107.0	DATASHEET	单一来源
360 Hz / 1,080 Hz	DATASHEET + 投球模块 README	两处一致
20 Hz / 40 Hz 滤波	投球模块 README + DATASHEET	两处一致
3 块 / 4 块力台	DATASHEET + 投球 README + 2022 早期仓库	三处一致
8 OptiTrack / 4 Edgertronic / 1 iPhone	computer_vision README + 2026-07 changelog	两处一致，均指 CV 视频机位
1.1 GB	GitHub 主 README	单一来源
Western IRB # WB-DLR-115	DATASHEET + JOMH 2026 伦理声明	两处一致
41.3% 方差解释	JOMH 2026 摘要	单一来源（第三方论文）

双口径冲突存照（逐条）：

1. 打者人数 98 vs 99：GitHub 主 README 快照表写 98，另一份 2026 年 README 镜像写 “~99 athletes” 且声明整表为 “Approximate figures”。以 DATASHEET 的 POI 行数 677 / 唯一运动员 98 为准；99 作为近似口径存照。
2. 许可表述：官网 Usage Terms 仍称 “All data, code, and any derived works … under CC BY-NC-SA 4.0”；GitHub 2026-07 起代码改为 MIT。本文按"代码 MIT / 数据 CC BY-NC-SA 4.0"成稿，并在坑 8 说明官网旧表述未同步。
3. 仓库体积：changelog 同句内出现 “.git 2.2 GB → ~25 MB” 与 “fresh clone ~28 MB” 两个数字，前者指 .git 目录、后者指工作树克隆总量，非冲突但易被误读为同一口径。
4. 事件名跨模块：投球 5 事件（foot contact / foot plant / MER / ball release / max IR）与击球 3 事件（front foot contact / front foot plant / contact）为不同模块，不可互换。
5. 相机口径：CV 模块的 8 路 OptiTrack 是视频机位，非动捕主系统相机；主系统相机台数官方未公开。这是全网二手资料最常出错的一处。
6. “elite” 措辞：官网自称 “elite-level”，但 DATASHEET 显示人群以大学水平为主（投球 314/411、击球 517/677）、球速中位 85.3 mph、MiLB 样本仅 23 条。“elite” 应理解为"高保真采集"，而非"职业精英"。

遗留疑点：

1. 动捕主系统的相机数量、品牌、型号、采集软件、标记点总数：官方未公开。
2. 无同行评审数据论文，引用依赖 2022 年 misc 条目（无 DOI）。
3. HitTrax 604 行与 677 次挥棒之间 73 次缺配的原因未说明。
4. 全信号表 time 列的零点对应哪个事件，文档未逐模块说明。
5. user / session 与 athlete_uid 之间是否有公开对照表，未确认。
6. DATASHEET 称"肩与髋部分力/力矩符号约定未报告"，具体是哪些分量未逐项列出。
7. OBP-CV 标定何时从"临时性"升级为"最终实验室坐标系"，路线图未给时间表。
8. 2026-07 历史重写后，是否有利用旧 commit 哈希的第三方复现脚本失效，未见公开讨论。

附录 D：与邻近资源的对照速查

对照项	OBP	AMASS	OpenCap 配套数据	UL-RED（1162）
动作类型	竞技专项（投球/挥棒）	日常生活	步态/深蹲等	康复操 22 式
规模	100 投手 + 98 打者	万余段	数十人	10 人
采集方式	光学标记 + 力台	光学/IMU 混合	智能手机视频	光学 + 无标记 + 深度
含 GRF	是（3/4 块力台）	否	否	部分
含关节力矩	是（内力矩）	否	可算（需模型）	否
含 EMG	否	否	否	否
许可	CC BY-NC-SA + 排除条款	多为非商业	开源	见条目
学术引用性	无 DOI	CC BY 4.0	有论文	有 DOI

附录 E：使用前检查清单

• [ ] 确认用途为非商业，且本人/资助方与职业体育组织、金融分析公司无关联
• [ ] 确认所用模块（投球 / 击球 / 体能 / CV）与数据层（Raw / Full signal / POI）
• [ ] 克隆后用 scripts/download_data.sh 拉取，并核对 sha256
• [ ] 解压所需的全信号 zip
• [ ] 用 data_dictionary.csv 核对列名（不要凭 README 记忆）
• [ ] 力台跨板计算前统一 X 轴符号
• [ ] 划分策略按 user 分组，防止运动员泄漏
• [ ] 若自行重算力矩，先与官方 POI 做符号一致性抽检
• [ ] 结论不外推到职业球员、青少年或变化球场景
• [ ] 署名、指明修改、派生数据同许可发布

附录 F：常见问题速答

Q：克隆仓库就能用吗？
A：能做 POI 与体能分析，不能做 C3D 与全信号分析，后者要跑下载脚本并解压。

Q：import obp 报 ModuleNotFoundError？
A：obp 是仓库内的本地包，必须在仓库根目录运行，或把仓库根加入 sys.path。

Q：数据和官网说的"100 名投手"对不上？
A：100 是人数，411 是试投数。POI 表 411 行，元数据唯一 user 100 个。

Q：为什么计算出来的关节力矩符号与官方 POI 相反？
A：肩与髋的部分符号约定官方未报告，不建议自行重算；必须重算时先做小批一致性抽检。

Q：可以用于商业产品吗？
A：不可以，除非取得商业许可。且专业体育组织、金融分析公司关联人员另有排除条款。

Q：能不能用它训练一个球速预测模型发论文？
A：可以，但必须按 user 分组划分、报告人群分层、声明横断面性质与外推边界。

Q：CV 模块的视频能和动捕数据对齐吗？
A：视频与动捕的同步机制未公开，CV 标定被标注为临时性，直接对齐有风险。

Q：数据会更新吗？
A：会。2022 首发、2023 加教程与 CV、2024 加体能、2026 重写仓库。使用时记录获取日期与 commit。

Q：有没有更权威的替代数据集？
A：在公开的精英棒球动捕这一细分领域，目前没有同等规模的替代品。其他运动（如足球、篮球）有各自的公开数据，但规模与力台配置通常不及 OBP。

Q：可以用它做医疗诊断或训练处方吗？
A：不能。受试者是健康运动员，数据是研究用评估记录，不构成诊断依据，也不适用于个体化处方。

附录 G：版本与获取时间线速查

日期	版本/事件	对使用者的影响
2022-12	首发投球 100 人	大文件直接进 git，克隆即得数据
2022-12（约一周后）	首发击球 98 人	同上
2023-01-10	ezc3d 教程	有了 Python 读取路径
2023-11-02	OBP-CV 发布	可做无标记姿态研究
2024-07-30	High Performance 发布	增加 1,934 次体能评估
2026-02	教育用途免费延至 2030-12-31	教学项目可放心使用
2026-07-04	仓库重写、双许可、dataset-v1	旧克隆必须重克隆；代码转 MIT
2026-07-19	CV 标定经交叉验证	仍为临时性，非最终实验室坐标

补章 H：核验过程中仍然没有答案的问题

以下是本条目在核验后仍然开放的问题。它们不是文档疏漏的抱怨，而是会影响研究设计的实质不确定性，按"影响程度"排序：

H1 动捕主系统的相机配置。 相机台数直接影响遮挡鲁棒性与空间精度，官方未公开。若你的研究与另一个实验室的动捕数据做跨集比较，这一项缺失就无法论证可比性。

H2 事件检测算法的实现。 体重阈值给出来了，但阈值是在滤波前还是滤波后判定、是单帧判定还是持续若干帧、插补缺失帧时如何处理，均未说明。这决定了事件时刻的复现性。

H3 user 与 athlete_uid 的对照。 两个模块之间能否做个体级连接，直接影响"动作表现 × 身体能力"这类交叉研究是否可行。

H4 完整数据集的规模。 官网明说公开的只是"更大数据集的样本"。完整集有多大、包含哪些球种、覆盖哪些年份，均未公开。这意味着任何"OBP 有多大规模"的说法，都只适用于公开部分。

H5 数据的年份跨度。 采集从哪一年开始、到哪一年结束，DATASHEET 未给明确区间。这影响"数据是否反映当下训练理念"的判断，JOMH 2026 那篇正是在这一点上自陈局限。

H6 校准溯源。 标记点坐标是否有实验室校准报告、空间精度指标（如重建误差）是多少，未公开。做绝对量研究时需要自行评估。

H7 CV 标定的升级时间表。 官方路线图文档给出了下一阶段的工作计划，但未给完成时间。依赖 CV 坐标的研究应先假定它长期处于"临时性"状态。

§8.6 一份"数据快照"应该长什么样

长期使用 OBP 的人迟早会问：三年后我还能拿到同一份数据吗？答案是不一定。仓库会重写、资产会重新打包、字段会改名。因此建议在做任何正式分析时，先做一份"数据快照"记录。

一份合格的快照至少包含：

1. 获取时间（精确到日）；
2. 仓库 URL 与 commit 哈希（2026-07 之后的哈希才有效）；
3. release 标签（如 dataset-v1）与资产文件名；
4. sha256 校验值（下载器已生成 release_checksums.sha256，把它一并存档）；
5. 实际使用的表与列清单（用代码导出列名，而不是手抄）；
6. 行数与人数核对结果（按 §4.9 的六步）；
7. 本地镜像路径（若磁盘允许，把用到的 CSV 或 C3D 复制一份）。

这份快照的价值不在于"严谨"，而在于当你半年后发现结果对不上时，能迅速判断是数据变了还是代码变了。没有快照，这两种情况无法区分。

§8.7 关于"可复现性"的分层理解

可复现性在数据科学里被用得很泛，实际上至少要分三层：

第一层：环境可复现。 同样的 Python 版本、同样的依赖，能跑出同样的错误或同样的结果。OBP 的 requirements.txt 与固定版本的标定依赖解决了这一层。

第二层：数据处理可复现。 从原始 C3D 到分析输入，每一步都能重跑且结果一致。这一层最难，因为涉及大量默认参数（滤波、缺失插补、事件阈值）。OBP 官方提供了 full signal 作为"官方处理结果"，但你自己的处理流程仍然不可复现，除非你把参数写死。

第三层：结论可复现。 别人用同样的数据、同样的流程，能得到同样的统计结论。这一层受限于数据划分（无标准划分）与统计方法（多种合理选择），几乎不可能完全做到。

评价一个 OBP 相关研究是否"可复现"，要看它停在哪一层。声称"完全可复现"的论文，通常只做到了第一层。

§8.8 一次 git 历史重写的教训

2026 年 7 月 4 日的仓库重写，是一个值得所有开放数据使用者记住的案例。

变化的动机是合理的：.git 2.2 GB 太大，克隆慢、CI 不可行。处理方式也是标准做法：清除历史里的大二进制，改由 Releases 分发。

但它带来了三个连锁后果：

其一，所有旧的 commit 哈希失效。 任何在论文补充材料里写"我们使用了 commit abc1234 的数据"的研究，其数据来源从此无法精确回溯。

其二，所有旧的路径引用失效。 文献里常见的 baseball_pitching/data/c3d，在新分发里要跑过下载脚本才存在。

其三，所有旧的克隆无法通过 pull 修复。 官方明确要求删除重克隆，这对在网络受限环境里维护长期副本的团队是实实在在的成本。

这个案例的一般性教训是：当数据集把"版本"寄托在 git 历史而不是 DOI 上时，它的历史是可以被改写的。DOI 一旦分配就不可变，git 哈希不是。这不是说 GitHub 不好，而是说二者在"可引用性"上不等价。

§8.9 一段代码：把 §4.9 的六步核对写成脚本

下面这段代码不是官方的，是把本文 §4.9 的六步核对落成可执行形式，供读者改用自己的路径。

import obp
import pandas as pd

poi = obp.load_poi("pitching")
meta = obp.load_metadata("pitching")

checks = {
    "rows": (len(poi), 411),
    "unique_users": (poi["user"].nunique(), 100),
    "speed_min": (round(poi["pitch_speed_mph"].min(), 1), 69.5),
    "speed_max": (round(poi["pitch_speed_mph"].max(), 1), 94.4),
}
for k, (got, expect) in checks.items():
    flag = "OK " if got == expect else "DIFF"
    print(f"{flag} {k}: got={got} expect={expect}")

print(meta.isna().sum().sort_values(ascending=False).head(10))

两点说明：第一，unique_users 期望值是 100，若你的结果不同，先检查是否把两个模块的表混在一起；第二，缺失统计的 head(10) 应按 DATASHEET 的描述解读，若某列缺失率异常高于文档所述，很可能是解压不完整。

这段代码只有十几行，却能替代一次完整的人工核对。建议把它加进你自己的 pipeline 作为"数据摄取断言"（data ingestion assertion），在每次训练或分析开始时自动运行。

§8.10 关于"官方示例"的读法

仓库的 examples/ 目录有四个脚本，它们的作用不是"教你做研究"，而是"证明数据能被读出来"。理解这一点很重要：示例代码写得再漂亮，也不能直接作为分析代码使用。

具体来说，示例脚本通常不做这些事：不做运动员分组划分、不做缺失处理、不做分布检查、不报告置信区间。它们的目标是"跑通"，不是"正确"。

建议的用法是：把示例当作文档的可执行版本，用来确认你的环境与数据路径正确；真正的分析代码另起一份，并按 §4.9 与 §8.9 的纪律写。这样既利用了官方的便利，又不把示例的简化带进研究发现里。

§9.4 为什么"缺肌电"是一个结构性的分水岭

把 OBP 与邻近资源对照时，最容易忽略的一条差异是：它们都没有肌电。AMASS 没有、OpenCap 配套数据没有、UL-RED 没有、OBP 也没有。这不是巧合。

肌电采集需要电极贴合、皮肤处理、信号放大与巨大的通道数，成本远高于标记点。在"大样本、多年积累"的场景里，肌电几乎不可能全程维持。因此公开的"大体量"运动数据，几乎必然止步于运动学加动力学，无法进入肌肉激活层面。

这个结构性的分水岭，对使用者的含义是：从公开数据出发的研究，很难直接讨论"某块肌肉在何时被激活多少"。你能算力矩，但算不出哪块肌肉贡献了多少；你能看能量流，但看不到肌肉的主动收缩模式。任何声称从 OBP 推断肌肉激活的研究，都需要额外的模型假设（如静态优化），而这些假设本身是巨大的不确定性来源。

这也是为什么 OBP 的第三方研究多集中在"运动学与表现的关系"（如 Perrett 2024）与"动力学指标的统计建模"（如 JOMH 2026），而很少涉及肌肉层面。不是因为研究者不想，而是因为数据到此为止。

§9.5 三个"看起来像但不是"的资源

写这篇条目时，我刻意核对了三个容易被误认为同源的名字：

OpenCap：拼写相似（Open 开头，与"开放"有关），常被误以为与 OBP 同源。实际是 Stanford 的无标记动捕工具链，与 OBP 无组织关系。二者的关系是"可能互用的上下游"，不是同一项目的两个版本。

OpenSim：OBP 的 C3D 可以导入 OpenSim，但 OpenSim 的标准模型与 OBP 的骨骼约定不一致（§9.2）。二者是不同的东西，只是可以衔接。

OpenBiomechanics 与 OpenBiome：后者是一个致力于粪便微生物群移植的非营利组织，名字相似，领域完全不同。检索时容易误命中。

这三个提醒看似琐碎，但在文献检索里，"名字撞车"是产生错误引用的高频原因。开源数据尤其容易，因为"Open"是命名惯用前缀。

§9.6 选型的一个补充维度：许可

§9.3 的决策表按"研究需求"排，但许可往往才是决定性因素。补一张按许可排序的表：

资源	数据许可	商用	特殊限制
OBP	CC BY-NC-SA 4.0	需付费许可	专业体育组织/金融分析公司关联人员禁用
AMASS	多为非商业（逐子集不同）	多数不可	需逐子集核对
OpenCap 配套数据	开源（以项目公告为准）	视子集	—
UL-RED（1162）	见该条目	见该条目	—

这张表的要点不是评价哪个许可"更好"，而是提醒：在选数据之前，先确认自己处在哪一类使用者里。学术机构的研究者、企业的研究部门、职业球队的分析师，同一份数据的使用权限可能完全不同。OBP 的排除条款把这一差异写到了明面上，这反倒是一种坦诚。

---

相关数据集导航

以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：

• body-sway-music-vr — 共享标签：生理信号 / 可穿戴传感 / 步态与运动 / 多模态
• grabmyo-flow — 共享标签：生理信号 / 可穿戴传感 / 步态与运动 / 多模态
• live-gaitneurokids — 共享标签：生理信号 / 可穿戴传感 / 步态与运动 / 多模态
• rehab-motion-capture — 共享标签：生理信号 / 可穿戴传感 / 步态与运动 / 医学影像
• multimodal-gait-dataset — 共享标签：生理信号 / 可穿戴传感 / 步态与运动 / 多模态
• wesad — 共享标签：生理信号 / 可穿戴传感 / 多模态
• ppg-dalia — 共享标签：生理信号 / 可穿戴传感 / 步态与运动
• covid-19-sounds — 共享标签：生理信号 / 可穿戴传感 / 医学影像
• pamap2 — 共享标签：生理信号 / 可穿戴传感 / 步态与运动
• mhealth — 共享标签：生理信号 / 可穿戴传感 / 步态与运动

导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。