Reference:Image Map

When all else fails and none of the 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.

Specifying an Image Map

The syntax for an image_map is:

IMAGE_MAP:
 pigment {
   image_map {
     [BITMAP_TYPE] "filename" [gamma GAMMA] [premultiplied BOOL]
     [IMAGE_MAP_MODS...]
     }
 [PIGMENT_MODFIERS...]
 }
IMAGE_MAP:
 pigment {
  image_map {
    FUNCTION_IMAGE
    }
 [PIGMENT_MODFIERS...]
 }
BITMAP_TYPE:
  exr | gif | hdr | iff | jpeg | pgm | png | ppm | sys | tga | tiff
GAMMA:
  Float_Value | srgb | bt709 | bt2020
IMAGE_MAP_MODS:
  map_type Type | once | interpolate Type | 
  filter Palette, Amount | filter all Amount |
  transmit Palette, Amount | transmit all Amount
FUNCTION_IMAGE:
  function I_WIDTH, I_HEIGHT { FUNCTION_IMAGE_BODY }
FUNCTION_IMAGE_BODY: 
  PIGMENT | FN_FLOAT | pattern { PATTERN [PATTERN_MODIFIERS] } 

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.

For 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: The sys format is a system-specific format. See the Output File Type section for more information.

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

The Gamma Option

The default gamma handling rules for any image input file can be overridden by specifying gamma GAMMA immediately after the file name. For example:

image_map {
  jpeg "foobar.jpg" gamma 1.8
  interpolate 2
  }

Alternatively to a numerical value, srgb may be specified to denote that the file is encoded or pre-corrected using the sRGB transfer function instead of a power-law gamma function. New in version 3.8, other valid special values are bt709 and bt2020, denoting that the file is encoded or pre-corrected using the ITU-R BT.709 or BT.2020 transfer function, respectively.

See section Gamma Handling for more information on gamma.

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 the section Color Expressions for details on the differences between filtered and non-filtered transparency.

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 some 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.

Note: In version 3.7 alpha handling for image file output has changed. Effectively, the background now requires a filter or transmit value in order for alpha transparency to work properly.

Previous versions of POV-Ray always expected straight (aka non-premultiplied) alpha for file input, this has been changed in v3.7 on a per-file-format basis as follows:

• PNG will use straight alpha as per specification.
• OpenEXR will use associated (ala premultiplied) alpha as per specifications.
• New as of version 3.8, TIFF will use straight or associated alpha as per the file header (v3.7.0 expected associated alpha).
• TGA and BMP 32-bit RGBA will use straight alpha, retaining file input compatibility for now, until a final decision has been made on these formats.

Additionally the premultiplied parameter may be used to specify the input image alpha handling. This boolean parameter specifies whether the file is stored in premultiplied associated or non-premultiplied straight alpha format, overriding the file format specific default. This keyword has no effect on files without an alpha channel. Like the gamma, it MUST immediately follow the filename, though the order does not matter.

Note: The following mechanism has some limitations with colored highlights.

When generating non-premultiplied alpha output to a classic low-dynamic-range file format (e.g. PNG), transparency of particularly bright areas will now be reduced, in order to better preserve highlights on transparent objects.

Note: When using an input image in a material_map, bump_map, or image_pattern definition, the following conditions apply.

• For material maps, no alpha premultiplication handling is done whatsoever, instead the data as stored in the file is used.
• For bump maps and image patterns, images with an alpha channel are treated as if they had a black background, unless the alpha channel itself is used.

Note: See also background and sky_sphere for additional information.

New as of version 3.8, using filter all and transmit all on an image file with an alpha channel is now supported properly (requires #version 3.8 or higher).