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.
Before you begin you will need the following:
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.
The basic steps to this process are:
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.
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.
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.
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.
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.