[size=150]Working with File Channel Map[/size]
A file channel map is associated with a Draft.Image and is used to specify on write and retrieve on read the bit depth and type of the image channels. A file channel map is represented using a dictionary. Each dictionary entry is made of two strings separated by a colon. The first string corresponds to the channel name, typically ‘R’, ‘G’, ‘B’ and ‘A’, and the second string corresponds to the channel bit depth. An ‘ui’ is appended to the bit depth string to specify that the channel represents an index and an ‘f’ to specify that the channel is of type float. Such a string represents a channel data type. Here are some common valid channel data types: ‘8’, ‘16’, ‘16f’, ‘32f’ and ‘32ui’. When Draft creates an image or add a new channel to an existing image, a default file channel data type of ‘8’ is assigned to the new channel(s).
The file channel map associated to a Draft.Image can be manipulated using the two functions SetFileChannelMap() and GetFileChannelMap().
- A dictionary representing a file channel map can be passed to the function SetFileChannelMap() to set the file channel map of a Draft.Image. Note that the dictionary must contain one entry for each channel present in the Draft.Image and for those channels only. An error will be thrown otherwise.
- A dictionary is returned by the function GetFileChannelMap() to retrieve the current file channel map of a Draft.Image.
Internally, Draft is still storing image channel data using 32 bit floats.
Usage:
- To write an EXR image file with a specific file channel map -
image = Draft.Image.ReadFromFile( '//path/to/in.exr' )
fileChannelMap = { 'R':'16f', 'G':'16f', 'B':'16f', 'A':'16f', 'ID':'32ui' }
image.SetFileChannelMap( fileChannelMap )
image.WriteToFile( '//path/to/out.exr' )
- To retrieve the file channel map associated to an EXR image file -
image = Draft.Image.ReadFromFile( '//path/to/in.exr' )
fileChannelMap = image.GetFileChannelMap()
It is important to understand that each file format only supports specific bit depth and type. Here’s a list of the valid channel data types supported by Draft for common file formats:
BMP: ‘8’
CIN: ‘10’
DPX: ‘8’, ‘10’, ‘12’, ‘16’
EXR: ‘16f’, ‘32f’, ‘32ui’
GIF: ‘8’
HDR: ‘16’
JPEG/JPG: ‘8’
PNG: ‘8’, ‘16’
TGA: ‘5’*, ‘8’
TIF/TIFF: ‘8’, ‘16’
While Draft supports specifying the file channel map for other file formats, correct resulting images written with requested bit depths are not guaranteed.
For more information, you can also consult the Image section of the Draft documentation. The pdf and the zipped html versions of the documentation can be downloaded from this thread’s initial post.
- Writing a TGA image file with a channel data type of ‘5’ corresponds to ImageMagick’s 16-bit TGA – 5*3 + 1.