The POV-Ray Cyclopedia

Image Maps have been known to cause some confusion in new POVers and this document is the first of a series to explain them better.

Setting up
Using an image_map

  Lets look at the basic no frills planar image map pigment:

box { <0,0,0> <1,1,0.01>
      pigment { image_map 
                { gif "plasma3.gif" // file type and file name
                  map_type 0 // 0=planar
                  interpolate 2 // bilinear
                 } } }

  The first line of the image map statement is simply the file type and the file name. You should keep the image file in the same folder as the scene file or in your Include directory for POV-Ray. (I keep mine in the same folder as the scene file, myself. It makes for easier file managment.) The second line tells POV that it is a planar map, so that the image will be mapped onto the object in a specified method.

  The Image is forced to fit in a box from <0,0,0> to <1,1,0> and it will repeat along the x-y plane indefinitly. Any plane parallel to the x-y will display the image the same way, and scaling by the z axis before any transformation is futile at this point.

  Of course the once keyword will prevent the image from repeating forever, and we can play with this like any other pigment.

  As for the two images to the right: The top one is a thumbnail of a lager picture I sketched out called "Every Wizard Enjoys a Good Pipe." It has a 5 by 7 aspect ratio. The second image is a square detail of part of the image.

The Full Image
The Full Image
Square Detail
A Square detail
Part Two
Trying the code

  Now when we plug both images into the image_map code we get images 1 and 2. Image 1 uses the square detail, while image 2 uses the full image. Notice how it's streched out or proportion.

  Remember that the planar image map takes the image, no matter what it's proportions, and forces it into a box from <0,0,0> to <1,1,0> So we have a couple of choices to fix this. Depending on what I need. If the width is important and I want to keep it 1 unit wide and height isn't important I can use the following code:

box { <0,0,0> <1,1,0.01>
      pigment { image_map 
                { gif "plasma3.gif" // file type and file name
                  map_type 0 // 0=planar
                  interpolate 2 // bilinear
                 } }
      scale <1,7/5,1> }
  Notice the placement of the scale keyword. It is after the pigment statement is closed to effect both the pigment and the shape of the box. On the other hand, if I want to keep the height restricted to 1 unit, I use the following:
box { <0,0,0> <1,1,0.01>
      pigment { image_map 
                { gif "plasma3.gif" // file type and file name
                  map_type 0 // 0=planar
                  interpolate 2 // bilinear
                 } } 
      scale <5/7,1,1> }
  These two are shown in Image3. They have the same ratio and they look normal.

You want to avoid the pifalls in Image4. (Sorry for the small size, I'm trying to save space)

// Upper Left Image
box { <0,0,0> <1,7/5,0.01>
      pigment { image_map { tga "wiz_lg.tga" 
                            map_type 0 
                            interpolate 2 } } }
// Upper Right Image
box { <0,0,0> <5/7,1,0.01>
      pigment { image_map { tga "wiz_lg.tga" 
                            map_type 0 
                            interpolate 2 } } }
// Lower Left Image
box { <0,0,0> <1,1,0.01>
      pigment { image_map { tga "wiz_lg.tga" 
                            map_type 0 
                            interpolate 2 } 
                scale <1,7/5,1> }
      }
//Lower Right Image
box { <0,0,0> <1,1,0.01>
      pigment { image_map { tga "wiz_lg.tga" 
                            map_type 0 
                            interpolate 2 } 
                scale <5/7,1,1> }
      }
  You should see the four common pitfalls with the planar image. Going clockwise from the upper left image: 1)Creating the box at the correct aspect ratio by scaling it up, but not scaling the image. 2) Creating the box at the correct aspect ratio by making it thinner. 3) Scaling the image to the correct aspect ratio, but not the box. 4) Scaling the image by shrinking the width but not scaling the box.

  These are the common mistakes that plague the image map. Remember to make the unit box, then add the image map pigment and then do your transformations. This is the easiest way in most cases because you only need to do one transformation on the object.

Square Detail
1. The Mapped Detail
The Full Image
2. The Mapped Full Image
The Full Image
3. The Corrected Full Image
The Full Image
3. Four Pitfalls

Send feedback, or head back to the Cyclopedia.

Thanks for watching.