Houdini 20.5 Mantra rendering

Rendering as part of a workflow

On this page

Overview

Integrating Houdini rendering into an automated workflow generally involves one or both of the following command line programs.

  • The hython and hbatch command line programs lets you run Houdini Python or HScript (respectively) scripts from the command line, allowing you to do almost everything you can do through the Houdini user interface on the command line, including generating IFD files from render nodes.

  • The mantra renderer program takes IFD files (mantra’s scene description format) and uses them to render images.

The main difference between the two approaches is that hbatch uses a Houdini license while mantra only uses a render license. A common general workflow is to use a single host to generate IFD files for the frames of an animation (using a single full license), and then farm out the rendering to mantra instances (using multiple cheaper render licenses).

windows

On Windows, use Start ▸ All Programs ▸ Side Effects Software ▸ Houdini x.x.x ▸ Command Line Tools to open a command line shell with environment variables defined and Houdini programs in the path.

General tips

  • You can use the Pre Post render node with the Shell render node to run scripts to load geometry files from a server before rendering, and save rendered images to a server after rendering.

  • As with many other network types, it’s a good idea to keep a Null render node with a noticeable, descriptive name (for example FINAL_OUTPUT) at the end of a render network, so that even as you insert and remove nodes from the network, you can always refer to the final node consistently.

  • You can set a render node to render using a specific take. This is an easy way to set up render passes.

Render dependencies

You can connect render nodes together to create dependency graphs, allowing you to control the order in which renders run. You can connect any number of inputs and outputs.

When rendering a node, Houdini will render all input nodes first.

When called from the command line, by default Mantra will render all frames in the input nodes before rendering any frames of the rendering node. That is, if Node B depends on Node A, all frames of Node A are rendered before any frames of Node B (A1, A2, …, An, B1, B2, …, Bn).

Note

When you start a render interactively in Houdini, such as by clicking the Render button on a render node, it runs Mantra with the -I (“interleaved”) flag, so it renders dependencies frame-by-frame instead of node-by-node. This is to allow you to see the result of a single frame faster when working interactively. This means the default behavior of interactive renders and command-line renders are different.

You can get the frame-by-frame behavior (A1, B1, A2, B2, …, An, Bn) on the command line using the -I flag.

Houdini generally ignores the Frame range parameter on an input node when rendering dependencies unless the child node’s Valid Frame Range parameter is “Render Frame Range Only (Strict)”. In that case, Houdini will only output frames within the input node’s frame range.

For example:

composite is dependent on char_diffuse, char_specular and backgound. char_diffuse and char_specular are both dependent on character. If composite is rendered, the order of the render process would be:

  1. All frames of character

  2. All frames of char_diffuse

  3. All frames of char_specular

  4. All frames of background

  5. All frames of composite

  • Houdini will not allow you to create a circular dependency.

  • All input render nodes to a subnetwork will render before the nodes inside the subnet.

  • The subnetwork will render all its “final” nodes (render nodes without output connections) at the same frame or frame range.

  • If a subnet has more than one “final” node, the order in which they render is arbitrary (it’s the order the nodes were created in). To enforce an ordering, use a Merge render nodes to merge the final render nodes together and order its inputs .

  • Render node SubNetworks have no direct connections between the child render nodes and the input render nodes to the SubNetwork. Thus, using a Switch or Batch render nodes with no inputs in a SubNetwork will not have them affect the inputs to the SubNetwork.

To...Do this

Make one node dependent on the output of another

Wire the output of the “parent” render node to the input the dependent node.

If a render node has more than one input, Houdini renders the inputs sequentially. Sibling inputs have no dependencies on each other.

Dependency render nodes

A number of render nodes manage dependencies, and do not render anything themselves.

  • Pre post allows optional “pre-render” and “post-render” branches to run before/after a “main” branch.

  • Batch causes the frames in the input to be rendered in sequential order, in one pass, regardless of the order in which frames are requested.

  • Frame Dependency - Makes a frame depend on other frame times.

  • Merge merges all dependencies together, to make networks easier to read.

  • Switch selects one input (or no inputs) to add a dependency on.

Workflow render nodes

  • Alembic “renders” the scene to an Alembic file.

  • Mantra Archive “renders” the scene to a geometry format optimized for loading by the renderer (using a procedural shader).

  • Geometry “renders” part of the Houdini scene to a geometry file.

  • Shell runs a script or command.

Render passes

Two different ways to show/hide different objects for different render passes:

  • Set up the visibility and settings for each render pass in a separate take, then set a render node to render using that take.

  • Create a bundle or wildcard pattern specifying the objects that should be visible in the pass. Use the Objects tab on the mantra node to specify which objects the render node should render. Note that Houdini wildcards can exclude names as well as include them.

