Matrices and Vectors

The matrix module provides a 4x4 homogenous matrix type, a 3-element vector type, and the standard operations. Matrices and vectors are both number and sequence types. As a number type, the basic mathematical operations, such as "+", "-", "%", are overridden with type-specific operations.

Operation	Vector Method	Matrix Method
+	(a,b,c)+(d,e,f)=(a+d,b+e,c+f)	Not Implemented
-	(a,b,c)-(d,e,f)=(a-d,b-e,c-f)	Not Implemented
*	(a,b,c)*(d,e,f)=(a*d,b*e,c*f)	Matrix Multiplication
/	Not Implemented	Not Implemented
% Vector.cross	Cross Product	Not Implemented
^ Vector.dot	Dot Product	Not Implemented
~	Not Implemented	Matrix Inversion
Vector.length()	Returns the length of the vector	Not Implemented

Unary minus also works on vectors. That is, "-v" negates each component of the vector. You can test to see if a vector is all zero using "if v:" which returns true if any component of the vector is nonzero.

Matrices can be used to transform a vector using one of three separate functions. You must call a method to transform a vector by a matrix -- there is no inline syntax for this operation. In the following table, "M" is a matrix and "v" is a vector:

Matrix.transform(v)	Transforms v by M without performing a division by the homogeneous coordinate.
Matrix.project(v)	Transforms v by M including homogenous division.
Matrix.transform_3x3(v)	Transforms v by M using only the upper 3x3 matrix. This is useful for trasforming normal vectors. Normal vectors should be transformed by this function using the inverse transpose of the matrix used to tranform points.

The following functions are used to construct and modify existing matrices. The functions that begin with "set_" initialize the matrix using the named transformation. The remaining functions apply the requested transformation as a post-multiplied matrix operation.

Matrix.set_identity()	Sets the matrix to the identity transformation.
Matrix.set_translate(x,y,z)	Sets the bottom row (homogenous coordinates) to the passed in vector.
Matrix.set_scale(x,y,z)	Sets the diagonal matrix values to the passed in vector.
Matrix.set_rotate(x,y,z)	Constructs a rotation matrix using the order Z -> Y -> X.
Matrix.translate(x,y,z)	Post multiplies the current matrix by the specified translation matrix.
Matrix.scale(x,y,z)	Post multiplies the current matrix by the specified scale matrix.
Matrix.rotate(x,y,z)	Post multiplies the current matrix by the specified Z->Y->X rotation matrix.
Matrix.lookat(x,y,z)	Points the current matrix's Z axis at the specified point in space.
Matrix.lens(fov,hither,yon)	Constructs a perspective matrix with the specified field of view and near and far clipping planes.
Matrix.copy()	Creates a copy of the current matrix.

Most of the vector operations will accept a 3-tuple as a quick standin for a vector. More precisely, a 3-tuple consisting of ints or floats will be coerced into a vector when used in an operation containing other vectors. Similarly, a float will be coerced into a vector with each component set to the float value. For example:

from parc.matrix import Vector

# Use full vector types:
a = Vector(0, 1, 0)
b = Vector(1, 0, 0)
c = a + b

# This does the same thing as above:
a = Vector(0, 1, 0)
c = a + (1, 0, 0)

# You can also do the standard scalar*vector operation:
a = Vector(2, 3, 4)
b = 0.5 * a    # b is set to (1, 1.5, 2)

Scene

The Scene class manages rendering and stores the information describing the camera, geometry, and light objects that make up the scene description. To render a scene, you instance a Scene object, describe the camera model, and then instance various Light, Material, and Geometry objects and add them to the scene. Once the entire scene has been described, you can "render" the scene. Currently, rendering is implemented using a REYES-style algorithm.

Geometry

Geometric primitives are generated procedurally in the generate() method of a Geometry subclass. Each primitive is made up of Vertex instances. For example, a quadrilaterial is generated using four vertices, while a Bezier patch is specified using 16 vertices as control points.

Materials and Lights

Material and light shaders are created by subclassing the respective base classes. Materials are assigned to geometry objects when the geometry is added to the scene. Lights are globally added to the scene independent of other objects. Materials are used to shade geometry, to displace grid vertices, and as texture maps.

Lights and materials are passed a special object, called a shader, in their respective computation methods. The shader is used to access data about the currently shaded point. For example, you can get the current position x,y,z of the shaded point through the shader.P variable. Some of the values accessible through the shader variable are defined by the rendering system while others are defined and computed by other material shaders.

