Beyond-KLE/PHYレイヤー.md

# PHYレイヤー

## 概要

PHYレイヤーは、キースイッチやキーキャップ、その他周辺部品の物理的な配置に関する情報を提供する。  
付加的な情報として、matrix情報(ELCレイヤー)や入力キー情報(MAP/IMEレイヤー)を含ませることができるが、必須ではない。

## 構造

### キースイッチ/キーキャップの配置

各キーはスイッチ・キャップの情報を統合された状態で持つ。
スイッチ位置は、キャップの (w, h) 矩形の中心からのオフセットとしてキーごとに持つ(既定値0、単位U、キーのローカル座標系)。
Stepped Caps Lockのようにスイッチがキャップ中心からずれるキーがあり、キャップ形状だけではスイッチ位置が決まらないため。  
以下、単に「キー」と呼ぶ場合、キーキャップの位置・サイズを表すオブジェクトをさすこととする。

### プロファイル設定

1ファイル内に複数のプロファイルを持たせることができる。  
ユニットサイズ(1Uが何mmか、x軸・y軸それぞれ)を規定。  
ビジュアル表現として、内側へのオフセット位置及びオフセット距離(mm or U単位)・R(U単位)を規定。

### 座標と回転

各ノードは、親ノードから見た相対的な配置を持つ。絶対座標は保持しない。
クラスター単位の移動・回転を親ノード1つの書き換えで済ませるため、相対座標を正本とする。

配置は「親の座標系で θ 回転してから (x, y) 平行移動」と定義する。

```txt
p_parent = Translate(x, y) · Rotate(θ) · p_child
```

この定義により、(x, y) は自分のローカル原点が親座標系のどこに来るかを表し、θ は自分の向きを表す。
回転軸は常に自分自身のローカル原点であり、パラメータとしては持たない。
キーもクラスターも同じ変換を持つため、キーごとに向きが異なる配置のためにクラスターを作る必要はない。

ローカル原点はキーキャップの左上角とする。座標単位はU。1Uのサイズはプロファイルで指定する。

座標・回転角度は、手作業での入力時に0.25U単位・15度単位でスナップするが正規化しない。
グリッドは操作開始時の値を基準とする相対グリッドとし、ローカル原点を基準とした絶対グリッドにはしない。
計算で得た値にはスナップを適用しない。組み替えで生じた非グリッド値を丸めると絶対配置が動くため。

KLE JSONやPCB向けの出力は、階層を畳んで絶対座標に変換した導出物として生成する。

### キーのサイズ

0.25U単位でスナップするが正規化しない。  
サイズはローカルの値であり、親の変換を受けない。

ISO Enterのように長方形でないキーは、サイズに2つ目の矩形(x2, y2, w2, h2)を加えて表す。
2つ目の矩形の位置は、キーのローカル原点からの相対値とする。

### 部品グループとスイッチの向き

PHYはスイッチの品種(MX-3pin、Choc V1 など)もソケット方式も持たない。
どのフットプリントを使うかはPCB設計ツール側の選択であり、Beyond KLEはその手前までを扱う。

キーが持つのは次の2つ。

- 部品グループ(partGroup): 同じ部品を使うキーをまとめるラベル。省略可
- スイッチの向き(orientation): 0/90/180/270の4方向。キーのローカル座標系に対する値で、既定は0。90度と270度は別物として扱う

部品グループの中身はBeyond KLEが解釈しない。穴・パッドの配置も、低背かどうかも持たない。
グループごとの実フットプリントはPCB出力時に割り当てる。
不均一な構成で「どのキーが同じ部品か」という設計者の意図だけを保存するために持つ。

スイッチのブランドも持たない。同じボードに対して利用者が好きなスイッチを選べるため、ボード設計の情報ではない。

キーごとの検出方式(接点マトリクス / アナログ / 光学)はELCが持ち、PHYは持たない。
ホールセンサのように端子数も配線トポロジも接点スイッチと異なるものがあり、これは電気的な性質のため。

### per-key LED

キーはper-key LEDの有無をbooleanで持つ。位置も向きも持たない。
per-key LEDの位置はスイッチのフットプリント内で決まり、向きはキーのorientationに従うため、
設計者が決められるのは載せるか載せないかだけ。

載せるキーと載せないキーが混在する構成を表せるよう、キーごとに持つ。キーごとの固定値であり、
条件によって有無が変わる構成は扱わない。

### 部品ノード

