3.3 Using the Texture Optimizer - tdlmake

tdlmake preprocesses TIFF, PNG, JPEG, GIF, IFF(5), SGI, PIC(6), PSD(7), TGA(8), "bake," RADIANCE and OpenEXR files to convert them into an efficient texture format suitable to 3Delight. It can also convert a `zfile' into a shadow map. We recommend running tdlmake on all textures before rendering, for two reasons:

• tdlmake creates a mipmapped version of the original texture, allowing 3Delight to produce nicer images more efficiently.
• 3Delight employs a caching mechanism for texture data which works well with tiled images. Using raw (striped) non-converted TIFFs may degrade overall performance.

Note that a converted file is a normal TIFF that can be viewed with any image viewer. We suggest using a `.tdl' extension for 3Delight texture files.

Command Line Options

tdlmake is invoked by specifying at least two file names and an optional set of command-line switches:

% tdlmake [options] input.tif [input2.tif ... input6.tif] output.tif

Valid options are:

` -envlatl'

Generates a latitude-longitude environment map.

` -envcube'

Generates a cubic environment map. Needs six images in input, ordered as follows: +x, -x, +y, -y, +z, -z.

` -twofish'

Generates a cubic environment map from two images taken with a circular fisheye lens. The first image is taken to be +z and the second -z.

` -lightprobe'

Generates a cubic environment map from a 360 degree fov lightprobe.

` -dirtex'

Creates a "directory texture". A directory texture (or "dirtex" in short) consists of a series of TIFF files save in a directory, along with an index file. The main advantage of such textures is to have a finer granularity of data transfer when using the network cache. Please refer to Network Cache for more about directory textures.

` -skymap s'

Generates a latlong environment map that is a representation of a sky as seen from the given position and the given time. The parameter to `-skypmap' is a comma separated list of six arguments specifying: `latitude,longitude,timezone,julian day,time,turbidity'. Ranges for each parameter are:

` latitude'

` longitude'

These two coordinates specify the location of the observer, in degrees.

` timezone '

This is the standard time zone indicator. Starting at 0 and ending at 12.

` Julian day'

Day of the year, from 0 to 365.

` time'

Time of the day. `6:30 PM' is `18.5'.

` turbidity '

This is a measure of "haziness" ranging from 2 to 10. A value of 2 will give a clear day and a value of 10 will give a very hazy skylight.

An example command line would be:

% tdlmake -skymap 42,74,5,10,12.5,4 daylight.tdl

` -shadow'

Generates a shadowmap from a zfile. When generating a shadowmap, only the `-c-' option is functional.

` -lzw'

Compresses output texture using LZW algorithm. This option is enabled by default since compressed textures take much less space and there is no noticeable speed penality when accessing them.

` -deflate'

Compresses output texture using the Deflate algorithm. Has a better compression ration than LZW.

` -packbits'

Compresses output texture using Apple's PackBits algorithm. Compression ratio is not as good as with LZW or Deflate but decompression is very fast.

` -c-'

Does not compress output texture.

` -separateplanes'

Writes the output TIFF with separate color planes instead of interleaved colors. This may help compatibility with some software packages.

` -fov n'

Specifies a field of view, in degrees, for cubic environment maps. Default is `90' degrees.

` -mode <black|clamp|periodic>'

` -smode <black|clamp|periodic>'

` -tmode <black|clamp|periodic>'

Specifies what action should be taken when accessing a texture (using texture() or environment()) outside its defined parametric range (s, t = [0..1]).

` black'

Sets texture to black outside its parametric range.

` clamp'

Extends texture's borders to infinity.

` periodic'

Tiles texture infinitely.

`-smode' and `-tmode' specify the wrapping modes of the texture in s or t only. Default mode is `clamp' for normal textures and `periodic' for latitude-longitude environment maps. Note that while the effects of this option are noticeable mostly when using texture() or environment() from inside a shader, it also slightly changes how the mipmaps of the texture are computed.

` -filter <box|triangle|gaussian|catmull-rom|bessel|mitchell|sinc>'

Specifies a downsampling filter to use when creating mipmap levels. The default filter is `sinc'. All supported filters, along with their `filterwidth' and window defaults, are shown in Table 3.1.

Table 3.1: tdlmake filters.

