openscenegraph 0.9.7

B1. Object Files (.obj) Object files define the geometry and other properties for objects in Wavefront's Advanced Visualizer. Object files can also be used to transfer geometric data back and forth between the Advanced Visualizer and other applications. Object files can be in ASCII format (.obj) or binary format (.mod). This appendix describes the ASCII format for object files. These files must have the extension .obj. In this release, the .obj file format supports both polygonal objects and free-form objects. Polygonal geometry uses points, lines, and faces to define objects while free-form geometry uses curves and surfaces. About this section The .obj appendix is for those who want to use the .obj format to translate geometric data from other software applications to Wavefront products. It also provides information for Advanced Visualizer users who want detailed information on the Wavefront .obj file format. If you are a 2.11 user and want to understand the significance of the 3.0 release and how it affects your existing files, you may be especially interested in the section called "Superseded statements" at the end of the appendix. The section, "Patches and free-form surfaces," gives examples of how 2.11 patches look in 3.0. How this section is organized Most of this appendix describes the different parts of an .obj file and how those parts are arranged in the file. The three sections at the end of the appendix provide background information on the 3.0 release of the .obj format. The .obj appendix includes the following sections: o File structure o General statement o Vertex data o Specifying free-form curves/surfaces o Free-form curve/surface attributes o Elements o Free-form curve/surface body statements o Connectivity between free-form surfaces o Grouping o Display/render attributes o Comments o Mathematics for free-form curves/surfaces o Superseded statements o Patches and free-form surfaces --------------- The curve and surface extensions to the .obj file format were developed in conjunction with mental images GmbH&Co.KG, Berlin, Germany, as part of a joint development project to incorporate free-form surfaces into Wavefront's Advanced Visualizer. File structure The following types of data may be included in an .obj file. In this list, the keyword (in parentheses) follows the data type. Vertex data o geometric vertices (v) o texture vertices (vt) o vertex normals (vn) o parameter space vertices (vp) Free-form curve/surface attributes o rational or non-rational forms of curve or surface type: basis matrix, Bezier, B-spline, Cardinal, Taylor (cstype) o degree (deg) o basis matrix (bmat) o step size (step) Elements o point (p) o line (l) o face (f) o curve (curv) o 2D curve (curv2) o surface (surf) Free-form curve/surface body statements o parameter values (parm) o outer trimming loop (trim) o inner trimming loop (hole) o special curve (scrv) o special point (sp) o end statement (end) Connectivity between free-form surfaces o connect (con) Grouping o group name (g) o smoothing group (s) o merging group (mg) o object name (o) Display/render attributes o bevel interpolation (bevel) o color interpolation (c_interp) o dissolve interpolation (d_interp) o level of detail (lod) o material name (usemtl) o material library (mtllib) o shadow casting (shadow_obj) o ray tracing (trace_obj) o curve approximation technique (ctech) o surface approximation technique (stech) The following diagram shows how these parts fit together in a typical .obj file. Figure B1-1. Typical .obj file structure General statement call filename.ext arg1 arg2 . . . Reads the contents of the specified .obj or .mod file at this location. The call statement can be inserted into .obj files using a text editor. filename.ext is the name of the .obj or .mod file to be read. You must include the extension with the filename. arg1 arg2 . . . specifies a series of optional integer arguments that are passed to the called file. There is no limit to the number of nested calls that can be made. Arguments passed to the called file are substituted in the same way as in UNIX scripts; for example, $1 in the called file is replaced by arg1, $2 in the called file is replaced by arg2, and so on. If the frame number is needed in the called file for variable substitution, "$1" must be used as the first argument in the call statement. For example: call filename.obj $1 Then the statement in the called file, scmp filename.pv $1 will work as expected. For more information on the scmp statement, see appendix C, Variable Substitution for more information. Another method to do the same thing is: scmp filename.pv $1 call filename.obj Using this method, the scmp statement provides the .pv file for all subsequently called .obj or .mod files. csh command csh -command Executes the requested UNIX command. If the UNIX command returns an error, the parser flags an error during parsing. If a dash (-) precedes the UNIX command, the error is ignored. command is the UNIX command. Vertex data Vertex data provides coordinates for: o geometric vertices o texture vertices o vertex normals For free-form objects, the vertex data also provides: o parameter space vertices The vertex data is represented by four vertex lists; one for each type of vertex coordinate. A right-hand coordinate system is used to specify the coordinate locations. The following sample is a portion of an .obj file that contains the four types of vertex information. v -5.000000 5.000000 0.000000 v -5.000000 -5.000000 0.000000 v 5.000000 -5.000000 0.000000 v 5.000000 5.000000 0.000000 vt -5.000000 5.000000 0.000000 vt -5.000000 -5.000000 0.000000 vt 5.000000 -5.000000 0.000000 vt 5.000000 5.000000 0.000000 vn 0.000000 0.000000 1.000000 vn 0.000000 0.000000 1.000000 vn 0.000000 0.000000 1.000000 vn 0.000000 0.000000 1.000000 vp 0.210000 3.590000 vp 0.000000 0.000000 vp 1.000000 0.000000 vp 0.500000 0.500000 When vertices are loaded into the Advanced Visualizer, they are sequentially numbered, starting with 1. These reference numbers are used in element statements. Syntax The following syntax statements are listed in order of complexity. v x y z w Polygonal and free-form geometry statement. Specifies a geometric vertex and its x y z coordinates. Rational curves and surfaces require a fourth homogeneous coordinate, also called the weight. x y z are the x, y, and z coordinates for the vertex. These are floating point numbers that define the position of the vertex in three dimensions. w is the weight required for rational curves and surfaces. It is not required for non-rational curves and surfaces. If you do not specify a value for w, the default is 1.0. NOTE: A positive weight value is recommended. Using zero or negative values may result in an undefined point in a curve or surface. vp u v w Free-form geometry statement. Specifies a point in the parameter space of a curve or surface. The usage determines how many coordinates are required. Special points for curves require a 1D control point (u only) in the parameter space of the curve. S