Image Copy: imf

Image Copy: imf_copy

The image copying and conversion utility for mental ray. It supports all image formats and types that mental ray generates, and can convert between them. Furthermore, image pyramids for texture filtering can be created and stored in appropriate texture format files.

Usage

The image copy utility is started as

imf_copy [options] infile outfile [outformat[outtype]]

The file infile will be copied to outfile using the file format outformat and the data type outtype. If no output format is specified then the file name extension of outfile is used to determine the format. If no output type is given then the default data type of the file format will be taken. The map format is especially suitable for creating memory-mapped or tile-based texture images.

Options

These options are supported:

-B: For .map files, write in big-endian byte order. Map files must have the byte order of the rendering host to be effective. Intel x86-class processors are little-endian; most others are big-endian. Default is the byte order of the current machine.
-c: For .map files, collate up to 20 input files to form an image pyramid. This option gives control over the image pyramid, unlike the -p option which automatically creates each successive pyramid level at one-half the resolution of the preceding one, using a box filter. The first input image should have full resolution, the next one approximately one-half width and height, the next one approximately one quarter, and so on.
-e: When re-sampling a format to another with fewer bits per component, perform error diffusion instead of truncation.
-f filter_scale_scalar: For .map files, store the filter scale value in the texture file. Memory-mapped texture files always override the filter value specified in the color texture statement or with mi_api_texture_set_filter.
-g gamma_scalar: Perform gamma correction with the given gamma factor. The default is 1.0.
-h: Print brief help text.
-k compression: For OpenEXR files, set the compression method to one of the following: none, piz, zip, rle, pxr24. Default is rle.
-L: For .map files, write in little-endian byte order. Map files must have the byte order of the rendering host to be effective. Intel x86-class processors are little-endian; most others are big-endian. Default is the byte order of the current machine.
-p: Create a pyramid texture, consisting of a sequence of progressively smaller filtered versions of the same image stored in one file. This allows faster texture anti-aliasing, see pyramid textures. Typically, a smaller version of the image is created from the next higher level by averaging 4 pixels using a simple box filter.
-q quality_int: For JPEG files, set the quality factor to quality, in the range 1..100. The default is 75.
-r: For .map, TIFF, and OpenEXR files, arrange pixels in rectangular tiles instead of the normal scanline order. This increases cache efficiency and reduces memory usage when rendering.
-t W[xH]: For .map, TIFF, and OpenEXR files, when written in tiled format use the specified tile size of WxH (width x height) pixels. If just one value is given then quadratic tiles of size WxW will be created. The size of the tiles has impact on the performance and efficiency of the mental ray texture cache during rendering. The default is 128x128.
-v: Print verbose progress messages and version banner.
-x N: For .map files, extract level N from a pyramid file. The first (and largest) level is 0; the highest is 19. This can be seen as the reverse operation to -c, but it also works with pyramids created with -p.

Example

mental ray can read and write a lot of image file formats and use them as textures without further preparation. This typically involves decoding and potential decompression for any texture access, having quite some impact on overall rendering performance. This tool can be used to convert an image to a texture format that is optimized for rendering with mental ray on the local machine. The following command will store image data uncompressed and ready for fast memory mapping:

imf_copy image.tif texture.map

Since mental ray does not depend on the file name extension to determine a texture format, the target file name can be custom and still use the .map format. Like:

imf_copy image.tif texture.tx map

Note Some systems may recognize the .map file extension as a system file.

The original file names may even be re-used after conversion to avoid touching the scene to render:

imf_copy image.tif converted/image.tif map

Note Most external image tools depend on a correct the file name extension to indicate its content. The above command will create files where this rule is not respected, on purpose.

Normally, texture filtering will be performed during rendering only, on demand. If filtering is known to be exploited anyway then pre-filtering can help to speed up rendering later. This command will filter the image down into pieces with smaller resolutions, and store these sub-images as a pyramid into a single texture file (thus becoming larger in file size):

imf_copy -p image.tif texture_pyramid.map

imf_info -l texture_pyramid.map

 width height comp bits gamma line  type     format   file
  2048   2048    3    8     1   up  rgb      map      texture_pyramid.map
  1024   1024    3    8
   512    512    3    8
   256    256    3    8
   128    128    3    8
    64     64    3    8
    32     32    3    8
    16     16    3    8
     8      8    3    8
     4      4    3    8
     2      2    3    8
     1      1    3    8

3.11 This command can be used to create standard image pyramids in TIFF and OpenEXR formats (similar to the exrmaketiled command). They will work in mental ray as well as in other third-party renderers.

mental ray's texture caching mechanism - the alternative to memory mapping - allows to handle the increasing demand for more higher resolution textures very efficiently, even on platforms with limited memory resources. For this to work, textures need to be pre-separated into rectangular tiles rather than stored as one large image. The following command will create a tiled texture version of the original image using the default tile size that is best suitable in most cases:

imf_copy -r image.tif texture_tiled.map

imf_info texture_tiled.map

 width height comp bits gamma line  type     format   file
  2048   2048    3    8     1   up  rgb      (re)map  texture_tiled.map
  5402    812    3    8 (remapped)

3.11 This command can be used to create tiled textures in TIFF and OpenEXR formats (similar to the exrmaketiled command). They will work in mental ray as well as in other third-party renderers that support it. Like in this example, where a specific tile size is enforced to optimize for a capable computer environment and larger texture resolutions:

imf_copy -r -t 256 image.tif texture_tiled.exr

exrheader texture_tiled.exr

file format version: 2, flags 0x200
channels (type chlist):
    B, 16-bit floating-point, sampling 1 1
    G, 16-bit floating-point, sampling 1 1
    R, 16-bit floating-point, sampling 1 1
...
tiles (type tiledesc):
    single level
    tile size 256 by 256 pixels