Grafix Draw Export

目的

• draw(t) を作る/直す
• python -m grafix export で PNG を複数枚出す
• 人間の選別 → 改良のループを回す

前提

• PNG は内部的に SVG を生成して resvg でラスタライズする（resvg が必要）。
• このリポジトリから実行する場合は PYTHONPATH=src を付ける（pip インストール済みなら不要）。
• 作品制作にあたり、md ファイルでユーザーへの事前確認は不要。

最短の進め方（デフォルト運用）

• ユーザーは モチーフ/雰囲気だけ入力する（毎回ここだけは聞く）。
• それ以外（canvas/t/run-id 等）が未指定なら、まずは以下のデフォルトで候補を出す。
  • canvas: 800 800
  • t: 0 0.25 0.5 0.75 1.0
  • run-id: v1（改良のたびに v2, v3…）
• resvg は質問しない。まず export を試し、失敗したらエラーメッセージに応じて案内する。

ワークフロー

1) 入力をもらう（最小）

• 必須: どんな絵にしたい？（モチーフ/雰囲気、線の密度、対称/非対称、ノイズ有無など一言で OK）
• 任意: 既存の draw(t) を export する？（するなら --callable 相当を指定してもらう: sketch.generated.foo:draw）

以降は、ユーザーの指定が無ければデフォルト値で進めて候補 PNG を出す。

2) draw(t) を作成/更新する

• 基本は sketch/generated/<slug>.py に作る。
• draw はモジュールトップレベル関数にする（import しやすくする）。

最小スケルトン:

from grafix import E, G

def draw(t: float):
    ...

2.1) G（primitives）と E（effects）の使い方（組み込み）

• G.<name>(...) は プリミティブの Geometry ノードを作る（線/多角形/テキスト等）。
• E.<name>(...) は effect のビルダを作る。E.a().b().c()(g) のようにチェーンして最後に (g) で適用する。

例:

from grafix import E, G

def draw(t: float):
    g = G.polygon(n_sides=6, center=(400, 400, 0), scale=300)
    e = E.fill().displace()
    return e(g)

メモ:

• effect によっては複数入力を取るものがある。multi-input effect はチェーンの先頭にしか置けない。

2.2) ユーザー定義 primitive / effect の使い方

ユーザー定義は デコレータで登録する。登録は import 時に行われるため、draw と同じモジュールに書けば python -m grafix export で import された時点で有効になる。

primitive（G.<name>(...) で呼べる）:

from grafix.api import primitive

@primitive
def my_prim(*, size: float = 1.0):
    ...

effect（E.<name>(...) で呼べる）:

from grafix.api import effect

@effect
def my_eff(inputs, *, amount: float = 1.0):
    ...

Notes:

• 組み込み primitive/effect は meta=... 必須だが、ユーザー定義は meta 省略でよい（GUI に出したいなら meta を付ける）。
• meta を付ける場合、対象引数は default 必須で None は使えない。

3) PNG を export する（候補出し）

この repo から実行する例（--out/--out-dir を省略すると、config の paths.output_dir（既定 data/output）配下に、スケッチの相対パスをミラーして保存される）:

単発（デフォルト出力: data/output/png/...）:

PYTHONPATH=src python -m grafix export \
  --callable sketch.generated.foo:draw \
  --t 0 \
  --canvas 800 800 \
  --run-id v1

複数枚（連番で保存。比較 → 選別用。デフォルト出力）:

PYTHONPATH=src python -m grafix export \
  --callable sketch.generated.foo:draw \
  --t 0 0.25 0.5 0.75 1.0 \
  --canvas 800 800 \
  --run-id v1

保存先を明示的に変えたい場合だけ（単発）:

PYTHONPATH=src python -m grafix export \
  --callable sketch.generated.foo:draw \
  --t 0 \
  --canvas 800 800 \
  --out /tmp/foo.png

保存先を明示的に変えたい場合だけ（複数枚 / ディレクトリ指定）:

PYTHONPATH=src python -m grafix export \
  --callable sketch.generated.foo:draw \
  --t 0 0.25 0.5 \
  --canvas 800 800 \
  --out-dir /tmp/foo_v1

Notes:

• --t 複数指定時は _f001 のように連番を付けて保存する。
• PNG と同名の .svg も生成される（PNG 生成の中間生成物）。

設定ファイル（config.yaml）を明示指定して PNG スケール等を変えたい場合:

PYTHONPATH=src python -m grafix export \
  --callable sketch.generated.foo:draw \
  --t 0 \
  --canvas 800 800 \
  --config ./.grafix/config.yaml

4) 選別 → 改良のループ

• ユーザーに「良かった画像」を決めてもらう（ファイル名 or t or インデックス）。
• 改良のたびに --run-id を進める（例: v2, v3）か、--out-dir を変えて上書き衝突を避ける。
• 画像を見ながら具体的な改善案が必要なら、ユーザーに PNG を添付してもらうか、残す画像のパスを指定してもらう。

組み込み（G/E）の一覧を調べる

最短:

• $grafix-api-catalog を併用し、skills/grafix-api-catalog/references/api.md を検索する。

CLI（一覧表示）:

PYTHONPATH=src python -m grafix list
PYTHONPATH=src python -m grafix list primitives
PYTHONPATH=src python -m grafix list effects

実装の場所（読む場所）:

• primitives 実体: src/grafix/core/primitives/
• effects 実体: src/grafix/core/effects/
• 公開ファサード（登録 import をしている）:
  • src/grafix/api/primitives.py
  • src/grafix/api/effects.py

トラブルシュート

• resvg が無い: resvg をインストールして PATH を通す。
• --callable が import できない:
  • repo ルートで実行しているか確認する
  • PYTHONPATH=src が付いているか確認する
  • module:attr が正しいか確認する