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