Racer DOF Files

The Racer Car Simulator uses a custom file format known as DOF files to store per-object geometry and material information. The DOF file format is highly structured which makes it easy to process, change and browse the data in a DOF file. The format is documented on the Racer page (link above).

Exporting DOF Files

Some 3D modeling tools, such as ZModeler, implement the DOF format and can directly export model meshes to it. Other modeling tools, like Blender or 3DS Max, do not. These latter two programs have scripting or plugin features, which makes writing exporters possible.

In the case of Blender, it uses the Python language to programmatically control model objects. This means you can use it to import from or export to file formats not directly supported by Blender, as well as programmatically generate new models (L-System shapes, mathematical surfaces, etc).

As a result of writing a DOF exporter for Blender, a numer of utility programs were created to display DOF contents, and do simple modifications. More information about the DOF utilities is on a separate page.

The DOF exporter for Blender is written in Python and resides in the "Mesh2DOF" module. This is a Blender-specific script to export textured model meshes to DOF files. Mesh2DOF in turn uses the DOFfile module which contains the core DOF-file reading and writing. The only real visible function in Mesh2DOF is Mesh2DOF.ExportLayer() which exports all meshes in a particular layer to DOF files.

How to Use Mesh2DOF

It has been tested with these software versions:

What you must do:

  1. Fetch the zip file below and extract the contents.
  2. Install Python 2.3 if you haven't already. On Windows, it may be c:\Python23
  3. Make a directory under the Python Lib/site-packages to store the DOF exporter. On Windows, mine is: c:/Python23/Lib/site-packages/racer.
  4. Copy the DOFfile.py, Mesh2DOF.py, and VertOpt.py files into the directory you just made (c:/Python23/Lib/site-packages/racer).
  5. Set your PYTHONPATH environment variable to point to this directory. On Windows, right-click on My Computer, click the Advanced tab, then Environment Variables. On unix/linux, add the appropriate command to your .login, .bash-profile, etc.
  6. To use the save_dof.py script listed below, start Blender, load your *.blend file, and create a new Text data block. Open the save_dof.py file, change the destination directory in the script to where you want to export the DOF files, and press Alt-P in the text window to run it.

The save_dof.py script is:


# Export layer 1 meshes as DOF
#

import os
import Mesh2DOF

print "-----"
dest = "c:/DOF"
if not os.path.exists(dest):
    os.mkdir(dest)
os.chdir(dest)
inverseScale = 1.0
Mesh2DOF.ExportLayer(1, dest, inverseScale)

That is it.

The Mesh2DOF.ExportLayer() function takes up to three arguments. The first is the layer (number) from which objects are exported. You can give -1 as the layer number, and that will export all mesh objects from ALL layers. The second argument is a directory where the resulting DOF files should be written. The third parameter, if given, is an inverse-scaling factor which allows you to model your geometry in Blender at scales other than 1:1. If the scaling argument is not given (as for past releases of this code and save_dof.py), the value defaults to 1.0.

The scaling factor is a new feature (as of 8 June 2005). For large tracks that cover more than a few square kilometers, 1:1 may be too large a scale because Blender's coordinates range only between -1000.0 and 1000.0 in X,Y and Z. A convenient scale to use is 1:10 so one real-world Racer meter is 0.1 units in Blender. On export, the scaling factor would then be 10.0. Using this 1:10 scale, Blender's -1000.0 to 1000.0 now covers 400 km^2.

Note:When exporting DOFs, no backups of existing DOF files are made, so be sure the directory path is set ... accurately.

While the script is exporting objects, it will print its progress to the console. For each mesh exported, it displays its name, the number of original vertices (Vin), the number of final vertices (Vout), and the number of triangles. Vout will, for almost all meshes, be larger than Vin; this is due to how texture coordinates and vertex data must be paired. Once all meshes are exported, it prints the total number of meshes, vertices and triangles it processed, and where the DOF files were saved.

The tail of one run is:


