グリフ改善

viz/ ビジュアライゼーションレイヤーの既存ピクトグラムグリフを改善する — 現在のレンダリングを監査し、ビジュアルの問題を診断し、的を絞った修正を適用し、再レンダリングし、ビフォー/アフターを比較する。スキル、エージェント、チームのグリフに対応。

使用する場面

• グリフが小さいサイズでレンダリングが不良な場合（ディテールが失われる、形状が統合される）
• グリフのビジュアルメタファーが不明確、またはそれが表すエンティティと一致しない場合
• グリフにプロポーションの問題がある場合（大きすぎる、小さすぎる、中心がずれている）
• ネオングロー効果がグリフを圧倒するか、物足りない場合
• あるパレットでは良く見えるが、他のパレットでは不良な場合
• 新しいパレットの追加やレンダリングパイプラインの変更後の一括改善

入力

• 必須: エンティティタイプ — skill、agent、または team
• 必須: 改善するグリフのエンティティID（例: commit-changes、mystic、tending）
• 必須: 対処する具体的な問題（可読性、プロポーション、グロー、パレット互換性）
• 任意: 目標とする品質レベルを示すリファレンスグリフ
• 任意: 最適化対象のパレット（デフォルト: すべてのパレット）

手順

ステップ 1: 監査 — 現状の評価

現在のグリフを調べ、具体的な問題を特定する。

1. エンティティタイプに基づいてグリフ関数を見つける:
   • スキル: viz/R/primitives*.R（19個のドメインごとのファイル）、viz/R/glyphs.R でマッピング
   • エージェント: viz/R/agent_primitives.R、viz/R/agent_glyphs.R でマッピング
   • チーム: viz/R/team_primitives.R、viz/R/team_glyphs.R でマッピング
2. グリフ関数を読み、構造を理解する:
   • レイヤー数は?
   • どのプリミティブを呼び出しているか?
   • スケールファクターと位置決めは?
3. レンダリング出力を確認する:
   • スキル: viz/public/icons/cyberpunk/<domain>/<skillId>.webp
   • エージェント: viz/public/icons/cyberpunk/agents/<agentId>.webp
   • チーム: viz/public/icons/cyberpunk/teams/<teamId>.webp
   • 可能であれば、クロスパレットレンダリングのために2〜3個の他のパレットも確認する
   • アイコンサイズ（グラフ内で約48px）とパネルサイズ（詳細パネルで約160px）の両方で確認する
4. 品質軸 でグリフを評価する:

Glyph Quality Dimensions:
+----------------+------+-----------------------------------------------+
| Dimension      | 1-5  | Assessment Criteria                           |
+----------------+------+-----------------------------------------------+
| Readability    |      | Recognizable at 48px? Clear at 160px?         |
| Proportions    |      | Well-centered? Good use of the 100x100 canvas?|
| Metaphor       |      | Does the shape clearly represent the entity?   |
| Glow balance   |      | Glow enhances without overwhelming?            |
| Palette compat |      | Looks good across cyberpunk + viridis palettes?|
| Complexity     |      | Appropriate layer count (not too busy/sparse)? |
+----------------+------+-----------------------------------------------+

5. 最低スコアの1〜2軸を特定する — これが改善ターゲットとなる

期待される結果: グリフの何が問題なのか、どの軸を改善すべきかの明確な診断。監査は具体的であるべき: 「見た目が悪い」ではなく「プロポーション: グリフがキャンバスの40%しか使用していない」。

失敗時の対応: グリフ関数が見つからない場合、またはエンティティが *_glyphs.R マッピングにない場合、グリフがまだ作成されていない可能性がある — 代わりに create-glyph を使用する。

ステップ 2: 診断 — 根本原因分析

特定された問題が存在する理由を判断する。

1. 可読性 の問題の場合:
   • 小さいサイズで統合される細かいディテールが多すぎないか?
   • グリフ要素間のコントラストが不十分ではないか?
   • 線が細すぎないか（s=1.0で size < 1.5）?
   • 要素が近すぎないか?
2. プロポーション の問題の場合:
   • スケールファクター s が小さすぎる、または大きすぎないか?
   • 中心が (50, 50) からずれていないか?
   • 要素が安全領域（10〜90の範囲）を超えていないか?
3. グロー の問題の場合:
   • グリフのストローク幅は ggfx::with_outer_glow() と相互作用する:
     • 細い線: グローがぼやける
     • 太い塗り: グローが過度のブルームを追加する
   • 複数の重なる要素: 複合グローがホットスポットを生成する
4. パレット互換性 の問題の場合:
   • グリフが col/bright パラメータの代わりにハードコードされた色を使用していないか?
   • 低コントラストパレット（cividis、mako）でグリフが見えなくなっていないか?
   • グリフが一部のパレットでは提供されない色のバリエーションに依存していないか?
5. 各問題の具体的な根本原因を文書化する

期待される結果: コード変更に直接つながる根本原因。「グリフが小さすぎる」→「スケールファクターが0.6だが0.8であるべき」。「グローが圧倒する」→「3つの重なる塗りポリゴンがそれぞれグローを生成している」。

失敗時の対応: コード調査から根本原因が明らかでない場合は、異なるパラメータでグリフを分離してレンダリングし、問題を切り分ける。render_glyph() で単一グリフをテストする。

ステップ 3: 修正 — 的を絞った修正の適用

診断された問題に対処するためにグリフ関数を編集する。

1. グリフ関数を含むファイルを開く
2. 診断に固有の修正を適用する:
   • スケール/プロポーション: s の乗数または要素のオフセットを調整
   • 可読性: 複雑な要素を簡略化し、ストローク幅を増やし、間隔を追加
   • グローバランス: 重なる塗り領域を減らし、塗りがブルームを生成する場所ではアウトラインを使用
   • パレット互換性: すべての色が col/bright パラメータから派生するようにし、深度のためにアルファを追加
