Here’s a snippet that loops over the shape nodes in an ASS file.

from arnold import *
AiBegin()

AiMsgSetConsoleFlags(AI_LOG_ALL)

# Required if the ASS file uses any SItoA shaders
AiLoadPlugins('C:/softimage/workgroups/sitoa-3.4.0-2015/Addons/SItoA/Application/Plugins/bin/nt-x86-64')

AiASSLoad('C:/softimage/projects/Support/Arnold_Scenes/Default_Pass_Main.1.ass')

# Iterate over all shape nodes
iter = AiUniverseGetNodeIterator(AI_NODE_SHAPE);
while not AiNodeIteratorFinished(iter):
	node = AiNodeIteratorGetNext(iter)
	print "[script] AiNodeGetName: {0}".format( AiNodeGetName( node ) )
	
	ne = AiNodeGetNodeEntry( node )
	print "[script]  AiNodeEntryGetName: {0}".format( AiNodeEntryGetName( ne ) )
	print "[script]  AiNodeEntryGetType: {0}".format( AiNodeEntryGetType( ne ) )
	print "[script]  AiNodeEntryGetTypeName: {0}".format( AiNodeEntryGetTypeName( ne ) )
	
AiNodeIteratorDestroy(iter)
AiEnd()

This would print something like this:

C:\solidangle\scripts>python shapes.py
[script] AiNodeGetName: root
[script]  AiNodeEntryGetName: list_aggregate
[script]  AiNodeEntryGetType: 8
[script]  AiNodeEntryGetTypeName: shape
[script] AiNodeGetName: cube.SItoA.1000
[script]  AiNodeEntryGetName: polymesh
[script]  AiNodeEntryGetType: 8
[script]  AiNodeEntryGetTypeName: shape

Note the root node of type list_aggregate. It’s shape used internally by Arnold. Just be aware that that root node is there in the universe, because even if you load an ASS file that contains just polymesh nodes, there will be a root node that you’ll have to skip over.

In this case, nParticles (render type = point) weren’t visible behind a refractive plane:

For the points render type, you get an Arnold points shape (with mode “disk”), so I exported an ASS file to see the parameter settings on the points node. I noticed the visibility 243 right away (the default visibility is 255, which is visible to all rays). And sure enough, in the Render Stats for the particle shape, some rays were turned off (and the check boxes were disabled too).

I used the User Options to force the visibility to 255

and the particles behind the refractive surface appeared:

This is a Maya thing. For most particle render types, the particles are not visible in reflections or refractions. It says so in the docs:

You can turn on reflections, refractions, and shadows when you software render Clouds, Tubes, and Blobby Surfaces

I’m not sure where the default values are set, but I did find the AEtemplate code that disables the render stats for all particle render types except the “s/w” type:

// C:\Program Files\Autodesk\Maya2015\scripts\AETemplates\AEparticleLayout.mel
		if( $value == 7 || $value == 8 || $value == 9 ) {
			// software particle type
			editorTemplate -dimControl $nodeName "visibleInReflections" false;
			editorTemplate -dimControl $nodeName "visibleInRefractions" false;
			editorTemplate -dimControl $nodeName "castsShadows"    		false;
			editorTemplate -dimControl $nodeName "receiveShadows" 		false;
			editorTemplate -dimControl $nodeName "primaryVisibility" 	false;
		} else {
			// hardware particle type
			editorTemplate -dimControl $nodeName "visibleInReflections" true;
			editorTemplate -dimControl $nodeName "visibleInRefractions" true;
			editorTemplate -dimControl $nodeName "castsShadows"			true;
			editorTemplate -dimControl $nodeName "receiveShadows" 		true;
			editorTemplate -dimControl $nodeName "primaryVisibility" 	true;
		}

So, since that AE template code just enables and disables UI controls, but doesn’t change the actual values, another way to enable Visible in Refractions (or Visible in Reflections) is to do this:

1. Change the Particle Render Type to one of the “s/w” types, like Blobby Surface.
2. Now the Visible in Refractions check box is enabled.
3. Select the check box.
4. Go back and change the Particle Render Type to points.

Now when you render, the points are visible to refraction rays, so they show up behind the glass.

If you’re still using ARNOLD_LICENSE_HOST and ARNOLD_LICENSE_PORT, now’s the time to stop. As of Arnold 4.2.4.0, these deprecated environment variables are no longer supported.

Instead, use solidangle_LICENSE.