...
Exporting mesh OvalWall.005
---> Vin: 112  Vout: 328  Tris: 164
Exporting mesh OvalWall.006
---> Vin: 104  Vout: 300  Tris: 150
Exporting mesh OvalWall.007
---> Vin: 128  Vout: 372  Tris: 186
Exporting mesh OvalWall.008
---> Vin: 84  Vout: 240  Tris: 120
Exporting mesh Pitlane
---> Vin: 4  Vout: 4  Tris: 2
79 meshes exported into c:/sims/racer/data/tracks/MyTrack
Totals: Vin: 3444  Vout: 7708  Tris: 3854

Summary


Get everything with this ZIP: DOFfile.zip

Contents:

DOF Probe/Dumping
dumpdof.cpp
dumpdof.exe
Python DOF Modules
DOFfile.py
Mesh2DOF.py
save_dof.py
joindofs.py

If you want an older version compatible with Blender 2.27, here's the exporter: Mesh2DOF.py (2.27). Be sure to fix the file extension to .py when done downloading.

Changes

DateChange
14 July 2003First public test release
15 July 2003Fixed normal direction in Mesh2DOF.py. Commented this little transform in the code.
16 July 2003Added vertex color chunk (VCOL) support to DOFfile.py. Added code in Mesh2DOF.py to export vertex colors.
20 July 2003Fixed a bug in Mesh2DOF.py regarding multiple objects sharing meshes. Before, the file written was based on the mesh's name, and it should have been the object's name. So multiple objs sharing a single mesh are exported to their own file correctly now.
1 August 2003Updated the source to work with Blender 2.28. Only Mesh2DOF.py was affected, and only the type strings changed ("NMesh" became "Blender NMesh"). Also added a version of Mesh2DOF.py for Blender 2.27.
4 February 2004Minor changes in how material names are saved. I've exchanged email with Ruud van Gaal about the DOF file format, and have a few more fixes to put in soon.
4 March 2004Bug fix in dumpdof.cpp -- printing colors was absolutely broken... DOFfile.zip now contains a compiled dumpdof.exe so others don't have to compile it.

Major changes to Mesh2DOF.py in functions _ConvertMeshToDOF() and _DefineMaterial() to handle multiple materials on a mesh. Each set of polygons that use a particular material are saved as a separate GOB1 (geob) chunk in the DOF file.

Unfortunately, using material colors precludes the use of vertex colors, and if vertex colors exist the material colors are not used. Shaders, if one exists named shader_<material-name>, trump all. This will be sorted out soon I hope.

7 March 2004More support for multiple materials. The Mesh2DOF module also handles meshes with no materials defined (it generates simple mats) and so should work with meshes that simply have a texture applied with no materials defined/applied.

This is labeled as version 0.90.

8 March 2004Minor bug fix in DOFfile.py, added vertex optimizer to Mesh2DOF.py that works as well as Modeler.
16 March 2004Fixed bug in setting materials transparent -- everything was getting the transparency flag set, causing Z-ordering problems. Fixed. Set Blender's Alpha value for a material (0.1-0.2 for glass) for transparency, and the DOF MTRA chunk is set correctly.

Also fixed the (minor) bug where empty GOB1 objects were created for unused materials... No more.

23 March 20040.94. fixed a bug in exporting meshes that used multiple textures without using materials. New "settrans" program enables (or disables) transparency in existing DOF files.
8 June 20051.00. Disabled exporting of vertex colors by default; before, exporting vertex colors would disable Racer's lighting on the mesh. New inverse-scaling arg in ExportLayer() and ExportMesh() make modeling in Blender at scales other than 1:1 much easier.
Also incorporated changes from Screwdriver (at RaceSimCentral) that preserve vertex normals. Thanks!
11 June 2005Web page re-org and rewrite of some poor text. Made the exporter page more exporter-specific, leaving other DOFFile info to dofutilities.html.

Last Edited: 11 June 2005
Written: 20 July 2003