# PHYレイヤー

## 概要

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

## 構造

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

各キーはスイッチ・キャップの情報を統合された状態で持ち、キャップの位置・サイズからスイッチ座標を特定する。  
以下、単に「キー」と呼ぶ場合、キーキャップの位置・サイズを表すオブジェクトをさすこととする。

### プロファイル設定

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

### キーの座標

キーキャップの左上角をローカル原点とする。  
座標単位はU。1Uのサイズは別途指定する。  
回転中心はローカル原点からの相対座標で表す。グローバル  
座標・回転角度は0.25U単位・15度単位でスナップするが正規化しない。

### キーのサイズ

0.25U単位でスナップするが正規化しない。

### グルーピング

複数のキーを「クラスター」としてまとめて運用することができる。  
クラスターのみにフォーカスして編集が可能。  
クラスターごとの回転中心を設定できる。  

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

- クラスターごとの一括編集・移動・回転
- 階層構造による管理（クラスターの入れ子構造）
- 編集時のフォーカス制御

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

- KLE JSON出力時は、個別のキー配置のみを出力（クラスター情報は含めない）
- 別途クラスター情報JSONとして構造を保存
- キーIDによる紐づけで関連性を管理

### 何かある？

## 保存形式

キーごとに絶対座標を持つ。  
全てのキー、またはキー及びクラスターをまとめたクラスターを配列として持つ

```ts
type Position={
    x:number,
    y:number,
    w:number,
    h:number,
    rx:number,
    ry:number,
    ra:number
}
type Key={
    position:Position,
    profile:Profile
}
type Cluster={
    position:Position,
    clusters:(Key[]|Cluster[])
}
const keys:(Key|Cluster)[]=[]
```

## 連携用出力形式

### 設計方針

KLE向けの出力は既存のKLE JSON形式を維持し、クラスター情報は別のJSONファイルとして出力する。
両者の紐づけは、KLEのlabel部分に埋め込むユニークIDを使用する。

### KLE JSON出力

標準的なKLE JSON形式で出力。各キーのlabelにはユニークIDを含める。

```ts
type ConfigObject = {
    x?: number,
    y?: number,
    w?: number,
    h?: number,
    x2?: number,
    y2?: number,
    w2?: number,
    h2?: number,
    rx?: number,
    ry?: number,
    ra?: number,
    l?: boolean,
    n?: boolean,
    d?: boolean,
    c?: string,
    t?: string,
    g?: boolean,
    a?: number,
    f?: number,
    f2?: number,
    p?: string,
    s?: string
}

type KeyLabel = string  // ユニークID + 表示用ラベルを含む
const kleData = (ConfigObject | KeyLabel)[][]
```

### クラスター情報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出力時に不要な情報を含めず、ファイルサイズを最小化