CanvasRenderingContext2D: getImageData() メソッド

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

CanvasRenderingContext2DgetImageData() は Canvas 2D API のメソッドで、キャンバスの指定の部分に対応するピクセルデータを表す ImageData オブジェクトを返します。

このメソッドは、キャンバスの変換行列の影響を受けません。指定された矩形がキャンパスの境界の外にはみ出る場合は、返される ImageData オブジェクトのキャンバスの外側の部分は透明な黒になります。

メモ: 画像データは、putImageData() メソッドでキャンバスに描画できます。

キャンバスとピクセル操作に、getImageData() およびキャンバスの内容の一般的な操作に関するさらなる情報があります。

構文

js
getImageData(sx, sy, sw, sh)
getImageData(sx, sy, sw, sh, settings)

引数

sx

ImageData を取り出す矩形の左上の角の x 座標です。

sy

ImageData を取り出す矩形の左上の角の y 座標です。

sw

ImageData を取り出す矩形の幅です。正の値を指定すると右向きに、負の値を指定すると左向きに取り出します。

sh

ImageData を取り出す矩形の高さです。正の値を指定すると下向きに、負の値を指定すると上向きに取り出します。

settings 省略可

以下のプロパティを持つオブジェクトです。

  • colorSpace: 画像データの色空間を指定します。sRGB 色空間 を表す "srgb"、もしくは display-p3 色空間 を表す "display-p3" が設定できます。

返値

キャンバスの指定の矩形の画像データが入った ImageData オブジェクトを返します。矩形の左上の角の座標は (sx, sy) であり、下の角の座標は (sx + sw - 1, sy + sh - 1) です。

例外

IndexSizeError DOMException

sw または sh のいずれかがゼロのとき投げられます。

SecurityError DOMException

キャンバスがドキュメント自身が読み込まれたオリジンとは異なるオリジンから読み込まれたピクセルを含むか、含む可能性があるとき投げられます。 このような場合に SecurityError DOMException が投げられるのを回避するには、元画像がこのように使われるのを許可するように CORS を設定してください。画像とキャンバスをオリジン間で利用できるようにするを参照してください。

キャンバスから画像データを取得する

この例では、画像を描画し、getImageData() を用いてキャンバスの一部を取得します。

getImageData() を用いて、画像の (10, 20) を始点とし、幅 80、高さ 230 の部分を取り出します。そして、この部分を 3 回、前回描画した部分の右下に描画していきます。

HTML

html
<canvas id="canvas" width="700" height="400"></canvas>

JavaScript

js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

const image = new Image();
image.src = "plumeria.jpg";
image.addEventListener("load", () => {
  ctx.drawImage(image, 0, 0, 233, 320);

  const imageData = ctx.getImageData(10, 20, 80, 230);
  ctx.putImageData(imageData, 260, 0);
  ctx.putImageData(imageData, 380, 50);
  ctx.putImageData(imageData, 500, 100);
});

結果

色空間の変換

省略可能な colorSpace を設定することで、欲しい形式の画像データを得ることができます。

js
const context = canvas.getContext("2d", { colorSpace: "display-p3" });
context.fillStyle = "color(display-p3 0.5 0 0)";
context.fillRect(0, 0, 10, 10);

// ImageData を sRGB に変換する
const imageData = context.getImageData(0, 0, 1, 1, { colorSpace: "srgb" });
console.log(imageData.colorSpace); // "srgb"

仕様書

Specification
HTML
# dom-context-2d-getimagedata-dev

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
getImageData

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
See implementation notes.

関連情報