Material shaders can be hierarchically combined to produce complex effects including texture mapping. Shaders are combined by assigning one material to the local instance variable of another material. Once set, the local parameter will be evaluated on-demand through the passed-in shader object. For example:

map = MapMaterial("image.ppm")
material = DiffuseMaterial()
material.Kd = map

The return value of the map material is automatically assigned to the local "Kd" value of the diffuse material. Any local variable can be mapped to another material, but, of course, only variables used within the shader have any meaning. It is completely up to the shader writer to make sure that the mapped values are actually useful. To make this task a bit easier, a number of conventions are used so that systems of shaders can be developed and used together. The following conventional parameters are used within material shaders:

Name	Definition
P	Position in current space of the point being shaded
Kd	Coefficient of diffuse reflection
Ks	Coefficient of specular reflection

Materials have two manditory functions:

__init__(self)

Called when the object is instanciated, this function is used to set default values. There is no return value.

  shade(self)

Called during shading, this method returns an RGBA 4-tuple. Additional values can also be set as instance variables of the passed in shader object. For example, a shader that manipulates the texture values can set the shader.uv tuple.

When a material is used as a displacement map, the return value is assumed to be an (X,Y,Z,unused) 4-tuple. The position value is used as the displaced value for "P", the position of the vertex after displacement.

 

Images

The image module provides a set of basic input and output options for 2D images. The image data is allocated using an on-demand, tile-based scheme. All data is stored in floating point. Each image can have (R,G,B), alpha, and depth information.

Image()

Allocate a new image object. No pixel memory is allocated and the viewport is not set until a file is read in or the viewport is manually set.

  Image.read(filename)

Open an image file. Depending on the file format, data will be read in during this call, or in an on-demand fasion as each tile is requested. The file type is determined from the filename extension, and verified using any magic numbers stored in the file. Currently, only PPM files are supported.

  Image.write(filename)

Write the entire image to disk. The filetype is determined by the filename extension. Currently, only PPM files are supported.

  Image.viewport(x0,y0,x1,y1)

Set the image viewport to the rectangle defined by the minimum and maximum integer values. The viewport includes the minimum and maximum pixels, ie. a viewport of [0,0,0,0] is a valid, 1-pixel viewport. This function will destroy any existing image data.

  Image.set_color((x,y),(r,g,b))

Set the pixel at (x,y) to the color (r,g,b). Allocates tile memory if necessary.

  Image.get_color(x,y)

Returns an (R,G,B) color value for the floating point pixel location using bi-linear interpolation of the four closest pixels.

 

Image Operations

The image operation module provides a set of deferred image processing nodes and a set of font operations for drawing text. The deferred operations all work using a tile-based pull scheme which computes the operation graph on demand.

Here's an example of how to do some simple image processing on a passed in image called render:

def comp(render, name):
    ip.match_viewport(render)
    foreground = ip.image(render)
    background = ip.gradient((0.5, 0.5, 0.9, 1, 1), (0.5, 0.5, 0.9, 1, 1),
                             (0.2, 0.2, 0.6, 1, 1), (0.2, 0.2, 0.6, 1, 1))
    comp = ip.matte(foreground, background).get_image()
# Unix    
    ft = ip.Font("/usr/share/fonts/default/Type1/n019003l.pfb")
# Windows
#    ft = ip.Font("C:/WINNT/Fonts/arial.ttf")
    ft.set_size(16)
    ft.draw_string(comp, 19, 9,  name, 0, 0, 0)
    return comp

The first call sets the viewport of the image graph to match that of the render image. Next, two input nodes are created, the first reads data from the render image and the second creates an image using a procedural gradient function. The two input nodes are composited together using a matte() operation and finally some black text is rendered on the image. The computation of the gradient and matte functions doesn't happen until the get_image() method is invoked.

Font rendering uses the FreeType2 library which recognizes most differnt font file formats.

Font(name)

Creates a new Font object required for rendering text. You must specifiy a valid font in the required name argument. Notice that fonts live in different places under different operating systems.

  Font.draw_string(image, x, y, text, r, g, b)

Render the string contained in text at the location (x,y) with the color (r,g,b) into the specified image.

  Font.set_size(points)

Set the font size to the specified number of integer points.

 

Image Viewer