For example, if you currently have these environment variable settings:

ARNOLD_LICENSE_HOST=lic_server
ARNOLD_LICENSE_PORT=5055

you can replace them with this:

solidangle_LICENSE 5055@lic_server

Note: solidangle_LICENSE was added in Arnold 4.0.4 (released back in 23-May-2012).

Also new with Arnold 4.2.4.0 is the ability to use a .lic file instead of an environment variable. Just create a .lic file that looks like this:

HOST lic_server 5055

and put the .lic file in the same folder as Arnold (ai.dll, libai.so, or libai.dylib).

If you want to put the .lic file somewhere else, then you need to set solidangle_LICENSE to point to the lic file.

You can download Arnold here. The Arnold download (aka the Arnold SDK) includes the Arnold library, the Arnold C++ API, the API docs, and the Python bindings for the Arnold API.

To use the Arnold Python API, you need to add the Arnold python folder to the PYTHONPATH:

set PYTHONPATH=C:\solidangle\arnold\Arnold-4.2.4.0-windows\python

Here’s a “hello world” written with the Arnold Python API:

#
# hello_world.py
#
from arnold import *

AiBegin()

AiMsgSetConsoleFlags( AI_LOG_INFO )

AiMsgInfo( 'Hello World' )

AiEnd()

Here’s a quick breakdown of the script.

• You need to import the arnold module.
• An Arnold session always starts with AiBegin() and ends with AiEnd(). You have to call AiBegin() to initialize Arnold and enable the Arnold API. Try commenting it out and see what happens…
• We need to call AiMsgSetConsoleFlags() to set the log verbosity level (otherwise we won’t see our “Hello World”, because the default level is AI_LOG_NONE).
• AiMsgInfo() sends our “Hello World” to the log.

Assuming that Python in is your PATH, you can run the hello world script like this:

python hello_world.py

and that will give you this output:

C:\solidangle\arnold\scripts>python helloworld.py
        | log started Wed Mar 04 14:31:40 2015
        | Arnold 4.2.4.0 windows icc-14.0.2 oiio-1.4.14 rlm-11.2.2 2015/02/26 15:08:42
        | running on StephenBlair-PC with pid 33812
        |  1 x Intel(R) Xeon(R) CPU E3-1240 V2 @ 3.40GHz (4 cores, 8 logical) with 16338MB
        |  Windows 7 Professional Service Pack 1 (version 6.1, build 7601)
        |
        | Hello World
        |
        | releasing resources
        | Arnold shutdown

For documentation, you use the Arnold SDK documentation. It’s for the C++ API, but the Python API is basically a one-to-one wrapper around the C++ API.

You can find the docs in the doc/api/index.html folder of the Arnold installation.

AiBegin() and AiEnd() are part of the Rendering API.
AiMsgSetConsoleFlags() and AiMsgInfo() are part of the Message Logging API, so go there to check out the possible flags, and what other logging functions are available.

As of Arnold 4.2.3.1, the minimum Windows version is Windows 7. We no longer support Windows versions before Windows 7 and Windows Server 2008 R2.

This applies to all plug-ins (such a MtoA 1.2.02 and later, or SItoA 3.4 and later) that use Arnold 4.2.3.1 or later.

If you try to load an Arnold plugin on an unsupported Windows, you’ll get an error (something like “The specified procedure could not be found”).

On Vista with Arnold 4.2.3.1 or later, kick -nodes gives you a more specific error:

"kick.exe - Entry Point Not Found" 
"The procedure entry point SetThreadGroupAffinity could not be located in the dynamic link library KERNEL32.dll."

When you enable file logging, it can seem a bit of a mystery where the .log files end up. You may find log files in different folders of your project, like the scenes folder, or the sourceimages folder.

Here’s how it works.

• If the MTOA_LOG_PATH environment variable is set, the log files are saved to the folder specified by MTOA_LOG_PATH.
• If MTOA_LOG_PATH is not set, the log files are saved in the current workspace directory (in MEL, that’s workspace -q -directory). In other words, the log files are saved to last place you went with the Maya file browser. If you haven’t used the file browser yet, the log file is saved in the root folder of the project.
• If you click the folder icon beside the Filename text box, you can choose where the log files are saved.

Note that the log files will always include the frame number, so you’ll get arnold.1.log, arnold.2.log, and so on.

mayaBump2D has an RGB parameter for normal maps, and it’s named “normal_map”:

