CanvasRenderingContext2D: getImageData() method
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.
The CanvasRenderingContext2D
method
getImageData()
of the Canvas 2D API returns an
ImageData
object representing the underlying pixel data for a specified
portion of the canvas.
This method is not affected by the canvas's transformation matrix. If the specified
rectangle extends outside the bounds of the canvas, the pixels outside the canvas are
transparent black in the returned ImageData
object.
Note: Image data can be painted onto a canvas using the
putImageData()
method.
You can find more information about getImageData()
and general
manipulation of canvas contents in Pixel manipulation with canvas.
Syntax
getImageData(sx, sy, sw, sh)
getImageData(sx, sy, sw, sh, settings)
Parameters
sx
-
The x-axis coordinate of the top-left corner of the rectangle from which the
ImageData
will be extracted. sy
-
The y-axis coordinate of the top-left corner of the rectangle from which the
ImageData
will be extracted. sw
-
The width of the rectangle from which the
ImageData
will be extracted. Positive values are to the right, and negative to the left. sh
-
The height of the rectangle from which the
ImageData
will be extracted. Positive values are down, and negative are up. settings
Optional-
An object with the following properties:
colorSpace
: Specifies the color space of the image data. Can be set to"srgb"
for the sRGB color space oder"display-p3"
for the display-p3 color space.
Return value
An ImageData
object containing the image data for the rectangle of the
canvas specified. The coordinates of the rectangle's top-left corner are
(sx, sy)
, while the coordinates of the bottom corner are
(sx + sw - 1, sy + sh - 1)
.
Exceptions
IndexSizeError
DOMException
-
Thrown if either
sw
odersh
are zero. SecurityError
DOMException
-
The canvas contains or may contain pixels which were loaded from an origin other than the one from which the document itself was loaded. To avoid a
SecurityError
DOMException
being thrown in this situation, configure CORS to allow the source image to be used in this way. See Allowing cross-origin use of images and canvas.
Examples
Getting image data from a canvas
This example draws an image, and then uses getImageData()
to grab a
portion of the canvas.
We use getImageData()
to extract a slice of the image, starting at (10, 20)
, with a width of 80
and a height of 230
. We then draw this slice three times, positioning the slices progressively below and to the right of the last slice.
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);
});
Result
Color space conversion
The optional colorSpace
setting allows you to get image data in the desired format.
const context = canvas.getContext("2d", { colorSpace: "display-p3" });
context.fillStyle = "color(display-p3 0.5 0 0)";
context.fillRect(0, 0, 10, 10);
// Get ImageData converted to sRGB
const imageData = context.getImageData(0, 0, 1, 1, { colorSpace: "srgb" });
console.log(imageData.colorSpace); // "srgb"
Specifications
Specification |
---|
HTML Standard # dom-context-2d-getimagedata-dev |
Browser compatibility
BCD tables only load in the browser
See also
- The interface defining this method:
CanvasRenderingContext2D
ImageData
objectCanvasRenderingContext2D.putImageData()
- Pixel manipulation with canvas