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 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 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 Util main menu,

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

before opening the dialog for creating a 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