🚶 moonbit-gaitlab (MoonBit 步态实验室)

面向跑步、术后康复、老年运动筛查的开源步态指标计算与临床筛查算法库，完全使用国产编程语言 MoonBit 编写。

🌟 项目简介

moonbit-gaitlab 致力于为医疗康复机构、体育科研单位和老年健康监护系统提供一套高集成、无第三方依赖、轻量且高度精确的步态生物力学分析组件。通过导入关节点轨迹数据（CSV/JSON 格式），对信号进行平滑去噪与波谷检测，切分步态周期，计算时间-空间维度参数，并结合 bilateral symmetry（双侧对称性）指标与临床辅助筛查算法，输出易读的步态健康 Markdown 报告。

🛠️ 核心功能范围

多源关节点轨迹导入：
- 内置 RFC 4180 兼容的 CSV 解析器，支持将关节位置时间序列直接解析为 Double 矩阵。
- 内置轻量 JSON 解析与序列化器，用于结构化步态元数据导入和分析结果导出。
信号滤波与事件检测：
- 提供简单移动平均（SMA）、指数移动平均（EMA）滤波，消除传感器噪音。
- 提供数值微分（中央差分法）计算关节点速度与加速度。
- 鲁棒的波峰/波谷查找算法，精准定位足部着地（Heel Strike）和离地（Toe Off）的帧位置与时刻。
步态周期自动切分：
- 以连续的同侧足部着地时刻（Heel Strike to Heel Strike）自动切分完整的步态周期（Gait Cycle）。
时空参数计算：
- 时间参数：步速、步频（Cadence）、步态周期时间、支撑相（Stance Phase）时间及比例、摆动相（Swing Phase）时间及比例、双支撑相（Double Support）时间。
- 空间参数：步长（Step Length）、步幅（Stride Length）、步宽（Step Width）。
双侧对称性分析：
- 自动计算双侧 Stride Time、Stance %、Step Length 的对称性指数（Symmetry Index, SI）。
- 计算综合步态对称性指数（Gait Symmetry Index）。
临床筛查与评估规则：
- 跌倒风险评估：根据步宽过宽、步幅短缩（拖地步态）和高不对称性进行老年跌倒风险分级。
- 康复进度评分：针对关节手术（如髋/膝关节置换）后患者提供量化的主动康复指数。
- 异常步态识别：基于规则分类常见异常步态类型（如疼痛避让步态 Antalgic、偏瘫步态 Hemiplegic、帕金森震颤/慌张步态 Parkinsonian、共济失调/摇晃步态 Ataxic）。
可视化命令行报告：
- 生成精美的终端 ASCII 进度图展示支撑/摆动相占比。
- 输出完整的 Markdown 临床诊断报告与运动干预建议。

📂 项目结构

moonbit-gaitlab/
  ├── moon.mod             # 模块配置文件 (hgetty/gaitlab)
  ├── README.md            # 中文主文档
  ├── README.mbt.md        # MoonBit 专有示例说明文档
  ├── LICENSE              # Apache 2.0 许可证
  ├── .github/             # GitHub Actions 自动化 CI 配置
  │   └── workflows/
  │       └── check.yml
  ├── lib/                 # 核心模块类库
  │   ├── math/            # 统计学、3D点几何及三角函数近似
  │   ├── csv/             # RFC 4180 兼容的 CSV 解析器
  │   ├── json/            # JSON 语法分析器及序列化组件
  │   ├── signal/          # 信号去噪滤波、一阶微分和峰值/谷值提取
  │   ├── gait/            # Biomechanics 周期切分、时空指标计算及临床筛查规则
  │   └── report/          # 报告文本格式化及终端 ASCII 柱状图生成
  └── main/                # CLI 应用入口
      ├── main.mbt         # 命令行逻辑及内置 Hemiplegic 模拟数据
      └── moon.pkg         # 编译配置 (is-main: true)

🚀 快速开始

环境依赖

安装 MoonBit 工具链 (建议版本 0.10.3 或更新)

编译与测试

# 格式化检查
moon fmt --check

# 执行静态类型与接口检查
moon check --deny-warn

# 运行全库单元测试
moon test --deny-warn

# 导出公共 API 签名文件
moon info

运行内置演示 Demo

我们内置了一个高保真模拟数据集，模拟一位偏瘫（Hemiplegic）患者（其右腿由于神经损伤导致步长缩短、拖地/ clearance 极低、支撑时间代偿延长）。

直接运行以下命令查看 GaitLab 输出的详细步态生物力学分析报告：

moon run main -- --demo

使用命令行参数

GaitLab 的 CLI 同时也支持直接分析传入的 CSV/JSON 数据流：

# 查看帮助信息
moon run main -- --help

# 分析传入的 JSON 数据
moon run main -- --json-data "{\"name\":\"sample\",\"x\":1.2}"

# 分析传入的 CSV 数据
moon run main -- --csv-data "time,x,y
0.0,0.0,0.0
0.5,0.3,0.12
1.0,0.6,0.0"

🛡️ 许可证说明

本项目采用 Apache License 2.0 开源许可证。所有的设计与算法实现均为 hgetty 原创编写，符合 MoonBit 生态大赛的合规性要求。