Render Setup Python API and commands

Render Setup Python API

The Render Setup Python API is available as part of the Maya installation, and you can find the relevant files in this folder: ..\Python\Lib\site-packages\maya\app\renderSetup.

Note: The Render Setup Python API is currently not officially supported and is subject to change over time.

To use the Render Setup API, you should first import the Render Setup module as follows: 

import maya.app.renderSetup.model.override as override
import maya.app.renderSetup.model.selector as selector
import maya.app.renderSetup.model.collection as collection
import maya.app.renderSetup.model.renderLayer as renderLayer
import maya.app.renderSetup.model.renderSetup as renderSetup

You should also import maya.cmds so that you can use the native Maya commands.

The following is an example script that creates a layer and two collections. It adds the sphere to the first collection using the expression mySphere*, and then adds the cube to the second collection with the expression myCube*.

An absolute override is created and applied to the first collection, then a relative override created and applied to the second.

The example ends by switching to the render layer, where you will see the sphere appear in template display mode and the cube translated. 

import maya.app.renderSetup.model.override as override
import maya.app.renderSetup.model.selector as selector
import maya.app.renderSetup.model.collection as collection
import maya.app.renderSetup.model.renderLayer as renderLayer
import maya.app.renderSetup.model.renderSetup as renderSetup
import maya.cmds as cmds

rs = renderSetup.instance()  
  
# Create and append the render layer
rl = rs.createRenderLayer("MyRenderSetupLayer")

# Create and append 2 collections
c1 = rl.createCollection("sphereCollection")
c2 = rl.createCollection("cubeCollection")

# Create a trivial scene with a cube, a sphere and a cylinder
cmds.polySphere(name='mySphere')
cmds.move(2, 'mySphere', y=True)
cmds.polyCube(name='myCube')
cmds.move(5, 'myCube', y=True)
cmds.polyCylinder(name='myCylinder')
cmds.move(10, 'myCylinder', y=True)

# Set up collection 1 to select all spheres using the pattern mySphere*, 
# and collection 2 to select all cubes using the pattern myCube*.
c1.getSelector().setPattern('mySphere*')
c2.getSelector().setPattern('myCube*')

# Set up an absolute override on mySphereShape.template with a value of True
ov1 = c1.createAbsoluteOverride('mySphereShape', 'template')
ov1.setAttrValue(True)

# Set up a relative override on myCube.translate with a multiply value of
# [2.0, 2.0, 2.0] and an offset of [0.1, 0.1, 0.1]
ov2 = c2.createRelativeOverride('myCube', 'translate')
ov2.setMultiply([2.0, 2.0, 2.0])
ov2.setOffset([0.1, 0.1, 0.1])

# Set the render layer as visible. 
# Only the sphere and the cube are displayed as they are collection members.
rs.switchToLayer(rl)

You can then extend this example to create shader overrides. In this example, two surface shaders are created, the first of which is assigned to the cube in the scene layer. The first surface shader is set to red, and the second shader set to blue. The cube is therefore set to red in the scene layer.

A shader override is then created where the cube is assigned the second surface shader. Now when you switch the render layers, you will see that the cube is blue and is translated. The sphere appears in template display mode. 

import maya.app.renderSetup.model.override as override
import maya.app.renderSetup.model.selector as selector
import maya.app.renderSetup.model.collection as collection
import maya.app.renderSetup.model.renderLayer as renderLayer
import maya.app.renderSetup.model.renderSetup as renderSetup
import maya.cmds as cmds

# Helper function for creating a shader
def createShader(shaderType):
    """ Create a shader of the given type"""
    shaderName = cmds.shadingNode(shaderType, asShader=True)
    sgName = cmds.sets(renderable=True, noSurfaceShader=True, empty=True, name=(shaderName + "SG"))
    cmds.connectAttr(shaderName + ".outColor", sgName + ".surfaceShader")
    return (shaderName, sgName)
	
# Helper function for assigning a material
def assignMaterial(shapeName, shadingGroupName):
    cmds.sets(shapeName, forceElement=shadingGroupName)
	
# Helper function for setting a color attribute to some color value
def setColor(attr, color):
    cmds.setAttr(attr, color[0], color[1], color[2], type="float3")
	
rs = renderSetup.instance()    

# Create and append the render layer
rl = rs.createRenderLayer("MyRenderSetupLayer")

# Create and append 2 collections
c1 = rl.createCollection("sphereCollection")
c2 = rl.createCollection("cubeCollection")

# Create a trivial scene with a cube, a sphere and a cylinder
cmds.polySphere(name='mySphere')
cmds.move(2, 'mySphere', y=True)
cmds.polyCube(name='myCube')
cmds.move(5, 'myCube', y=True)
cmds.polyCylinder(name='myCylinder')
cmds.move(10, 'myCylinder', y=True)

# Set up collection 1 to select all spheres using the pattern mySphere*, 
# and collection 2 to select all cubes using the pattern myCube*.
c1.getSelector().setPattern('mySphere*')
c2.getSelector().setPattern('myCube*')

# Set up an absolute override on mySphereShape.template with a value of True
ov1 = c1.createAbsoluteOverride('mySphereShape', 'template')
ov1.setAttrValue(True)

# Set up a relative override on myCube.translate with a multiply value of
# [2.0, 2.0, 2.0] and an offset of [0.1, 0.1, 0.1]
ov2 = c2.createRelativeOverride('myCube', 'translate')
ov2.setMultiply([2.0, 2.0, 2.0])
ov2.setOffset([0.1, 0.1, 0.1])

# Creates two surface shaders. Makes one red, the other blue and assigns the
# red shader to myCubeShape. Then creates a shader override with the blue
# shader.
shaderName, sgName = createShader("surfaceShader")
shaderName2, sgName2 = createShader("surfaceShader")
assignMaterial("myCubeShape", sgName)
setColor(shaderName + ".outColor", [1.0, 0.0, 0.0])
setColor(shaderName2 + ".outColor", [0.0, 0.0, 1.0])
outColorShaderOvr = c2.createAbsoluteOverride(shaderName2, 'outColor')

# Set the render layer as visible. 
# Only the sphere and the cube are displayed as they are collection members.
rs.switchToLayer(rl)
Note:

Call the rs.switchToLayer() method to ensure that Render Setup is synchronized with any scene changes. This is equivalent to clicking the layer visibility icon to update your layer membership when using Maya interactively.

Render Setup Python commands

Render Setup commands are available that allow you to query render setup membership.

To find out more about these commands:

Query the docs strings using help().

For example, the following Python commands allow you to query the renderLayerMembers command: 

import maya.app.renderSetup.model.modelCmds as modelCmds
help(modelCmds.RenderLayerMembersCmd)

You can query the docs strings for the other commands in a similar fashion.

To find out more about the renderSetupSelect command, enter these commands in the Python tab of the Script Editor: 

import maya.app.renderSetup.views.viewCmds as viewCmds
help(viewCmds.RenderSetupSelectCmd)

To import and export a .json file in Python

You can define functions as follows that imports and exports a Render Setup .json file into the scene. 

import maya.app.renderSetup.model.renderSetup as renderSetup

import json

# Cannot name function "import", as this is a reserved Python keyword.
def importFile(filename):
    with open(filename, "r") as file:
        renderSetup.instance().decode(json.load(file), renderSetup.DECODE_AND_OVERWRITE, None)

def exportFile(filename):
    with open(filename, "w+") as file:
        json.dump(renderSetup.instance().encode(None), fp=file, indent=2, sort_keys=True)

Parent topic: Render setup in Maya