V-Ray Scene Access |
Post-translate python callback
Available python functions and classes
The V-Ray scene access python API allows you to modify the V-Ray scene after it is translated by the V-Ray for Maya translator, and before it is rendered and/or exported to a .vrscene file. Note that the V-Ray scene may be quite different from its representation in Maya. As such, some knowledge about the way V-Ray translates various Maya constructs may be required. It would be best to study .vrscene files exported by V-Ray for Maya.
The scene access API allows you to expand the V-Ray for Maya translator by providing custom translation for constructs that are not recognized by V-Ray, or for modifying the scene before rendering without changing the original Maya scene.
You can specify the python script to be executed in the VRayCommon tab of the Render Settings dialog, in the MEL/Python callbacks rollout. The script is executed right after the scene is translated, and before it is rendered and/or exported to a .vrscene file. At present, when rendering an animation, the script is executed just once, before any frame is rendered.
The declarations (and in some cases the implementations) for all the python functions and classes are available in the vray/vrayplugins/sceneaccess/vray folder which is normally installed inside the Maya root folder.
Functions
The following python functions are available in the vray.utils module.
create(pluginType, pluginName) - create a plugin with the given name and type.
delete(pluginName) - delete a plugin with the given name.
findByName(pattern) - return a list of all plugins of a given type. pattern may contain wildcards.
findByType(pattern) - return a list of all plugins of a given type. pattern may contain wildcards.
getPluginParams(plugin, getValues=False) - return a list of all available parameters for the given plugin. If getValues is True the value for each parameter is also returned.
getTypeParams(pluginType) - return a list of all parameters for a given plugin type.
exportTexture(textureName) - export the texture from the Maya scene and return the exported plugin. This function can be useful if the texture hasn't been exported while translating the scene.
exportMaterial(materialName) - export the material from the Maya scene and return the exported plugin. This function can be useful if the material hasn't been exported while translating the scene.
addSceneContent(scenefile, prefix="") - load all plugins from the given .vrscene file and insert them in the current scene. You can optionally specify a prefix that will be prepended to every plugin's name.
Classes
The following python classes are available in the vray.utils module.
Plugin
This class represents an instance of a V-Ray plugin in the scene.
duplicate(self, newName) - return a new plugin instance of the same type and with the same parameters.
get(self, paramName) - return the value of a parameter.
has(self, paramName) - check whether the plugin instance has a parameter with this name.
name(self) - return the name of the plugin instance.
params(self, getValues=False) - return a list of all available parameters for this plugin. If getValues is True the value for each parameter is also returned.
output(self, paramName) - return a reference to a plugin output parameter, which can be set as a value for parameters of other plugins.
set(self, paramName, value) - set the value of a parameter.
type(self) - get the type of the plugin instance.Classes representing plugin parameter values
Parameters of the V-Ray plugins in the scene can be simple numbers, or more complex data types. Simple values can be directly manipulated, whereas complex types are represented by a dedicated python class.
PluginOutput
This class represents a reference to an output parameter of a V-Ray plugin. It is used whenever one plugin is connected to another plugin's output parameter.
AColor
This class represents a four-component color value (red, green, blue, alpha).
Color
This class represents a three-component color value (red, green, blue).
Vector
This class represents a three-component vector or point in 3D space.
Matrix
This class represents a 3x3 matrix.
Transform
This class represents a 3x4 transformation in 3D space.
Changing the color of a material and moving a node
This example script changes the color of the material of the first node in the scene (assuming the original material is a lambert one) and moves the node one unit up.
from vray.utils import *
l=findByType("Node") # Get all Node plugins
p=l[0].get("material") # Get the material of the first node
brdf=p.get("brdf") # Get the BRDF for the material
brdf.set("color_tex", Color(1.0, 0.0, 0.0)) # Set the BRDF color to red
t=l[0].get("transform") # Get the transformation for the first node
t.offs+=Vector(0.0, 1.0, 0.0) # Add one unit up
l[0].set("transform", t) # Set the new transformation
Example 2
This example shows how to converts all regular meshes in the scene to subdivision surfaces.
from vray.utils import *
def smooth(geom, maxSubdivs = None, edgeLength = None):
subdiv = create('GeomStaticSmoothedMesh', geom.name() + '@subdivGeometry') # Create a smoothed mesh plugin
subdiv.set('mesh', geom) # Set the base geometry for the subdivision to be the original mesh plugin
nodes = findByType('Node') # Get a list of all nodes
for node in nodes:
if node.get('geometry') == geom: # If a node references the original geometry...
node.set('geometry', subdiv) # ...replace it with the subdivided one
if maxSubdivs is not None: # Set the max. subdivs if specified
subdiv.set('use_globals', False)
subdiv.set('max_subdivs', maxSubdivs)
if edgeLength is not None: # Set the max. edge length if specified
subdiv.set('use_globals', False)
subdiv.set('edge_length', edgeLength)
p = findByType('GeomStaticMesh') # Find all mesh plugins
for geom in p: # Replace each mesh plugin with a smoothed one
smooth(geom)
Example 3
This example instances the first node in the scene a number of times to form a helix.
from vray.utils import *
import math
geomNodes = findByType('Node') # Get all Node plugins
sp = geomNodes[0] # The first node
geom = sp.get('geometry') # The geometry of the first node
r = 12 # helix radius
n = 20 # number of objects per helix turn
m = 3 # number of helix turns
h = 0.5 # height difference between objects on the helix
for i in range(n * m):
d = sp.duplicate('sphereNode' + str(i)) # Create a copy of the first scene node
tr = d.get('transform') # Get the transformation matrix
tr.offs += Vector(r * math.cos(i * 2 * 3.14159 / n), i * h, r * math.sin(i * 2 * 3.14159 / n)) # Add an offset according to the helix formula
d.set('transform', tr) # Set the new transformationExample 4
This example exports several textures and materials and changes the material of an object.
from vray.utils import *
lambert = exportMaterial('lambert1') # Export lambert1 material
checker = exportTexture('checker1') # Export checker1 texture
cloth = exportTexture('cloth1') # Export cloth1 texture
brdf = lambert.get('brdf') # Get the 'lambert1@material' plugin
brdf.set('transparency_tex', checker.output('color')) # Set the transparency_tex parameter of the brdf
brdf.set('color_tex', cloth) # Set the color_tex parameter of the brdf
planeNode = Plugin('pPlaneShape1@node') # Get the plane node
planeNode.set('material', lambert) # Set the material of the plane
Example 5
This example adds the contents of several scenes and uses some of the newly created plugins.
from vray.utils import *
addSceneContent('blinn.vrscene', 'basic_') # Create all plugins in this scene file and prepend 'basic_' to the names of all plugins
addSceneContent('vraymtl.vrscene') # Create all plugins in this scene file and use the original names
blinn = Plugin('basic_blinn1@material') # Get the blinn material from the first added scene
vraymtl = Plugin('VRayMtl1@material') # Get the V-Ray material from the second added scene
nodes = findByType('Node') # Find all nodes in the scene
# Change the materials of some of the nodes
nodes[0].set('material', blinn)
nodes[1].set('material', vraymtl)