FarmAPI
========

Introduction to Katana's FarmAPI
--------------------------------

The ``FarmAPI`` Python package allows developers to integrate render farms with
Katana. This allows artists to start renders on a render farm right from within
Katana's user interface.

The API supports the following features:

  - `Custom Farm Menu Commands`_: You can define custom render farm-related
    menu commands for the **Util** main menu and the context menu of nodes that
    support render farms, such as Render nodes.
  - `Custom Farm Settings`_: You can define and retrieve custom render
    farm-related settings in the form of parameters on Render nodes.
  - `Validity Checks`_: You can check whether a project contains nodes which
    will generate render passes which are valid and fulfill certain criteria as
    determined by specific flags.
  - `Render Node Dependencies`_: You can retrieve information about
    dependencies between Render nodes, which can help in the creation of custom
    render farm submission tools.
  - `Creating Farm Files`_: You can create `Farm files` that can then be
    processed externally to Katana in order to create jobs on a render farm. A
    **Generate Farm Output** UI dialog for configuring the creation of such a
    Farm file is provided as well.

|sparkles| **New in Katana 4:** :doc:`/Plugins/FarmAPI`: The ``FarmAPI`` Python
package now provides a base class for a new type of plug-in that allows
developers to even more closely integrate a specific render farm system with
Katana. For every render farm plug-in that is registered with Katana, menu
commands for starting renders on the respective render farm are added to the
context menu of `any` 3D node in the **Node Graph** tab (not just Render
nodes).

|sparkles| **New in Katana 4:** :doc:`KatanaQueue`: Katana now ships with a
minimal render farm implementation, named `Katana Queue`, which is integrated
with Katana using a custom render farm plug-in. The Katana Queue system uses
`Agent` processes on the local workstation to host ``renderboot`` processes for
performing renders. It is also possible to run these Agents on other
workstations that are accessible on the network (`Remote Agents`), and to add
them to the pool of Agents that are managed by the local Katana Queue, thus
boosting rendering capabilities and increasing productivity even further.

.. _farmapi-example-code:

FarmAPI Example Code
--------------------

Katana ships with the following Python scripts as source, which demonstrate the
use of various parts of the ``FarmAPI``:

===========================================  ==================================
Topic / Tool                                 Python Source File
===========================================  ==================================
Generating Farm XML Files                    ``$KATANA_ROOT/plugins/Src/Resources/Examples/Plugins/FarmXML.py``
:doc:`KatanaQueue` farm plug-in              ``$KATANA_ROOT/plugins/Src/Resources/Core/Plugins/KatanaQueueFarmPlugin.py``
:kat:ui:`Katana Queue` tab                   ``$KATANA_ROOT/plugins/Src/Resources/Core/Tabs/KatanaQueue.py``
:kat:ui:`Start Multiple Renders` shelf item  ``$KATANA_ROOT/plugins/Resources/Core/Shelves/KatanaQueue/MultiRender.py``
:kat:ui:`Launch Remote Agents` shelf item    ``$KATANA_ROOT/plugins/Resources/Core/Shelves/KatanaQueue/AgentManager.py``
`OpenCue`_ [#f1]_ farm plug-in               ``$KATANA_ROOT/plugins/Src/Resources/Examples/Plugins/OpenCueFarmPlugin.py``
===========================================  ==================================

.. note::

    .. image:: opencue.svg
        :align: left
        :alt: OpenCue logo
        :target: `OpenCue`_
        :width: 80px

    The `OpenCue` farm plug-in is provided as a reference example of how to
    integrate `OpenCue`_, an open source render management system, with Katana.

    For more information on how to set up an OpenCue deployment, please consult
    the `OpenCue documentation`_.


FarmAPI Reference Documentation
-------------------------------

  - `FarmAPI Python Package`_
  - `FarmAPI Constants`_
  - `Custom Farm Menu Commands`_
  - `Custom Farm Settings`_
  - `Validity Checks`_
  - `Render Node Dependencies`_
  - `Creating Farm Files`_
  - `FarmAPI Helper Functions`_
  - `Render Farm Plug-ins`_

    - `FarmAPI.FarmPluginManager Module`_

FarmAPI Python Package
~~~~~~~~~~~~~~~~~~~~~~

.. automodule:: FarmAPI
    :no-members:
    :synopsis: Python package for integrating render farms with Katana.

FarmAPI Constants
~~~~~~~~~~~~~~~~~

.. py:data:: FarmAPI.NODES_ALL

    Value that indicates that farm operations should act on all Render nodes.

.. py:data:: FarmAPI.NODES_SELECTED

    Value that indicates that farm operations should act on selected Render
    nodes only.

.. py:data:: FarmAPI.NODES_SINGLE

    Value that indicates that farm operations should act on a single Render
    node only.

Custom Farm Menu Commands
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: FarmAPI.AddFarmMenuOption
.. autofunction:: FarmAPI.AddFarmPopupMenuOption
.. autofunction:: FarmAPI.GetFarmMenuOptions
.. autofunction:: FarmAPI.GetFarmPopupMenuOptions

Custom Farm Settings
~~~~~~~~~~~~~~~~~~~~

.. autofunction:: FarmAPI.AddFarmSettingNumber
.. autofunction:: FarmAPI.AddFarmSettingNumberArray
.. autofunction:: FarmAPI.AddFarmSettingString
.. autofunction:: FarmAPI.AddFarmSettingStringArray
.. autofunction:: FarmAPI.GetAddedFarmSettings
.. autofunction:: FarmAPI.ExtractFarmSettingsFromNode

.. autoclass:: FarmAPI.FarmSetting

Validity Checks
~~~~~~~~~~~~~~~

.. autofunction:: FarmAPI.IsSceneValid
.. autofunction:: FarmAPI.AddWarningMessage
.. autofunction:: FarmAPI.AddErrorMessage
.. autofunction:: FarmAPI.GetWarningMessages
.. autofunction:: FarmAPI.GetErrorMessages

Render Node Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: FarmAPI.GetSortedDependencies
.. autofunction:: FarmAPI.GetSortedDependencyList

.. autoclass:: FarmAPI.NodeRenderSettings
.. autoclass:: FarmAPI.RenderScriptSettings

Creating Farm Files
~~~~~~~~~~~~~~~~~~~

.. autofunction:: FarmAPI.WriteFarmFile
.. autofunction:: FarmAPI.OpenDefaultDialog

FarmAPI Helper Functions
~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: FarmAPI.Initialise
.. autofunction:: FarmAPI.GetNodeProcessType
.. autofunction:: FarmAPI.GetClickedNode
.. autofunction:: FarmAPI.GetSelectedNodes
.. autofunction:: FarmAPI.GetCurrentNode
.. autofunction:: FarmAPI.GetNodeList
.. autofunction:: FarmAPI.GetSceneFrameRange
.. autofunction:: FarmAPI.GetCurrentNodeFrameRange
.. autofunction:: FarmAPI.GetKatanaFileName

Render Farm Plug-ins
~~~~~~~~~~~~~~~~~~~~

|sparkles| **New in Katana 4**

:doc:`/Plugins/FarmAPI` are managed using the
:py:mod:`FarmAPI.FarmPluginManager` module.

FarmAPI.FarmPluginManager Module
````````````````````````````````

.. automodule:: FarmAPI.FarmPluginManager
    :synopsis: Functionality to interact with registered FarmAPI plug-ins.

.. rubric:: Footnotes

.. [#f1] OpenCue |copy| 2020 Copyright Contributors to the OpenCue Project

.. _OpenCue: https://www.opencue.io
.. _OpenCue documentation: https://www.opencue.io/docs/

.. |copy| unicode:: 0xA9 .. copyright sign
.. |sparkles| unicode:: U+2728