.. _Concepts/ImageInfo:

ImageInfo
=========

Overview
--------

A :class:`Draft.ImageInfo` object is used to specify on write and retrieve on read the image's compression, quality, tile size and :class:`~Draft.Timecode`, when applicable.

Implementation Details
----------------------

Besides the image's channel data type described in the section :ref:`Concepts/ImageFileChannelMap` in Concepts, other image saving settings can be controlled. Unlike the file channel map, those saving settings are not associated with a :class:`Draft.Image` but with a :class:`Draft.ImageInfo`. An :class:`~Draft.ImageInfo` stores those saving settings using the four properties: :attr:`~Draft.ImageInfo.compression`, :attr:`~Draft.ImageInfo.quality`, :attr:`~Draft.ImageInfo.tileSize` and :attr:`~Draft.ImageInfo.timecode`. 

To specify the saving settings, you can simply set those properties in an :class:`~Draft.ImageInfo` and pass that :class:`~Draft.ImageInfo` as an additional parameter in the function :meth:`~Draft.Image.WriteToFile`.

To retrieve the saving settings, you can pass an :class:`~Draft.ImageInfo` as an additional parameter in the function :meth:`~Draft.Image.ReadFromFile` and the fields in :class:`~Draft.ImageInfo` will be automatically populated. Those fields can then be easily queried.

.. _Concepts/ValidCompressionReference:

Valid Compression Values
~~~~~~~~~~~~~~~~~~~~~~~~

Valid values for compression are summarized in the following table.

===========     ==============================================================================
File Format     Valid compression
===========     ==============================================================================          
EXR             'none', 'rle', 'zip', 'zips', 'piz', 'pxr24', 'b44', 'b44a', 'dwaa' and 'dwab'
GIF             'lzw'
HDR             'rle'
JPEG/JPG        'jpeg'
PNG             'zip'
TGA             'none' and 'rle'
TIF/TIFF        'none', 'jpeg', 'lzw', 'rle' and 'zip'
===========     ==============================================================================

The property compression defaults to ‘default’ which corresponds to the file format default. 

Valid quality values are integer value in the range [0..100]. The property quality defaults to None and is only valid for format EXR and JPEG/JPG. 

Note that the mapping between Draft and OpenEXR DWA quality is done using an exponential regression to fit the three points proposed by Karl Rasche (creator of DWA). See: https://lists.nongnu.org/archive/html/openexr-devel/2014-08/msg00049.html

Valid tileSize values are tuples of size 2 of strictly positive integers. The property tileSize default to None which corresponds to non-tiled image and is only valid for the file format EXR.

Please, consult the section :ref:`Concepts/Timecode` in Concepts for valid timecodes values.

Relevant Cookbook Recipes
-------------------------

* :ref:`Basic/SetSavingSettingsInImageFile`
* :ref:`Basic/EmbedTimecodeInImageFile`
* :ref:`Intermediate/EmbedTimecodeInVideoFile`



