JavaScript Canvas putImageData Tutorial
last modified April 3, 2025
In this article, we explore the Canvas putImageData method in JavaScript. This method is essential for direct pixel manipulation on HTML canvas. Mastering putImageData is crucial for image processing and special effects.
Basic Definition
putImageData is a Canvas API method that writes pixel data to a canvas. It works with ImageData objects containing pixel color values. This allows direct low-level manipulation of canvas pixels.
The method takes an ImageData object and draws it at specified coordinates. It can optionally take a dirty rectangle to copy only part of the image data. This is powerful for performance optimization.
Basic putImageData Usage
This example demonstrates how to create and draw a simple ImageData object.
<!DOCTYPE html>
<html>
<head>
<title>Basic putImageData</title>
</head>
<body>
<canvas id="myCanvas" width="300" height="200"></canvas>
<script>
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
// Create blank ImageData
const imageData = ctx.createImageData(100, 100);
const data = imageData.data;
// Fill with red pixels
for (let i = 0; i < data.length; i += 4) {
data[i] = 255; // R
data[i + 1] = 0; // G
data[i + 2] = 0; // B
data[i + 3] = 255; // A
}
ctx.putImageData(imageData, 50, 50);
</script>
</body>
</html>
In this basic example, we create a 100x100 pixel ImageData object. We then fill it with solid red pixels by setting RGBA values in the data array.
The putImageData method draws this pixel data at position (50,50).
This demonstrates the simplest way to create and draw pixel data on canvas.
Copying Canvas Data
This example shows how to copy part of the canvas and manipulate it.
<!DOCTYPE html>
<html>
<head>
<title>Copy Canvas Data</title>
</head>
<body>
<canvas id="myCanvas" width="300" height="200"></canvas>
<script>
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
// Draw original content
ctx.fillStyle = 'blue';
ctx.fillRect(50, 50, 100, 100);
// Get image data
const imageData = ctx.getImageData(50, 50, 100, 100);
const data = imageData.data;
// Invert colors
for (let i = 0; i < data.length; i += 4) {
data[i] = 255 - data[i]; // R
data[i + 1] = 255 - data[i + 1]; // G
data[i + 2] = 255 - data[i + 2]; // B
}
// Draw modified data
ctx.putImageData(imageData, 150, 50);
</script>
</body>
</html>
Here we first draw a blue rectangle. We then copy its pixel data using
getImageData. We modify the data by inverting the colors.
The modified data is drawn back to the canvas at a new position using
putImageData. This shows how to process existing canvas content.
Partial Image Update
This example demonstrates updating only part of the canvas with putImageData.
<!DOCTYPE html>
<html>
<head>
<title>Partial Update</title>
</head>
<body>
<canvas id="myCanvas" width="300" height="200"></canvas>
<script>
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
// Create full canvas image data
const imageData = ctx.createImageData(canvas.width, canvas.height);
const data = imageData.data;
// Fill with gradient
for (let y = 0; y < canvas.height; y++) {
for (let x = 0; x < canvas.width; x++) {
const i = (y * canvas.width + x) * 4;
data[i] = x % 255; // R
data[i + 1] = y % 255; // G
data[i + 2] = 128; // B
data[i + 3] = 255; // A
}
}
// Draw only a portion (dirty rectangle)
ctx.putImageData(imageData, 0, 0, 50, 50, 100, 100);
</script>
</body>
</html>
This example creates a full-canvas gradient but only draws a 100x100 portion. The last four parameters define the dirty rectangle (source x, y, width, height).
This technique is useful for performance when you only need to update part of the canvas. The rest of the pixel data is ignored during drawing.
Image Processing Filter
This example shows how to create a simple grayscale filter using putImageData.
<!DOCTYPE html>
<html>
<head>
<title>Grayscale Filter</title>
</head>
<body>
<canvas id="myCanvas" width="300" height="200"></canvas>
<img id="source" src="image.jpg" style="display:none">
<script>
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
const img = document.getElementById('source');
img.onload = function() {
ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const data = imageData.data;
// Convert to grayscale
for (let i = 0; i < data.length; i += 4) {
const avg = (data[i] + data[i + 1] + data[i + 2]) / 3;
data[i] = avg; // R
data[i + 1] = avg; // G
data[i + 2] = avg; // B
}
ctx.putImageData(imageData, 0, 0);
};
</script>
</body>
</html>
This example loads an image, draws it to canvas, then converts it to grayscale. The grayscale conversion averages the RGB values of each pixel.
After processing, we use putImageData to draw the modified pixels
back to canvas. This demonstrates practical image processing with putImageData.
Pixel Animation Effect
This example creates an animated pixel effect using putImageData.
<!DOCTYPE html>
<html>
<head>
<title>Pixel Animation</title>
</head>
<body>
<canvas id="myCanvas" width="300" height="200"></canvas>
<script>
const canvas = document.getElementById('myCanvas');
const ctx = canvas.getContext('2d');
// Initial drawing
ctx.fillStyle = 'blue';
ctx.fillRect(0, 0, canvas.width, canvas.height);
let offset = 0;
function animate() {
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const data = imageData.data;
// Shift pixels horizontally
for (let y = 0; y < canvas.height; y++) {
for (let x = 0; x < canvas.width; x++) {
const i = (y * canvas.width + x) * 4;
const ni = (y * canvas.width + ((x + offset) % canvas.width)) * 4;
data[i] = imageData.data[ni]; // R
data[i + 1] = imageData.data[ni + 1]; // G
data[i + 2] = imageData.data[ni + 2]; // B
}
}
ctx.putImageData(imageData, 0, 0);
offset++;
requestAnimationFrame(animate);
}
animate();
</script>
</body>
</html>
This example creates a horizontal pixel shifting animation. Each frame, pixels are shifted right by one position, creating a scrolling effect.
The animation loop uses getImageData and putImageData
to continuously update the canvas. This shows how putImageData can be used for
real-time effects.
Source
MDN putImageData Documentation
In this article, we have explored various techniques for using putImageData to manipulate canvas pixels. Mastering this method is essential for advanced graphics and image processing in web applications.
Author
List all JS Canvas tutorials.