pyrtl

Python extension module for the rtl ray tracing library. The functionality defined in this module allows the building of a scene through an interface similar to that of OpenGL. There are three types supported in this module: pyworld, pymaterial, and pytexture. What they are for should be obvious. See the documentation for the module functions for how to construct instances of these types.

Please see example.html for an example of a scene definition and its rendering.

Module Functions

World([<fov:float=45>])

Create an pyworld object for the construction of a scene to render. The parameter sets the field of view for the image that will be created.

Material([(<r:float=1>,<g:float=1>,<b:float=1>)])

Create a pymaterial object for the use on objects in the scene. The parameter is the diffuse colour for the material. Illumination is through the Phong illumination model so the parameters for materials (changeable through the pymaterial member functions) are the standard ones.

Glass([(<r:float=0.95>,<g:float=0.95>,<b:float=0.95>),<frost:float=0.1>])

Create a pymaterial object for the use on objects in the scene. This functions returns a material suitable for use to simulate glass. The index of refraction is set to 1.66, and the parameters set the transparency colour and the frosting of the glass.

Checkers(<mat1:pymaterial>,<mat2:pymaterial>)

Creates a pytexture object to apply a solid texture checker board onto a material. The two parameters are the materials to use for each of the checks.

Tiles(<mat1:pymaterial>,<mat2:pymaterial>,[(<w:int=1>,<h:int=1>),<gw:int=1>,<of:int=0>])

Creates a tiled solid texture. Tiles are arranged in rectangles with the given width and height w, separated by rows and columns of gw (grout width). The materials passed in the first two arguments are the respectively the material for the tiles and the material for the grout. The final parameter indicates if the tiles should be offset .. like bricks.

Turbulence(<mat1:pymaterial>,<mat2:pymaterial>,[<w:float=1>])

Creates and returns a ubiquitous Perlin turbulence solid texture. The first two parameters specify the materials to be mixed by the turbulence. The third parameter says how much to weight the turbulence value by. The resampling parameter is fixed at 8 octaves.

TextureMap(<file:string>,[<utiles:int>,<vtiles:int>])

Place a texture map onto an object. The second and third parameters are thenumber of tiles to use on application of the map. The quality of the mapping is heavily dependent on the object to which it is applied. Each object defines its own uv mapping. If this function is poor than the aesthetic result will be poor. Stay tuned for Bier & Sloan two-part texture mapping.

NewAlloc()

Creates a new allocation collector object. This object will collect all rtl dynamically created types. The point is to facilitate easy memory management. If you are rendering frames in an animation, you should wrap the definition of the scene with a call to NewAlloc and a call to KillAlloc.

KillAlloc()

Destroys the last created allocation collector object. This object will collect all rtl dynamically created types. The point is to facilitate easy memory management. If you are rendering frames in an animation, you should wrap the definition of the scene with a call to NewAlloc and a call to KillAlloc.

Print(<msg:string>)

Prints the given message. If the library was compiled with the parallel switch, only the master process will print the message. The message is printed to stdout.

pyworld Member Functions

progress([<p:int=1>])

Turns on/off a progress indicator. As your image renders you will be given an output of the lines it has rendered and how many lines it will render.

shadows([<s:int=1>])

Turns on/off the rendering of shadows.

recursion([<s:int=1>])

Turns on/off the rendering of recursive rays, ie reflection and refraction.

render([<mins:int=-1>,<maxs:int=-1>])

Renders the scene. The default parameters indicate one sample per pixel. You can specify the minimum and maximum samples per pixel to take base on adaptive jittered sampling.

prender([<mins:int=-1>,<maxs:int=-1>])

Parallel render. The parameters are the same as for prender. This function will fail if pyrtl was not compiled with -DPARALLEL, (see the Makefile). Also the program executing the python script must initialize MPI. This parallel rendering system uses MPI and assumes that it has been initialized. See mpipython.c for my implementation of such a beast.

light((<x:float>,<y:float>,<z:float>),[(<r:float=1>,<g:float=1>,<b:float=1>),<radius:float=0>])

