Your browser doesn't support HTML canvas. Get a modern browser such as Chrome, Firefox, Opera, or IE9. Otherwise, you'll just see images of canvases, below, instead of canvases. Admittedly, this isn't much of an issue for this particular demo, but you should upgrade, anyway.
In an earlier post, I wrote about a few of the things HTML5's <canvas> element could do. This post is about one more of them: direct pixel manipulation. You can basically do the three following things:
Once you have an array of pixels, you can manipulate it using the standard array accessors "[", "]". The pixels in the array are arranged in row-major order, and are represented as integers between 0 and 255, where each four-integer group represents the four color channels of one pixel: red, green, blue, and alpha (RGBA). What did I just say? Basically, it looks like this... say you have an image that's 3 pixels wide, and 2 pixels high. I know that's tiny, but I want to fit it all in the following super-busy diagram which shows the array indices for given elements of each pixel.
We'll get to a quick-and-easy calculation to find your way around the array in just a moment, but first, how does one create a pixel data array to be used on a canvas? You use the drawing context's createImageData() method. (Use getImageData() to get the array from an existing canvas.)
It's going to be useful later to know the width of the image data, and fortunately that's baked into the ImageData object:
Now we have what we need to write a pixel-setting routine:
There you can see how we first calculate the pixel "position" in the array (which is the row number y times the number of pixels in each row (the width), plus the column number x) and then we multiply it by 4 to get the first channel for that pixel, namely red, because each pixel takes up 4 array elements.
Exercise: write a getPixel(x,y) function that returns the RGBA values for a given pixel as an array, or as a packed 32-bit number (0xRRGGBBAA).
We've seen how to create an image pixel data array, and we've seen how to access it. The only thing left to do is to "paste" the pixels back onto the canvas so that we see them. We do this with a call to putImageData(), to which we pass the image data object, plus an X and Y offset at which to stamp the new data. Let's use this to produce a canvas that is covered with randomly-colored pixels:
But that's so ugly. Let's do something a little prettier, by setting the color of each pixel depending on the sine of the distance it is away from some point on the canvas:
And that'll give you one of these:
Notice in that case how I didn't bother calling my setPixel() function—I just walked all the way through the array one element at a time (indexed by the pos variable.)
What's going on there with all that Math.max() and Math.min() stuff? That's clamping the value between 0 and 255, inclusive. The min() call makes sure the value is less than 255, and then the max() call makes sure that result is greater than 0. Every browser I tried would automatically clamp the values in the array between 0 and 255, but the HTML5 draft says thou shalt not use values outside that range, so you'd better do the clamping yourself.
Exercise: write a script that generates a gradient that goes from black on the top to yellow on the bottom. Then modify it to also make the gradient go from black on the left to blue on the right.
There's just one final thing needed to wrap up this post, I feel, and that's to show manipulation of an existing canvas.
For this demo, we'll load an image, we'll draw that image onto the left half of the canvas (using the drawImage() method), then we'll get the pixel data (with the getImageData() method), and copy the image to the right half of the canvas—except along the way we'll be munging the colors to make it way more blue! Only about 87 million things get more exciting than that, yes?
See Also: HTML5 canvas Part 1
I was just curious if using the putImageData() API method was faster for animation purposes?
@David It would depend on the animation, I think. For instance, if you use the CSS transform property to rotate a bitmap and put it on the screen in the DOM, I would think that had a chance of being faster than a putImageData() having done the rotation yourself. (That is, the path to the screen for the bitmap in the DOM might have been a step shorter.)
But I've seen examples with putImageData() that were absolutely fast enough.
One trick you can use is to pass the "dirty" parameters to putImageData(), so that only the updated part of the data is actually drawn.
Another trick (if you're drawing the same data over and over) is to draw your data to a small canvas, and then use drawImage() to stamp it on the display canvas. Again, my gut feeling is this would be faster than putPixelData() for the same usage, but I'm not really sure; it might be implementation-dependent, too.
I wrote a Mandelbrot and Julia set viewer using this technique.
You can see it here:
@Kevin Cool! I put a link to it on my Mandelbrot Set article.
Thanks for the post.
Canvas is so disappointing... I cannot even rotate a single bitmap without extremely complex and processor intensive calculations... How can I ever build a seriously engaging user experience with it?
@Filippo Gregoretti Ah, but you can rotate a single bitmap very very quickly with canvas.
You'll want to set the rotation in the drawing context (context.rotate()), then drawImage() the image on the canvas. This uses the fast internal blitting to make it happen in a hurry.
So you can do 2D transformations very quickly with canvas, and even some kinds of compositing very quickly. Other things, like conditionally manipulating each pixel, you will have to do the slow way.
@Vidar If you're going HTML5, you also have the option to rotate individual DOM elements (like images) in CSS3 with the "transform" property. (But of course, using canvas is an option, as well.)
As for collision detection, check out this fantastic page at Gamasutra:
Page 5 talks about "Oriented Bounded Boxes" which might be along the lines of what you need.
Great article, and great writing style.
I have a question:
I modify your code as below:
// put pixel data on canvas
c.putImageData(imageData, 0, 0);
Why is the output image still in (0,0) not (50,50)?
I too have the same question as OrNot, although what I want to do is to read the pixel at (x,y) after a translate and rotation. Is this possible? perhaps there is a way to get the "real" coordinates of x and y after a translate and rotate has been done, and get the pixel at the "real" coordinates?
@OrNot getImageData() and putImageData() operate on a low level, referring to the pixels in the bitmap backing store, and are not affected by the drawing context.
In the spec: "The current path, transformation matrix, shadow attributes, global alpha, the clipping region, and global composition operator must not affect the getImageData() and putImageData() methods."
@michael This is tricky for a couple reasons. (If it's possible, given your needs, to read the pixel at x,y before the transform, it could be a lot better.)
First of all, the math isn't hard, and there are a number of JS libraries to do it. (I've used Sylvester: http://sylvester.jcoglan.com/ ). Basically, you have to run the math again in parallel to get the result.
However, canvas will render to a subpixel. This means that part of your color could be on one pixel, and the rest would be on another. It might be a while pixel, originally, but it might turn to several gray pixels after rotation.
Is it possible to get the raw pixel value of an 8-bit indexed png, not the associated RGBA? I have images where the values (0-255) in the raw pixels have an actual data meaning. Depending on the time of year, the actual index palette changes, (so the displayed colors change) but not the 0-255 values in each pixel. I can do this client side, but with overhead which I don't want.
What I want to do is a browser side calculation. So when a user mouses over an image, the x,y provides the pixel needed, and the 0-255 is extracted. This is then converted to a data value (using a know formula,) which can be displayed for the user (and of course, a coresponding lat long which can be determined since I know the outer lat/long bounds of the image)
I meant "I can do it server side,..."
@brock I'm unaware of a way to get this low level data from the PNG, short of writing a PNG decoder in JS, and even then, my JS-fu isn't strong enough to know a way to get the binary data in JS.
By the time the data gets exposed, it's already abstracted. :-/
Hi Brock, were you able to find a way to get the raw PNG values in JS? I have a similar requirement and want to use IMG if possible. Thanks!