How to Use the HelloRenderMan Programs

Just to be clear, this is not an introduction to Python programming. Nor is it an introduction to 3D graphics and RenderMan. This is about two useful Python programs for creating 3D graphics with Pixar RenderMan.

If you are a 3D artist but don't know anything about programming, or a programmer but don't know anything about 3D graphics, I hope you will dive in anyway. Python is an excellent language for beginning programming, with too many books and online tutorials to list here. RenderMan API is also excellent introduction to 3D graphics, and you can find tutorials online at Pixar.

If you prefer books, at the time of writing (Sep 2017) there are none that are ideal for beginners because RenderMan 21 replaced the RenderMan Shading Language so older tutorials and examples no longer run.

1. Downloading

The Python programs and example code are at my BitBucket project page.

The easiest way is to just click the downloads link and then Download repository. You'll get a ZIP file named something like hugh_fisher-hellorenderman-hexnumber.zip. Or if you are familiar with Mercurial, you can clone the project.

Either way, you should end up with a directory/folder with at least these files in it:

There should also be copies of these web pages, so you can work through it offline if you like.

2. Is this switched on?

Note: all the commands here were copied from my Linux workstation. If you're on a Mac, /home/hugh/ would instead be /Users/hugh/. On Windows PowerShell it will be \Users\hugh\ and forward slashes should be replaced by backslashes.

First step after downloading is to ensure everything iw working. The download includes a simple RenderMan RIB file which should display a green teapot:

/home/hugh% cd hellorenderman
/home/hugh/hellorenderman% prman green-teapot.rib

(On my MS Windows system the teapot sometimes looks a little strange, but if you move the window it corrects itself.)

If that worked, render the teapot again but this time grey and from Python:

/home/hugh/hellorenderman% python teapot.py

If you don't see teapots, something is wrong with your RenderMan and/or Python configuration. Work through the Getting Started With Python and RenderMan guide and try again.

3. Coding with rmwatch

Developing in Python is already fast because there's no compilation or linking required. But I'm lazy, so rmwatch.py is designed to make the development process even faster.

From a terminal window, change into the hellorenderman directory. Type this command:

/home/hugh/hellorenderman% python rmwatch.py teapot.py

As before, you'll see the teapot rendered in a preview window. But notice that the rmwatch.py program doesn't finish. Leave it running, and don't close the render window.

Now start your editor and open teapot.py. (If you are using emacs or vi or similar, you'll need to open another terminal window - don't background rmwatch.py.) About line 40 in the render() function look for this just before drawing the teapot:

ri.Rotate(-90, 1, 0, 0)

This puts the teapot into an upright orientation. Change the -90 angle to -135 or -45 or something and save. Within a second or so the original render window should close and a new one open, with the teapot at the new angle.

4. Animation

Have a look at the code in teapot.py. The "main" control code is function render(), which takes at minimum two arguments. The first is a RenderMan interface object to draw with, the second is a frame number which defaults to 1.

This is meant to be a spinning teapot, so about line 39 in render() there is a rotation by frame * 2. The frame number when run either directly or from rmwatch.py is 1, but this is easily changed. Add a new after line 32, just before # Camera setup:

frame = 10

The teapot will change rotation. Try a few other frame values, but remember you must delete this line before doing a batch render. If you forget, every single frame will be identical.

rmwatch.py can watch more than one file and re-run the main program when any of them change. Useful files to watch include RIB archives, texture maps, or shaders.

(Since there are different frame rates across TV and film and stereo, basing values on just the frame number is usually not a great idea. The extra **args to render() can be used to pass additional parameters. This is just a deliberately simplified example.)

Time to render the entire sequence. To stop rmwatch.py, just press Control-C. Because it isn't the editor, there is nothing that needs saving.

5. Batch rendering with rmframes

The second Python program is rmframes.py. In the terminal type:

/home/hugh/hellorenderman% python rmframes.py teapot.py 300

This will chug away for many minutes and create 300 numbered TIFF files in /tmp/teapot/ on Linux or MacOSX, in \Users\YourName\temp\teapot\ on MS Windows. Assuming there weren't any errors, use your image assembly program to create a movie file from them, and your movie player to admire your spinning teapot.

Have a look at the code for rmframes.py. There's an -out pattern command line option to generate frames into a different directory or with different names if you want. There's also a configFrame() function which sets the resolution and any other global rendering parameters. And the program does a certain amount of housekeeping for you, such as deleting any frames left over from a previous run.

All done

You know how to use rmwatch.py and rmwatch.py. I hope you have found this useful.

Python programmers may be asking why rmwatch.py and rmframes.py are run through the Python interpreter, not as stand-alone programs. The answer is that they'll work fine under Linux and MacOS, but under MS Windows the import path changes for some reason I don't understand. If you're not using Windows, go for it.

These programs only work together by following a few rules about program behaviour and the render() function. Of course, these are just my ideas of how things should work. Everything is Open Source meaning you are free to make copies, change things, give your modified copies to other people, and generally do what you like. And if you have a better idea, please tell me about it at the email address below.

At the end of the teapot program is a standard Python if __name__ == "__main__" for when teapot.py is run directly instead of through rmwatch or being imported by another program. For this special case the main code must create an interface object, configure Begin-Display-Format-FrameBegin, render frame number 1, and clean up again. It's not necessary to put this code into every Python RenderMan file, but I think it is nice to have.


Suggestions, mistakes, other feedback?

Any and all feedback about this gratefully accepted.

hugo.fisher@gmail.com.

Copyright 2017 Hugh Fisher, Canberra. Released under Creative Commons Attribution-NonCommercial-ShareAlike license.