# YMSKE **Repository Path**: yao_mi/ymske ## Basic Information - **Project Name**: YMSKE - **Description**: YMSKE 是一套mini可裁剪的 C99 骨架与 CPU 蒙皮库，大小约为400KB，支持骨架层级、姿态更新、绑定矩阵及 1–8 槽线性混合蒙皮，可同步更新顶点位置和法线。通过适配层，可由 PME 刚体驱动骨骼，并将蒙皮结果直接写入 GRE 网格。既能使用独立数组，也能共享只读绑定数据，并为不同实例保留独立姿态与输出。适用于角色展示、机械关节可视化及仿真应用。 - **Primary Language**: C - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-09-14 - **Last Updated**: 2026-10-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: C语言, 蒙皮, 仿真, 骨骼, 动画 ## README

让骨骼动起来，让网格跟上。
独立、可裁剪的 C99 骨架与 CPU 蒙皮库。

演示画廊 · 快速开始 · 模块与集成 · 发布包 · API · 文件格式

展开双关节快捷键

| 按键 | 功能 | | --- | --- | | Space | 暂停 / 自动弯曲 | | 左 / 右 | 手动弯曲第一个关节 | | 下 / 上 | 手动弯曲第二个关节 | | R | 回到绑定姿态并暂停 | | W / B | 切换线框 / 骨架 | | Esc | 退出 |

## 预编译 SDK 可直接下载 [releases 发布包](releases/README.md)，附带 SHA-256 校验文件。运行 `python3 sdk/build.py --release` 会重新构建、验证并更新发布包，默认仍为一体库。可搬移的库包位于 `build/YMSKE_libs`，使用方式见包内 README 和 `手册.md`。`find_package(YMSKE 0.2 CONFIG REQUIRED COMPONENTS core skin io)` 即可按需导入；可选 gre/pme 组件使用独立发布的 GRE/PME SDK。包内提供全部 1–8 槽权重变体，以及 16/32 位索引适配库；GRE 预编译适配匹配 RGB565。默认 `python3 sdk/build.py` 将全部模块合并为一体库；`python3 sdk/build_modular.py` 保留独立模块归档，输出到 `build/YMSKE_libs`。两种构建共用该目录，默认使用一体库，显式运行模块化脚本才切换。两者都会构建、搬移验证并生成带校验和的压缩包，成功后整包替换原输出。需要自定义依赖路径时使用 `--gre-sdk /path/to/YMGRE_libs --pme-sdk /path/to/YMPME_libs`。源码构建及窗口演示保留原方式；0.2 的库与调用方须一起重编译。详见 [SDK 说明](sdk/README.md)。 ## 快速开始 ### 只用骨架和蒙皮准备 C99 编译器和 CMake 3.16+。独立库只需要 C 标准库与 `libm`，不依赖 GRE、PME 或 SDL。 ```sh cmake -S . -B build-standalone -DCMAKE_BUILD_TYPE=Release cmake --build build-standalone -j4 ctest --test-dir build-standalone --output-on-failure ./build-standalone/bench_skin ``` 仅需要骨架时，配置 `-DYMSKE_BUILD_SKIN=OFF`。最小骨架例子可通过 `cmake --build build-standalone --target demo_bind` 构建。 ### 运行窗口演示以下命令在 YMSKE 根目录执行，假设相邻目录是 `YMPME` 与 `0502_YMGRE`；其他布局请替换两个依赖路径。窗口演示还需要 GRE 宿主的 SDL2 开发依赖。 ```sh cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \ -DYMSKE_BUILD_PME=ON \ -DYMSKE_BUILD_GRE=ON \ -DYMSKE_BUILD_DEMO=ON \ -DYMSKE_BUILD_HAND_DEMO=ON \ -DYMSKE_BUILD_OWL_DEMO=ON \ -DYMSKE_HAND_ASSET=refined \ -DYMSKE_PME_ROOT=../YMPME \ -DYMSKE_GRE_ROOT=../0502_YMGRE cmake --build build -j4 ctest --test-dir build --output-on-failure ./build/demo_two_joint ./build/demo_hand ./build/demo_owl ``` 人体演示单独构建，自动配置六槽权重： ```sh cmake -S project_Demo/human -B build/human -DCMAKE_BUILD_TYPE=Release cmake --build build/human --target demo_human -j4 ctest --test-dir build/human --output-on-failure ./build/demo_human ``` 人体项目可通过 `-DGRE_ROOT=/path/to/GRE` 指定渲染引擎。修改源码后需重新构建；直接启动已有可执行文件不会自动编译。

离屏输出、文本资产与窗口自检

