Import-Lightwave() Unix Programmer's Manual Import-Lightwave() NAME imp_lightwave - Lightwave geometry import filter SYNOPSIS This man page describes the options specific to the Lightwave geometry import converter. EXAMPLE CONVERSION SYNTAX To convert a Lightwave file to Wavefront using the default parameters listed in the setup.ini file: pt -i lw -o wave filename.lw To convert a Lightwave file to VRML and override some of the default options in setup.ini: pt -i lw -in-lw-print-stats = yes -o vrml filename.lw OVERVIEW This geometry import converter reads in Lightwave binary object files (.lw) and ASCII scene files (.scn). In addition to its core import capabilities, the converter can also reconstruct scene hierarchy using information gleamed from the scene file and accurately create texture coordinates for the object data from the input texture projections. It is the second most complex import converter, next to that of the 3D Studio reader - it handles all Lightwave geometry attributes (including texture coordinates), all shading and texture mapping options, and the various Lightwave texture projection methods. A nice feature of the converter is that it will use object instancing to reduce the size of the imported scene. For example, if the Lightwave scene file references a Lightwave object 10 times then the converter will only read in and store the basis geometry for the referenced object once. All other references to the file will create instances of the object (in other words, "virtual" objects); this is a benefit of the object/instancing capabilities of the converter's internal database. Some of the features of the converter include: 1. Reading of all Lightwave supported polygon geometry, 2. Ability to break apart each Lightwave object according to the materials assigned to each polygon, 3. Objects which are instanced one or more times within Lightwave (cloned) are likewise instanced within NuGraf. Thus, much memory is saved since only one true copy of the raw geometry is stored in memory for each of the instances. 4. The object hierarchy within the original Lightwave file is recreated exactly within NuGraf. 1 Import-Lightwave() Unix Programmer's Manual Import-Lightwave() 5. All cameras and lights types are supported. 6. Every surface (material) attribute is mapped to equivalent NuGraf surface attributes. 7. All texture mapping types are supported (diffuse, specular, spherical environment mapping, etc). 8. All of the Lightwave texture projection methods are supported, including planar, spherical, cylindrical and cubical. These projection methods are converted directly to equivalent NuGraf projection methods. The conversion is exact, so the textures should appear faithfully when rendered within NuGraf or when the data is exported to another file format (such as 3D Studio, VRML or Wavefront). 9. An IFF image format reader has been added to the NuGraf software so that it can directly read in the Lightwave IFF-formatted texture maps. As some background information, Lightwave uses two types of files to describe a scene: 1. The raw geometry for each object is stored in a separate file called a Lightwave Object File. Normally it has a file extension of .lw, .lwb, .lwobj or sometimes no extension at all. These files are binary and cannot be viewed directly with a text editor. 2. The scene setup description file is stored in a single file called a Lightwave Scene File; it lists the Lightwave binary object files (see above) which are to be read into the scene. Normally it has a file extension of .scene, .scn or it must use a descriptive filename such as "Load Up The Entire Scene". This file is human readable and can be edited with a normal text editor. Due to the fact that many Lightwave scene files originated on the Amiga you will have to perform some hand editing of the files before they can be loaded. In particular you should perform the following changes to the files: 1. Copy any "brushes" (or "textures" in NuGraf lingo) used by the Lightwave scene to the NuGraf texture directory. The textures are probably in the IFF file format (with extensions .IFF, .MAP or .COL) so you must first rename the file extension to .IFF then use a paint program (such as Adobe PhotoShop) to convert the texture files to TIFF format (which is expected by this converter). 2. If not using Windows NT or Windows 95 then change the filenames of all Lightwave files to have a maximum length of 8 characters. 3. Change the file extension of the Lightwave scene file to .scn. 4. Change the file extension of the Lightwave object files to .lw. 2 Import-Lightwave() Unix Programmer's Manual Import-Lightwave() 5. Edit the main Lightwave scene with a text editor and modify the filepath and filename after each occurrence of the "LoadObject" keyword. For example, the original filepath may look something like "LoadObject HD1:Bottle/ExampleBottle". This should be changed, for example, to "bottle.lw". Once these changes have been made invoke the geometry converter and import the Lightwave scene file (.scn). If no scene file exists for the scene then directly import each Lightwave object file (.lw) one-by-one. NOTES 1. Texture files are expected to be in TIFF format by this converter although you are free to edit the imported scene to use any other format for the textures. 2. If an object has more than one surface applied to it then the converter will explode the object into separate pieces, each with a single surface assigned to it. 3. A valiant attempt is made to map Lightwave surface attributes to equivalent NuGraf surface attributes but it will probably not be perfect due to the differences between the two programs. 4. Lightwave allows a different texture projection type to be assigned to each texture applied to a surface (ie: spherical for the color texture, cylindrical for the bump texture). NuGraf only allows one, so it chooses the first texture projection type assigned to the surface. 5. The "smoothing angle" specified with the '-in-lw-smoothing-angle' option will be overridden on an object-by-object basis if a surface definition has a "smoothing angle" associated with it. 6. "Detail" polygons are created as separate polygons. This might cause problems when rendered with NuGraf. COMMAND LINE OPTIONS The following options are specific to this import converter: -i lw This is the optional command line option which specifies that the input data is in one of the Lightwave file formats. If not specified then the converter will try to guess the input file's format from its file extension (.lw, lwobj, .lws, etc) and then from the contents of its file. -in-lw-break-apart-by-surf-name = [ yes | no ] If set to 'yes' then each imported Lightwave object will be exploded into separate objects based on the surfaces currently assigned to the object. For example, if a single object has surfaces 'surf1', 'surf2' and 'surf3' assigned to it then the object will be exploded into 3 sub-objects with an appropriate name for each new object. If set to 'no' then the object will not be exploded. The default is 'yes'. 3 Import-Lightwave() Unix Programmer's Manual Import-Lightwave() -in-lw-compute-normals = [ yes | no ] If set to 'yes' then new vertex normals will be computed for a polygon if it does not have any vertex normals already. The smoothing criterion is based on the angle between abutting polygons; common smoothed vertex normals will be computed if the angle between their geometric surfaces normals is less than the '-in-lw-smoothing- angle' angle described below. If set to 'no' then no new vertex normals will be created. -in-lw-debug = [ yes | no ] If 'yes' then verbose parsing information will be output to the file ASCII 'debuglw.txt' located within the current working directory. The default is 'no'. -in-lw-smoothing-angle = # This option sets the cut-off smoothing angle (in degrees) used by the vertex normal computation algorithm. If the angle between two abutting polygons is greater than this number then no smoothing will occur (a crease will be evident between the two polygons), else smoothing will occur where the polygons meet. The default angle is 30 degrees. If a Lightwave object file (.lw) specifies a smoothing angle then that angle will override the angle specified in this option (but only for a specific object). -in-lw-print-stats = [ yes | no ] If this option is set to 'yes' then the converter will report the number of polygons and vertices read from the file. 4