C:\solidangle\mtoadeploy\2015\bin>kick -l ..\shaders -info mayaBump2D
node:         mayaBump2D
type:         shader
output:       RGBA
parameters:   11
filename:     ..\shaders/mtoa_shaders.dll
version:      4.2.4.1

Type          Name                              Default
------------  --------------------------------  --------------------------------

FLOAT         bump_map                          0
FLOAT         bump_height                       1
RGB           normal_map                        0, 0, 1
BOOL          flip_r                            true
BOOL          flip_g                            true
BOOL          swap_tangents                     false
BOOL          use_derivatives                   true
BOOL          gamma_correct                     true
ENUM          use_as                            bump
RGBA          shader                            0, 0, 0, 1
STRING        name

In Maya, you don’t connect your normal map directly to mayaBump2D.normal_map. Instead, just connect the normal map alpha to the Bump Value

and then change bump2d > 2d Bump Attributes > Use As to Object Space Normals or Tangent Space Normals.

The Use As parameter controls how MtoA translates the shaders to Arnold. For example, if Use As is Object Space Normals, you get this:

mayaBump2D
{
 name bump2d1
 bump_map file1.a
 bump_height 1
 normal_map file1
 flip_r on
 flip_g on
 swap_tangents off
 use_derivatives on
 gamma_correct on
 use_as "object_normal"
 shader aiStandard1
}