LED・OLED・ロータリーエンコーダ・ネジ穴のように、設計者が位置を決めるキー以外の部品は、
キーと同じ変換を持つノードとして木に置く。per-key LED以外のLEDもここに入る。

部品ノードが持つのは変換と部品グループだけ。品種・端子配置・フットプリント・表裏は持たない。
どの部品を実際に載せるかはPCB設計ツール側の選択であり、キーと同じ原則が適用される。

スイッチの向き(orientation)に当たる軸は持たない。キーが2軸を持つのはキーキャップとスイッチが
独立に回せるためで、部品ノードにその二重構造はない。向きは変換の回転角度で表す。

部品グループ名のうち `@` で始まるものは予約で、エディタ上の描画を変えるために使う。
フットプリントの選択には使わない。予約名以外および省略時は既定の形で描く。
ユーザーが付ける名前は `@` で始めない限り予約と衝突しない。

部品ノードはクラスターの子になれる。クラスターを動かせば配下の部品も追随する。

LEDの配線はPHYが持たない。デイジーチェーンの順序はELC、RGB効果が使う論理インデックスはIDXが持つ [推測:P-11]。

### デカールとゴースト

デカールとゴーストはキーとして扱い、フラグで区別する。KLEの d, g に対応する。

### ラベル

キーはラベルを参考情報として持つ。KLE JSONの取り込みでは照合に使う。

### グルーピング

複数のキーを「クラスター」としてまとめて運用することができる。  
クラスターのみにフォーカスして編集が可能。  
クラスターの原点が、配下のノードの回転中心になる。

**内部処理での利用**：

- クラスターごとの一括編集・移動・回転
- 階層構造による管理（クラスターの入れ子構造）
- 編集時のフォーカス制御
- 回転中心を保存したい場合はクラスターにする（ノード自身は回転中心を持たないため）

**外部連携での扱い**：

- クラスター構造はBeyond KLEのデータにのみ存在する。外部形式へは階層を畳んだキー配置だけを出力する

### クラスターの組み替え

クラスター構造は、配置を作ったあとから組み替える。KLE JSONから取り込んだ平坦なキー配置に
クラスターを与える経路がこれしかないため、エディタの基本操作として持つ。
(エディタの操作仕様。将来ツール側のドキュメントへ移す)

操作は次の2つの演算に還元される。どちらも対象の絶対配置を変えない。

- reparent: 親を変える。新しい親の変換を M_C、元の変換を M_i として `M_i' = M_C⁻¹ · M_i`
- reframe: 自分の変換を変え、配下を逆補正する。`M_i' = M_C'⁻¹ · M_C · M_i`

| 操作 | 内部 |
| --- | --- |
| 選択をクラスター化 / 既存クラスターへの出し入れ / クラスター解除 | reparent |
| クラスターの原点移動・基準角度の変更 | reframe |
| クラスターの移動・回転(配下が追随する) | 自分の変換の書き換え |

Transform は回転と平行移動だけを持つ剛体変換であり、合成と逆変換について閉じている。
組み替えの結果は必ず Transform で表せる。サイズ・switchOffset・orientation はローカル値なので影響を受けない。

- 組み替えの対象は同一の親を持つノードに限る。複数の親にまたがる選択は組み替えできない
- クラスター化したときの初期値は、原点を選択の境界矩形の左上、基準角度を0とする。
  ただし選択したノード全部が同じ回転角度を持つ場合はその角度を基準角度に採り、境界矩形もその角度の座標系で取る
- 組み替えで生じた非グリッド値はそのまま保持する。クラスターを解除して親に戻ったノードも同じ

## 保存形式

各ノードは親から見た変換を持つ。キー・クラスター・部品ノードを混在させた木構造として保持する。
各ノードはIDを持つ。木の中のノードを一意に指すために持ち、キーのIDは他レイヤーからの参照にも使う。

`phase1-json-schema.md` のPHYスキーマは、この節の Key 型(x2〜h2, decal, ghost, labels, switchOffset, partGroup, orientation, perKeyLED)と Component 型にまだ追従していない。

