Look File Baking
================

|sparkles| **New in Katana 4**: The ``LookFileBakeAPI`` Python module now
provides facilities for baking Look Files.

Introduction
------------

The ``LookFileBakeAPI`` Python module provides facilities for baking Look
Files, and for implementing custom output formats for use with nodes that make
use of this API, such as the :kat:node:`LookFileBake` node, allowing users to
write Look Files in custom data formats other than the built-in ``.klf``
formats.

:py:class:`LookFileBakeAPI.LookFileBaker` may be used in combination with
:py:mod:`Nodes3DAPI.LookFileBaking` to create custom Look-File-baking nodes.


Output Format Plug-ins
----------------------

Registered LookFileBake output formats are listed as options for the
:kat:ui:`option.outputFormat` parameter of :kat:node:`LookFileBake` nodes.

Katana ships with two built-in output formats: :kat:ui:`as archive` (classic
``.klf`` files) and :kat:ui:`as directory` (directory containing pairs of
``.klf`` and ``.attrs`` files, one pair per pass). These output formats make
use of the ``LookFileBakeAPI`` internally.

A third output format, :kat:ui:`as USD`, is available as part of the
``Examples`` plug-ins (source code also available, see ``UsdLookFileBake.py``).
To make this format available for users to choose in :kat:node:`LookFileBake`
nodes, add the path of the ``Examples`` folder to the ``KATANA_RESOURCES``
environment variable. The USD output format is a basic example that writes
``.usda`` files.

.. note:: The USD LookFileBake output format will only be available if the USD
    library's Python modules have been added to the ``PYTHONPATH`` environment
    variable.

JSON LookFileBake Output Format Example
---------------------------------------

The JSON LookFileBake output format is a simple example to demonstrate how
LookFileBake output formats can be plugged in into Katana.

This format outputs a directory. For each pass, a JSON file containing the pass
data will be written into the directory (previously specified by the user).

To make this format available, copy the code below into a Python file inside
the ``Plugins/`` directory in one of the configured Katana resources.
Alternatively, this code can be executed in a :kat:ui:`Python` tab (note that
if the format has been previously registered, it will have to be unregistered
with :py:func:`LookFileBakeAPI.UnregisterOutputFormat` first).

.. literalinclude:: JsonLookFileBake.py
  :caption: :download:`JsonLookFileBake.py`
  :language: python


LookFileBake API
----------------

.. automodule:: LookFileBakeAPI
    :imported-members:


.. |sparkles| unicode:: U+2728