Tip

A good practice is to create a separate render node for each render pass. However, you could use a single render node and script the node’s Take parameter.

Generating an IFD or RIB file

IFD is the scene description format produced by Houdini and consumed by mantra to produce a rendered image or animation sequence. The IFD file contains a complete description of the scene and how to render it.

RIB is the equivalent of IFD for RenderMan and RenderMan-compatible renderers.

You can set up a render output node to save a file instead of rendering an image directly. This gives you the flexibility of rendering at another time, from another machine, or on a render farm. See network rendering.

To...Do this

Set up a render node to output IFD instead of an image

  1. Turn on the Disk File checkbox on the Driver tab of the render node and click the file chooser icon to set a file path.

  2. Click the Render button to generate the IFD file.

Render an IFD file from the command line

mantra -f <<filename>>.ifd <<output_filename>>.pic

(If you don’t specify the -f option, mantra will read the IFD from stdin.)

Save an IFD file from a .hip file on the command line

Use the hbatch command line program to load the .hip file and trigger the render node.

  1. Set up a render node to output IFD, as above.

  2. Load the .hip file into hbatch.

    hbatch myjob.hip
    
  3. On the hbatch command line, use the render command to trigger the render node.

    / -> render my_render_node
    / -> quit
    

Render a .hip file directly from the command line

Use the provided hrender script in $HFS/bin. This script is written in csh. To use this script on Windows, you will need to use a UNIX-like environment such as Cygwin.

This script uses hbatch and so uses a Houdini license, unlike rendering an IFD with mantra which only uses a rendering license.

Using mantra on the command line

Once you have an IFD file you can use mantra to render it on the command line, for example:

mantra -f frame0001.ifd rendered_frame0001.pic

(If you don’t specify the -f option, mantra will read the IFD from stdin.)

mantra -h will print a summary of the available options.

Most command-line options are overrides for properties. This means you can set these properties on the scene camera, and then override them on the command line if necessary.

Control options

-H ‹hostlist

Specify a comma separated list of hosts to perform rendering. For example -H chili,cayenne.

-n ‹val

Number of processes to render using network rendering (deprecated in favor of -j).

-N ‹maj›.‹min›(.‹ren›)

When network rendering, ensure that remote hosts will run at least this version of mantra.

-j ‹numthreads

Specify the number of threads (-j 0 uses maximum threads).

-f ‹file

Read the IFD from the file given instead of from stdin.

If the specified file has a .gz or .sc file extension, mantra will assume the file is compressed.

In addition, file system plug-ins (FS) are used, so you can specify IFD files using opdef:, op:, or even http: protocols.

-e none|basic|full

Enable or disable use of engine procedural shaders that generate geometry from a SOP network at render time.

none is the default instead of basic because to enable geometry-generation procedurals mantra sets up an environment to evaluate SOP networks, impacting start-up performance (both memory and time). The impact will differ based on your environment. One studio might find engine mode added 12 seconds to the process startup time, while for another it could be less than 0.5 seconds.

The argument to -e should be one of the following:

none

Do not enable use of engine procedurals (the default).

basic

Enable procedural shaders that only generate curves or points (enginecurvegen and enginepointgen). Unlike full, this does not consume a Houdini Engine license.

full

Use a Houdini Engine license to enable procedural shaders to generate surface geometry (Mantra: Houdini Engine Procedural and Instance with Hscript Procedural).

If your scene has SOP procedurals but you do not render with the appropriate support enabled using -e, the shader will print an error message and not generate any geometry, but the rest of the render will work normally.

-F

Indicates that the first argument after all options specifies the name of the IFD file to render (instead of the output image).

-o ‹file

Send verbose output to the file given.

On Windows, you can use consolewait or consolenowait instead of a file name. consolewait opens a console window for the output, and you must close the window before the next frame will render. It lets you read fast-moving output but requires you to babysit the window. consolenowait opens a console window and closes it as soon as the frame is done. For slow renders you might still be able to read the output, and it doesn’t require you to click to close the window at every frame.

-p ‹file

Append verbose output to the file given.

-P ‹pyfilter

Specifies a python filter program (see Python Filtering).

-V ‹string

If the string contains:

0-9

Set the renderer:verbose IFD property

a

Set the renderer:alfprogress IFD property

p

Set the renderer:vexprofile IFD property to 1

P

Set the renderer:vexprofile IFD property to 2

On Windows, if the output appears in a pop-up console window, use -o consolewait to keep the window open so you can read the verbose output.

Rendering options

-r

Set renderer:renderengine to raytrace.

-q

Set render quality (deprecated in favor of -Q).

-Q ‹arg

Set render quality. If the argument contains

Example: -Q Bd

-s ‹factor