filter filterwidth window Comment box 1.0 - This filter tends to blur textures. Use only if texture generation speed is an issue. triangle 2.0 - `filterwidth' larger than 2.0 is unnecessary. gaussian 2.50 - A good filter that might produce slightly blurry results, not as much as the box filter though. catmull-rom 4.0 - A better filter (producing sharper textures). bessel 6.47660 `lanczos' Filter width chosen in order to include 2 roots. sinc 8.0 `lanczos' We recommend this high quality filter as the best choice. Although it can produce some ringing artifacts on some textures. Using a `filterwidth' smaller than 4 is not recommended.

` -window <lanczos|hamming|hann|blackman>'

Applies a windowing function to `bessel' and `sinc' filters (which are infinite in width) to achieve a softer cut at the filter's support boundaries. Possible windowing functions are `lanczos', `hamming', `hann' and `blackman'. By default, no function is applied.

` -filterwidth n'

Overrides the default filter width in s and t.

Important

Filter's width is the diameter of the filter and not the radius.

` -sfilterwidth n'

` -tfilterwidth n'

Overrides the default filter width in s or t, respectively.

` -blur n'

Blurs or sharpens the output image. Values larger than `1.0' make the image more blurry and values smaller than `1.0' give sharper looking textures. This function works by scaling the filter function by the specified value. This is not the same thing as scaling `filterwidth'. Default is `1.0'.

` -scale n'

Scales down the output image. Values larger than `1.0' or smaller than `0.0' are not accepted. Default is `1.0'.

` -preview n'

Adds a preview image to the texture. The preview is the first image in the TIFF file and is written in a format which is readable by most software, unlike the mipmaps 3Delight uses. The argument is interpreted as an absolute size for the preview if greater than 1 and as a relative size otherwise.

` -preview8 n'

Does the same as -preview except that the preview image is always 8-bit. This makes it smaller and potentially more compatible with some software.

` -quality <low|medium|high>'

Controls mipmap downsampling strategy: when using `low', each mipmap level is created from the previous one. At `medium' quality, each level is created from the 2nd previous level. At `high' quality, each level is created from up to the 4th previous level. The default `medium' setting is more than enough for most applications.

` -flips'

` -flipt'

Flips the image horizontally or vertically, respectively.

` -flipst'

Flips the image in both directions.

` -bakeres n'

Specifies the output image resolution when converting `.bake' files to a texture map. Note that a `.bake' file can be of any resolution but is of the same width and height.

` -forcecolor'

Force greyscale input to be expanded to RGB.

` -gamma n'

Indicates the gamma of the input image. This allows tdlmake and 3Delight to convert the texture to a gamma of 1.0 before performing computations on it.

` -rgbagamma n n n n'

Indicates the gamma of each red, green, blue and alpha channel of the input image. This allows tdlmake and 3Delight to convert the texture to a gamma of 1.0 before performing computations on it.

` -colorspace <linear|srgb|BT.709>'

Indicates the color space of the input image (linear, sRGB or BT.709). This allows tdlmake and 3Delight to convert the texture to a linear space before performing computations on it.

` -byte or -ubyte'

Forces the output to be 8-bit unsigned data.

` -sbyte'

Forces the output to be 8-bit signed data.

` -ushort'

Forces the output to be 16-bit unsigned data.

` -short or -sshort'

Forces the output to be 16-bit signed data.

` -float'

Forces the output to be floating point data.

` -pixelaspectratio'

Specifies the aspect ratio of the pixels. This can be retrieved with textureinfo() (see textureinfo shadeop).

` -imageaspectratio'

Specifies the aspect ratio of the image. A pixel aspect ratio is computed from this value.

` -newer'

If the destination texture already exists, regenerates it only if one of the input textures is newer than the destination.

` -nomipmap'

By default, tdlmake creates mipmapped textures that are suitable for efficient and high quality texture mapping. This option turns this feature off and is not recommended.

` -progress'

Shows texture creation progress, only useful for really large textures (or really slow computers!).

` -v'

Prints version and copyright information.

` -h'

Shows help text.

Supported Input Formats

tdlmake supports most of the common formats used in a production environment:

TIFF

tdlmake supports stripped or tiled TIFFs with 1 to 6 channels. Suppported data types are:

• 1, 4, 8, 16 or 32 bits of unsigned integer data
• 8, 16 or 32 bits of signed integer data
• 32 bits of floating point data

