キーフレームクリップ

概要

キーフレームで動きを作るタイムライン系ノードです。波形ノードが「数式の動き」 なら、こちらは「このフレームでこの形」を直接指定する作り方。パスや画像の変形を 専用エディタでポーズ登録・記録し、AnimationClip として再生・書き出しできます。

使い方のポイント

• モーションとの使い分け: 周期的・機械的な動き→motion ノード、 「振りかぶって→溜めて→振り下ろす」のような演技→このノード
• 基本の流れ: path か image をつなぐ → エディタでフレームを動かしながら pose mode でキーを打つ → play で確認 → 同名の パス / 画像 出力で下流へ。 出力は「現在フレームの適用結果」なので、後段にフィルタや motion 系を重ねて 最後にアニメーションレンダーへ繋げば全部まとめて再生される。 シートが直接欲しいときは spritesheet 出力でもよい
• クリップの尺・キー位置はフレーム基準。新規クリップの尺と fps は プロジェクトのアニメーション既定(キャンバスバー)に従う
• progress 入力(0〜1)を外部から与えると、クリップの評価時刻をグラフ側で 制御できる(time_source 連携や、進行度による演出分岐)
• value_float 出力は、クリップ内の最初の数値(Scalar)トラックを現在の評価時刻で 評価したただの Float。数値パラメータ 1 個をキーフレームで動かす用途 (Inspector の 🎞️ アニメーションボタン「キーフレーム」フレーバーはこの出力を 対象パラメータへ自動接続する)に使う。キーの範囲外では端のキー値にクランプされ、 補間はトラックの補間設定(ease_in_out と共通のイージング語彙)に従う。 Scalar トラックが無いクリップでは 0.0 を出す
• source ノード自体は書き換えられない(非破壊)。元の形はいつでも無傷

よくある失敗

• キーを打ったのに動かない: キーが1つだけだと補間できない。始点と終点の 最低2キーが必要
• エディタと出力が違って見える: エディタの表示は「source+clip適用後」。 同じ見た目を下流に流すのは パス/画像 出力(現在フレームの適用結果)。 clip/value はアニメデータそのもの、spritesheet は全フレームのシートなので、 どの出力を使っているかを確認する

interactive editor

Keyframe Clip は source 埋め込み型の interactive editor を持ちます。

editor でできること:

• source 切替
  • Path と Image のどちらを今編集するか選べます
• pose mode
  • 現在時刻の形を 1キーの pose として保存します
• record mode
  • drag 軌跡を開始/終了範囲へ記録します
• play / stop / loop
  • editor 内 preview をそのまま再生できます
• key list
  • 保存済み key を一覧で見て、そこへジャンプできます
• タイムラインのキーは複数選択して一括操作できます
  • Ctrl+クリックで追加選択 / Shift+クリックで範囲選択 / Ctrl+A で全選択 / 上の目盛り帯からドラッグで矩形範囲選択
  • 選択したキーはドラッグでまとめて移動(Alt+ドラッグで複製)、Delete でまとめて削除
  • 右クリックメニューまたは Ctrl+C / Ctrl+V でコピー&ペースト (再生ヘッド位置を先頭に、キー同士の間隔を保って貼り付け)
  • , / . で前後のキーへジャンプ、矢印キーで選択キーを1フレーム移動(Shift でスナップ単位)
  • キー一覧パネルでも同じ選択操作に加えて、等間隔化 / 時間反転 / 「先頭→終端」(先頭キーを終端フレームへ複製してループを閉じる)が使えます
  • ショートカットはユーザー設定のキーマップ(キーフレームクリップ)で変更できます
• ❔ 操作ガイド(Ctrl+Alt+K): ソース切替・ツール・キー操作・再生の全ショートカットと マウス操作をエディタ内で一覧でき、その場でキー割り当ての変更もできます。 主なショートカット: ソース切替 1/2/3、キャプチャ P(ポーズ)/R(録画)、 変形パネル D、キー追加 K、再生 Space、ループ L、全体表示 0
• export
  • 尺 D フレームを t=0〜D-1 でサンプルした spritesheet PNG (最終フレームは「先頭に戻る直前」で止まるループ規則)
  • 実キーのフレームだけをまとめた key PNG 一括書き出し
  • 現在フレーム PNG 書き出し

重要:

• source node 自体は書き換えません
• editor 上で見えているのは source + clip 適用後の姿 です
• キーを切り替えると、その key pose がそのまま表示されます
• 画像 source は v1 では移動 / 回転 / 拡大縮小の transform を編集します
  • 回転は外周付近へマウスを持っていくと ↺ が出る zone drag 方式です
