Programming model for Surfaces

The method used here is to package each geometric primitive (e.g. sphere) as a Matlab 'struct'. Geometric primitives are then grouped in a 'cell array'. The cell array is ultimately passed to the renderpatch function for conversion to a shaded polygon image or the renderwire function for conversion to a wireframe image.

Each geometric primitive struct may have several data fields. Each struct must have a faces field and a vertices field in order to be rendered. The vertices field of N vertices must be an Nx3 array. The faces field of M faces must be an Mxf array, where f would be 3 for a triangle list and 4 for a rectangle list. For example a struct called cube could be defined as:

cube.vertices=[ 0 0 0; 1 0 0; 1 1 0; 0 1 0; ...
                0 0 1; 1 0 1; 1 1 1; 0 1 1;]; 
cube.faces=[ 1 2 6 5; 2 3 7 6; 3 4 8 7; ...
             4 1 5 8; 1 2 3 4; 5 6 7 8; ] ; 

Of course, it would be tedious to have to figure out the faces for spheres and other objects, so a set of prototype objects is included below.

There are several optional fields which can be defined. The field names are case-sensitive and must be all lower-case. If you do not specify a field value, its default value is used. All fields can be used with the renderpatch function. Only facecolor, edgecolor and visible may be used with renderwire. In addition, renderwire maps the facecolor to the edgecolor.

• facecolor: Can take the values
  • 'none' which makes the faces invisible
  • a color string e.g. 'white'
  • a 3-vector [red, green, blue]
  • default=cyan
• edgecolor: Can take the values
  • a color string e.g. 'white'
  • a 3-vector [red, green, blue]
  • default='none' which makes the edges invisible
• ambientstrength: The non-directional light reflectance. Range=0 to 1, default=.6
• specularstrength: The specular highlight reflectance. Range=0 to 1, default=.2
• specularexponent: The specular highlight size. Range=1 to 1000, default=10
• diffusestrength: The directional light reflectance. Range=0 to 1, default=.5
• facelighting: Can take the values
  • 'none' which means that lighting computations are not done.
  • 'flat' which means that each polygon has one color.
  • 'gouraud' which means that each polygon has interpolated colors.
  • default='phong' which means that each polygon has interpolated normals.
• visible: Can take the values
  • 'off' which is invisible
  • default='on'

For instance for the cube struct you might want to specify

cube.facelighting='flat';   %flat shading with no edge interp 
cube.facecolor=[.9,.2,.2];  %a red color

The renderers, renderpatch and renderwire expect a cell array as a parameter. The cell array should contain all objects to be rendered. The combine function described below concatenates objects in the correct format for the renderers. See the example code below for specific use.

The Matlab Code for Surfaces

The code is packaged as several Matlab functions so that is can be used in a natural fashion. The Matlab 'help' function will return information on each function.

• renderpatch
  • count=renderpatch(scene);
  • Converts a cell array or struct to an shaded polygon image.
  • returns a count of the number of structs actually rendered.
• renderwire
  • count=renderwire(scene);
  • Converts a cell array or struct to an wireframe image.
  • returns a count of the number of structs actually rendered.
• combine
  • newobject=combine(obj1, obj2 , ...);
  • Several objects may be combined into one composite object
• scale
  • scaledobj=scale(obj,xscale,yscale,zscale);
  • Input paramenters are an object and the scale along each of 3 axes.
• translate
  • movedobj=translate(obj,x,y,z);
  • Input paramenters are an object and the distance to move along each of 3 axes.
• rotateX
  • rotatedobj=rotateX(obj,angle);
  • angle is rotation in degrees around the x axis.
• rotateY
  • rotatedobj=rotateY(obj,angle);
  • angle is rotation in degrees around the y axis.
• rotateZ
  • rotatedobj=rotateZ(obj,angle);
  • angle is rotation in degrees around the z axis.
• UnitSphere:
  • sphere1=UnitSphere(3);
  • Input parameter is a measure of the output sphere...