getframe

座標軸または Figure のムービー フレームとしてのキャプチャ

構文

F = getframe

F = getframe(ax)

F = getframe(fig)

F = getframe(___,rect)

説明

F = getframe は、画面上に表示されている現在の座標軸をムービー フレームとしてキャプチャします。F はイメージ データをもつ構造体です。getframe は、画面上の表示と同じサイズで座標軸をキャプチャします。目盛りラベルなど、座標軸の外枠の外側にあるコンテンツはキャプチャしません。

F = getframe(ax) は、現在の座標軸ではなく ax で指定された座標軸をキャプチャします。

F = getframe(fig) は、fig で指定された Figure をキャプチャします。座標軸、タイトル、ラベル、目盛りなど、Figure ウィンドウの内側全体をキャプチャする場合は、Figure を指定します。キャプチャしたムービー フレームには、Figure のメニューやツール バーは含まれません。

F = getframe(___,rect) は、rect で定義された四角形内部の領域をキャプチャします。rect は、[left bottom width height] の形式の 4 要素ベクトルとして指定します。このオプションは、前述の構文の入力引数 ax または fig と共に使用します。

例

現在の座標軸のコンテンツのキャプチャ

2 本のラインをプロットします。座標軸をキャプチャし、イメージ データを返します。getframe は、座標軸の内側と座標軸の外枠を取得します。座標軸の外枠からはみ出したコンテンツはキャプチャしません。

plot([0 1; 1 2])
F = getframe;

F は、キャプチャしたイメージ データを格納するフィールド cdata をもつ構造体です。

imshow を使用して、キャプチャしたイメージ データを表示します。

figure
imshow(F.cdata)

Figure のコンテンツのキャプチャ

表面プロットを作成します。メニューとツール バーを除いて、Figure ウィンドウの内部をキャプチャします。

surf(peaks)
F = getframe(gcf);

F は、キャプチャしたイメージ データを格納するフィールド cdata をもつ構造体です。

imshow を使用して、キャプチャしたイメージ データを濃い背景色で Figure に表示すると、キャプチャした領域を確認できます。

figure('Color',[0.5 0.5 0.5])
imshow(F.cdata)

キャプチャする四角形領域の指定

座標軸の内側に加えて、各方向に 30 ピクセルのマージンをキャプチャします。キャプチャするフレーム内に目盛りラベルを含めるには、追加マージンが必要です。目盛りラベルのサイズによっては、マージンの調整が必要となる場合があります。

2 本のラインをプロットします。

plot([0 1; 1 2])

座標軸の単位をピクセルに変更し、現在の座標軸の位置を返します。位置ベクトルの第 3 と第 4 の要素は、座標軸の幅と高さをピクセル単位で指定します。

drawnow
ax = gca;
ax.Units = 'pixels';
pos = ax.Position

pos =

   73.8000   47.2000  434.0000  342.3000

座標軸に目的のマージンを加えた四角形領域を定義する 4 要素ベクトル rect を作成します。rect の最初の 2 つの要素は、座標軸の左下隅を基準にして、四角形の左下隅の位置を指定します。rect の最後の 2 つの要素は、四角形の幅と高さを指定します。座標軸の単位を既定値 'normalized' にリセットします。

marg = 30;
rect = [-marg, -marg, pos(3)+2*marg, pos(4)+2*marg];
F = getframe(gca,rect);
ax.Units = 'normalized';

imshow を使用して、キャプチャしたイメージ データを濃い背景色で Figure に表示すると、キャプチャした領域を確認できます。

figure('Color',[0.5 0.5 0.5])
imshow(F.cdata)

タイトルおよびラベルを含める領域の計算

キャプチャするイメージ データにタイトル、軸ラベルおよび目盛りラベルが含まれるように、座標軸の周囲のマージンを計算します。

タイトルと x 軸ラベルをもつプロットを作成します。

plot([0 1; 1 2])
xlabel('x values')
title('Plot of Two Lines')

座標軸の単位をピクセルに変更し、座標軸の Position と TightInset のプロパティ値を格納します。TighInset プロパティは、[left bottom right top] の形式の 4 要素ベクトルです。この値は、座標軸の周囲にある目盛りの値とテキスト ラベル用のマージンです。

drawnow
ax = gca;
ax.Units = 'pixels';
pos = ax.Position;
ti = ax.TightInset;

座標軸に自動計算されたマージンを加えた四角形領域を定義する 4 要素ベクトル rect を作成します。rect の最初の 2 つの要素は、座標軸の左下隅を基準にして、四角形の左下隅の位置を指定します。rect の最後の 2 つの要素は、四角形の幅と高さを指定します。

rect = [-ti(1), -ti(2), pos(3)+ti(1)+ti(3), pos(4)+ti(2)+ti(4)];
F = getframe(ax,rect);

imshow を使用して、キャプチャしたイメージ データを濃い背景色で Figure に表示すると、キャプチャした領域を確認できます。

figure('Color',[0.5 0.5 0.5])
imshow(F.cdata)

特定の座標軸のキャプチャ

関数 tiledlayout を呼び出して、2 行 1 列のタイル表示チャート レイアウトを作成します。関数 nexttile を呼び出して、axes オブジェクト ax1 および ax2 を作成します。各座標軸にラインをプロットします。