3. グリフ関数の契約 に従う:

   glyph_name <- function(cx, cy, s, col, bright) {
     # cx, cy = center (50, 50)
     # s = scale (1.0 = ~70% of canvas)
     # col = domain color, bright = brightened variant
     # Returns: list() of ggplot2 layers
   }
   

4. 関数シグネチャを保持する — パラメータを変更しない
5. 修正は最小限に留める: 診断された問題を修正し、グリフ全体を再設計しない

期待される結果: ステップ1〜2で特定された具体的な問題に対処する修正済みのグリフ関数。変更は的を絞った最小限のもの — 改善であって再設計ではない。

失敗時の対応: 修正が他の軸を悪化させる場合（例: プロポーションの修正が可読性を壊す）、変更を元に戻し、別のアプローチを試す。グリフの完全な再設計が必要な場合は、代わりに create-glyph を使用する。

ステップ 4: 再レンダリング — 更新されたアイコンの生成

修正されたグリフをレンダリングし、修正を検証する。

1. エンティティタイプに基づいて再レンダリングする:

   スキルの場合:

   cd /mnt/d/dev/p/agent-almanac/viz
   Rscript build-icons.R --only <domain> --no-cache
   

   エージェントの場合:

   cd /mnt/d/dev/p/agent-almanac/viz
   Rscript build-agent-icons.R --only <agent-id> --no-cache
   

   チームの場合:

   cd /mnt/d/dev/p/agent-almanac/viz
   Rscript build-team-icons.R --only <team-id> --no-cache
   

2. 各パレットの想定パスに出力ファイルが存在することを確認する

3. ファイルサイズを確認する — アイコンは2〜15 KB（WebP）であるべき:

   • 2 KB未満: グリフが単純すぎるか、レンダリングが失敗した可能性
   • 15 KB超: グリフが複雑すぎる可能性（レイヤーが多すぎる）

期待される結果: すべてのパレットに対して新しいアイコンファイルが生成される。ファイルサイズが想定範囲内。

失敗時の対応: ビルドスクリプトがエラーになる場合は、Rコンソール出力で具体的なエラーを確認する。よくある原因: グリフ関数の閉じ括弧の欠落、未定義のプリミティブの参照、関数が非リストを返す。レンダリングは成功するが出力が空白の場合、グリフのレイヤーがキャンバス範囲外にある可能性がある。

ステップ 5: 比較 — ビフォー/アフターの検証

改善がターゲット軸を向上させたことを検証する。

1. 旧レンダリングと新レンダリングを比較する:
   • cyberpunkパレットバージョンをアイコン（48px）とパネル（160px）の両サイズで確認
   • 少なくとも2つの他のパレットも確認（turboのような明るいもの、makoのような暗いもの）
2. ステップ1の品質軸を再評価する:
   • ターゲット軸は少なくとも1ポイント改善されるべき
   • 非ターゲット軸は低下すべきではない
3. グリフがフォースグラフで使用されている場合は、そこでテストする:
   • HTTPサーバーを起動: viz/ から python3 -m http.server 8080
   • グラフを読み込み、エンティティノードを見つける
   • デフォルトズームとズームイン時にアイコンが正しくレンダリングされることを確認
4. 行った変更と達成された改善を文書化する

期待される結果: ターゲット軸での測定可能な改善と、他の軸でのリグレッションがないこと。グリフが両サイズおよびパレット間でより良く見える。

失敗時の対応: 改善がわずかであるか、リグレッションが発生する場合は、変更を元に戻して診断を再検討する。元のグリフの限界がメタファーに固有のものであり、実装ではない場合もある — その場合はメタファー自体を変更する必要がある（create-glyph にエスカレーション）。

検証チェックリスト

• 現在のグリフが具体的な問題診断で監査されている
• 各問題の根本原因が特定されている
• 修正が診断された問題に的を絞っている（過剰な編集をしていない）
• グリフ関数の契約が保持されている（シグネチャが変更されていない）
• すべてのパレットに対してアイコンが再レンダリングされている
• ビフォー/アフター比較がターゲット軸での改善を示している
• 非ターゲット軸でのリグレッションがない
• ファイルサイズが想定範囲内（2〜15 KB WebP）
• グリフがフォースグラフコンテキストで正しくレンダリングされる（該当する場合）

よくある落とし穴

• 過剰な改善: 1つの問題を修正してから他のすべてを微調整すること。診断された問題に固執すること
• 契約の破棄: 関数シグネチャを変更するとレンダリングパイプラインが壊れる。5パラメータの契約は不変
• パレット固有の最適化: cyberpunkでは完璧だがviridisでは不良なグリフを作ること。常に3つ以上のパレットを確認
• 小サイズレンダリングの無視: 160pxでは美しいが48pxではブロブになるアイコンは改善失敗
• 再レンダリングの忘れ: 関数を編集しても、ビルドコマンドを実行しないと変更が反映されない
• 間違ったビルドコマンド: スキルは build-icons.R、エージェントは build-agent-icons.R、チームは build-team-icons.R を使用

関連スキル

• create-glyph — ゼロから新しいグリフを作成する（改善では不十分な場合に使用）
• audit-icon-pipeline — パイプライン全体で改善が必要なグリフを検出する
• render-icon-pipeline — 改善後にフルレンダリングパイプラインを実行する
• ornament-style-mono — グリフ構成に適用されるビジュアルデザイン原則
• chrysopoeia — グリフ最適化に類似した価値抽出の方法論（金を増幅し、不純物を除去）