More VRay Scene Access… or some more random tidbits

Following on from the last post. Here are another example of how you can mess around with VRay scenes using Python.

figure 1: transform += random() * 2, random() * 2, random() *2

This collection of cubes was created using only one cube, it’s been instanced 2500 times and moved about randomly, to do this I’ve used the random module in Python which is handy for doing random number things.

# figure 1
from vray.utils import *

import random as r
r.seed(1)

l=findByType("Node") # Get all Node plugins
v=Vector(0.0, 0.0, 0.0)
for x in range(2500):
	dupl = l[0].duplicate('dup' + str(x))
	t=dupl.get('transform')
	v = Vector(r.random()*2, r.random()*2, r.random()*2)
	t.offs += v
	dupl.set("transform", t)

The r.send(1) is used to create a seed point for any future calls to random module, this means that the random numbers chosen are going to be the same each time we render the image – if we’re making changes to the render we don’t want the position of the cubes to change each time we render.

The v variable is used to store the random number we’re using to offset the transform, at the moment this is just is using random.random() which produces random values between 0 and 1, in the above example this has the effect of moving the cubes only along the positive xyz axis. There is also random.uniform(min,max) which produces random values between the min and max numbers we give it.

figure 2: transform += uniform(-1,1) * 2, random() * 2, random(-1,1) * 2

Here the effect moves the cubes along positive and negative XZ. I’ve keep the Y axis in positive space so that the cubes don’t go through the ground plane.

# figure 2
from vray.utils import *

import random as r
r.seed(1)

l=findByType("Node") # Get all Node plugins
v=Vector(0.0, 0.0, 0.0)
for x in range(20):
	dupl = l[0].duplicate('dup' + str(x))
	t=dupl.get('transform')
	v = Vector(r.uniform(-1,1)*2, r.random()*2, r.uniform(-1,1)*2)
	t.offs += v
	dupl.set("transform", t)

VRay Scene Access… or modifying your scene after you’ve hit render

Introduction

One of the lesser known features of VRay is it’s ability to access information about the scene and modify it after the render button has been pressed and before it is rendered. This ability to access the VRay scene and modify it allows you the ability to create some custom solutions to problems which might not be doable inside the 3d application itself. It can also be used to workaround bugs in VRay – but only as a temporary measure to get around bugs when a deadline is fast approaching.

Note: I’m using VRay for Maya. I am not sure how much of this is possible in tools such as Max or Softimage, hopefully this knowledge is easily transferable between 3d applications.

Examples…

Some simple examples of what you do with this include changing shader properties such as colour and texture information, duplicating and moving geometry around or even loading in extra geometry at render time.

All of these things you can do inside your 3d application, but might present problems if your dealing with lot’s of objects – for example you may have thousands of objects that you wish to do texture variants on, rather than create a shader for each object, you could set it up so that you can use one shader on all the objects and use an attribute on each object to specify which texture to use when you hit render.

To get a better idea of what is going on behind the scenes, the diagram below shows what happens when you hit render in your favourite 3d application. The Post Translate Python script is run during the translation process (the nodes in red).

In order to manipulate the scene data requires an understanding of the vrscene file format. The best way to do this is to turn on the Export to a .vrscene file setting in the Render Globals and have a read of the file it outputs.

The VRay Scene Structure and Nodes

The vrscene file describes the 3d scene in a human-readable ascii file. If you open it up in your favourite text editor you should be able to figure out what is going on quite easily, the section below determines the image width, height, pixel aspect ratio and it’s filename…

