2D Pixel coordinate mapping tool for images

Here is a quick and dirty pixel mapping tool.

You can upload a photo, click to mark a coordinate on the image, press z (not control-z) to remove the last coordinate.

It puts the coordinates into a text area for copying to pixelblaze mapper tab, drawing the pixel index number on the image.

Remember, Pixelblaze mapper coordinates can be in any unit, pixels work too :slight_smile:

The coordinates are in pixels from the source image. It will also accept edits/pastes into the text area to edit maps later, so you can upload the same image and paste the map to edit later.

I’ll clean it up and throw it on my main website in the future, but perhaps even this quick tool will be handy!


OK this is awesome,

I had an idea ages ago for making a mask with leds on it, but couldn’t wrap my head around matrixes and mapping. This pretty much solves that problem. Stoked to give this a try!

1 Like

Here’s a 3D one that takes two movies of LEDs lighting up in order, taken at 90 degrees of each other, and creates a XYZ coordinate set, all within a browser. @wizard, might be worth adjusting this to fit PB, and having it available as well, there is source on GitHub.

1 Like

I’ve just updated this tool!

This improves usability for smaller images, and especially pixel art bitmaps.

  • It will now use your native resolution regardless of image size for rendering so that the pixel index text is readable (including retina displays!).
  • Font sizes are no longer dependent on image size
  • Images are drawn without smoothing if any dimension is less than 256. This makes it much easier to map pixel art.
  • Text drawn over the image is now properly centered on the pixel, which is pretty important when you have giant pixels!
1 Like

Great! Thanks for the update.

I mapped from my dance costume (1160 pixels) using the 2D Pixel tool.

Here is the image. I need to go back and recreate the map. As you can see from the image below, the pixels are not aligned. Is there a faster or more efficient way of doing this other than painstakingly adding each pixel with greater care and precision, or manually entering the coordinates?

2D render

Image used for mapping costume


1: What is the function of the SAVE button at the bottom of the Mapper page?
2: How can I save and reload my coordinates other than in a text document?
3: How can I take PB Saved Patterns and modify them to run on my 2D mapping coordinates?


Hi @Kamehana,

Is there a faster or more efficient way of doing this other than painstakingly adding each pixel with greater care and precision, or manually entering the coordinates?

Not at this time with a construction like yours and the tool as it exists today. If your LED layout were regular (like square, or followed some pattern), some code could generate the map.

The image pixel mapper tool was a quick project. In an ideal tool you could draw lines, snap to a grid, drag and drop points, etc., but the tool does not support those things now.

The recent enhancement I just uploaded will let you work with lower resolution images, which then naturally “snap” to pixel rows/columns.

That said, what you have is still quite close, and would look good with most 2D patterns.

1: What is the function of the SAVE button at the bottom of the Mapper page?

Once you paste the map in Pixelblaze, it will be used immediately much like editing a pattern. Both the preview on the right and the in-memory pixel map used for rendering are updated. Click Save to make this change permanent (and overwrite any previously saved pixel map). Otherwise your pixel map will not persist if you close the page and restart PB. This will store both the normalized pixel map used internally, as well as the text for your map.

2: How can I save and reload my coordinates other than in a text document?

The JSON text is a portable format for your coordinates. When you click save this is persisted on PB, and you can also save this elsewhere, like in a text file on your computer for safe keeping or to use later with other PBs. These coordinates can also be loaded and transformed using just about any programming language since JSON is a widely supported syntax.

3: How can I take PB Saved Patterns and modify them to run on my 2D mapping coordinates?

On the Mapper tab, scroll down to view the documentation for the mapper tool and how these work with Pixelblaze pattern code. You can also access that documentation here.

Once a 2D pixel map is installed on the Mapper tab, patterns can implement a render2D(index, x, y) exported function.

A super easy trick to convert a plain old render() pattern is to swap out any code that uses the expression index/pixelCount with x or y.

For example take the default rainbow pattern:

export function beforeRender(delta) {
  t1 = time(.1)

export function render(index) {
  h = t1 + index/pixelCount
  s = 1
  v = 1
  hsv(h, s, v)

To convert this, the render function is modified to become render2D with additional arguments, and the index/pixelCount is replaced with x:

export function beforeRender(delta) {
  t1 = time(.1)

export function render2D(index, x, y) {
  h = t1 + x
  s = 1
  v = 1
  hsv(h, s, v)

This will cause a rainbow to sweep to the right on any pixel mapped LEDs, and the best part is that the now 2D pattern works on any LEDs that have a 2D mapping. It would work equally well on a square matrix as on your orc LED suit.

There are many patterns on the pattern sharing site with 2D and/or 3D support!

I think “fast pulse 3d” would look really good, give it a try!


Thanks for the information and for the examples. They are very helpful.

1). I downloaded and opened Fast pulse 3d, Bouncer3D and other 2D patterns in the editing window.
2). In Setting, I changed the number of pixels to 1066 (number of pixels in this costume)

However when I change over to the Mapping tab, I still see the rainbow preview pattern. How do I get the preview in the mapping tab to show the pattern from the editing tab?

1 Like

The rainbow preview in the Mapper tab is only a preview of your map. The colors and “pulse” animation show the wiring direction and is used to show information about the map instead of the pattern. However, edits to the map should reflect live on the LEDs if a 2D pattern is running as well.

There are 2D/3D mapping helper patterns that do things like sweeps across an axis that can help if you have something not quite right.

A post was split to a new topic: Troubleshooting an LED suit with 2D pixel maps

This tool is awesome. I just mapped the order of my nanoleaf panels and will be diving into the code soon.

1 Like

I cant make it work. What I have to do before add the image or having the mapper done? I set it up to the Led quantity, leave the PB in a 2D pattern then I press save and nothing happens.


it won’t update that display, that’s just a rainbow display, leave that page, select a pattern and see if the actual pattern works as expected.

That said, that rainbow display looks wrong, given what we know the real thing looks like… @wizard?

I do that already. The display look ok. It move like left to right. But when I select the pattern it won’t do a 2D on the Leds. I try with some 2D patterns. I am trying with a pixelblaze v2. Any pattern that you know it work? Could be the pattern?

Could be the pattern, some require you to edit it to put in the size of the matrix you are using, so it understands height/width.

In your case, looks like 5 height and 22 wide

Since Ben’s recent update of the code to add transformation, many of the existing 2D patterns could use an update to the newer ways of handling things. I’d say try a bunch, figure out which work as expected, and then make a list of the ones that don’t (and the ones that do) and post the list. Some of us might take a look and figure out what needs an update.

Please remember, this forum is all volunteers. We’re often happy to help, but at the end of the day, learning how this works for your particular setup (especially non standard layouts, not 8x8 or 16x16, etc) and how to tweak it to work right will take some learning how this stuff works.

1 Like

@Changchung ,
Your preview doesn’t look very uniform, but I can’t tell if it actually looks that way in the picture you used to map. It should be mostly OK for patterns even if it’s a little off.

If you post the image you used to map, and the text of your pixel map coordinates, any of us can put these into the pixel mapper tool and help troubleshoot the map itself.

Pixelblaze V2 didn’t ship with many patterns that used render2D and could take advantage of the pixel map. Give it a try with “cube fire”, or some of the 2D patterns from the pattern site. Very old 2D patterns calculated the coordinates via pattern code, and assumed regular matrix configurations so won’t work with your sign. Look for “render2D” in the code.


Thanks Ben. Here is the picture and code that I am getting.



Hmm, I think the forum might have resized your image - it’s only showing up at 1920x662 pixels. If I double it, it’s close, but not quite. Whats the resolution of your source image?

It looks like the clicks/points aren’t on-center. The back of the D looks off a bit. Still, it’s close enough you’ll get some nice 2D effects from it. You could try mapping it again, just be sure to click right in the center of the LED each time - undo if needed to adjust.

1 Like

I am getting this with the firecube after saving the map code.

That looks correct to me.

Try this code

That’s not in the pattern library (yet), but does the KITT scan with 2D. Compare that to the normal KITT pattern (which would trace out each letter back and forth)