```sh ./build/demo_two_joint --headless ./build/demo_hand --headless ./build/demo_owl --headless ./build/demo_human --headless ./build/demo_owl --text ./build/demo_human --text ./build/demo_hand --smoke-test ./build/demo_human --capture-ui ``` 离屏和截图模式把 PPM 写入当前工作目录。猫头鹰和人体支持 `--assets /path/to/assets`；`--text` 切换为对应的 `.ske.txt` / `.ska.txt` 文件。无显示环境的窗口自检可设置 `SDL_VIDEODRIVER=dummy`。

## 独立核心，按需接入保留原来的 `YMSKE_Skin_Init` 独立数组接口；新增 `YMSKE_Skin_InitView`，可借用外部位置、法线和独立权重的连续或交错布局。核心不依赖 GRE/PME，不复制整份绑定数据、不分配。GRE 用户可通过 `YMSKE_GRE_Skin_InitView` 借用只读绑定网格，各实例另备姿态和输出缓冲。详见 [共享数据与所有权](SHARED_DATA.md)。 GRE 桥接支持 16/32 位 `GRE_Index`；骨骼索引仍保持 SKE 自己的定义。`ske_skin` 增加字段，需要将库和调用方一起重新编译；SKE/SKA v1 文件无需转换。 ```text 应用写入局部姿态 ──→ Pose_Update ───────────┐ ├──→ Skin_UpdatePacked ──→ 应用自己的输出 PME 刚体步进 ─────→ PME_Sync ──────────────┘ └──→ GRE_Update ─────────→ GRE 渲染 ``` **独立使用时，应用提供输入和输出；接入 GRE 时，蒙皮直接写入 GRE 的持久顶点缓冲。** 骨架资源和只读绑定顶点可供多个实例共用，每个实例持有自己的姿态和变形结果。绑定数据与变形输出分开，避免逐帧累积变形。 | 目标 | 职责 | 依赖 | | --- | --- | --- | | `YMSKE::core` | 数学、骨架层级、姿态与矩阵缓存 | C99 + `libm` | | `YMSKE::skin` | 顶点与法线的 CPU LBS | core | | `YMSKE::io` | SKE / SKA 的二进制与文本读写 | skin | | `YMSKE::pme` | 将刚体姿态映射到骨骼 | core + PME 头文件 | | `YMSKE::gre` | 直写网格，更新面法线与包围体 | skin + GRE | 通过 `add_subdirectory` 按需链接这些目标。仅链接 core 不会带入 skin、PME 或 GRE；启用可选目标时设置对应构建选项。CMake 不下载外部库。 `PME_Sync` 已更新姿态和矩阵缓存，无需重复调用 `Pose_Update`。连续数组用 `Skin_UpdatePacked`，交错输出用 `Skin_Update`。GRE 路径同步普通位置与高级位置/法线，保留 UV、颜色和材质，避免中间网格拷贝。完整约定见 [结构与集成](ARCHITECTURE.md)。

CMake 配置一览

| 选项 | 默认 | 用途 | | --- | --- | --- | | `YMSKE_BUILD_SKIN` | ON | CPU 蒙皮 | | `YMSKE_BUILD_IO` | OFF | 骨架 / 采样姿态文件读写 | | `YMSKE_BUILD_PME` | OFF | PME 刚体映射 | | `YMSKE_BUILD_GRE` | OFF | GRE 网格适配 | | `YMSKE_BUILD_DEMO` | OFF | 双关节演示，至少两槽权重 | | `YMSKE_BUILD_HAND_DEMO` | OFF | 手掌演示，要求 PME、至少四槽 | | `YMSKE_BUILD_OWL_DEMO` | OFF | 猫头鹰演示，自动启用 IO，无需 PME | | `YMSKE_BUILD_GIRL_DEMO` | OFF | Girl 演示，自动启用 IO/GRE 并默认八槽权重 | | `YMSKE_GIRL_ORIGINAL` | OFF | Girl 高模与烘焙表情，要求 GRE 32 位索引 | | `YMSKE_BUILD_TESTS` | ON | 无窗口测试、集成验证和基准 | | `YMSKE_MAX_INFLUENCES` | 4 | 固定权重槽数，范围 1–8 | | `YMSKE_SANITIZERS` | OFF | GCC / Clang 地址与未定义行为检查 | 权重槽数影响公开结构的 ABI；GRE 的索引位宽和色深也影响数据布局。库与调用方必须使用匹配配置，并在切换配置后重新编译。

