FarmAPI

The FarmAPI Package is used to retrieve dependencies for the nodes: Render, RenderScript, ImageWrite.

These nodes are populated with generic farm settings which determine how the dependencies are used. Custom farm settings can be added and accessed through the API.

Examples

Example code which generates an XML file from the node dependencies is at: $KATANA_ROOT/PLUGINS/Resources/Examples/Plugins/FarmXML.py

FarmAPI.AddErrorMessage(message)

Adds an error message to the error list.

Parameters:message (str) – Error message.
FarmAPI.AddFarmMenuOption(menuText, handle)

Adds a new menu option to Katana’s Util menu and the right-click pop-up menu for the following nodes: Render, RenderScript, ImageWrite.

Parameters:
  • menuText – The label of the new menu item.
  • handle – A handle to the function that will be executed when the menu item is selected.
FarmAPI.AddFarmPopupMenuOption(menuText, handle)

Adds a new menu option to Katana’s Util menu and the right-click pop-up menu for the following nodes: Render, RenderScript, ImageWrite.

Parameters:
  • menuText – The label of the new menu item.
  • handle – A handle to the function that will be executed when the menu item is selected.
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 – The name of the new parameter.
  • defaultValue – The default value for the parameter.
  • hints – 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 – The name of the new parameter.
  • size – The number of elements to use for the number array parameter.
  • hints – 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 – The name of the new parameter.
  • defaultValue – The default value for the parameter.
  • hints – 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 – The name of the new parameter.
  • size – The number of elements to use for the string array parameter.
  • hints – UI hints that will be assigned to the parameter.
FarmAPI.AddWarningMessage(message)

Adds a warning message to the warning list.

Parameters:message (str) – Warning message.
FarmAPI.ExtractFarmSettingsFromNode(node)

Returns a dictionary with the farm settings and values from a node.

Return type:dict
Parameters:node (NodegraphAPI.Node) – The node for which the farm settings will be extracted from.
Returns:A dictionary of farm settings.
FarmAPI.GetAddedFarmSettings()

Returns the added custom farm settings.

Returns:A dictionary with the added farm settings.
Return type:dict
FarmAPI.GetClickedNode()
Return type:NodegraphAPI.Node
Returns:The clicked node.
FarmAPI.GetCurrentNode()
Return type:NodegraphAPI.Node
Returns:The current node.
FarmAPI.GetCurrentNodeFrameRange()

Returns the frame range as defined by the farm settings.

Return type:dict
Returns:A dictionary with the ‘start’ and ‘end’ times.
FarmAPI.GetErrorMessages()
Return type:list of str
Returns:A list of any error messages which have been logged. @see IsSceneValid
FarmAPI.GetFarmMenuOptions()
Return type:dict
Returns:Farm-specific menu option names and handles.
FarmAPI.GetFarmPopupMenuOptions()
Return type:dict
Returns:Farm-specific popup menu option names and handles.
FarmAPI.GetKatanaFileName()
Return type:str
Returns:The filename of the current Katana scene.
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.GetNodeProcessType()

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

Return type:str
Returns:The current node-scope.
FarmAPI.GetSceneFrameRange()

Returns the frame range for the current scene.

Return type:dict
Returns:A dictionary with the ‘start’ and ‘end’ times.
FarmAPI.GetSelectedNodes()
Return type:list of NodegraphAPI.Node
Returns:The selected nodes.
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

Note:

This method replaces GetSortedDependencyList, which has been deprecated.

Raises:

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

FarmAPI.GetSortedDependencyList(nodeList=None, syncAllOutputPorts=False, includeInternalDeps=False)
Deprecated:This function will be removed. Please use GetSortedDependencies() instead.
FarmAPI.GetWarningMessages()
Return type:list of str
Returns:A list of any warning messages which have been logged. @see IsSceneValid
FarmAPI.Initialise(clickedNode=None)
FarmAPI.IsSceneValid(nodeScope=None, allowUnsavedChanges=False, allowCapitalLetters=True, allowDigits=True, unwantedSymbols=[])

Returns a flag indicating whether or not the scene 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:

Return type:

bool

Parameters:
  • nodeScope (str) – Can be a single node, the selected nodes, or all nodes (NODES_SINGLE, NODES_SELECTED or NODES_ALL).
  • allowUnsavedChanges (bool) – Determines if a dirty scene 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 scene is valid, based on the nodes in the given scope, and the additional given criteria, otherwise False.

FarmAPI.OpenDefaultDialog(handle=None, dialogTitle='', fileExtension='')

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

Parameters:
  • handle (callable or None) – A handle to the function which will be executed when the confirmation button is pressed. If no handle is defined then the 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.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 that will be created.
  • farmString – The string contents that will be written.