```ts
type Transform = {
    x: number,        // 親座標系での位置
    y: number,
    rotation: number  // 親座標系での回転角度（度）
}
type Size = {
    w: number,        // ローカル値。親の変換を受けない
    h: number,
    x2?: number,      // 長方形でないキーの2つ目の矩形。ローカル原点からの相対値
    y2?: number,
    w2?: number,
    h2?: number
}
type Key = {
    id: string,
    transform: Transform,
    size: Size,
    profile: Profile,
    decal?: boolean,
    ghost?: boolean,
    labels?: string[], // 参考情報
    switchOffset?: { x: number, y: number }, // (w, h) 矩形の中心から。省略時は0
    partGroup?: string, // 同じ部品を使うキーをまとめるラベル。中身は解釈しない
    orientation?: 0 | 90 | 180 | 270, // スイッチの向き。キーのローカル座標系。省略時は0
    perKeyLED?: boolean // per-key LEDの有無。省略時はfalse
}
type Component = {
    id: string,
    transform: Transform,
    partGroup?: string // `@` 始まりは描画用の予約名
}
type Cluster = {
    id: string,
    transform: Transform,
    children: (Key | Cluster | Component)[]
}
const root: (Key | Cluster | Component)[] = []
```

## 連携用出力形式

### KLEとの関係

KLEは、PHYデータを表示できる既存のビュワーとして扱う。
KLEで編集された時点で、そのデータはBeyond KLEのデータではない。

- KLE JSONにはBeyond KLE固有の情報(キーID、クラスター構造など)を含めない。出力は素のKLE JSONで、KLE JSONを読む他ツールにそのまま渡せる
- KLE JSONの取り込みは、手元のPHYデータとの照合で行う。IDや埋め込み情報には頼らない
- 過去のKLE JSONは、PHYデータがなくても読み込めなければならない。変換を伴ってよい

### KLE JSON出力

階層を畳んで絶対座標に変換し、標準的なKLE JSON形式で出力する。

```ts
type ConfigObject = {
    x?: number,
    y?: number,
    w?: number,
    h?: number,
    x2?: number,
    y2?: number,
    w2?: number,
    h2?: number,
    r?: number,     // 回転角度
    rx?: number,    // 回転中心
    ry?: number,
    l?: boolean,
    n?: boolean,
    d?: boolean,
    c?: string,
    t?: string,
    g?: boolean,
    a?: number,
    f?: number,
    f2?: number,
    fa?: number[],
    p?: string,
    sm?: string,
    sb?: string,
    st?: string
}

type KeyLabel = string  // 表示用ラベルのみ。識別情報は含めない
const kleData = (ConfigObject | KeyLabel)[][]
```

- 回転角度は正規化せずそのまま出力する。KLEのデータは任意の角度を受け付け、15度刻みはKLEのUI上の操作単位にすぎない
- rx, ry はPHYに持たないので、出力時に選ぶ
- ユニットサイズ(mm)、ビジュアルオフセット、クラスター構造、部品ノード、per-key LEDはKLE JSONに出力されない
- 部品グループ・スイッチの向きはKLE JSONに出力しない。sm, sb, st には取り込み時に保持した値をそのまま書き戻す
- KLEの `p` はキーキャップのプロファイル名(SA、DCSなど)であり、PHYのプロファイルとは対応させない

### KLE JSONの取り込み

既存のPHYデータを畳んだ配置に対して、KLE JSONの各キーを形状(位置・サイズ・回転)とラベルで照合する。

- 照合できたキーは元のノードとして扱う。KLE側で配置が変わっていれば、元の親から見た相対座標に戻して反映する
- 照合できないキーは root 直下に新規キーとして置く。クラスターへの割り当てはユーザーが行う
- 構造の復元は保証しない。KLE側での編集が大きいほど、クラスター構造は失われる
- 配列の順番は照合に使わない。KLEは保存時にキーを「角度 → rx → ry → y → x」の順に並べ替えるため、順番は形状から決まる以上の情報を持たない

KLEの rx, ry, r はキーの絶対配置 (x, y, rotation) に変換して取り込む。元の rx, ry は保持しない。

見た目の属性(c, t, p, a, f, f2, fa, l, n)は、KLE JSONへ書き戻せるように保持する。どの層で持つかは決まっていない。

KLEの sm, sb, st(ファイル単位では switchMount, switchBrand, switchType)も同様に、不透明なまま保持して書き戻す。
Beyond KLEはスイッチの品種を持たないため、対応づける先がない。

## 検討済み・非採用

- スイッチのブランドをPHYで持つ (journal/2026-09-20-switch-terminal.md)
- スイッチの品種・ソケット方式をPHYで持つ (journal/2026-09-20-switch-terminal-reversal.md)
- LED専用ノード (journal/2026-09-20-led-node.md)
- per-key LEDに座標を持たせる (journal/2026-09-20-led-node.md)
- KLE取り込み時のクラスター自動推定 (journal/2026-09-20-cluster-manual-grouping.md)