tiledlayout(2,1)
ax1 = nexttile;
plot(1:10,'b')
ax2 = nexttile;
plot(1:10,'r')

下の座標軸のコンテンツをキャプチャします。getframe は、プロットの内部と枠線をキャプチャします。プロットの外枠を越える目盛りの値やラベルはキャプチャしません。

F = getframe(ax2);

imshow を使用して、キャプチャしたイメージ データを表示します。

figure
imshow(F.cdata)

フレームの記録とムービーの再生

getframe をループで使用して、振動する関数 peaks のフレームを記録します。ムービー フレームを保存する配列を事前に割り当てます。

Z = peaks;
surf(Z)
axis tight manual
ax = gca;
ax.NextPlot = 'replaceChildren';

loops = 40;
F(loops) = struct('cdata',[],'colormap',[]);
for j = 1:loops
    X = sin(j*pi/10)*Z;
    surf(X,Z)
    F(j) = getframe(gcf);
end

ムービーを 2 回再生します。

fig = figure;
movie(fig,F,2)

入力引数

ax — キャプチャする座標軸

Axes オブジェクト | GeographicAxes オブジェクト

キャプチャする座標軸。Axes オブジェクトまたは GeographicAxes オブジェクトとして指定します。このオプションは、現在の座標軸以外の座標軸をキャプチャする場合に使用します。

getframe は、座標軸の外枠を囲む最小の四角形の内側にあるコンテンツをキャプチャします。目盛りの値およびラベルをすべてキャプチャする場合は、代わりに入力引数 fig を使用します。

例: F = getframe(ax);

fig — キャプチャする Figure

figure オブジェクト

キャプチャする Figure。Figure オブジェクトとして指定します。

rect — キャプチャする四角形の領域

[left bottom width height] の形式の 4 要素ベクトル

キャプチャする四角形の領域。[left bottom width height] の形式の 4 要素ベクトル (ピクセル単位) として指定します。left と bottom の要素は、四角形の左下隅の位置を定義します。この位置は、getframe の最初の入力引数として指定された Figure または座標軸に対する位置です。width 要素と height 要素で四角形の大きさを定義します。

Figure ウィンドウ内に全体が収まる四角形を指定します。

メモ

四角形領域全体が Figure の描画可能領域内に収まらない場合、getframe はエラーを返します。描画可能領域は、Figure の境界線の内側にある領域で、Figure ツールストリップは含まれません。 (R2025a 以降)

出力引数

F — ムービー フレーム

構造体

ムービー フレーム。次の 2 つのフィールドをもつ構造体として返されます。

• cdata — uint8 型の値の配列として格納されるイメージ データ。イメージ データの配列のサイズは、画面の解像度によって決まります。

• colormap — カラーマップ。トゥルーカラー システムでは、このフィールドは空になります。

メモ

cdata のサイズに関して、重要な検討事項がいくつかあります。

• getframe がキャプチャした領域 (Figure、座標軸、あるいは rect で指定した領域) のサイズをクエリした場合、そのサイズ (ピクセル単位) が cdata の要素数と一致しないことがあります。この違いの理由は、cdata の要素数は画面の解像度 (およびオペレーティング システムの設定) によって決まるのに対して、MATLAB^® でのピクセル数は画面上の実際のピクセル数に対応していない場合があるからです。

• R2015b 以降で高解像度システムを使用している場合、cdata のサイズは、旧リリースまたは他のシステムでのサイズよりも大きくなることがあります。

制限

getframe はWeb アプリ (MATLAB Compiler)での内容の取得はサポートしていません。

詳細

ピクセル

Windows^® システムおよび Macintosh システムでは、ピクセルのサイズは 1/96 インチです。このサイズはシステムの解像度に依存しません。

Linux^® システムでは、ピクセルのサイズは使用しているシステムの解像度によって決まります。

ヒント

• getframe の使用時にパフォーマンスを最大限に高めるには、必ず Figure を画面上に表示します。Figure が表示されていない場合でも getframe は Figure をキャプチャできますが、パフォーマンスが低下することがあります。

• イメージ データの解像度を詳細に制御するには、代わりに関数 print を使用します。print に出力引数 cdata を指定すると、イメージ データを返します。入力引数 resolution は、イメージの解像度を制御します。

• 3 次元プロットの横に表示されたカラーバーと凡例が確実にキャプチャされるようにするには、getframe の呼び出し時に fig 引数を指定します。

バージョン履歴

R2006a より前に導入

R2025a: MATLAB Online でのアプリおよび Figure の内容の取得

MATLAB Online™ で、App Designer または uifigure 関数で作成された Figure の内容を取得できるようになりました。これらのタイプの Figure は、ローカル インストールを使用して取得することもできます。

R2023b: Figure ツール バー、メニュー バー、境界線の取得はサポートなし

Figure の描画可能領域内に全体が収まらない領域を rect 引数を使用して取得すると、getframe はエラーを返します。描画可能領域は、Figure の境界線の内側にある領域で、Figure ツールストリップは含まれません。

この変更は R2022b で発表されました。R2023b ～ R2024b では、Figure の描画可能領域内に全体が収まらない四角形領域を指定すると、getframe 関数は警告を発行します。

参考

movie | frame2im | im2frame | image | imshow | print | writeVideo

トピック

• Compare Ways to Export Graphics from Figures