.. _Basic/EmbedTimecodeInImageFile:

Embed a Timecode in an Image File 
=================================

Problem
-------

You want to embed a :ref:`timecode <Concepts/Timecode>` in an image file.

Solution
--------

::

    import Draft

    # Read an image from file
    image = Draft.Image.ReadFromFile( '//path/to/in.dpx' )
    
    # Create a Draft.Timecode object
    timecode = Draft.Timecode( '12:40:10:15' )
    
    # Create a Draft.ImageInfo object and set the timecode property
    imageInfo = Draft.ImageInfo()
    imageInfo.timecode = timecode
    
    # Write the image back to file
    image.WriteToFile( '//path/to/out.dpx', imageInfo )

Discussion
----------

In the above example, we decided to embed a timecode in a DPX image file. Alternatively, it is possible to embed a timecode in an EXR image file. Note that those two file formats are the only one for which embedding a timecode is possible. The line::

    timecode = Draft.Timecode( '12:40:10:15' )

creates a :class:`~Draft.Timecode` object representing a non-drop frame timecode. It is also possible to create a timecode representing a drop frame timecode using the following notation::

    timecode = Draft.Timecode( '12:40:10;15' )

Once you have created a valid :class:`~Draft.Timecode` object, you need to create a :class:`~Draft.ImageInfo` object and set its timecode property in the following way::    

    imageInfo = Draft.ImageInfo()
    imageInfo.timecode = timecode
 
Finally, you add the imageInfo as an additional parameter when the file is written to file::

    image.WriteToFile( '//path/to/out.dpx', imageInfo )
    
Alternatively, you can retrieve a timecode previously embedded into an image file using::

    imageInfo = Draft.ImageInfo()
    image = Draft.Image.ReadFromFile( '//path/to/in.exr', imageInfo )
    timecode = imageInfo.timecode

See Also
--------

For more information on the import statement, :meth:`~Draft.Image.ReadFromFile` and :meth:`~Draft.Image.WriteToFile`, see the :ref:`Basic/CreateAnImage` section of this Cookbook.

You can consult the sections :ref:`Concepts/Timecode` in Concepts and :ref:`Intermediate/EmbedTimecodeInVideoFile` in the Intermediate Cookbook.