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:

• Python: 2.3.x (ActiveState Python is a good install)
• Blender 2.36
• Racer 0.5.0 final, and 0.5.2b89

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

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