Racer DOF Utilities

The Racer Car Simulator uses .DOF files to store per-object geometry and material information. It has a chunked architecture, making it easy to programmatically parse and browse.

Some 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 do have scripting or plugin features, making 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).

DOF Generation

The typical process of modeling, mesh export, mesh conversion, and eventual testing in Racer can be slow and tedious, especially for small tuning changes... While ZModeler can export directly to DOF, I know Blender better. However, to use Blender one would also need the ASE-format exporter script, export the object meshes to ASE files, then use Racer's TrackEd to convert the ASEs to DOFs, then try it out with Racer. I needed a faster way to export Blender meshes to DOF files, and Python was the way.

DOF Dumping

I wrote "dumpdof" to probe existing DOF files. This was originally due to a small bug in some mesh conversion routines in Racer's TrackEd program, and my probing tool could show what the problem was by comparing the generated output from two DOF files. Source code for this simple C++ program is in the zip file.

Run dumpdof with a DOF file argument: dumpdof somemesh.dof
It will show you the data chunks and a few details about each one (size, small bits of data).
Run dumpdof with the -v switch for verbose: dumpdof -v somemesh.dof
Verbose output includes the basic chunk information, but also all vertex, normal, UV, indices and burst/face data. Redirect the output or pipe it through "more" or "less".

DOF Manipulation

Back to Blender and DOF files. The "DOFfile" module contains numerous utility functions and classes to create, read, modify and save DOF files. During creation or after reading, a DOF object will maintain an internal representation of the mesh geometry. Once the representation is built, a program could request, check and modify internal object data (although not everything is implemented yet). Then, the same object can write itself to a new DOF file. The DOFfile module is independent of Blender, and can be used by standalone Python programs.

More specific to Blender is the "Mesh2DOF" module. This is a Blender-specific script to export textured model meshes to DOF files. The only real visible function is Mesh2DOF.ExportLayer() which exports all meshes in a particular layer to DOF files.

Also for Blender are sample scripts to use the above two modules.

These two Python files are quite powerful, and more capabilities will be added as needed.

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)
Mesh2DOF.ExportLayer(1, dest)

That is it.

The Mesh2DOF.ExportLayer() function takes two 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. No backups of existing files are made, so be sure this 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

DOF Management

Once you have the DOF files exported, you may wish to include several together into one file. The export functions only write one mesh out per DOF file; grouping several related objects together into the same DOF file make it easier for Racer to manage visible objects.

The "joindofs.py" program does just this. Run it as:
joindofs -o allofem.dof file1.dof file2.dof file3.dof

All the meshes and materials are concatentated; no duplicated materials are looked for, and this will be a future addition since it can make rendering more efficient.

Recap

If you want an older version compatible with Blender 2.27, here's the exporter: Mesh2DOF.py (2.27).

If you are a programmer...

The DOFfile.py module is entirely independent of Blender. You can utilise this module in your own Python programs to generate DOF files programmatically (landscape, buildings, towers, etc, anything that can be churned out). See the joindofs.py program for one way to use it.

The Mesh2DOF.py module is Blender specific. It knows about Blender's internal mesh objects, and performs the data representation translation to a DOF object. It uses the DOFfile.py module for output only. Except for bug fixes, there is probably less interest in this module.

Changes