Insert a light into the scene. There is no limit on the number of lights that you can have in the scene. I hope that the parameters are self explanatory. Lights do not render, and spherical lights are the only area lights supported. To get a point light source, just pass 0 for the radius.

image([(<width:int=320>,<height:int=240>),(<r:float=0>,<g:float=0>,<b:float=0>)])

Specify the image buffer that the scene should be rendered into. The parameters setup for the width and height of the image, and the background color.

lookat((<x:float>,<y:float>,<z:float>),[(<fx:float=0>,<fy:float=0>,<fz:float=0>),(<nx:float=0>,<ny:float=1>,<nz:float=0>)])

Standard lookat transformation for the camera position. The parameters are the camera position, a point in the direction where the camera is looking and the world up vector.

viewing((<x-rot:float>,<y-rot:float>,<zoom:float>,(<x-tx:float,y-tx:float))

Specify a viewing transformation for the scene. Multiplies the current transformation matrix by the transformation implied by the parameters. The parameters are the same as pybv uses. This should probably be the first specified transformation in the scene specification.

identity()

Load the identity matrix into the current transformation.

translate(<x:float>,<y:float>,<z:float>)

Multiply the current transformation matrix by given translation.

scale(<x:float>,<y:float>,<z:float>)

Multiply the current transformation matrix by given scale.

scale(<axis:int,<angle:float>)

Multiply the current transformation matrix by given rotate. The parameters are the axis to rotate around, zero based, and the angle to rotate by in degrees.

push()

Push the current attributes.

pop()

Pop the attributes stack.

material(<m:pymaterial>)

Set the current material for objects.

texture(<t:pytexture>)

Set the current texture to be applied to materials when objects are added.

begin(<type:string>)

Begin a csg object. Pass either union, intersection, or difference.

end()

Ends a csg object.

box([<x:float=-1>,<y:float=-1>,<z:float=-1>,<x:float=1>,<y:float=1>,<z:float=1>])

Inserts a cube geomtery into the scene.

plane()

Inserts a plane (y=0) into the scene

floor()

Inserts a plane (y=0) which is bound from -1..1 in both x and z into the scene

infcone()

Inserts an infinite cone into the scene.

infcylinder()

Inserts an infinite cylinder into the scene.

sphere()

Inserts a sphere into the scene.

sphere()

Inserts a super-ellipsoid into the scene.

torus([<ra:float=0.75>,<rb:float=0.25>)

Inserts a torus into the scene.

soft(<o:pycsoft|pyjbt>,[<kill:in>])

Inserts a soft object into the scene. This function is only available if pyrtl was compiled with -DSOFT. The integer parameters are both booleans, their semantic is respectively that soft-materials should be used, and the pycsoft object should be killed when done.

save([<file:string="/tmp/_pyworld_rendering"])

Save the image to a PPM raw (P6) formatted image file.

clear([<type:string="">])

Clear the current texture or material, pass the string texture to clear the current texture, material for material or nothing for both.

pymaterial Member Functions

texture(<m:pymaterial>)

Set the texture for a material.

kA(<float>)

Set the ambient coefficient

kD(<float>)

Set the diffuse coefficient

kS(<float>)

Set the specular coefficient

kR(<float>,[<float>,<float>])

Set the reflection colour, if the green and blue coefficients are not supplied they are assumed to be the same as the red.

kT(<float>,[<float>,<float>])

Set the transmission colour, if the green and blue coefficients are not supplied they are assumed to be the same as the red.

n(<float>)

Set the specular exponent.

ior(<float>)

Set the index of refraction.

diffuse(<float>,[<float>,<float>])

Set the diffuse colour, if the green and blue channels are not supplied they are assumed to be the same as for red.

specular(<float>,[<float>,<float>])

Set the specular colour, if the green and blue channels are not supplied they are assumed to be the same as for red.

pytexture Member Functions

translate(<x:float>,<y:float>,<z:float>)

Multiply the textures transformation by the given translation.

scale(<x:float>,<y:float>,<z:float>)

Multiply the textures transformation by the given translation.

rotate(<axis:int>,<angle:float>)

Multiply the textures transformation by the given rotatation. The axis to rotate around is zero based, and the angle is in degrees.