DSFTool manual

Version History

12/13/04 - Alpha 1		Initial release. 12/20/04 - Alpha 2		Fixed file-close bug. 1/12/05 - Alpha 3		Fixed crash bug! 1/23/05 - Alpha 4		Added pipe support. 12/19/05 - 1.0.1		Fixed support for global DSFs. (Change to polygon 							command to support arbitrary coord depth) Allowed spaces in DEF file names. Mach-O native Mac Grinder 1/05/06 - 1.1			Added ENV->Overlay Conversion Fixed crashes and hung files on Windows Fixed return codes for command-line tool Changed output for clean piping 7/24/06 - 1.1.1		Fixed support for bezier polygon parsing 2/13/07 - 1.2			Support for bezier curves with ST coordinates. Command line options can take one or two dashes. Tool can show version. Total capacity for polygons increased a lot. 3/11/08 - 1.3			Support for X-Grinder automation.

Overview
DSFTool is a utility that converts X-Plane Distribution Scenery Format (DSF) files to a text format and back again.

DSFTool can also extract the custom objects from an ENV file and build an overlay DSF.

Warning: Working with DSF files as text with DSFTool is intended primarily for programmers who want to create DSF files.

Warning: this utility does not work with Mars ENV files!

Note: Previously the UI version was called DSF2Text; now both are called DSFTool.

System Requirements and Installation
DSFTool is provided for Windows and Mac OS X. To install DSFTool, simply unzip the compressed archive. To use DSFTool with X-Grinder, make sure both executables are in the same directory.

Using DSFTool
DSFTool can be used via the command-line or in conjunction with X-Grinder. To use DSFTool with X-Grinder, simply drag a .txt, .dsf or .env file into the X-Grinder window.

Warning: If DSFTool crashes, check your line endings! There have been reports that TextEdit on the Mac ruins line endings.

SUFFIX			CONVERSION TXT				Text -> DSF* DSF				DSF* -> Text ENV				ENV -> Overlay DSF


 * DSFs can be converted to text and back for full or overlay DSFs.

Warning: DSFTool is slow, especially when converting text back to a DSF file. Conversion can take ten minutes or more. DSFTool will be unresponsive while it is working, but you should see elevated CPU usage.

The syntax for the command line version is:

DSFTool --dsf2text

to convert from DSF to text and

DSFTool --text2dsf

to convert the other way. To convert an ENV to an overlay use:

DSFTool --env2overlay

For you can specify a single dash (-) to read from stdin/stdout instead of a text file. This allows for piped usage of DSFTool, e.g.

cat file.txt | ./DSFTool -text2dsf - output.dsf ./DSFTool -DSFTool foo.dsf - | grep OBJECT_DEF | wc -l

Piping is not available for DSF and ENV output files. When converting to a binary file, status messages are sent to stdout and error messages to stderr. When converting to text, all messages are sent to stderr so that piped output is strictly the DSF contents. The result code indicates a successful conversion.

DSFTool File Format
The DSFTool file format starts out with a typical X-Plane header:

A 800 DSFTool

It then consists of a series of commands, each one taking up one line. In this reference, properties in are to be filled in with real values in the file.

The DSFTool file format is not an exact replication of DSF--some of the complexities of point pools and other compression schemes are omitted. However the basic notion of indexed building block definitions, patches, etc. are all preserved, so it may help to read the DSF File Specification before trying to understand this format.

Warning: certain properties must come first--see the PROPERTY command below.

(Hint: the easiest way to get a feel for the file format is to take a DSF file, convert it to text and look through it.)

The file format is:

DIVISIONS
 * This is a meta-command that instructs DSFTool to use a certain number of point pools to allocate points. More pools generally means more accuracy in storage, but may also increase file size if improperly used.  The default is four divisons if this command is omitted, resulting in sixteen point pools.

PROPERTY
 * This adds a "property" to the DSF file. Properties are key-value pairs that specify various header information.  See the DSF file format spec for useful property values.


 * Important: ''the DIVISIONS and PROPERTY commands MUST come before all other commands! The north/south/east/west properties must come last among

all properties!!'' TERRAIN_DEF OBJECT_DEF POLYGON_DEF NETWORK_DEF


 * These commands define a new type of building block. Order is significant: the first building block of each type has index zero and they then count upward sequentially.  File extensions must be included.  The entire line is utilized, so you may have whitespace in your filenames, although it is not recommended. These comands are mandatory if related commands are used, TERRAIN_DEF is mandatory if BEGIN_PATCH is used and etc.

BEGIN_PATCH   <# point coords>


 * This command begins a new terrain patch. Terrain definition index is number of terrain definition to use on patch, starting from 0. The LOD range is the distance it is visible - use 0..-1 to make it be always visible. The flag values are:
 * 1 - This patch should be used in the physics/collision engine.
 * 2 - This patch is an overlay and should be Z-buffer-offset.


 * These flags correspond to the patch flags in the DSF spec. You also specify the number of coordinates used in vertices for the patch.  At least 5 coordinates are required for X-Plane: longitude, latitude, elevation, and two normal coordinates.

BEGIN_PRIMITIVE
 * This begins a single primitive. Types correspond to the DSF/spec and the usual OpenGL definitions, and are:
 * 0 - Triangles
 * 1 - Triangle Strip
 * 2 - Triangle Fan

PATCH_VERTEX [ ...]
 * This specifies one vertex within a primitive within a patch. See the DSF File Specification and TER File Specification for information on how this information is interpreted.  Generally the first five values are longitude and latitude in degrees, elevation in meters, and the X and Z coordinates of the point's normal vector as a fraction (where +X = east, and +Z = south).

END_PRIMITIVE END_PATCH
 * These end the primitive and patch in progress, respectively.

OBJECT
 * This adds an object to the file of a given type. The position is specified in degrees and the angle is in degrees as well.

BEGIN_SEGMENT BEGIN_SEGMENT_CURVED
 * These start a new vector segment. Type should be 0 for X-Plane and subtype specifies the road type.  See the DSF spec for a discussion of node IDs - these unique numbers identify each vertex.  The position is specified in latitude and longitude degrees and meters MSL.  For the curved variant, a second point specifies a "control handle" for bezier curve-type curving of the road.

SHAPE_POINT SHAPE_POINT_CURVED
 * A shape point defines a turn in the vector road without an intersection.

END_SEGMENT END_SEGMENT_CURVED
 * These end a vector segment, with similar parameters to the above commands.

BEGIN_POLYGON [ ]
 * This begins a polygon primitive, which is usually a facade in X-Plane. The parameter's meaning depends on the primitive - for facades it is the height in meters. If coords is specified any number of points can follow in the poylgon_point command, otherwise they must be lon/lat.

BEGIN_WINDING
 * This indicates the beginning of a winding, or single polygon within a nested polygon. This command is mandatory even if the polygon is not nested.

POLYGON_POINT [ ]
 * This adds a point to the polygon.

END_WINDING END_POLYGON
 * This ends the winding and polygon respectively.