Remotionの画像差分テストでしきい値を決める方法
執筆: RenderComp チーム 編集方針
Remotion では、動画はフレーム番号を入力にとる React コンポーネントの計算結果です。同じ props と同じフレーム番号を渡せば同じ絵が出るので、特定のフレームを静止画として書き出し、前回の画像と画素単位で比べるテストが組めます。レイアウト崩れやフォントの差し替わりは、目で動画を見返すより先にこの比較で見つかります。
実際に組むと、詰まるのはしきい値です。差分ゼロを合格条件にすると、出力形式や拡大率の設定次第で毎回落ちるテストになります。逆に緩めすぎると、ボタンが 1 つ消えても通ってしまいます。この記事では、しきい値を出力設定とセットで決める手順を、コードと一緒に追います。
テスト対象のフレームを決める
比較するフレームは、アニメーションの途中より、動きが止まった直後や Sequence の切り替わり直後を選ぶと意図が読みやすくなります。次のコンポジションは 30fps で、タイトルが 0〜20 フレームでフェードインし、45 フレーム目からサブタイトルの Sequence が始まります。
import {AbsoluteFill, Sequence, interpolate, useCurrentFrame, useVideoConfig} from 'remotion';
export const TitleCard: React.FC<{title: string; subtitle: string}> = ({title, subtitle}) => {
const frame = useCurrentFrame();
const {width} = useVideoConfig();
// 0〜20フレームで不透明度を0→1に。20フレーム以降は1で固定される
const opacity = interpolate(frame, [0, 20], [0, 1], {
extrapolateLeft: 'clamp',
extrapolateRight: 'clamp',
});
return (
<AbsoluteFill style={{backgroundColor: '#0b0b10', justifyContent: 'center', alignItems: 'center'}}>
<h1 style={{opacity, color: 'white', fontSize: width * 0.06}}>{title}</h1>
{/* 45フレーム目から表示。差分テストではこの境界の直後を撮る */}
<Sequence from={45} layout="none">
<p style={{color: '#9aa0b4', fontSize: width * 0.025}}>{subtitle}</p>
</Sequence>
</AbsoluteFill>
);
};
このコンポジションなら、フェードが終わった 20 フレーム目と、サブタイトルが出た 45 フレーム目の 2 枚を撮れば足ります。フェードの途中を撮ると、interpolate の範囲を少し変えただけで不透明度が変わり、意図した修正でもテストが落ちます。
基準画像は PNG で書き出す
renderStill の imageFormat には png、jpeg、pdf、webp を指定でき、既定値は png です。差分テストでは既定のまま PNG を使います。JPEG を選ぶと jpegQuality に 0〜100 の整数を渡すことになり、既定値は 80 です。非可逆圧縮のノイズが画素差分に混ざるので、そのぶんしきい値を緩める必要が出てきます。
jpegQuality は PNG で書き出すときには効きません。設定ファイルに jpegQuality を残したまま形式だけ PNG に切り替えても、出力は変わりません。品質値を変えたのに差分が出ないときは、この組み合わせを疑います。
import {bundle} from '@remotion/bundler';
import {renderStill, selectComposition} from '@remotion/renderer';
import path from 'node:path';
// 撮影するフレーム。Sequenceの境界直後とフェード終了直後
const FRAMES = [20, 45];
export const captureFrames = async (outDir: string) => {
const serveUrl = await bundle({entryPoint: path.resolve('src/index.ts')});
const inputProps = {title: 'RenderComp', subtitle: 'Visual regression'};
const composition = await selectComposition({serveUrl, id: 'TitleCard', inputProps});
for (const frame of FRAMES) {
await renderStill({
composition,
serveUrl,
inputProps,
frame,
output: path.join(outDir, `title-card-${frame}.png`),
imageFormat: 'png', // 既定値と同じだが、テストの前提として明示しておく
scale: 1, // 基準画像と比較画像で必ず同じ値にそろえる
});
}
};
imageFormat を明示しているのは、後から誰かが既定値に頼らず jpeg に変えたとき、差分テストの前提が崩れたことをコード上で追えるようにするためです。
しきい値は画素数ではなく比率で持つ
scale は 0 より大きく 16 以下の値をとり、既定値は 1 です。16 にすると縦横がそれぞれ 16 倍になり、画素数は 256 倍になります。1 未満も指定でき、0.5 なら縦横が半分になって画素数は 4 分の 1 です。
このため「差分が 500 画素まで」のように画素数でしきい値を書くと、scale を変えた瞬間に意味が変わります。1 から 2 に上げると同じ崩れでも差分の画素数は 4 倍に増えるので、比較的小さな修正でもテストが落ちます。しきい値は画像全体に対する比率で持ち、1 画素ごとの色の許容差とは分けて考えます。
type DiffOptions = {
// 1画素のRGBAの各チャンネルで、この値を超える差があれば「違う画素」と数える
channelTolerance: number;
// 違う画素が全体のこの割合を超えたら失敗にする
maxDiffRatio: number;
};
// rgbaA / rgbaB は同じ幅・高さでデコード済みのRGBA配列
export const comparePixels = (
rgbaA: Uint8Array,
rgbaB: Uint8Array,
width: number,
height: number,
{channelTolerance, maxDiffRatio}: DiffOptions,
) => {
const total = width * height;
if (rgbaA.length !== total * 4 || rgbaB.length !== total * 4) {
// サイズ違いは差分以前の問題。scaleの食い違いがよくある原因
throw new Error(`Size mismatch: expected ${total * 4} bytes`);
}
let diffPixels = 0;
for (let i = 0; i < rgbaA.length; i += 4) {
const delta = Math.max(
Math.abs(rgbaA[i] - rgbaB[i]),
Math.abs(rgbaA[i + 1] - rgbaB[i + 1]),
Math.abs(rgbaA[i + 2] - rgbaB[i + 2]),
Math.abs(rgbaA[i + 3] - rgbaB[i + 3]),
);
if (delta > channelTolerance) diffPixels++;
}
const ratio = diffPixels / total;
return {diffPixels, ratio, passed: ratio <= maxDiffRatio};
};
PNG で書き出す前提なら channelTolerance は小さく始め、落ちたフレームの差分画素を目で確かめてから広げます。JPEG に切り替える場合は、jpegQuality を固定したうえで channelTolerance を別に設定します。2 つの形式で同じ値を使い回すと、どちらかが緩すぎるか厳しすぎるかのどちらかになります。
サイズが一致しないときに例外を投げているのは、scale の食い違いを差分率の数字に紛れ込ませないためです。基準画像が scale: 1、比較画像が scale: 2 なら、差分率を計算する前に止めるのが正しい挙動です。
Lambda で回すときの容量
CI から Lambda で基準画像を撮る場合、scale の値はメモリと一時領域の見積もりに直結します。Lambda のメモリは 128 MB から 10,240 MB まで 1 MB 刻みで、/tmp の容量は 512 MB から 10,240 MB まで 1 MB 刻みで設定できます。
scale を 2 にすると 1 枚あたりの画素数は 4 倍になり、撮るフレーム数を増やすほど /tmp に溜まる画像も増えます。先に scale: 1 で全フレームを通し、その出力サイズを見てから拡大率と /tmp の設定を決めると、容量不足で途中終了する事態を避けられます。次にやるのは、上の FRAMES に自分のコンポジションの Sequence 境界を並べ、scale: 1 の PNG で最初の基準画像を書き出すことです。
無料50本
テンプレート50本を ZIP で受け取る
メールアドレスを入れると、50本の ZIP のリンクをすぐにお送りします。
50本の ZIP をメールで受け取ります。あわせて RenderComp テンプレートの更新と、有料ライブラリを含む製品のご案内を受け取ることに同意します(メールは数通・ワンクリック解除)。 プライバシーポリシー(英語)
メールを使わずに受け取ることもできます。GitHub のリポジトリは公開のままで、登録も不要です。 リポジトリを開く
送信しました
ZIP のリンクを記載したメールをお送りしました。届かない場合は迷惑メールをご確認ください。いますぐ受け取る場合はこちらから直接ダウンロードできます。