概要
アニメーション画像ウィジェットは、画面に動きを加えるいちばん簡単な方法です。回転するローダー、跳ねるアイコン、まばたきする目などに使えます。このガイドでは、PicoPixel で LVGL アニメーション画像ウィジェットがどう動くのか、追加方法、すべてのフレームを同じサイズにする理由、速度とループの制御方法、そしてインターフェース実行中に開始・停止する方法を説明します。
アニメーション画像ウィジェットとは？
アニメーション画像は、静止画像の列を順番に再生します。パラパラ漫画のようなものです。それぞれの画像は フレーム で、素早く切り替えることで動いているように見えます。フレーム一式を渡し、再生速度とループするかどうかを指定すれば、あとはウィジェットが処理します。
単一の繰り返しアニメーションに最適です。ローディングスピナー、脈打つハート、手を振るアイコンなどです。1 つのウィジェット、1 つのシーケンス、ループ再生という形です。
内部では LVGL の lv_animimg ウィジェットを使っています。プロジェクトを書き出すと、PicoPixel が LVGL コード（lv_animimg_create、lv_animimg_set_src、lv_animimg_set_duration など）を生成します。自分で触る必要はありません。対象は LVGL 8.x です。
アニメーション画像とスプライトの使い分け
この 2 つのウィジェットは似ていますが、解決する問題が違います。
- アニメーション画像 は、ループする 1 つ のアニメーションです。スピナーのように、グラフィックがいつも 1 つの動きしかしない場合に使います。
- スプライト は、1 つのウィジェットに 複数 のアニメーションを持ち、それらを切り替えられます（Idle、Running、Happy など）。グラフィックに複数のモードが必要な場合に使います。
実際には、スプライトはアニメーション画像を組み合わせて作られており、各モードは内部では個別のアニメーション画像として扱われます。切り替えたい 2 つ目のアニメーションが欲しくなったら、スプライトを使う合図です。
アニメーション画像を追加してフレームをアップロードする
- 画面に Animated Image ウィジェットを追加します。
- プロパティで Image Set 行を見つけ、Add Image Set をクリックします。
- NEW タブでアップロード領域（"Click to upload frames"）をクリックし、画像を選択します。複数選択できます。形式は PNG と JPEG（
.png、.jpeg、.jpg）です。 - Continue をクリックして、フレームをウィジェットに紐づけます。Image Set 行にはフレーム数（例："8 frames"）が表示されます。
以前使ったフレームセットは、再アップロードせず Assets タブから選ぶこともできます。
フレームはファイル名のアルファベット順に並びます。正しい順序で再生するには、frame_01.png、frame_02.png、frame_03.png のように先頭ゼロ付きで連番にしてください。frame_2.png は frame_10.png の 後 に並ぶため、アニメーションが崩れます。
アニメーション画像には最低 2 フレームが必要で、最大 32 フレームまで追加できます。それ以上の動きが必要な場合は、動きの要点が伝わるフレームに絞ってください。すべてのフレームはデバイスに保存されます。
すべてのフレームを同じサイズにする理由
覚えておくべきルールは 1 つです。すべてのフレームは、幅と高さが完全に同じでなければなりません。 サイズの異なるフレームを追加しようとすると、PicoPixel は "All frames must have the same dimensions." と表示して止めます。
理由は単純です。ウィジェットは各フレームを同じ場所、同じ箱の中に描画します。フレーム 1 が 64×64 でフレーム 2 が 80×80 だと、滑らかにその場で動くのではなく、絵が跳ねたりずれたりします。全フレームを同じサイズに保つことで、きれいな動きになります。
アップロードする前にフレームのサイズを揃えてください。きれいなシーケンスを作る最短の方法は、画像ツールで同じキャンバスから各フレームを書き出すことです。そうすれば必ず同じ寸法になります。
速度を設定する：再生時間
Duration 設定はアニメーションの再生速度を制御します。単位は**ミリ秒（ms）**で、1 フレームあたりの時間ではなく、すべてのフレームを 1 周する 時間を表します。デフォルトは 1000 ms（1 秒）です。
PicoPixel はその時間をフレーム全体に均等に割り振ります。つまり 8 フレームに 1000 ms を設定すると、各フレームは 125 ms 表示されます。速くしたいなら再生時間を下げます。ゆっくり落ち着いた動きにしたいなら上げます。
ループ：1 回再生か、ずっと再生か
Repeat 設定は、アニメーションが最後まで到達したあとどうするかを決めます。選択肢は 2 つです。
- Infinite、アニメーションを永遠にループします。デフォルトで、止まってほしくないスピナーなどに向いています。
- Normal（回数）、指定した回数だけ再生して停止します。3 に設定すると 3 回再生し、最後のフレームで止まります。
UI 実行中に再生を制御する
アニメーションを自動で動かし続ける必要はありません。イベントエディタ を使えば、ユーザー操作に応じて開始・停止できます。イベントを追加し、Animated Image Mode アクションを選び、対象のアニメーション画像を指定して、モードを選択します。
- Start、再生を開始（または再開）します。
- Stop、アニメーションを一時停止します。
- Restart、最初のフレームに戻って再生し直します。
例："connecting..." スピナーをボタンが押されるまで停止させ、押されたら Start、処理が終わったら Stop できます。
メモリ使用量を抑える
アニメーションは画像であり、画像は小さなデバイスでは容量を使います。次の点を意識すると容量を抑えられます。
- 必要なフレームだけ使う。 滑らかな動きでも、動きの要点を押さえた少数のフレームで表現できることがあります。
- フレーム寸法を控えめにする。 64×64 のアニメーションは 240×240 よりはるかに軽量です。
- 色深度をディスプレイに合わせる（実機向けビルドについては ESP32 チュートリアル を参照）。
ファームウェアへ書き出す場合、アニメーション画像には lv_conf.h で LV_USE_ANIMIMG を有効にする必要があります。PicoPixel は書き出した README.md にこれを記載するので、ビルド手順（または AI アシスタント）が何を有効にすべきか分かります。
次のステップ
- 1 つのウィジェットに複数のアニメーションが必要ですか？ スプライトウィジェット に進みましょう。
- イベントエディタ で、アニメーションをボタンや他のトリガーにつなぎます。
- ESP32 LVGL チュートリアル で、完成した UI を実機に組み込みます。