Unsigned single channel images (grayscale or b&w) can have either MINISBLACK or MINISWHITE photometric. Either way, the output file (`.tdl') is MINISBLACK. Signed files are required to have either RGB or MINISBLACK photometric. Files with less than 8 bits per sample are promoted to 8 bits per sample in the output. Otherwise, the output format is the same as the input. LogLuv encoded TIFFs are supported and are kept in their LogLuv form when processed. TIFFs with JPEG compression are not supported.

IFF files from Maya software

Both RGB and RGBA formats are supported.

PNG files are supported (all formats and bit depths).

SGI files from Maya software

GRAYSCALE, GRAYSCALE+ALPHA, RGB and RGBA formats are supported. Note that 16 bits images are not supported.

PIC files from SoftImage software

Both RGB and RGBA formats are supported.

PSD files from Abobe Photoshop software

Both GRAYSCALE and GRAYSCALE+ALPHA formats without layers are supported; both RGB and RGBA formats with or without layers are supported.

TGA files developped by Truevision Inc.

GRAYSCALE, GRAYSCALE+ALPHA, RGB, RGBA, INDEXED and INDEXED+ALPHA formats are supported.

`.bake' files

These files are generated by the bake (see bake shadeop) shadeop and are converted to a floating point, mipmapped, TIFF file. Output resolution can be specified using the `-bakeres' option.

JPEG

8 bit (grayscale) and 24 bit JPEGs are supported.

Radiance Picture Format

Files produced by Radiance(9) are supported. Both XYZE and RGBE encoding modes are recognized by tdlmake. Run-length encoded files are also supported. Note that there is a restriction on image orientation: only -Y +X orientation is correctly recognized, any other orientation is reverted to -Y +X. This is not a major problem since it can be corrected by using `-flips' and `-flipt' options (see tdlmake options).

OpenEXR

ILM's OpenEXR format is supported by tdlmake with the restriction that images should be in RGB or RGBA format(10).

zfile

zfiles are only used to produce shadow maps.

For cube environment maps (`-envcube'), all six images are required to be of the same file format.

Quality and Performance

As with all 3Delight tools, tdlmake was designed to fulfill the tough demands of a production environment. In this case, special attention was given to filtering quality and memory usage, without penalizing execution speed. Among other things:

• All internal filtering algorithms are executed in floating point to preserve as much accuracy as possible.
• An efficient caching system is used to keep memory usage footprint very low. tdlmake was tested on textures as large as 16K x 16K (1 Gigabyte of disk space) and accomplished its work using less than 12megs of memory.
• The filtering process has been designed to have a linear cost increase relative to `-filterwidth', unlike some software in which the cost is quadratic. For example, `-filterwidth 8' runs twice as slow as `-filterwidth 4'.

Working with Large Textures

As mentioned, tdlmake has been designed to adapt very well to huge textures. One exception is compressed TIFFs that have a large "rows per strip" value. Here is an example output of tiffinfo on a large texture file that can cause problems for tdlmake:

% tiffinfo earth.tif
  Image Width: 43200 Image Length: 21600
  Resolution: 72, 72 (unitless)
  Bits/Sample: 8
  Compression Scheme: AdobeDeflate
  Photometric Interpretation: RGB color
  FillOrder: msb-to-lsb
  Software: "ImageMagick 5.5.7 07/22/03 Q16 http://www.imagemagick.org"
  Document Name: "earth.tif"
  Orientation: row 0 top, col 0 lhs
  Samples/Pixel: 3
  Rows/Strip: 21600
  Planar Configuration: single image plane
  Predictor: horizontal differencing 2 (0x2)

There is only one strip, made of 21600 (total image height) rows. This means that accessing any scanline in this TIFF forces the TIFF reading library to uncompress the entire file(11). In order to lower memory usage for such large files, it is suggested that a lower "rows per strip" count be used. Typically, 16 or 32 scanlines is a good choice. tdlmake prints a warning if it encounters a file that has the aforementioned "problem":

tdlmake: warning, reading texture 'earth.tif' may take a large
tdlmake: amount of memory. Please refer to user's manual if you are
tdlmake: unable to convert this file.

Examples

Here are some examples using tdlmake on the command line:

To create a texture named `grid.tdl' from a TIFF named `grid.tif' using a gaussian downsampling filter of width 4:

% tdlmake -filter gaussian -filterwidth 4 grid.tif grid.tdl

To create a cubic environment map in which all cube sides were rendered using 90 degrees field of view:

% tdlmake -fov 90 -envcube \
  in1.tif in2.tif in3.tif in4.tif in5.tif in6.tif \
  envmap.tdl  

or (won't work in a DOS shell) :

% tdlmake -fov 90 -envcube in?.tif envmap.tdl

To create a texture using the high quality downsampling mode and show progress while doing so:

% tdlmake -progress -quality high grid.tif grid.tdl

To create a shadow map from a zfile (The zfile display driver):

% tdlmake -shadow data.z shadowmap.tdl

3Delight 10.0. Copyright 2000-2011 The 3Delight Team. All Rights Reserved.