Texture Mapping Fundamentals

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.

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.

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.

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.

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!

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.

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.

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.

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!

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.

This guide was first published on Aug 25, 2019. It was last updated on Aug 25, 2019. This page (Texture Mapping Fundamentals) was last updated on Dec 05, 2019.