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.

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

{
  "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" : {
  }
}

{
  "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" : {
  }
}

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!

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.

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!