2.5.1.5 Image Maps

When all else fails and none of the above pigment pattern types meets your needs you can use an image_map to wrap a 2-D bit-mapped image around your 3-D objects.

2.5.1.5.1 Specifying an Image Map

The syntax for an image_map is:

IMAGE_MAP:
    pigment
    {
        image_map
        {
            [BITMAP_TYPE] "bitmap[.ext]"
            [IMAGE_MAP_MODS...]
        }
        [PIGMENT_MODFIERS...]
    }
BITMAP_TYPE:
    gif | tga | iff | ppm | pgm | png | jpeg | tiff | sys
IMAGE_MAP_MOD:
    map_type Type | once | interpolate Type | 
    filter Palette, Amount | filter all Amount |
    transmit Palette, Amount | transmit all Amount

After the optional BITMAP_TYPE keyword is a string expression containing the name of a bitmapped image file of the specified type. If the BITMAP_TYPE is not given, the same type is expected as the type set for output.
Example:

  plane {
    -z,0 
    pigment {
      image_map {png "Eggs.png"}
    }
  }

  plane {
    -z,0 
    pigment {
      image_map {"Eggs"}
    }
  }

The second method will look for, and use "Eggs.png" if the output file type is set to be png (Output_File_Type=N in INI-file or +FN on command line). It is particularly useful when the image used in the image_map is also rendered with POV-Ray.

Several optional modifiers may follow the file specification. The modifiers are described below.

Note: earlier versions of POV-Ray allowed some modifiers before the BITMAP_TYPE but that syntax is being phased out in favor of the syntax described here.

Note: sys format is a system-specific format such as BMP for Windows or Pict for Macintosh.

Filenames specified in the image_map statements will be searched for in the home (current) directory first and, if not found, will then be searched for in directories specified by any +L or Library_Path options active. This would facilitate keeping all your image maps files in a separate subdirectory and giving a Library_Path option to specify where your library of image maps are. See "Library Paths" for details.

By default, the image is mapped onto the x-y-plane. The image is projected onto the object as though there were a slide projector somewhere in the -z-direction. The image exactly fills the square area from (x,y) coordinates (0,0) to (1,1) regardless of the image's original size in pixels. If you would like to change this default you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired.

In the section "Checker", the checker pigment pattern is explained. The checks are described as solid cubes of colored clay from which objects are carved. With image maps you should imagine that each pixel is a long, thin, square, colored rod that extends parallel to the z-axis. The image is made from rows and columns of these rods bundled together and the object is then carved from the bundle.

If you would like to change this default orientation you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired.

The file name is optionally followed by one or more BITMAP_MODIFIERS. The filter, filter all, transmit, and transmit all modifiers are specific to image maps and are discussed in the following sections. An image_map may also use generic bitmap modifiers map_type, once and interpolate described in "Bitmap Modifiers"

2.5.1.5.2 The Filter and Transmit Bitmap Modifiers

To make all or part of an image map transparent you can specify filter and/or transmit values for the color palette/registers of PNG, GIF or IFF pictures (at least for the modes that use palettes). You can do this by adding the keyword filter or transmit following the filename. The keyword is followed by two numbers. The first number is the palette number value and the second is the amount of transparency. The values should be separated by a comma. For example:

  image_map {
    gif "mypic.gif"
    filter   0, 0.5 // Make color 0 50% filtered transparent
    filter   5, 1.0 // Make color 5 100% filtered transparent
    transmit 8, 0.3 // Make color 8 30% non-filtered transparent
  }

You can give the entire image a filter or transmit value using filter all Amount or transmit all Amount. For example:

  image_map {
    gif "stnglass.gif"
    filter all 0.9
  }

Note: early versions of POV-Ray used the keyword alpha to specify filtered transparency however that word is often used to describe non-filtered transparency. For this reason alpha is no longer used.

See section "Specifying Colors" for details on the differences between filtered and non-filtered transparency.

2.5.1.5.3 Using the Alpha Channel

Another way to specify non-filtered transmit transparency in an image map is by using the alpha channel. POV-Ray will automatically use the alpha channel for transmittance when one is stored in the image. PNG file format allows you to store a different transparency for each color index in the PNG file, if desired. If your paint programs support this feature of PNG you can do the transparency editing within your paint program rather than specifying transmit values for each color in the POV file. Since PNG and TGA image formats can also store full alpha channel (transparency) information you can generate image maps that have transparency which is not dependent on the color of a pixel but rather its location in the image.

Although POV uses transmit 0.0 to specify no transparency and 1.0 to specify full transparency, the alpha data ranges from 0 to 255 in the opposite direction. Alpha data 0 means the same as transmit 1.0 and alpha data 255 produces transmit 0.0.