Using DSF2Text to Transfer Custom Objects From ENV to DSF Files

	Revision History
		12/15/04	Initial Draft
		 2/03/05	Added notes for object prioritization

This tutorial explains how to use DSF2Text to transfer custom objects from an X-Plane 7 ENV file to an X-Plane 8 DSF file. This is uesful if you have custom objects in an XP7 scenery package (an airport for example) and you want to apply these objects to an XP8 default US scenery file.

Note: DSF2Text is not meant to be a great scenery editing tool - its long term purpose will be to allow programmers to create DSF files as text without having to write DSF files directly. If your editing task is very complex you should probably wait for the real X-Plane scenery editor to be released.

What you need to do this tutorial:

Before you begin you will need the following:

  • DSF2Text
  • Env2CSV (part of XPTools)
  • The +34-118.dsf scenery file (part of the X-Plane 8 demo area).
  • The +34-118.env scenery file (aprt of the X-Plane 7 demo area).
  • A good text editor.

Note: different versions of X-Plane contain different demo areas. The easiest way to get these areas is to get +34-118.env from a version 7 installation of X-Plane and +34-118.dsf from a version 8 installation of X-Plane. If you have X-Plane from the DVD you will only have +34-118.dsf if you installed G8 scenery. If you have an X-Plane 8 demo, it will always come with +34-118.dsf.

Overview of the Process.

The basic steps to this process are:

  1. Convert the old ENV file to text format with ENV2CSV.
  2. Use a text editor to extract the objects we want.
  3. Convert the DSF file to text with DSF2Text.
  4. Use a text editor to paste the new objects into the DSF text file.
  5. Use DSF2Text to convert the text file back into DSf.

Converting the ENV file to text format.

The first step is to convert the ENV file to a text format so we can extract objects from it.

1. Start Env2CSV.
2. Drag the file +34-118.env into the Env2CSV window.

After a minute or so, a new text file called +34-118.csv will be created in the same directory as the original +34-118.env file.

Extracting objects from the ENV file.

Next we must extract the objects that we want. We must find the objects we want to keep.

3. Open +34-118.cvs in a text editor.
4. Search for the string 'socal'.

You will find a number of lines that look like this:

8,34.100407,-117.227966,10.000000,SoCal:hangar
8,34.095680,-117.247093,270.000000,SoCal:terminal
8,34.097301,-117.250847,0.000000,SoCal:town
8,34.097782,-117.246880,270.000000,SoCal:hangar
8,34.100227,-117.229469,300.000000,SoCal:heliplatform
8,34.100384,-117.229309,330.000000,SoCal:heliplatform
8,34.100380,-117.229027,20.000000,SoCal:heliplatform
8,34.100235,-117.228851,50.000000,SoCal:heliplatform
8,34.093376,-117.248398,0.000000,KSBD_example
8,34.126537,-117.207405,90.000000,SoCal:DriveIn
8,34.095612,-117.243248,0.000000,SoCal:Apt_Light
8,34.098816,-117.243126,0.000000,SoCal:Apt_Light
8,34.100906,-117.230019,0.000000,SoCal:Apt_Light
8,34.100548,-117.227257,0.000000,SoCal:Apt_Light
8,34.098392,-117.247078,0.000000,SoCal:Apt_Light

Each line starting with 8 before the END is a custom object in the ENV file. These are the lines we want.

5. Cut these lines into a separate text file for use later.

Converting the DSF file to text format.

Now we will convert the DSF file to text format.

6. Start DSF2Text.
7. Drag +34-118.dsf into the DSF2Text window.

DSF2Text will take a while (maybe a few minutes) and create a very large file in the same directory as +34-118.dsf called +34-118.dsf.txt. This is the text version of the DSF file. This file will be very large.

Inserting the objects into the DSF text file.

The trickiest part of this process is converting the text listing of our objects from the EnvCSV to the DSF2Text format. In particular, while ENV files list each object by name, DSF2Text requires an index number for each object. So we must determine what the first unused index number is for objects.

8. Open +34-118.dsf.txt in a text editor.
9. Count the number of lines that contain OBJECT_DEF.

