Overview

John Park
graphic_tfts_IMG_7679.jpg

The Adafruit MONSTER M4SK is our most user friendly eyes project to date! This guide offers practical tips for creating your own custom texture map graphics to use on the iris and sclera for your bespoke eyeballs!

Parts

Adafruit MONSTER M4SK - DIY Electronic Eyes Mask

PRODUCT ID: 4343
Peep dis! Have you always wanted to have another pair of eyes on the back of your head? Or outfit your costume with big beautiful orbs? The MONSTER M4SK
$44.95
IN STOCK
Add to Cart
JST SH 9-Pin Cable - 100mm long

JST SH 9-Pin Cable - 100mm long

PRODUCT ID: 4350
This 9-pin cable is just about 100mm / 4" long and fitted with JST-SH female connectors on both ends. Compared with chunkier JST-PH these are 1mm pitch instead of 2mm,...
$1.95
IN STOCK
Add to Cart
Lithium Ion Polymer Battery with Short Cable - 3.7V 420mAh

Lithium Ion Polymer Battery with Short Cable - 3.7V 420mAh

PRODUCT ID: 4236
Lithium ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery...
$6.95
IN STOCK
Add to Cart
Mini Oval Speaker - 8 Ohm 1 Watt

Mini Oval Speaker - 8 Ohm 1 Watt

PRODUCT ID: 3923
Hear the good news! This wee speaker is a great addition to any audio project where you need 8 ohm impedance and 1W or less of power. We particularly like...
OUT OF STOCK
Out of Stock

Either 2 of the glass lenses

Convex Glass Lens with Edge - 40mm Diameter

Convex Glass Lens with Edge - 40mm Diameter

PRODUCT ID: 3853
The eyes have it! Add this little lens to make a big expression with our Spooky Eyes demo for microcontrollers or Raspberry Pi. These are gorgeous glass (not plastic/acrylic!)...
$5.95
IN STOCK
Add to Cart

Or plastic lenses

Convex Plastic Lens with Edge

Convex Plastic Lens with Edge

PRODUCT ID: 3917
The eyes have it! Add this little lens to make a big expression with our Spooky Eyes demo for microcontrollers or Raspberry Pi. These are plastic lenses, with brilliant clarity and a...
$3.95
IN STOCK
Add to Cart

Texture Mapping Fundamentals

John Park

Quickstart

You should be familiar with the basic setup of the M4 Eyes project based on the most excellent Adafruit MONSTER M4SK guide Quickstart. Before you proceed with making your own texture maps, be sure you've got the M4Eyes.UF2 working properly using the default Hazel eyes graphics.

Customization Basics

You will also need to be familiar with the how the eye system works -- check out this Customization Basics page next. Make sure you're comfortable editing and saving the config.eye JSON file onto your M4SK and resetting the board to invoke your changes.

graphic_tfts_adafruit_products_config-eye-file.png

Preparing Graphics

