diff --git a/PHYレイヤー.md b/PHYレイヤー.md index 393d724..c1ffe57 100644 --- a/PHYレイヤー.md +++ b/PHYレイヤー.md @@ -59,9 +59,7 @@ KLE JSONやPCB向けの出力は、階層を畳んで絶対座標に変換した **外部連携での扱い**： -- KLE JSON出力時は、個別のキー配置のみを出力（クラスター情報は含めない） -- 別途クラスター情報JSONとして構造を保存 -- キーIDによる紐づけで関連性を管理 +- クラスター構造はBeyond KLEのデータにのみ存在する。外部形式へは階層を畳んだキー配置だけを出力する ### 何かある？ @@ -93,14 +91,17 @@ const root: (Key | Cluster)[] = [] ## 連携用出力形式 -### 設計方針 +### KLEとの関係 -KLE向けの出力は既存のKLE JSON形式を維持し、クラスター情報は別のJSONファイルとして出力する。 -両者の紐づけは、KLEのlabel部分に埋め込むユニークIDを使用する。 +KLEは、PHYデータを表示できる既存のビュワーとして扱う。 +KLEで編集された時点で、そのデータはBeyond KLEのデータではない。 + +- KLE JSONにはBeyond KLE固有の情報(キーID、クラスター構造など)を含めない。出力は素のKLE JSONで、KLE JSONを読む他ツールにそのまま渡せる +- KLE JSONの取り込みは、手元のPHYデータとの照合で行う。IDや埋め込み情報には頼らない ### KLE JSON出力 -標準的なKLE JSON形式で出力。各キーのlabelにはユニークIDを含める。 +階層を畳んで絶対座標に変換し、標準的なKLE JSON形式で出力する。 ```ts type ConfigObject = { @@ -128,86 +129,24 @@ type ConfigObject = { s?: string } -type KeyLabel = string // ユニークID + 表示用ラベルを含む +type KeyLabel = string // 表示用ラベルのみ。識別情報は含めない const kleData = (ConfigObject | KeyLabel)[][] ``` -### クラスター情報JSON +### KLE JSONの取り込み -キーのクラスター構造を管理する別ファイル。 +既存のPHYデータを畳んだ配置に対して、KLE JSONの各キーを形状(位置・サイズ・回転)とラベルで照合する。 -```ts -interface ClusterInfo { - id: string, // クラスターのユニークID - name?: string, // 表示用クラスター名 - position?: Position, // クラスター自体の位置・回転情報 - keyIds: string[], // 所属するキーのIDリスト - subClusters?: string[] // 子クラスターのIDリスト（ネスト構造用） -} - -interface ClusterData { - version: string, - profiles: Profile[], // プロファイル定義 - keys: { // キーID -> 追加情報のマップ - [keyId: string]: { - originalLabel?: string, // KLEのlabelから抽出した表示用文字列 - matrix?: MatrixPosition, // matrix情報（オプション） - mapping?: KeyMapping // キーマッピング情報（オプション） - } - }, - clusters: ClusterInfo[] // クラスター構造定義 -} -``` - -### 出力例 - -#### keyboard.json (KLE形式) - -```json -[ - ["key-001\nQ", "key-002\nW", "key-003\nE"], - ["key-004\nA", "key-005\nS", "key-006\nD"] -] -``` - -#### keyboard-clusters.json - -```json -{ - "version": "1.0.0", - "keys": { - "key-001": { "originalLabel": "Q", "matrix": [0, 0] }, - "key-002": { "originalLabel": "W", "matrix": [0, 1] }, - "key-003": { "originalLabel": "E", "matrix": [0, 2] }, - "key-004": { "originalLabel": "A", "matrix": [1, 0] }, - "key-005": { "originalLabel": "S", "matrix": [1, 1] }, - "key-006": { "originalLabel": "D", "matrix": [1, 2] } - }, - "clusters": [ - { - "id": "cluster-alpha", - "name": "英字キー", - "keyIds": ["key-001", "key-002", "key-003", "key-004", "key-005", "key-006"] - } - ] -} -``` - -### 分離設計のメリット - -この設計により以下の利点が得られる： - -1. **KLE互換性の維持**：既存のKLE関連ツールとの完全な互換性を保持 -2. **柔軟な拡張性**：クラスター情報を独立して管理・拡張可能 -3. **段階的移行**：既存のKLEユーザーが段階的に拡張機能を利用可能 -4. **ツール間連携**：KLE標準形式での出力により、他のキーボード設計ツールとの相互運用性を確保 -5. **データの軽量化**：KLE出力時に不要な情報を含めず、ファイルサイズを最小化 +- 照合できたキーは元のノードとして扱う。KLE側で配置が変わっていれば、元の親から見た相対座標に戻して反映する +- 照合できないキーは root 直下に新規キーとして置く。クラスターへの割り当てはユーザーが行う +- 構造の復元は保証しない。KLE側での編集が大きいほど、クラスター構造は失われる ## 検討済み・非採用 - キーごとの絶対座標保持 (journal/2026-09-18-phy-coordinate-model.md) - 相対座標と絶対座標の併記 (journal/2026-09-18-phy-coordinate-model.md) - ノードごとの回転中心パラメータ (journal/2026-09-18-phy-coordinate-model.md) +- KLE JSONへの識別・構造情報の埋め込み(labelのID、`_beyondkle` メタデータ、ゴーストキー) (journal/2026-09-18-kle-roundtrip.md) ## 未確認事項 @@ -216,3 +155,9 @@ interface ClusterData { - 位置づけ: 本文が前提にしているものではない。連携用出力形式の設計に関わる未解決の問い - 現状の認識: 階層を畳んでKLEに読み込ませると行のまとまりが崩れる。他レイヤーの情報を使ってでも行ごとにまとめたいが、方法は未検討 - 格上げ条件: 回転を含むPHYデータをKLE JSONに変換してKLE本家に読み込ませ、rotation groupと行配列がどう再構成されるかを確認する + +### P-2 KLE JSON取り込み時の照合基準 + +- 位置づけ: 本文「KLE JSONの取り込み」の具体化に必要な未解決の問い +- 現状の認識: 形状の許容誤差、ラベルの扱い、複数候補がある場合の決め方が未定。KLEが保存時にキーの並び順を変えるかは未確認で、配列順を照合に使えるかも分からない +- 格上げ条件: 照合規則を決めたうえで、KLE本家でキーの移動・追加・削除をしたJSONを取り込み、意図どおりに対応づくことを確認する diff --git a/journal/2026-09-18-kle-roundtrip.md b/journal/2026-09-18-kle-roundtrip.md new file mode 100644 index 0000000..a5e95e6 --- /dev/null +++ b/journal/2026-09-18-kle-roundtrip.md @@ -0,0 +1,48 @@ +# KLE往復: 埋め込みなし + 取り込み時の照合 + +## 結論 + +- KLE JSONにBeyond KLE固有の情報(キーID、クラスター構造)を一切埋め込まない +- KLEは既存のビュワーとして使えればよい。KLEで触った時点でBeyond KLEのデータではない(ユーザーの線引き) +- KLE JSONの取り込みは、手元のPHYデータとの形状+ラベル照合で行う。照合できないキーはroot直下 +- 構造の復元はベストエフォート。保証しない + +## 案の比較 + +| 案 | 出典 | 問題 | +|---|---|---| +| labelにIDを埋め込み、別ファイルのクラスターJSONと紐づけ | PHYレイヤー.md(旧) | VIAのlabelハックと同じ道。IDが長くなりラベルが見づらい | +| `_beyondkle` メタデータ + labels[8] のハイブリッド | kle-compatibility.md | 同上。独自プロパティはKLEが保存時に落とす可能性 | +| ゴーストキーにクラスター情報を格納 | kle-compatibility-analysis.md | 下記。所属情報が残らず、結局labelハックに戻る | +| 埋め込みなし + 照合(採用) | 今回 | KLEで大きく編集されると構造が失われる | +| metadataのnotesにクラスター表 + sm/sb/stにキーID | 今回の検討中に出た | 意味の違うフィールドの流用で、種類としては同じハック | + +## 根拠 + +### 前提の変化 + +PHY座標モデルの決定(相対座標の木が正本)により、KLE JSONは導出物になった。 +問いは「KLE JSONのどこにクラスターを埋めるか」から「KLEを経由して戻ってきたとき何を復元したいか」に変わった。 +ユーザーの回答は「KLEはビュワーとして使えればよい」。これで埋め込み自体が不要になった。 + +### ゴーストキー案の穴 + +- キーの所属は `key.clusterId` という独自プロパティで持たせる設計だった(kle-compatibility-analysis.md の createCluster)。 + KLEのシリアライザは既知のプロパティしか書き出さないはずで(未確認)、保存時に所属が消える。 + 残すには各キーのlabelにIDを入れることになり、labelハックに戻る +- 矩形に含まれるかで所属を判定する方法は、入れ子や回転があると曖昧になる +- ゴーストキー自体も labels[0]="CLUSTER_META"、labels[4]=JSON という形で、汚す対象がダミーキーに変わっただけ +- KLE JSONを読む他ツール(QMK変換、KiCad配置プラグインなど)がゴーストキーを実在するキーとして扱う懸念(未確認)。 + KLE JSONを出力する目的は互換性なので、偽のキーを混ぜるのは本末転倒 + +### KLEを改造するか自作するかとは独立 + +KLEを改造する場合でも、内部データと保存形式は自分で決められるので、ゴーストキーは要らない。 +ゴーストキーが必要になるのは「改造していないKLEを通っても構造が残る」を要件にした場合だけで、その要件は今回捨てた。 + +## 未決のまま残したもの + +- 照合基準の詳細(許容誤差、ラベルの扱い、複数候補の解決)。PHYレイヤー.md の未確認事項 P-2 +- KLEが保存時にキー順を並べ替えるか(未確認)。配列順を照合に使えるかに関わる +- kle-compatibility.md / kle-compatibility-analysis.md の埋め込み案の記述は今回の決定と食い違うが、 + 既存ドキュメントの再編は別タスクのため触っていない