The easiest way to do this is to copy the OBJECT_DEF lines into their own file and note the number of lines. All OBJECT_DEF statements will be grouped together. You should find 75 OBJECT_DEF lines in +34-118.dsf.txt, implying that there are 75 different objects referenced in this file.

10. Confirm that OBJECT 74 is present in +34-118.dsf.txt and OBJECT 75 is not.

By checking for an OBJECT of type 74 and no object of type 75 you can make sure that you have correctly counted the number of objects in the file.

11. Create OBJECT_DEF commands in your text file for each of the Socal objects, starting at index 75.

We must assign an object index to each of the Socal objects. When done we will have this:

OBJECT_DEF SoCal:hangar.obj             75
OBJECT_DEF SoCal:terminal.obj           76
OBJECT_DEF SoCal:town.obj               77
OBJECT_DEF SoCal:heliplatform.obj       78
OBJECT_DEF KSBD_example.obj             79
OBJECT_DEF SoCal:DriveIn.obj            80
OBJECT_DEF SoCal:Apt_Light.obj          81

The third item, the index numbers are ignored by DSF2Text - they are just there for our reference so we can remember what indices each object has.

NOTE: it is ok in a DSF file to have the same object in more than one index slot, it is just less efficient.

NOTE: if you wanted to use the new object prioritization RFC to make sure all of these objects are visible, you would add a line like this before all other properties:

PROPERTY sim/require_object 1/75
12. Create OBJECT commands out of each one of the objects we extracted from the Env2CSV text file.

Env2CSV uses the format 8,latitude,longitude,heading,name but DSF2Text uses the format OBJECT index longitude latitude heading. When you have reformatted the objects you should have this:

OBJECT   75   -117.227966   34.100407   10.000000   
OBJECT   76   -117.247093   34.095680   270.000000   
OBJECT   77   -117.250847   34.097301   0.000000   
OBJECT   75   -117.246880   34.097782   270.000000   
OBJECT   78   -117.229469   34.100227   300.000000   
OBJECT   78   -117.229309   34.100384   330.000000   
OBJECT   78   -117.229027   34.100380   20.000000   
OBJECT   78   -117.228851   34.100235   50.000000   
OBJECT   79   -117.248398   34.093376   0.000000   
OBJECT   80   -117.207405   34.126537   90.000000   
OBJECT   81   -117.243248   34.095612   0.000000   
OBJECT   81   -117.243126   34.098816   0.000000   
OBJECT   81   -117.230019   34.100906   0.000000   
OBJECT   81   -117.227257   34.100548   0.000000   
OBJECT   81   -117.247078   34.098392   0.000000   

Note how the object name has been replaced with the index numbers from above.

13. Locate the last OBJECT_DEF statement in +34-118.dsf.txt and paste your OBJECT_DEF statements after them.
14. Locate the last OBJECT statement in +34-118.dsf.txt and paste your OBJECT statements after them.
15. Save and close +34-118.dsf.txt.

The OBJECT_DEF statements you pasted should go right after a statement for misc/monument.obj and right before a POLYGON_DEF statement. Your OBJECT statements should go right after an OBJECT 74 statement and right before a BEGIN_POLYGON statement.

Building the final DSF file.

Now we can build the real DSF file.

16. Drag the newly edited +34-118.dsf.txt file into DSF2Text.
17. Get a cup of coffee.

The conversion process can be very slow - possibly ten minutes or more depending on how fast your computer is and how much memory it has.

18. Rename the new file +34-118.dsf.txt.dsf to +34-118.dsf.

For your safety, DSF2Text always appends new extensions on file names to avoid overwriting and erasing old files. So you will have to trim down the extension to use it.Postscript: Viewing the results.

To view this file, you need to put it into a custom scenery package.

19. Copy the San Bernardino Example example package from X-Plane 7 into your X-Plane 8 custom scenery folder.
20. If you have a demo area, rename the San Berandino exmaple package to have a name that is earlier in the alphabet, like An Exmaple.
21. Copy your new +34-118.dsf file into the your package's +30-120 folder in the Earth nav data folder.

You now have demo area objects in a custom scenery package that you can use. Here is the results in WorldMaker:

WARNING: you will only see all of these objects in the demo area if you have the objects rendering setting set to 'INSANE'. Otherwise X-Plane will drop some objects to improve framerate.