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.

✨ New in Katana 4: Render Farm Plug-ins: 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).

✨ New in Katana 4: Katana Queue: 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¶

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`
Katana Queue farm plug-in	`$KATANA_ROOT/plugins/Src/Resources/Core/Plugins/KatanaQueueFarmPlugin.py`
Katana Queue tab	`$KATANA_ROOT/plugins/Src/Resources/Core/Tabs/KatanaQueue.py`
Start Multiple Renders shelf item	`$KATANA_ROOT/plugins/Resources/Core/Shelves/KatanaQueue/MultiRender.py`
Launch Remote Agents shelf item	`$KATANA_ROOT/plugins/Resources/Core/Shelves/KatanaQueue/AgentManager.py`
OpenCue 1 farm plug-in	`$KATANA_ROOT/plugins/Src/Resources/Examples/Plugins/OpenCueFarmPlugin.py`

Note

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¶

Python package that allows developers to integrate render farms with Katana.

FarmAPI Constants¶

FarmAPI.NODES_ALL¶: Value that indicates that farm operations should act on all Render nodes.

FarmAPI.NODES_SELECTED¶: Value that indicates that farm operations should act on selected Render nodes only.

FarmAPI.NODES_SINGLE¶: Value that indicates that farm operations should act on a single Render node only.

Custom Farm Menu Commands¶

FarmAPI.AddFarmMenuOption(menuCommandText, callback)¶

Adds a new render farm-related menu command to Katana’s B{Util} main menu.

Parameters

menuCommandText (str) – The text to use for the menu command.
callback (callable) – The function to call when the menu command is chosen.

FarmAPI.AddFarmPopupMenuOption(menuCommandText, callback)¶

Adds a new render farm-related menu command the context menu of nodes that support render farms, such as Render nodes.

Parameters

menuCommandText (str) – The text to use for the menu command.
callback (callable) – The function to call when the menu command is chosen.

FarmAPI.GetFarmMenuOptions()¶

Return type: list of 2-tuple
Returns: A list of tuples of texts and callbacks of render farm-related menu commands that have been added to be shown in Katana’s B{Util} main menu.

FarmAPI.GetFarmPopupMenuOptions()¶

Return type: list of 2-tuple
Returns: A list of tuples of texts and callbacks of render farm-related menu commands that have been added to be shown in the context menu of nodes that support render farms, such as Render nodes.

Custom Farm Settings¶

FarmAPI.AddFarmSettingNumber(name='', defaultValue=0, hints=None)¶

Adds a custom farm setting (node parameter) of type number to the Render node and other applicable nodes (RenderScript, ImageWrite).

Parameters

name (str) – The name of the new parameter.
defaultValue (int) – The default value for the parameter.
hints (dict or None) – UI hints that will be assigned to the parameter.

FarmAPI.AddFarmSettingNumberArray(name='', size=1, hints=None)¶

Adds a custom farm setting (node parameter) of type number array to the Render node and other applicable nodes (RenderScript, ImageWrite).

Parameters

name (str) – The name of the new parameter.
size (int) – The number of elements to use for the number array parameter.
hints (dict or None) – UI hints that will be assigned to the parameter.

FarmAPI.AddFarmSettingString(name='', defaultValue='', hints=None)¶

Adds a custom farm setting (node parameter) of type string to the Render node and other applicable nodes (RenderScript, ImageWrite).

Parameters

name (str) – The name of the new parameter.
defaultValue (str) – The default value for the parameter.
hints (dict or None) – UI hints that will be assigned to the parameter.

FarmAPI.AddFarmSettingStringArray(name='', size=1, hints=None)¶

Adds a custom farm setting (node parameter) of type string array to the Render node and other applicable nodes (RenderScript, ImageWrite).

Parameters

name (str) – The name of the new parameter.
size (int) – The number of elements to use for the string array parameter.
hints (dict or None) – UI hints that will be assigned to the parameter.

FarmAPI.GetAddedFarmSettings()¶

Return type: list of FarmSetting
Returns: A list of farm settings that were added via the functions above.

FarmAPI.ExtractFarmSettingsFromNode(node)¶

Return type: dict
Parameters: node (NodegraphAPI.Node) – The node from which to extract the farm settings.
Returns: A dictionary with names and values of farm settings that are stored on the given node.

class FarmAPI.FarmSetting(name='', farmType='string', defaultValue=None, size=0, hints=None)¶

Bases: object

Class representing a custom farm setting.

Since: Katana 1.0v1

NUMBER = 'number'¶

NUMBERARRAY = 'numberarray'¶

QUALIFIER = 'farmSettings'¶

STRING = 'string'¶

STRINGARRAY = 'stringarray'¶

VALID_TYPES = ('string', 'number', 'stringarray', 'numberarray')¶

__init__(name='', farmType='string', defaultValue=None, size=0, hints=None)¶

Initializes an instance of the class.

Parameters

name (str) – The name of the farm setting.
farmType (str) – The name of the type of the farm setting (FarmSetting.STRING, FarmSetting.NUMBER, FarmSetting.STRINGARRAY, or FarmSetting.NUMBERARRAY).
defaultValue (str or int or float or list or None) – The default value of the farm setting.
size (int) – The number of elements in the farm setting, for array settings.
hints (dict or None) – A dictionary of UI hints for the farm setting, or None if no UI hints are provided.

Raises

Exception – If the given farmType is not one of the FarmSetting.VALID_TYPES.

getHints()¶

Return type: dict or None
Returns: A dictionary of UI hints for the farm setting, or None if no UI hints are provided.

getName()¶

Return type: str
Returns: The name of the farm setting.

getQualifiedName()¶

Return type: str
Returns: The name of the farm setting with a FarmSetting.QUALIFIER prefix.
Since: Katana 4.0v1

getShortName()¶: Alias of getName().

getSize()¶

Return type: int
Returns: The number of elements in the farm setting, for array settings.

getType()¶

Return type: str
Returns: The name of the type of the farm setting (FarmSetting.STRING, FarmSetting.NUMBER, FarmSetting.STRINGARRAY, or FarmSetting.NUMBERARRAY).

getValue()¶

Return type: str or int or float or list or None
Returns: The default value of the farm setting.

Validity Checks¶

FarmAPI.IsSceneValid(nodeScope=None, allowUnsavedChanges=False, allowCapitalLetters=True, allowDigits=True, unwantedSymbols=[])¶

Returns a flag indicating whether or not the project contains nodes which will generate render passes which are valid and fulfill the criteria determined by the given flags. The warning and error message lists are populated if the validation fails. These messages are accessible using:

GetWarningMessages()

GetErrorMessages()

Return type

bool

Parameters

nodeScope (str) – Can be a single node, the selected nodes, or all nodes (FarmAPI.NODES_SINGLE, FarmAPI.NODES_SELECTED, or FarmAPI.NODES_ALL).
allowUnsavedChanges (bool) – Determines if a dirty project is valid.
allowCapitalLetters (bool) – Determines if a Render node’s pass name is allowed to contain capital letters.
allowDigits (bool) – Determines if a Render node’s pass name is allowed to contain numeric characters.
unwantedSymbols (list of str) – Specifies a list of characters that are not allowed in the Render node’s pass name.

Returns

True if the project is valid, based on the nodes in the given scope, and the additional given criteria, otherwise False.

FarmAPI.AddWarningMessage(message)¶

Adds a custom warning message to the list of warning messages.

Parameters: message (str) – The warning message to add.

FarmAPI.AddErrorMessage(message)¶

Adds a custom error message to the list of error messages.

Parameters: message (str) – The error message to add.

FarmAPI.GetWarningMessages()¶

Return type: list of str
Returns: A list of any warning messages which have been added since Initialise() was called, or while IsSceneValid() was run.

FarmAPI.GetErrorMessages()¶

Return type: list of str
Returns: A list of any error messages which have been added since Initialise() was called, or while IsSceneValid() was run.

Render Node Dependencies¶

FarmAPI.GetSortedDependencies(nodeOrNodes=None, includeBypassed=False)¶

Returns a list of the render passes and their dependencies based on a list of input nodes.

Return type

list of NodeRenderSettings

Parameters

nodeOrNodes (NodegraphAPI.Node or list of NodegraphAPI.Node or None) – The input node or nodes which define the search scope for available render passes. If a node list is not supplied then a default list is used based on the current node scope.
includeBypassed (bool) – An optional flag that controls whether to include nodes that are bypassed.

Returns

A list of NodeRenderSettings instances containing information about a node and its dependencies.

See

NodeRenderSettings

Raises

ValueError – If the given nodeOrNodes argument is not an instance of NodegraphAPI.Node, not a sequence, and not None.

Since

Katana 2.1v1

FarmAPI.GetSortedDependencyList(nodeList=None, syncAllOutputPorts=False, includeInternalDeps=False)¶

Deprecated: This function is deprecated. Please use GetSortedDependencies() instead.

class FarmAPI.NodeRenderSettings(dependencyListEntry=None)¶

Bases: object

A class representing render settings for a node. Instances of this class provide the following instance variables:

nodeName - The name of the node.

isEnabled - A flag indicating whether the node should be rendered.

dependencies - A list of other nodes which this node’s render depends upon.

renderType - The type of the render - either '3D' or '2D'.

renderService - The name of the service used to render this node - 'prman', 'arnold', etc.

activeViews - A string containing the names of the active views to be rendered. Only applicable when rendering from a 2D ImageWrite node. If all views have been selected, this string will be '__all__'.

passName - The name of the render pass to be rendered.
outputs - A list of dictionaries containing information about this node’s outputs. Each dictionary has the following keys:
'name'
'enabled'
'outputLocation'
'tempRenderLocation'
renderScriptSettings - A RenderScriptSettings instance containing information about a render script job.

frameRange - A tuple containing two frame numbers giving the frame range to be rendered.

dependAll - A flag indicating whether all frames of dependencies should be rendered before this node is rendered.

renderInternalDependencies - A flag indicating whether internal dependencies of this node should be rendered in the same farm process as this node.

memory - A string specifying the memory requirements for the render. Units should be specified as 'm' for megabyte or 'g' for gigabyte, e.g. '512m' or '2g'. Only applicable when rendering from a 2D ImageWrite node.

customFarmSettings - A dictionary containing any other farm settings which were found in the dependency list entry.

Since: Katana 2.1v1

__init__(dependencyListEntry=None)¶

Initializes an instance of the class.

Parameters: dependencyListEntry (dict or None) – A dictionary containing information about the render dependencies for a node, or None.

getNode()¶

Return type

NodegraphAPI.Node or None

Returns

The node corresponding to this node render settings instance, or None if no such node could be found.

Raises

ValueError – If no node name has been set in this instance.
RuntimeError – If no node with the stored node name was found.

getNodeType()¶

Return type

str

Returns

The node type identified by the dependency list entry, e.g. 'Render' or 'RenderScript'.

Raises

ValueError – If no node name has been set in this instance.
RuntimeError – If no node with the stored node name was found.

class FarmAPI.RenderScriptSettings(settings={})¶

Bases: object

Class representing settings for a render script job.

Since: Katana 2.1v1

__init__(settings={})¶

Initializes an instance of the class based on the given dictionary of render script settings. The command, arguments and keyword arguments for the render script job are obtained respectively from the 'outlineFunc', 'outlineArgs', and 'extraArgs' entries in the given dictionary.

Parameters: settings (dict) – A dictionary containing render script settings.

appendXML(xmlElement)¶

Appends a <renderScriptCommand> element to the given XML element containing the settings for this instance.

Parameters: xmlElement (xml.etree.ElementTree.Element) – the parent XML element to which the <renderScriptCommand> element should be added.

Creating Farm Files¶

FarmAPI.WriteFarmFile(fileName, farmString)¶

Writes farm contents into a file and creates necessary directories if they do not exist.

Parameters

fileName – The name and path of the file to create.
farmString – The string contents to write to the file.

FarmAPI.OpenDefaultDialog(callback=None, dialogTitle='', fileExtension='')¶

Opens a basic dialog which can be used to specify a target filename and to configure the generic farm settings.

Parameters

callback (callable or None) – A function that is executed when the confirmation button in the dialog has been pressed. If no callback is given, then a default action of generating an XML file is executed.
dialogTitle (str) – The title of the dialog and the label of the confirmation button.
fileExtension (str) – The accepted file extension for the dialog’s file browser.

FarmAPI Helper Functions¶

FarmAPI.Initialise(clickedNode=None)¶

Internal helper function that initializes the FarmAPI module before performing a render farm operation.

Is called automatically

before calling a callback of a custom farm menu command that was chosen from Katana’s B{Util} main menu,

before executing commands from the B{Render Farm} section of the context menu of Render nodes in the B{Node Graph} tab, and

before opening the dialog for creating a I{Farm file}.

Clears internal module-global variables, such as the lists of warning and error messages, and initializes the nodes that may be affected by render farm commmands.

Parameters: clickedNode (NodegraphAPI.Node) – The Render node for which a context menu was opened.

FarmAPI.GetNodeProcessType()¶

Returns whether the current node scope is set to clicked only, selected nodes, or all nodes (FarmAPI.NODES_SINGLE, FarmAPI.NODES_SELECTED, or FarmAPI.NODES_ALL).

Return type: str
Returns: The current node-scope.

FarmAPI.GetClickedNode()¶

Return type: NodegraphAPI.Node
Returns: The node for which a context menu was opened, as passed to the Initialise() function.

FarmAPI.GetSelectedNodes()¶

Return type: list of NodegraphAPI.Node
Returns: The nodes that were selected when the Initialise() function was called.

FarmAPI.GetCurrentNode()¶

Return type: NodegraphAPI.Node
Returns: The node for which a context menu was opened, as passed to the Initialise() function, or the first of the nodes that were selected when the Initialise() function was called.

FarmAPI.GetNodeList()¶

Returns nodes based on the current node scope. If a node was clicked then it is returned. Alternatively, the selected nodes and their children are found (recursively) and returned.

Return type: list of NodegraphAPI.Node or None
Returns: A list of selected or clicked nodes, or None if no such nodes could be found.

FarmAPI.GetSceneFrameRange()¶

Returns the frame range for the current project, as returned by NodegraphAPI.GetInTime() and NodegraphAPI.GetOutTime().

Return type: dict
Returns: A dictionary with the in and out time of the current project stored as values under 'start' and 'end' keys.

FarmAPI.GetCurrentNodeFrameRange()¶

Returns the frame range as defined by the farm settings.

Return type: dict
Returns: A dictionary with the frame range defined in the farm settings stored on the current node as values under 'start' and 'end' keys.
See: GetCurrentNode()

FarmAPI.GetKatanaFileName()¶

Return type: str
Returns: The filename of the current Katana project.

Render Farm Plug-ins¶

✨ New in Katana 4

Render Farm Plug-ins are managed using the FarmAPI.FarmPluginManager module.

FarmAPI.FarmPluginManager Module¶

Module that provides functionality to interact with registered FarmAPI plug-ins.

since: Katana 4.0v1

exception FarmAPI.FarmPluginManager.FarmPluginManagerException¶

Bases: Exception

Class representing an exceptional case that may occur when interacting with the FarmAPI.FarmPluginManager module.

class FarmAPI.FarmPluginManager.JobRequest(nodeName, renderContextName, frames, commands, environment, tempDir)¶

Bases: object

Contains the commands, environment and unique identifier that together make up a single render job that should be submitted to the render farm.

__init__(nodeName, renderContextName, frames, commands, environment, tempDir)¶

Initializes an instance of this class.

Parameters

nodeName (str) – The name of the 3D node from which the render was started.
renderContextName (str) – A globally unique identifier for this render job.
frames (list of int) – list of frames to render.
commands (list of str) – ordered list of commands to run
environment (dict of str) – environment variables that should be present when running the commands.
tempDir (str) – temporary directory used for this render on the farm.

FarmAPI.FarmPluginManager.GetDefaultFarm()¶

Return type: str
Returns: The farm plug-in that is used by functions of this module when none is specified.

FarmAPI.FarmPluginManager.SetDefaultFarm(farm)¶

Sets the default farm plug-in to be used if none is specified.

Parameters: farm (str) – The default farm plug-in to use if none is specified.
Raises: FarmPluginManagerException – If no farm plug-in with the given name has been registered.

FarmAPI.FarmPluginManager.GetFarmPluginNames()¶

Return type: list of str
Returns: A list of names of render farms and compute resources currently available to the user.

FarmAPI.FarmPluginManager.CreateRenderContextName(sequenceID=None)¶

Return type: str
Parameters: sequenceID (int or None) – A number that uniquely identifies a render in Katana’s catalog system in the current Katana session.
Returns: A string that can be used to uniquely identify a render job.

FarmAPI.FarmPluginManager.CreateTemporaryDirectory(renderContextName, farm=None)¶

Creates a temporary directory for the render job specified by renderContextName.

Return type

str

Parameters

renderContextName (str) – A globally unique identifier for the render job for which to create a tempoary directory.
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Returns

The path to a temporary directory for use by the render job.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.CopyRenderFiles(renderFiles, renderContextName=None, farm=None)¶

Copies the files specified in renderFiles to a location accessible by the render farm, returning a mapping of where each file was copied to.

Return type

map of str rarr str

Parameters

renderFiles (list of str) – A list of names of files to be copied.
renderContextName (str or None) – A globally unique identifier for the render job for which to copy the files, or None to generate one using CreateRenderContextName().
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Returns

Mapping of local file to farm file.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.SubmitJob(nodeName, renderContextName, remoteTempDir, commands, farm=None)¶

Submits the specified job to the render farm.

Return type

str

Parameters

nodeName (str) – The name of the 3D node from which the render was started.
renderContextName (str) – A globally unique identifier for the render job to submit.
remoteTempDir (str) – Temporary directory on farm to be used by this render.
commands (list of str) – Ordered list of commands to be run by the render farm.
farm (str) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Returns

String that uniquely identifies the submitted job on the render farm.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.StartJob(jobId, farm=None)¶

(Re-)Starts the job specified by jobId.

Note: Depending on the implementation of the farm plug-in used, the job may enter the render farm’s queue in a ‘started’ or ready to start state, so a call of this function may not have any effect.

Parameters

jobId (str) – The identifier for a job submitted to the render farm as returned by SubmitJob().
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.StopJob(jobId, farm=None)¶

Stops the job specified by jobId.

Parameters

jobId (str) – The identifier for a job submitted to the render farm as returned by SubmitJob().
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.GetJobs(filters=None, farm=None)¶

Return type

list of FarmAPI.Job

Parameters

filters (list of str or None) – A list of filter entries of the format '<name>=<value>'. Defaults to an empty list if not provided, meaning all jobs managed by the render farm with the given name are returned.
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Returns

A list of render farm jobs matching the given list of filter criteria.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.GetRenderLogFilename(jobId, farm=None)¶

Return type

str or None

Parameters

jobId (str) – The identifier for a job submitted to the render farm as returned by SubmitJob().
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Returns

The name of the render log file of the job with the given ID, or None if the filename is not yet known, or inaccessible from this host.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.GetJobState(jobId, farm=None)¶

Return type

str

Parameters

jobId (str) – The ID of the Job for which to retrieve the state.
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Returns

The state of the render farm job with the given ID.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

FarmAPI.FarmPluginManager.Initialize()¶

Initializes the FarmAPI.FarmPluginManager module.

Is called by Katana during application startup.

FarmAPI.FarmPluginManager.LoadFarmPlugins()¶: Loads all FarmAPI plug-ins, registers them with the FarmAPI.FarmPluginManager module, and sets the default farm plug-in to the first plug-in that was loaded.

FarmAPI.FarmPluginManager.PrepareRemoteCommand(localCommandLine, renderContextName, remoteTempDirectory, farm=None)¶

Converts the given local command line to a remote equivalent, and copies any files required for this job to the farm, then returns the remote command line.

Return type

str

Parameters

localCommandLine (str) – The local command line to convert, containing quoted arguments separated by spaces.
renderContextName (str) – A globally unique identifier for the render job for which to prepare the remote command.
remoteTempDirectory (str) – Path to the temporary directory on the render farm used by this job.
farm (str or None) – The name of the render farm plug-in to use, or None to use the default farm plug-in.

Returns

The remote command line created from the given local command line.

Raises

FarmPluginManagerException – If no farm plug-in with the given name is registered.

Footnotes