Set the renderer:shadingfactor property.

-L ‹factor

Set the renderer:rayshadingfactor property.

-M ‹memory

Set the renderer:geocachesize property.

-S ‹filename

Specify a stylesheet file for rendering.

-v ‹variance

Set the image:variance to the value specified.

-A

Set image:samples to (1,1).

-B ‹size

Set the image:bucket property.

-J ‹jitter

Set the image:jitter property.

-c ‹coving

Set the object:coving property.

Image options

-i

Force interactive rendering (into MPlay).

-I

Set various image options (using a comma separated list).

  • resolution=‹W›x‹H – set image:resolution

  • jitter=‹V – set image:jitter

  • subpixel=0|1 – set image:subpixel

  • sample=‹W›x‹H – set image:samples

  • sample=‹N – equivalent to sample=‹N›x‹N

For example, -I resolution=100x80,bucket=16,sample=4,subpixel=1

-w ‹width›, -h ‹height

Specify width/height of image (deprecated in favor of -I).

-b ‹depth

Specify default quantization for image planes.

-z

Render a depth image, use average depth value for each pixel.

-Z

Render a depth image, use closest depth value for each pixel.

-u ‹object›[:‹attrib›]

Set the renderer:uvobject and optionally renderer:uvattribute properties.

Output log

  • You can use -V to set the verbosity level (1 to 9), and -o to direct the output log to a file or device.

  • The output log includes different timing measurements.

    Frame Wall Clock Time

    The real-world time taken to render the frame (the time you would measure looking at a clock on the wall).

    Total Wall Clock Time

    The real-world time taken in total (this includes any work done before and after the actual frame rendering).

    Total CPU Time

    Time the CPU(s) actually spent rendering the frame. If you have multiple cores, this time can be longer than the wall clock time (for example, in an ideal render, this would be 8 times the wall clock time if you have an 8 CPU system).

    System CPU Time Only

    The time mantra spent in operating system calls (for example, reading data from disk or allocating memory). This does not include time spent by the OS waiting for devices (for example, it does not include time spent loading a file across a slow network).

hython and hbatch

  • Running hython gives you a Python command-line environment with the houdini object model package (hou) available.

    % hython myscene.hip
    Python ...
    Houdini ... hou module imported.
    Type "help", "copyright", "credits" or "license" for more information.
    >>> rnode = hou.node("/out/mantra1")
    >>> help(rnode)
    >>> rnode.render()
    
  • Running hbatch gives you an HScript command-line environment. This lets you script almost any action you can perform

    % hbatch myscene.hip
    hbatch Version ... (Compiled on ...)
    / -> cd out
    /out -> help render
    /out -> render mantra1
    

    hbatch -h will print a summary of the available options.

Multithreaded rendering

Mantra is a multithreaded process, which means that a single mantra render will split work between available processors to speed up rendering. By default, mantra detects the number of processors installed in the system and will start enough threads to use all of the processors.

You can turn off multithreaded rendering by unchecking the Use Max Processors checkbox on the Rendering sub-tab of the Properties tab on the mantra render node. You can also manually set the number of threads to use for rendering by setting the Thread Count.

Simple network rendering

Mantra has a simple method for distributing rendering to multiple machines on the local network. This may be useful for ad-hoc speedups when rendering a single image. For more robust and full-featured network rendering, use a render queue manager such as HQueue or Alfred.

The -H option lets you specify hostnames to render on. You can use this to render an IFD file on the command line, or in the Command parameter on the Main tab of the mantra output driver.

For example:

mantra -H localhost,clinton,beijing,finland

This command line will start up mantra on 4 servers named localhost, clinton, beijing, and finland. The machines will render tiles and send them back to the host machine to be assembled into the final image.

  • This only works for rendering a single image.

  • All machines must be running the same version of Houdini license software (hserver). If one of the machines you specify is running a different version of hserver, or not running hserver at all, the render will hang.

    You can check the version of hserver that is running on a machine by running the command hserver -l.

    % hserver -l
    Hostname:       clinton [Linux (little endian)]
    Uptime:         21:29:16        [Started: Wed Aug 15 18:11:48 2007]
    License Server: internal
    Server Version: sesinetd9.0.634
    Version:        Houdini9.0.688
    ...
    

    The major and minor numbers of the Version: value (in this example, 9.0) must match on all machines.

Managing a render farm

HQueue is a general-purpose job management system that distributes, monitors and manages tasks across a collection of servers. It specializes in managing render and dynamic simulation jobs submitted from Houdini however it can be customized to work with any job from any application.

See the online HQueue documentation for information on how to install and use HQueue.

Mantra rendering

Mantra user guide

Basics

Lighting

Next steps

Guru-level

Other renderers