• path source は point / handle を直接動かして pose を作ります
• 🌀 変形 ボタン(path source のみ): 現在の pose を「潰し・伸ばし / 膨らみ / 波 / ゆらぎ」で 一括変形し、そのまま現在フレームの pose key へ焼き込めます。 計算は path_deform ノードと同一で、プレビューを見ながら量を調整できます。 適用後も点を個別に微調整できるので、「キー3だけ潰して角を直す」が editor 内で完結します
  • 波・ゆらぎで制御点が足りない時は「細分化して有効化」ボタンが出ます。 押すと、ソースのパスノードと既存の全キーが同じ形のまま一括で細分化され (見た目は変わりません)、以後は波・ゆらぎもプレビュー・適用できます (パス入力が直接ベジェパス/マルチパスノードに繋がっている時のみ)

技術詳細

AnimationClip は P07 の user-facing animation 型です。
内部では explicit な track / keyframe を持ち、必要に応じて RecordedLayer と相互 bridge します。

layer 入力が接続されている場合は:

• layer 入力を base clip へ変換
• clip_data を local clip として重ねる
• 出力では同じ clip を AnimationClip / RecordedLayer の両方で見られます

path / image 入力は editor 用の source でもあり、同時に downstream の ClipApplyPath / ClipApplyImage と組み合わせる前提です。

使用例

Path をキー編集する

1. BezierPath を作る
2. KeyframeClip.path へつなぐ
3. KeyframeClip editor を開く
4. フレーム 0 で point / handle を動かして最初の pose を作る
5. 最終フレームで別 pose を作る
6. KeyframeClip.clip を ClipApplyPath.clip へつなぐ
7. BezierPath.path を ClipApplyPath.path へつなぎ、progress(0〜1)を Float Input か Time Source で動かして再生する

Image をキー編集する

1. PixelCanvas.image などの image source を作る
2. KeyframeClip.image へつなぐ
3. KeyframeClip editor を開く
4. 画像本体をドラッグして移動、角で拡大、外周近くの ↺ zone で回転する
5. KeyframeClip.clip を ClipApplyImage.clip へつなぐ
6. source image を ClipApplyImage.image へつなぎ、progress を動かして再生する

clip editor から書き出す

1. KeyframeClip editor を開く
2. 尺(フレーム数) を決める(初期値はプロジェクト既定のフレーム数)
3. 列数 を必要なら指定する
4. スプライトシートPNG で全フレームを書き出す
5. キー画像一括 で実キーだけを個別 PNG として書き出す

補足:

• Image source の spritesheet は尺 D フレームを t=0〜D-1 でサンプルして並べます
• 列数 = 0 の時は横一列ではなく、自動でほぼ正方形に近い配置を選びます
• 配置順は 右へ (row_major) と 下へ (column_major) を選べます
• node 出力は P07A の SpriteSheet 契約
  • spritesheet は専用型
  • frame_count / fps / columns / rows / frame_width / frame_height / fill_order は helper metadata 出力 を同じ書き出し設定で返します
• columns / rows / frame_width / frame_height / fill_order 出力を使うと、後段でフレーム分割しやすくなります
• Path source の書き出しは editor 上の line preview を透明背景 PNG にしたものです
• 最終見た目で書き出したい場合は ClipApplyPath -> PathStroke -> AnimationRender を使ってください

関連ノード

• clip_apply_path / clip_apply_image — クリップをパス・画像に適用して下流へ流す
• animation_render — 最終見た目でのスプライトシート化
• clip_mixer / clip_loop_fit — クリップの合成・ループ調整
• motion 等の波形 — 数式的な動きで足りる場合

時刻・複数トラック・データ保護

• 時刻入力は progress(0〜1 の正規化進行度)一本です。progress * 尺(フレーム数) を 評価します。未接続ならグラフの評価時刻を正規化進行度として扱います。 旧バージョンの絶対秒 time ピンは廃止され、旧プロジェクトの time 接続は 読込時に progress へ自動で繋ぎ替えられます。
• Time Source の 0〜1 出力は progress へ接続してください。
• クリップの尺・キー位置はフレーム基準(v2)。旧 v1(秒基準)の clip_data は 読込時に旧「1コマ秒」設定から fps を逆算してフレームへ自動変換されます (設定が無い場合は旧既定 10fps で換算)。
• 画像の Transform track が複数ある場合、プレビューと書き出しには全 track を 順に適用します。キャンバス操作、キー追加・移動・削除は選択中 track だけが対象です。
• 尺を短くしても範囲外キーは削除しません。評価時刻は 0〜尺に clamp されます。不要なら editor の「範囲外キーを削除」、比率を保って収めるなら 「全キーを尺へ縮尺」を明示的に実行します。
• 非空の壊れた clip_data は空データへ読み替えません。元文字列を保持して保存を止め、 コピーまたは確認付きリセットを選べるエラー画面を表示します。
• キー間の補間はトラックごとに選べ、イージングの語彙・カーブは ease_in_out ノードと共通です(リニア/イーズイン/…/バウンスアウト/ステップ)。