SettingsOutput vraySettingsOutput {
  img_width=450;
  img_height=337;
  img_pixelAspect=1;
  img_file="tmp/untitled.png";

Each section represents a node (plugin) that VRay recognises. The basic structure of each node is simply…

[Type] [Name] {
    [Attribute]=[Value];
}

So using the image settings example from above…

[Type] = SettingsOutput
[Name] = vraySettingsOutput
[Attribute] = img_width
[Value] = 450

As you move down through the vrscene you’ll move pass all your image settings, render settings, global illumination settings and down towards all your material, brdf, texture, transform and geometry nodes. For example you might see a few nodes which looks like this…

BRDFDiffuse lambert1@diffuse_brdf {
  color=Color(0, 0, 0);
  color_tex=lambert1@diffuse_brdf_color_tex@tex_with_amount;
  transparency=Color(0, 0, 0);
}

TexAColorOp lambert1@diffuse_brdf_color_tex@tex_with_amount {
  color_a=AColor(0.5, 0.5, 0.5, 1);
  mult_a=0.8;
}

MtlSingleBRDF lambert1@material {
  brdf=lambert1@diffuse_brdf;
  allow_negative_colors=1;
}

It’s the default Lambert shader in Maya, which is made up of three nodes, starting from the bottom we have the MtlSingleBRDF node, this is the top-level material which gets applied to our object. You’ll notice that the brdf attribute refers to the node at the top which is a BRDFDiffuse node, this node determines what type of shading model to use (diffuse, blinn, mirror, phong, etc). Finally is a TexAColorOp, this stores a colour value along with an alpha value – this value is used in the BRDFDiffuse node to give us our colour, this node is perhaps redundant as we can specify the colour directly in the BRDFDiffuse node. To visualize how these are all connected, think of them in terms of nodes inside Nuke or Houdini…

Finally we come to the object and geo nodes which look something like this…

Node pSphereShape1@node {
  transform=TransformHex("0000803F0000000000000000000000000000803F0000000000000000000000000000803FE8B64401FDEE7EA96AB5F3BF00000000000000000000000000000000");
  geometry=pSphereShape1@mesh1;
  material=lambert1@material;
  nsamples=1;
  visible=1;
  user_attributes="";
  primary_visibility=1;
}

GeomStaticMesh pCubeShape1@mesh2 {
  vertices=ListVectorHex("ZIPB600000001C000000e7X81OBd6CFA3Xb712GUVKO4a886dYKD2YAA1ODEU9");
  faces=ListIntHex("ZIPB9000000036000000e7XKOVAHC79E523BHGNecBbRYaFa5SUJLaNJQacU6BC2UaSI67LYXAYOQJb0N6MZL28O79N1GJAUV7eNT");
  normals=ListVectorHex("ZIPB2001000021000000e7X81OY3TG4S11YMEZWOUH5bdV54FLVaU4DFGXQZbALLSKXD2FA");
  faceNormals=ListIntHex("ZIPB9000000041000000e7XQH4YFC8PHFTACH6UCF0ZcdXZKE4VAEK4FJGKIST0AUZREYbbB0TCbCEbbVcTEFEUbbAZ3MQV8d7CKR6L49d785aCaLYIA4DA");
  map_channels=List(
      List(
          0,
          ListVectorHex("ZIPBB40000003C000000e7X81O60O9EAZVBdOBaeK1U3QBFUDPGV6aSF5d1b4UKbE4CJIaUGbEb53TUBWAS3aEJZ5468IcAFdHDT3AAA2b7ZaS"),
          ListIntHex("ZIPB900000003A000000e7XUUVDECQRH923NF053bdb10CKCZA2PWbKGdUKQDaOKaFQ7HV7J719DREK7DTQ23Od3Xd73I2L5UIMMAQTQZT2")
      )
  );
  map_channels_names=ListString(
    "map1"
  );
  edge_visibility=ListIntHex("ZIPB0800000010000000e7XTYQd97OLXZ3TBAAIU92PP");
  primary_visibility=1;
  dynamic_geometry=0;
}

The first node (Node) is our object node and includes information about the transformation, geometry and material on the object. The second node (GeomStaticMesh) is storing information about the mesh – it’s vertices, faces, uv’s and normals.  You’ll notice that the transform and mesh data attributes are being stored as hex values, this is to save space in the file – you can write out ascii data if you want to. With transform data it’s not so bad and looks something like this…

transform=Transform(Matrix(Vector(1, 0, 0), Vector(0, 1, 0), Vector(0, 0, 1)), Vector(-1.231791174023726, 0, 0));

But with mesh-data you probably only want to write out ascii information for debugging purposes. Otherwise it makes the vrscene long and difficult to read.

Getting Started

The easiest way to see this all in action is to take the first example from the VRay documentation and run it by copying it into the Post Translate Python script field, which can be found in the Common tab within the Render Globals…

Editing the Post Translate Python in Maya 2009

Note: This brief section only applies to Maya 2009, you can ignore this section if your using Maya 2011, 2012 or 2013.

If your like me and using Maya 2009 you’ll notice that the text entry field here can only take one line. This is because Maya 2009’s python interpreter can’t handle escape characters properly (in particular carriage returns). This script works-around the problem by removing the problem escape characters before setting the attribute correctly.

DOWNLOAD willVR_ptpEditor.mel HERE

Download the file, copy it to one of your Maya script folders and in the script editor run…

source "willVR_ptpEditor.mel";

A window will pop up that will allow you to edit the python code.

Users of Maya 2011+ can continue reading

The following python code…

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

All it does is change the colour to red and moves one of the objects up one unit – not particular inspiring or useful, but it is a good introduction to what you can do.

The ‘before’ render shows what the scene looks like when rendered without the modification, while the ‘after’ render shows what happens when I paste the above python code into the Post Translate Python field. There isn’t any performance hit with an example like this, but I can imagine that once you started getting into some fairly complicated python code and when your dealing with lot’s of nodes that it could create a performance hit.

Camera Projection in Nuke

Camera projection is pretty straight forward when it comes to mapping one projection onto one object. It becomes less straight forward when you want to map multiple projections onto one object.

That’s where the MergeMat node comes in handy. It allows you to composite your Project3D nodes together before you apply them to an object. It acts exactly like the regular Merge node so you’ll need to have an alpha channel in the projection going into the Foreground Input (A) on the MergeMat.

If you do want to do multiple projection on multiple objects which share a similar 3d space, you may find that Nuke has trouble figuring out which object is supposed to be in front and which is at the back. This happens due to a lack of precision in the Z-Buffer. Nuke creates the depth pass in the ScanlineRenderer by remapping the near and far clipping plane values on the rendering camera to zero and one (respectively). If the near and far clipping planes are too far apart then this can result in a “chattering” effect where the two objects intersect.

This lack of precision is very similar to colour-banding you see 8-bit images. Even through Nuke is storing the depth as a floating point value which has lot’s of precision to begin with it can still result in banding if the near and far clipping planes are too far apart.

The way to fix this inside Nuke is to adjust the clipping planes so that they tightly bound the 3D scene as much as possible – taking into account any animation on the cameras or geometry. You can animate the clipping planes, but it’s best to leave them static, animating them results in an animated depth pass, which can cause troubles if your using the depth pass to do depth effects such as defocusing or atmospherics.

Another option which can also help is to adjust the Z-Blend Mode and Z-Blend Range within the ScanlineRenderer. This works at a pixel level by taking the depth values of each object in the scene, if the depth values of any object are within the Z-Blend Range of each other it’ll render the objects blended together.

 

Screenspace Texture Mapping in Maya/Mental Ray

Screenspace mapping or to be more geeky Normalized Device Coordinates  (NDC) mapping allows you to map a texture according the screenspace coordinates rather than use traditional UV coordinates.

The example below shows traditional UV mapping on the left and screenspace mapping on the right applied to a flat plane inside Maya (see middle for what the camera is seeing).

This technique was used in ye olden’ days (it started getting phased out around 2006-2008) inside Renderman shader to composite occlusion renders with beauty renders. The occlusion would be rendered out in a prepass and then composited during the beauty render.

You could also use this technique to do 2d compositing or even just general purpose image processing inside Maya.

The method of doing this is slightly different between Maya Software and Mental Ray, in order to do this in Mental Ray you need to use a mib_texture_vector and mib_texture_filter_lookup, the shading network looks like this…

The settings in the mib_texture_vector need to look like this…

With Maya Software the shading network looks like this…

The projection settings should look like this…

Note that the camera should be the one your rendering from if you want the mapping in screenspace, otherwise this will act like a camera projection (it is a projection node). One final caveat with Maya Software is that you’ll need to delete the UVs on the geometry in order for this to work. If you want to switch between UVs and no UVs, apply a Delete UVs node and set the node behaviour to HasNoEffect when you want UVs and set it to Normal when you don’t want UVs.

OpenEXR and 3Delight

The OpenEXR format has a number of useful features which are super handy for CG animation and VFX such as saving the image data in either half or full floating point, setting data-windows and adding additional metadata to the the file. 3Delight for Maya allows you to use all these features, but doesn’t cover how to use them in the documentation (at least I couldn’t find mention of it).

In order to use gain access to these features you need you need to add an extra attribute to the render pass called “exrDisplayParameters”. In the example below, the name of my render pass is called “beauty”.

addAttr -dt "string" -ln exrDisplayParameters beauty;
setAttr "beauty.exrDisplayParameters" -type "string"
"-p \"compression\" \"string\" \"zip\" -p \"autocrop\" \"integer\" \"1\" ";

The string attribute should end up looking like so in the attribute editor…

-p "compression" "string" "zip" -p "autocrop" "integer" "1"

The above sets the compression type to zip and to also tells 3Delight to autocrop the image when it’s rendered. Auto-crop adjusts the bounding box of the data-window (or ROI, region-of-interest) to only contain non-black pixels (I believe it does this based on the alpha channel), this allows Nuke to process the image quicker as it only calculates information within that data-window. See this tutorial on Nuke Bounding Boxes and how to speed up your compositing operations.

The basic syntax of the parameter string is easy enough to understand, the three arguments passed to the -p flag are name, type and value.

-p "[name]" "[type]" "[value]"

You can also add additional metadata to the header of the EXR render. For example you may wish to include things such as

  • Project, scene and shot information.
  • Characters or creatures in the shot.
  • Model, texture, animation versions used.
  • Maya scene used to render the shot.
  • Focal length, Fstop, Shutter Angle, Filmback size.

3Delight already includes some metadata already with the EXR, so you don’t need to add information for the following…

  • Near and far clipping planes.
  • WorldToCamera and WorldToNDC matrices. The Nuke Python documentation has info on how you can use this to create cameras in Nuke based of this data.

You can add this metadata using the “exrheader_” prefix and then the name of your attribute. The following will add three metadata attributes called “shutter”, “haperture” and “vaperture”.

-p "exrheader_shutter" "float" "180" -p "exrheader_haperture" "float" "36" -p "exrheader_vaperture" "float" "24"

While the following will add the project name “ussp” and the maya scene name that was used to render the shot…

-p "exrheader_project" "string" "ussp" -p "exrheader_renderscene" "string" "h:/ussp/bes_0001/scenes/lighting_v01.ma"

The easiest way to get information from your scene to this parameter pass is to set up a Pre-Render MEL script in your render-pass along the lines of…

string $sceneName = `file -q -sn`; //Grab the name of the current scene.
string $projectName = `getenv "PROJECT"`; //This assumes you have an environment variable called "PROJECT" with the project name setup already.
string $parameters = "";
$parameters += (" -p \"exrheader_renderScene\" \"string\" \"" +  $sceneName + "\" ");
$parameters += (" -p \"exrheader_projectName\" \"string\"" + $projectName + "\" ");
setAttr ($pass + ".exrDisplayParameters") -type "string" $parameters;

See the 3Delight documentation has more information on what type of metadata you can add  to the EXR.

Custom Shader UI in 3Delight

When you create a custom SL shader in 3Delight it’ll create a automatically create a shader which looks like this in Maya. Now the following UI doesn’t look very useful – the names we’ve called our variables vary in how descriptive they are – which isn’t very useful if others are going to be using this shader

This is based off a shader which looks like this the following SL code.

surface ui_example_srf
(
	string texmap = "";
	float blur = 0;
	float usebake = 1;
	float numsamples = 16;
	float doRefl = 0;
	color diffuseColour = color (0.5);
)
{
	// SHADER DOESN'T DO ANYTHING //
}

3Delight does however provide a method of creating nice looking shader UIs. You can use #pragma annotations in your shader source code to make things nicer.

#pragma annotation texmap "gadgettype=inputfile;label=Texture Map;hint=Texture Map"
#pragma annotation blur "gadgettype=floatslider;label=Blur;min=0;max=1;hint=Blur the Texture Map"
#pragma annotation usebake "gadgettype=checkbox;label=Use Bake;hint=Use Bake"
#pragma annotation numsamples "gadgettype=intslider;min=1;max=256;label=Samples;hint=Number of samples to use."
#pragma annotation doRefl "gadgettype=optionmenu:gather-env:occlusion-env:ptc-env;label=Reflection Method;hint=Reflection Method"
#pragma annotation diffuseColour "gadgettype=colorslider;label=Diffuse Colour;hint=Diffuse Colour."

This will create a shader that looks like this. The hint will be displayed either in the Maya status line or as a tool-tip if you hover the cursor over the UI element.

You can place the #pragma lines anywhere in your SL file, to see them you will need to re-compile the shader and then reload the shader inside Maya by right clicking on the shader, selecting “reload shader” and then selecting the shader in either the Assignment Panel or the Outliner.

Procedural Weathering

Based on seeing the VRay dirt shader, I decided to try replicate it in Renderman.

The above image was created using the following function with a couple of additional layers of noise to create the streak effect.

void dirtOcclusion (
	normal NN; vector down; float invmaxdistance, downmaxdistance, invsamples, downsamples;
	output float invocc, downocc;
)
{
	extern point P;
			
	downocc = 1;
	invocc = 1;
	
	downocc -= occlusion(P, down, downsamples, "coneangle", PI/6, "bias", 0.1, "maxvariation", 0, "hitsides", "front", "maxdist", downmaxdistance, "falloff", 0.001);
	invocc -= occlusion(P, -NN, invsamples, "coneangle", PI/2 , "bias", 0.1, "maxvariation", 0, "maxdist", invmaxdistance, "hitsides", "back", "falloff", 0);
}

sRGB to Linear

From “What the RiSpec never told you” we get this little nugget of useful information. Which is how to convert an sRGB colour to linear light. You can use this to convert textures, but best practice is to pre-convert your textures to linear before creating any mipmapped textures in order to preserve energy in the texture – see the Texture Painting section in Sony Pictures Imageworks colour pipeline for details. A much more common use would be to use this to set the colour of lights.

// decode from sRGB luma to linear light
float sRGB_decode_f(float F)
{
	float lin;
	if(F <= 0.03928)
		lin = F/12.92;
	else
		lin = pow((F+0.055)/1.055, 2.4);
	return lin;
}

color sRGB_decode(color C)
{
	color D;
	setcomp(D, 0, sRGB_decode_f(comp(C,0)));
	setcomp(D, 1, sRGB_decode_f(comp(C,1)));
	setcomp(D, 2, sRGB_decode_f(comp(C,2)));
	return D;
}

The first function sRGB_decode_f does the majority of the work, the second function sRGB_decode uses that in order to operate on an input colour. To use this in SL we would use something along the lines of this. The first line here creates a colour variable with a mid-grey value in sRGB space. The second line converts that colour into a linear colour.

color myColour = (0.5);
myColour = sRGB_decode(myColour);

 

Custom Passes in 3Delight

Quite often in CG when working with multiple passes – you want  to do different things depending on what type of pass your rendering – the two more common ways to do this are to either create two different shaders and change the assignment for each pass or to write a shader which is able to figure out what type of pass it is and act appropriately.

For example in a bake pass you typically want to bake out attributes which aren’t dependant on the position or direction of the camera  – this includes things like diffuse/ambient shading, subsurface scattering and ambient occlusion data  – which can all be baked out and reused on objects. Only when the position and direction of the objects or lights changes does the scene need to be rebaked.

In order to control this in 3Delight you can use the RiMel commands to setup custom RIB commands which can be read by your shaders. The following MEL commands are placed inside a PreWorldMEL attribute on the render pass itself.

RiOption -n "user" -p "pass" "string" "bake";

RiAttribute -n "cull" -p "hidden" "integer" "0";
RiAttribute -n "cull" -p "backfacing" "integer" "0";
RiAttribute -n "dice" -p "rasterorient" "integer" "0";

This will output the following commands into the RIB file.

Option "user" "string pass" [ "bake" ]
Attribute "cull" "integer hidden" [ 0 ]
Attribute "cull" "integer backfacing" [ 0 ]
Attribute "dice" "integer rasterorient" [ 0 ]

Then within the shader I can query what pass I’m currently rendering and do something appropriate for that type of pass.

uniform string passtype = "";
option( "user:pass", passtype );
if (passtype == "bake")
{
    // Do something here
}

By default 3Delight also exports out the name of the render pass to an attribute called delight_renderpass_name – this is name of your render pass inside Maya. You can query that name using the following RSL. Obviously using this method highly depends on what you call your passes – the following shading code wouldn’t work if the render pass was called anything other than “bake” – for example if you wanted to do multiple bake passes for within the same scene like separating out animated bakes (which require multiple frames) from static bakes (things which don’t move which can be stored in one frame).

string passtype = "";
option ("user:delight_renderpass_name",passtype);
if (passtype == "bake")
{
	// Do something here	
}