# クォータニオン・スケール修正 検証レポート

対象: ORPHE-INSOLE.js v1.2.1

## 結論と根拠

- 本PRでは SENSOR_VALUES header 50 / 56 の quaternion を signed Q14（`1.0 = 16384`）としてデコードする。
- acc / gyro は従来どおり signed Q15（`1.0 = 32768`）であり、今回の変更対象ではない。
- Euler 角は quaternion を単位ノルムへ正規化してから計算する。
- 社内のBLEペイロード表では header 50 のバイト配置とFW世代の対応は確認できたが、Q14/Q15の除数は明記されていなかった。Q14判断は、NEC実測値と同系統の ORPHE-CORE.js における既修正実装の一致に基づく。

依頼時に共有されたNEC CSV解析結果（87,316サンプル、左右2台、約443秒）では、全サンプルの quaternion ノルムが約0.500（分位点0.49994〜0.50000）だった。旧SDKの `/32768` デコード値と一致し、行ごとに正規化すると yaw の約±20°の圧縮が解消して約±180°の範囲が復元した。

> マージ前ゲート: FW担当者に `1.0 = 16384` を明示確認し、FWバージョンによるスケール差がないことを確認する。現行の社内BLEペイロード表には除数の記載がないため、この確認が終わるまで本PRはドラフトのままとする。

## 自動テスト結果

`tests/insole-parser.test.js` の合成パケットで次を固定する。

| 項目 | 合成値 | 期待値 |
|---|---:|---:|
| header 56（mode 4）quat | w=z=11585, x=y=0 | norm=0.999979500（許容差1e-4） |
| header 50（mode 1）quat | w=16384, x=y=z=0 | norm=1.0 |
| Euler 防御 | 意図的に非単位のquat | `toEuler()` 入力 norm=1.0 |
| mode 55（mode 3） | acc/gyro/pressのみ | quatなし、従来挙動を維持 |
| acc / gyro | 既知int16値 | `/32768` のまま、換算値も不変 |

## 実機テスト数値レポート

実機測定は [`examples/quaternion-validation/`](../examples/quaternion-validation/) を使う。左右をBLE接続すると10秒スモークチェックが自動開始し、静置・回転・歩行・200Hz回帰の結果をJSON / Markdownで保存できる。長時間の生CSVはブラウザメモリへ保持せず、選択ファイルへ逐次追記する。

この文書を複製せず、測定後に以下の空欄へ実測値を追記する。角度は yaw を±180°で折り返さず連続化（unwrap）してから差分・回帰を計算する。

### 1. 左右1時間静置（mode 4 / 100Hz）

| 指標 | 左 | 右 |
|---|---:|---:|
| 有効サンプル数 | 未測定 | 未測定 |
| quat norm 平均 | 未測定 | 未測定 |
| quat norm 標準偏差 | 未測定 | 未測定 |
| quat norm 最小〜最大 | 未測定 | 未測定 |
| yaw 最小〜最大 [deg] | 未測定 | 未測定 |
| yaw 線形ドリフト [deg/min] | 未測定 | 未測定 |
| ±20°付近への張り付き | 未測定 | 未測定 |

合格目安: quaternion norm が量子化誤差の範囲で約1、旧SDK特有の約0.5が再現しないこと。yawドリフト自体は6軸IMUの原理上残るため、ゼロを合格条件にしない。

### 2. 既知角度回転

| デバイス | 実角度 [deg] | yaw変化 [deg] | 誤差 [deg] | 絶対誤差 [%] |
|---|---:|---:|---:|---:|
| 左 | 90 | 未測定 | 未測定 | 未測定 |
| 左 | 180 | 未測定 | 未測定 | 未測定 |
| 左 | 360 | 未測定 | 未測定 | 未測定 |
| 右 | 90 | 未測定 | 未測定 | 未測定 |
| 右 | 180 | 未測定 | 未測定 | 未測定 |
| 右 | 360 | 未測定 | 未測定 | 未測定 |

### 3. 周回歩行

| デバイス | 実周回数×360° | quat yaw累積 [deg] | gyro_z積分 [deg] | quat誤差 [deg] | gyro誤差 [deg] |
|---|---:|---:|---:|---:|---:|
| 左 | 未測定 | 未測定 | 未測定 | 未測定 | 未測定 |
| 右 | 未測定 | 未測定 | 未測定 | 未測定 | 未測定 |

### 4. 回帰確認

| 項目 | 結果 | 観測値 |
|---|---|---|
| mode 3（200Hz、quatなし）の acc/gyro/press | 未測定 | レート・欠損率を記録 |
| showcase CSVの列・行数・左右device列 | 未測定 | ファイル名・行数を記録 |
| 修正版 mode 4 の quat/euler | 未測定 | norm統計・yaw範囲を記録 |

## 既存CSVの救済手順（NEC共有用）

旧SDKで保存された quaternion は4成分が同じ比率で小さくなっているため、データは廃棄不要です。各行の `quat_w, quat_x, quat_y, quat_z` をその行のノルムで割り、長さ1へ正規化してください。ノルムが約0.5なら4成分を一律2倍することと同じです。その後、`euler_pitch, euler_roll, euler_yaw` は補正後の quaternion から再計算してください。Euler列そのものを2倍してはいけません。ノルム0または非有限値の行は無効として除外してください。
