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.

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

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

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

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

構文

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

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 を設定することで、欲しい形式の画像データを得ることができます。

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 Standard # dom-context-2d-getimagedata-dev

ブラウザーの互換性

BCD tables only load in the browser