## 资产可以保存，也可以检查 | 格式 | 保存内容 | | --- | --- | | `.ske` | 骨骼名字、父子关系、绑定矩阵、绑定顶点与法线、权重 | | `.ska` | 帧率、循环标记、每帧每骨骼的局部姿态矩阵 | | `.ske.txt` / `.ska.txt` | 同一数据的可读文本版本 | 读取接口自动识别编码，加载缓存由调用者提供。GRE 的 `.mesh`、材质和贴图独立保存；骨架与网格指纹用于检查配对。完整协议以 [SKE/SKA v1 格式规范](YMSKE/IO/FORMAT.md) 为准。 ```sh ./verify_asset_io.sh ``` 这条命令验证二进制和文本读写、逐字段与逐 float 位比较，以及猫头鹰全部 34 帧的蒙皮位置和法线。报告写入 `build/io-verification/verification.log`。 ## 验证与边界已有测试覆盖骨架层级、解析蒙皮结果、非均匀缩放、非法权重、文件损坏、实际 GRE 网格更新及窗口事件。运行时分配测试通过包装堆函数，检查指定的姿态、物理、蒙皮与渲染路径；窗口系统和 C 库内部行为不属于核心的零分配承诺。基准方法、测试配置和历史实测见 [性能与验证](PERFORMANCE.md)。性能数字对应具体机器和构建，不作为所有设备的帧率承诺。当前实现 CPU 线性混合蒙皮。大角度关节可能产生 LBS 固有的体积压缩；通用动画播放器、混合、IK、GPU 蒙皮和切线蒙皮尚未纳入核心。猫头鹰的采样播放与插值在演示层实现。 ## 附带资源：草与树 [![草树低模资源中的九种树与枝叶，来自 GRE 原生渲染](docs/images/vegetation-trees.png)](Resource/vegetation_lowpoly/README.md) **41 个静态模型：6 棵完整树、3 个枝叶素材、32 个草模型。** 低模资产总计 24,439 个三角面，仓库只保留低模资源，原始高模与下载包需另行准备。配套工具提供准备、减面、验证和 GRE 预览；这些静态资产没有骨架或动作。 [资源说明 →](Resource/vegetation_lowpoly/README.md) · [植被工具 →](tools/vegetation/README.md) ## 文档与资源来源 | 想了解什么 | 从这里开始 | | --- | --- | | 接口与调用顺序 | [API.md](API.md) | | 坐标、缓存、所有权与引擎接入 | [ARCHITECTURE.md](ARCHITECTURE.md) | | 独立与共享输入、缓冲生命周期 | [SHARED_DATA.md](SHARED_DATA.md) | | 性能与验证方法 | [PERFORMANCE.md](PERFORMANCE.md) | | 资产文件协议 | [SKE/SKA v1](YMSKE/IO/FORMAT.md) | | 代码约定 | [代码风格](代码风格.md) | | 截图来源与复现 | [首页图片说明](docs/images/README.md) | 演示资源各自保留来源与授权说明：[手掌](Resource/hand_refined/README.md)、[猫头鹰](Resource/owl/README.md)、[人体](Resource/human/README.md)、[植被](Resource/vegetation_lowpoly/README.md)。人体来自 Eliber 的 **Rigged Base Mesh**，当前许可为 **CC0**；包内旧许可文件尚未同步。各资源的来源与许可说明见对应目录。 ## 调试诊断（0.2.1）核心库现提供独立 DEBUG 模块：错误位置和元素编号、等级过滤、自定义日志回调，以及可分别裁剪的日志、stderr 和断言。原有错误返回码保持不变，成功更新不逐帧打印。配置与 SDK 示例见 [调试诊断说明](DEBUG.md)。 ## 授权声明个人及非商业组织以非营利目的学习、研究或自用 YMSKE，可免费使用；商业用途必须事先说明并取得著作权人的书面授权。对外分发修改版或使用修改版对外提供服务时，须按许可条款公开本库的对应源码及必要构建文件。第三方 CC0 资源及外部依赖按各自原许可使用。完整条款见 [LICENSE](LICENSE)。当前版本 **0.2.2**，更新说明见 [CHANGELOG](CHANGELOG.md)。根目录也可构建 Girl 高模窗口演示： ```sh cmake -S . -B build/girl-root -DYMSKE_BUILD_GIRL_DEMO=ON -DYMSKE_GIRL_ORIGINAL=ON -DYMSKE_GRE_ROOT=../0502_YMGRE cmake --build build/girl-root --target demo_girl -j4 ./build/demo_girl_original ``` 使用新构建目录；低模省略 `YMSKE_GIRL_ORIGINAL`。Girl 的场景实现与 SDK 示例共用。