## 未確認事項

### P-1 KLE JSONへ書き出した配置が行のまとまりを保てるか

- 位置づけ: 本文が前提にしているものではない。連携用出力形式の設計に関わる未解決の問い
- 現状の認識: 階層を畳んでKLEに読み込ませると行のまとまりが崩れる。他レイヤーの情報を使ってでも行ごとにまとめたいが、方法は未検討
- 手がかり: KLEは r, rx, ry が同じで y が等しいキーを1行にまとめる。同じ絶対角度を持つキーに共通の rx, ry(例えばクラスターの原点)を選べば、行にまとめられる見込み
- 格上げ条件: 回転を含むPHYデータをKLE JSONに変換してKLE本家に読み込ませ、rotation groupと行配列がどう再構成されるかを確認する

### P-2 KLE JSON取り込み時の照合基準

- 位置づけ: 本文「KLE JSONの取り込み」の具体化に必要な未解決の問い
- 現状の認識: 形状の許容誤差、ラベルの扱い、複数候補がある場合の決め方が未定
- 格上げ条件: 照合規則を決めたうえで、KLE本家でキーの移動・追加・削除をしたJSONを取り込み、意図どおりに対応づくことを確認する

### P-6 キーキャップの見た目情報を持つ層

- 位置づけ: 本文「見た目の属性は保持する。どの層で持つかは決まっていない」の未解決部分
- 現状の認識: c, t, p, a, f系に加え、l, n もキーキャップの見た目属性であり、PHYとは別の層が要りそう。退避だけして書き戻す sm, sb, st も同じ置き場の問題を持つ。そもそもキーキャップは設計時に決める必要が薄く、カスタムキーボードの文脈に属するため、Beyond KLEの扱う範囲かどうかも未定。ファイル単位の backcolor, radii, background, css も同じ問いに含まれる
- 格上げ条件: キーキャップの情報をBeyond KLEの範囲に含めるかをユーザーが決め、保持する層を決める

### P-8 ラベルをMAPに適用するか

- 位置づけ: 未解決の問い。本文ではラベルを参考情報として持つことだけを決めている
- 現状の認識: どのラベルがMAPに適用できるかは、おそらく機械的には判断できない。自動で適用してユーザーが不要なものを落とす方式も考えられる
- 格上げ条件: 適用するか、する場合は自動適用とユーザーによる取捨の流れをユーザーが決める

### P-11 LEDのチェーン順序をELCが持つか

- 位置づけ: 本文「部品ノード」が前提にしている
- 現状の認識: 電気的な接続なのでELC、という切り分けで進めている。ただしデイジーチェーンの順序が接点マトリクスと同じ層に収まるかに確信がない。引っかかりを言語化できていない
- 格上げ条件: ELCの構造を具体化し、チェーン順序がその中に無理なく収まるか、別の持ち方が要るかを確認する

### P-12 部品の表裏を描画でどう扱うか

- 位置づけ: 本文「部品ノードは表裏を持たない」の残余
- 現状の認識: どちらの面に載るかはPCB設計ツールが決める情報なのでPHYには持たない。ただしエディタ上で裏面の部品を描き分けたくなる可能性があり、`@` 始まりの予約グループ名だけで表現できるかは未検証
- 格上げ条件: 予約グループ名による描画を実装し、表裏の描き分けが必要になるか、必要なら予約名で足りるかを確認する

### P-13 reframeと通常の移動・回転をエディタ上でどう区別するか

- 位置づけ: 本文「クラスターの組み替え」の残余。データモデル側は決まっており、操作系だけが未定
- 現状の認識: クラスターへのフォーカス状態に紐づけ(中に入っている間は配下の絶対配置が変わらない)、
  そのうえで原点ハンドルと通常の移動・回転ハンドルを分ける案が有力。専用モードを設ける案もある
- 格上げ条件: 操作系をユーザーが決める

### P-14 クラスター原点の吸着先

- 位置づけ: 未解決の問い。数値入力以外に、原点をどこへ吸着させるか
- 現状の認識: キーのローカル原点(左上角)・キー中心・境界矩形の角と中心が候補。相対グリッドとは別の機構になる
- 格上げ条件: 原点移動を実装し、吸着なしで足りるか、足りない場合どの候補が要るかを確認する