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