Another important section to absorb from the MONSTER M4SK guide (are you noticing a trend here? It's a very important guide!) is on preparing graphics. This is important so that we are all on the same page with regard to eye anatomy and terminology.

The most critical bit being the two texture maps we'll be using, how they work, and the image file formats/sizes to use.

graphic_tfts_adafruit_products_eye-texture-diagram.png

Editing Texture Maps

Perhaps the simplest way to begin customizing the eye is to edit the colors of the example maps from the Hazel eyes graphics folder.

This way, you don't need to worry about image sizes and ratios, or the seam where the rectangular map ends meet when they're warped into the eyeball's spherical shape. You can simply open the maps into your image editor of choice, such as Photoshop, Preview.app, or GIMP, and then use the hue adjustment or colorization tools.

Editing Texture Maps

Perhaps the simplest way to begin customizing the eye is to edit the colors of the example maps from the Hazel eyes graphics folder.

This way, you don't need to worry about image sizes and ratios, or the seam where the rectangular map ends meet when they're warped into the eyeball's spherical shape. You can simply open the maps into your image editor of choice, such as Photoshop, Preview.app, or GIMP, and then use the hue adjustment or colorization tools.
graphic_tfts_iris_adj_blue.bmp

Above you'll find the color adjusted iris map I created. One nicely organized way to use it is to create a new folder on the MONSTER M4SK called blue that contains all of the same maps as the hazel folder. Then, download the iris_adj_blue.bmp map into that folder and remove the hazel iris.bmp.

You'll then edit the texture map paths in config.eye to match, like this:

Download: file 
{
  "boopThreshold" : 17500, // lower = more sensitive
  "eyeRadius"     : 125,
  "eyelidIndex"   : "0x00", // From table: learn.adafruit.com/assets/61921
  "pupilColor"    : [ 0, 0, 0 ],
  "backColor"     : [ 140, 40, 20 ],
  "irisTexture"   : "blue/iris_adj_blue.bmp",
  "scleraTexture" : "blue/sclera.bmp",
  "upperEyelid"   : "blue/upper.bmp",
  "lowerEyelid"   : "blue/lower.bmp",
  "left" : {
  },
  "right" : {
  }
}

Sclera De-grossing

The default sclera map is fantastic -- it's got just the right amount of squiggly veins and reddish cast! If you're going for a more stylized look, you may want to tone down the veins, and maybe even add in a gradient from white to gray as the orb recedes into the socket, as a sort of pronounced fake shadowing or ambient occlusion.

Again, you can download the map below, add it to your MONSTER M4SK's blue folder, and then update the config.eye to use the sclera_adj_white.bmp file.
graphic_tfts_sclera_adj_white.bmp

The sky's the limit when it comes to adjusting the iris and sclera maps. A nice way to start creating original maps is to keep them simple -- either solid colors or gradients. Here's a cartoonish, bonkers look, with a non-black pupil color dialed into the config.eye setting for good measure!

graphic_tfts_IMG_7654.jpg
graphic_tfts_iris_toon_purple.bmp
graphic_tfts_sclera_toon_stripes.bmp
Fun Fact: the two maps shown above can actually be saved as only one pixel wide! Since the only variance is vertical, the width doesn't matter! Keep this in mind later when creating maps, it's a great way to save memory.
graphic_tfts_iris_toon_purple.bmp
graphic_tfts_sclera_toon_stripes.bmp

Texture Mapping

So far we've colorized existing maps, and made simple gradients. But what about more complicated designs? Before we create those, we need to learn about 2D and 3D texture space.

Projecting Texture Space to 3D Space

You'll use flat (2D), rectangular images called texture maps to be displayed in on the spherical eyes in 3D space. You can think of it like the familiar topic of unwrapping the spherical image of the Earth -- a 3D globe -- to create a flat map or poster, which is akin to a 2D texture map.

graphic_tfts_Screen_Shot_2019-08-23_at_10.04.29_AM.png
Derrived from: map by Strebe - Own work, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=16115228

In fact, if we look at the south pole of the globe, we can see how the long, flat white section of the map projection wraps around the sphere's pole.

graphic_tfts_Screen_Shot_2019-08-23_at_10.08.32_AM.png

To take this a step further, here's what happens if we replace the Earth texture map with a single texture map of the pupil, iris, and sclera.

graphic_tfts_Screen_Shot_2019-08-23_at_10.18.55_AM.png

Two Maps

Rather than a single sphere, we can think of the M4 Eye as a set of four shells -- pupil, iris, sclera, and outer edge. The pupil and edge shells don't use texture maps, they're just solid colors, so there are really two maps we need to create for the iris and sclera.

Texture Distortion

As you may remember from school, whenever we create a map projection from 3D space to 2D space, or vice versa, there will be some amount of distortion to the image. This is what makes tiny little things such as Greenland and Antartica so huge on a Mercator projection map of the Earth!

graphic_tfts_distort_2D_fan.jpg
graphic_tfts_distort_3D_fan.jpg

From 3D to 2D

Just as in the Earth example, if we begin with an image that looks correct wrapped onto a 3D object, it will be distorted when unwrapped into 2D.

From 2D to 3D

Here, we can see the distortion in effect as we wrap a pair of grid textures from 2D to 3D.

Note, these texture maps were created to look correct in 2D space, so they appear distorted in 3D space.

Create Texture Maps

John Park

Practical Pre-distortion

The question you may now be asking is, how difficult is this? Honestly, it's not too bad! First of all, there are plenty of images that will look just fine if you create them in flat, 2D space and then let them get warped around the sphere of the eye. In fact, the realistic human iris can be created with even vertical striations in the 2D map and it looks just fine when it becomes distorted by the 3D re-mapping. Since it is an organic, semi-squiggly pattern, we're pretty forgiving of it's minor distortions when looking at it.

The greater difficulty comes when trying to do more mechanical, man-made patterns, such as mechanical cyborg eyes, alien writing patterns, sci-fi glyphs, camera-style aperture blades and so on. If we create those patterns in 2D, we won't get the results we're looking for after the transform to 3D.

Spike Eyes Example

Here's an example -- lets say we want to create four triangular spikes in the iris. Here's a pattern that makes sense when created in a flat, rectangular texture map:

graphic_tfts_iris2d.bmp

However, when the map is warped to the 3D space of the eye, they become rounded spikes. They look really cool, but what if we are really intent on having straight sided iris spikes?

One solution is warp the texture map into a circular shape, fix the triangles to once again have straight sides, and then un-warp it back into a rectangle. Let's go over it step-by-step using Photoshop. (You should be able to replicate these steps in the free and open source GIMP software as well).

Step 1. Rotate the rectangular texture map 180 degrees. This is necessary due to the direction in which Photoshop's polar coordinates distortion works.

Step 2. Set the canvas height equal to the texture map's width. In this case, 512 x 512 pixels. This will give the distortion room to warp the rectangle into a circle.

Step 3. Use the Filter > Distort > Polar Coordinates... menu item to bring up the Polar Coordinates window.

Step 4. In the Polar Coordinates window, set the option to Rectangular to Polar, then hit OK.

Step 5. The result of the distortion is the same bulging effect we saw on the M4 Eyes. Let's fix that! You can use the polygonal lasso selection tool to mask the nice, straight sided spikes and then paint out the bulging sections with yellow to match the background.

Step 6. In order to get a good result when un-warping the circle, make a rectangular marquee selection around it, keeping the selection tight to the texture. You can see here that I used guide lines to assist.

Step 7. Use the Filter > Distort > Polar Coordinates... menu to again bring up the window, but this time select the Polar to Rectangular option. Hit OK to turn the circle back into a rectangle.

Step 8. Now, you can rotate the image 180 degrees to get it back to its starting point, and then crop the canvas back to the original 512 x 128 pixels.
graphic_tfts_iris3d.bmp

Notice how the spikes all now curve inward which will make them appear straight-sided when we apply it to the 3D eyes!

graphic_tfts_IMG_7656_2.jpg

With these techniques, we can now create highly detailed texture maps that aren't distorted when applied to the M4 Eyes!

Here's a totally METAL set to try out. Have fun making your own weird and wonderful peepers!

graphic_tfts_IMG_7679.jpg
graphic_tfts_iris_chain2.bmp
graphic_tfts_sclera_scales.bmp
This guide was first published on Aug 25, 2019. It was last updated on Aug 25, 2019.