MayaFile
{
 name file1
 ...
 filename "shaders_offest_normalmap.jpg"
 ...

Notice that file1 (the MayaFile node) is linked to mayaBump2D.normal_map.

Here’s a question asked recently. Given a shading tree like the one below, why don’t AOVs like diffuse_direct include the blended color from the Blend Color node?

The answer: because it is the Standard shader that writes the AOV, not the Blend Color shader. The diffuse_direct AOV gets the diffuse layer calculated by the Standard shader, and that’s it.

The MtoA AOV browser shows you what AOVs are implemented by which shaders:

MtoA provides an arnoldFlushCache command (and the Arnold > Flush Caches menu uses that command). You can call it from Python like this:

import maya.cmds as cmds
cmds.arnoldFlushCache( textures=True )

Here’s a snippet that shows how to create a simple four-polygon polymesh node with the Arnold Python API.

n = AiNode( "polymesh" )
AiNodeSetStr( n, "name", "grid" )

nsides = [4, 4, 5, 6]
AiNodeSetArray( n, "nsides", AiArrayConvert(len(nsides), 1, AI_TYPE_UINT, (c_uint*len(nsides))(*nsides) ) )

vidxs = [0, 1, 4, 3, 1, 2, 5, 4, 3, 4, 7, 6, 9, 4, 5, 11, 8, 10, 7]
AiNodeSetArray( n, "vidxs", AiArrayConvert(len(vidxs), 1, AI_TYPE_UINT, (c_uint*len(vidxs))(*vidxs) ) )

nidxs = [0, 1, 2, 3, 1, 4, 5, 2, 3, 2, 6, 7, 8, 2, 5, 9, 10, 11, 6]
AiNodeSetArray( n, "nidxs", AiArrayConvert(len(nidxs), 1, AI_TYPE_UINT, (c_uint*len(nidxs))(*nidxs) ) )

vlist = [-1, 0, -1, -1, 0, 0, -1, 0, 1, -0.197835326, 0, -0.742445886, 0, 0, 0, 0, 0, 1, 0.802164674, 0, -0.742445886, 1, 0, 0, 1, 0, 1, 0.270379633, 0, -1.21302056, 1, 0, 0.508926511, 0.496316135, 0, 1]
AiNodeSetArray( n, "vlist", AiArrayConvert(len(vlist), 1, AI_TYPE_FLOAT, (c_float*len(vlist))(*vlist) ) )

nlist = [0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]
AiNodeSetArray( n, "nlist", AiArrayConvert(len(nlist), 1, AI_TYPE_FLOAT, (c_float*len(nlist))(*nlist) ) )

m = AtMatrix( 	1, 0, 0, 0,
		0, 1, 0, 0,
		0, 0, 1, 0,
		0, 0, 0, 1 )

am = AiArrayAllocate(1, 1, AI_TYPE_MATRIX)
AiArraySetMtx( am, 0, m )

AiNodeSetArray( n, "matrix", am  )

AiNodeSetBool( n, "smoothing", True )

AiNodeSetByte(n, "visibility", 255 )

# Assign a shader to the polymesh node
u = AiNode( "utility" )
AiNodeSetStr( u, "name", "aiUtility1" )

AiNodeSetPtr( n, "shader", u )

And here’s the resulting node in the ASS file:

polymesh
{
 name grid
 nsides 4 1 UINT
4 4 5 6
 vidxs 19 1 UINT
  0 1 4 3 1 2 5 4 3 4 7 6 9 4 5 11 8 10 7
 nidxs 19 1 UINT
  0 1 2 3 1 4 5 2 3 2 6 7 8 2 5 9 10 11 6
 vlist 12 1 POINT
  -1 0 -1 -1 0 0 -1 0 1 -0.197835326 0 -0.742445886 0 0 0 0 0 1 0.802164674 0 -0.742445886 1 0 0
  1 0 1 0.270379633 0 -1.21302056 1 0 0.508926511 0.496316135 0 1
 nlist 12 1 VECTOR
  0 1 0 0 1 0 0 1 0 0 1 0 0 1 0 0 1 0 0 1 0 0 1 0 0 1 0 0 1 0 0 1 0 0 1 0
 smoothing on
 visibility 255
 matrix
 1 0 0 0
 0 1 0 0
 0 0 1 0
 0 0 0 1
 shader "aiUtility1"
}

If you want to instance lights in Maya, use Duplicate Special. MtoA will correctly translate those instances to Arnold (as copies, not instances, because Arnold itself doesn’t support light instances).

MtoA doesn’t support the particle instancer for lights.

PS I don’t think Maya supports instancing lights with the particle instancer. The Maya docs say “Do not instance lights; they’ll have no effect in rendering.”, and that’s the behavior I’ve observed with mental ray and the Maya Software renderer. Also, if I leave the viewport set to Viewport 2.0, Maya crashes when I try to use the particle instancer with point or spot lights (and that’s without MtoA loaded).

The technical reason for a “No ISV servers to start” message is that that RLM could not read the ISV line from the license file.

So, for example, if you somehow save the license file as a binary file that looks like this:

then you’ll get No ISV servers to start, because obviously there’s no ISV line in that file.

Note: You’ll also see The hostname in the license file(s) may be incorrect, but that warning can always be safely ignored.

05/14 09:17 (rlm) 
05/14 09:17 (rlm) WARNING: No license file for this host (StephenBlair-PC)
05/14 09:17 (rlm)          The hostname in the license file(s)
05/14 09:17 (rlm)          may be incorrect
05/14 09:17 (rlm) 
05/14 09:17 (rlm) License files:
05/14 09:17 (rlm)     arnold_eval_90b11c647d93_20150514.lic
05/14 09:17 (rlm) 
05/14 09:17 (rlm) RLM License Server Version 11.2BL2

	Copyright (C) 2006-2014, Reprise Software, Inc. All rights reserved.

05/14 09:17 (rlm) License server started on StephenBlair-PC
05/14 09:17 (rlm) Server architecture: x64_w2
05/14 09:17 (rlm) License files:
05/14 09:17 (rlm)     arnold_eval_coffee0000_20150514.lic
05/14 09:17 (rlm) 
05/14 09:17 (rlm) Web server starting on port 5054
05/14 09:17 (rlm) Using TCP/IP port 5053
05/14 09:17 (rlm) ... adding UDP/IP port 5053
05/14 09:17 (rlm) (No ISV servers to start)

Here’s how to set up your custom camera in Houdini. I’ll use the Oculus camera as an example.

1. Copy OculusCamera.dll and OculusCamera.mtd to your HtoA arnold\plugins folder. For example, on my machine, that’s here:

   C:\Users\StephenBlair\htoa\htoa-1.5.0_r1338_houdini-14.0.258\htoa-1.5.0_r1338_houdini-14.0.258\arnold\plugins

2. In the Shop network, create an Arnold Shader Network.
   
3. In the Arnold Shader Network (arnold_vopnet), create an Camera > Oculus Camera and an Output > Camera Output. Connect the Oculus Camera to the OUT_Camera.
   
4. In the Obj network, select your camera, and in the Camera properties, set the Camera Shader to point to your arnold_vopnet.
   

A few quick notes about instancing support in HtoA:

• For instancing, use the Instance object with fast point instancing. HtoA doesn’t support full point instancing.
• You can assign material to instances with the shop_materialpath string attribute on the instance points.
• Fast point instancing supports per-instance user data and instance OBJ property overrides.
• Light instancing is not supported [yet]. Actually, Arnold itself doesn’t support light instances, but what plugins like MtoA and SItoA do is translate the light instances into duplicates of the light for Arnold.
• Procedurals (both DSO and ASS) can be instanced.

No, there isn’t. HtoA recently added support for an ARNOLD_PROCEDURAL_PATH environment variable, but neither MtoA or Arnold itself support ARNOLD_PROCEDURAL_PATH.

Here’s a few things you can do:

• If you’re kicking ASS files, you can set the procedural search path on the kick command line. For example, assuming ARNOLD_PROCEDURAL_PATH is set in your environment, you could do this on Windows:

     kick -set options.procedural_search_path %ARNOLD_PROCEDURAL_PATH%

  Or this on Linux or OSX:

     kick -set options.procedural_search_path $ARNOLD_PROCEDURAL_PATH

• You could add the procedural search path to the system path (PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on OSX). Arnold will then find the procedural by searching through the system path.
• Maya, you can put an environment variable in the Procedural Search Path text box. Note that you have to use square brackets, like this: [ARNOLD_PROCEDURAL_PATH].
  

In general, Arnold is going to work on pretty much any 64-bit system where Houdini, Maya, Cinema 4D, or Softimage works. However, there are some minimum OS requirements:

• OSX 8 or later (as of Arnold 4.2.7.0)
• Windows 7 or later (as of Arnold 4.2.3)
• Linux with at least glibc 2.12 and libstdc++ 3.4.13 (gcc 4.4.7) (as of Arnold 4.2.6)

Other than that, Arnold works on Intel and AMD processors, and has no graphic card or GPU requirements, since Arnold is a CPU-based renderer.

When RLM detects that it’s running on a virtual machine, you’ll see “This server does not run on virtual machines, exiting” and “solidangle initialization error: 5, not restarting” in the RLM debug log:

06/22 11:45 (solidangle) RLM License Server Version 10.1BL2 for ISV "solidangle"
06/22 11:45 (solidangle) Settings from RLM Version 10.1BL2 for ISV "solidangle"
...
06/22 11:45 (solidangle) This server does not run on virtual machines, exiting
06/22 11:45 (rlm) Reread request (for everyone) by webuser@example-pc
06/22 11:45 (rlm) Restarting solidangle on port 55555
06/22 11:45 (rlm) New thread created to watch ISV solidangle
06/22 11:45 (rlm) Starting any new ISV servers...
06/22 11:45 (rlm) 
06/22 11:45 (rlm) solidangle initialization error: 5, not restarting
06/22 11:45 (rlm) 
06/22 11:45 (rlm) The ISV server is running on the wrong host.
06/22 11:45 (rlm) 
06/22 11:45 (rlm) This can happen if:
06/22 11:45 (rlm)  The hostid of this machine doesn't match any license file
06/22 11:45 (rlm)  - or -
06/22 11:45 (rlm)  You are attempting to run the server on a virtual machine

In this case, the machine wasn’t virtual. And both RLM and the solidangle ISV were the same version (10.1BL2), so it wasn’t a case of a newer solidangle.set with an older RLM, which gives you the same log output.

The problem was the older RLM version. The older RLM 10.1BL2 would sometimes issue a false positive for virtual machine detection. The solution is to upgrade to the newer RLM 11.2BL2, which you can get by downloading Arnold 4.2.4.0 or later.

The Arnold log is important, not just for troubleshooting and getting help from us at Solid Angle, but also for understanding what’s going on when Arnold renders your scene.

But, first things first: where’s the log? The Arnold log is output to the Cinema 4D Console:

To open the Console, click Script > Console.

You can set the verbosity level in the Render Settings > Diagnostics. By default, the verbosity level is Warnings, but by increasing it to Info, you’ll get the % done log entries. You can also send the log to a file (good for logging support cases!).

• Use a Volume Sample Float to sample the heat channel
• Plug the volume sample into a ramp
• Plug the ramp into the Emission (the Emission Source must be set to Parameter)

This error

ERROR   | [mtoa] [xgenTranslator] Could not find xgen_procedural in search path $ARNOLD_PLUGIN_PATH

happens only when MtoA is first loaded, and it can be safely ignored. It doesn’t cause any problems when you render, and MtoA loads the XGen procedural from the MtoA procedurals folder.

The error is a consequence of how MtoA searches folders when it loads extensions. If you really need to get rid of the error, you can try copying the xgen_procedural library to the MtoA shaders folder.