DSF overlay scenery editor

Overview

This application edits X-Plane^® DSF “overlay” scenery packages for X-Plane 8.30 or later. It runs on Windows 2000 or later, MacOS 10.7 or later and Linux.

The application allows you to place 3D objects, building facades, draped textures, roads and other kinds of scenery objects on top of X-Plane's terrain. The application does not edit X-Plane airport layouts (i.e. runways, taxiways and navaids) and does not edit X-Plane's terrain mesh, but it does read and display both of these in simplified form so you can see where you're placing your objects.

Other applications allow you to edit or replace airport layouts, terrain mesh, and/or place objects. Please read the section below if you intend to use OverlayEditor in conjunction with other scenery tools.

Quick Start

• Press the button to create a new scenery package:
• Supply a name for your new scenery package. Many people use the convention of “<ICAO code> <Airport name>” (e.g. EGLC London City), but it's up to you.
• Press OK.
• Press the button to take you to the area that you want to model:
• Click in the Airports by name column and type to seach by name; or
• Click in the Airports by code column and type to seach by ICAO code.
• Choose an airport and press OK.
• We're going to place a 3D Object of a static aircraft at this airport, so point to the airport's ramp area with the mouse and use the Mouse wheel or Zoom gesture to zoom in.
• From the menu titled Objects in this package choose lib/airport.
• Choose the top item aircraft/corporate_biz/P180_avanti_ferrari. You'll see a preview of this aircraft in the space below.
• Press the button to place this aircraft. It appears at the centre of the screen, and is colored pink to indicate that it is selected.
• Use the Q and E to rotate the aircraft to your satisfaction (you can hold down Shift for bigger steps or Ctrl for tiny steps). Its current heading is shown to the right of the status bar.
• You can click and drag the aircraft to change its position, or use the W, S, A and D keys.
• When you're happy, press the button.
• Start X-Plane, go to this airport and you'll see the static aircraft sitting where you placed it.

That's it; you have created your first scenery package. You can continue to place additional objects in this scenery package if you like. You should probably also read the Tool bar, Main window and List of objects sections of this document.

The application window

The application window consists of five parts. Click on this screenshot for a description:

Tool bar

	Create a new scenery package. This creates a new folder in X-Plane's Custom Scenery folder.
	Open an existing scenery package. All the packages in X-Plane's Custom Scenery folder are listed, but you can only actually edit those that use DSF overlays (rather than ENVs or “full” DSFs that contain a terrain mesh).
	Save the scenery package. Note: Any existing .dsf files are backed up with the extension .dsf.bak
	Import objects (and their textures) from another scenery package or from a downloaded collection of scenery objects, and add them to the list of objects. You can also import .dds and .png texture files directly for use as draped polygons. The imported objects are copied to custom objects or objects if either of these folders exist, otherwise to the package's top-level folder. (So this button is only available once you have saved the scenery package). Before you import objects from another scenery package you should first check the license terms; these often prohibit re-distribution of individual objects.
	Import objects from the default scenery and place them in your scenery package. This is most useful for “tweaking” small areas of “autogen” objects, roads or forests; place an Exclusion region of appropriate type and use this button to pull in the “autogen” objects, roads or forests from the default scenery that are within the area of the Exclusion region.
	Add the object that is highlighted in the list of objects to the scenery. The object is added at the current cursor location and with the current heading.
	If you have a forest or draped polygon selected - Add a hole in it. If you have a polygon node selected - Add new polygon node next to it.
	Give the selected polygon node curve control handles.
	Delete the selected object(s) or selected node.
	Undo the last edit.
	Turn background imagery on or off. You can use a mapping service or a simple file to provide background imagery (just for reference; it's not saved with the scenery package). If you use a file you can adjust its position while the Background imagery dialog is displayed. If you use a GeoTIFF or JPEG2000 file it will be placed according to any geolocation info that it contains. (Note: it may not be placed on-screen - click on the main window and press C to centre the view on it).
	Reload the object, texture and apt.dat files in the scenery package. Use this if you have modified any of these files outside of this application. Also use this if you have added new objects and you want these new objects to appear in the list of objects. (Note that the DSF files are not reloaded - just re-open the package if you want to revert to the last saved version).
	Go to an airport or lat/lon location.
	Lock object types. Locked objects can't be selected or modified. Use this to avoid accidentally selecting or editing certain kinds of objects.
	Change X-Plane's top-level folder and display options. Do not change the location of X-Plane's top-level folder while you are editing a scenery package, otherwise your unsaved changes will be lost.
	Show this help file.

Main window

This shows the objects that have been placed in a 1°×1° region of the loaded scenery package.

By default terrain is textured, displayed as flat, and roads and taxiway markings are omitted - you can change this with and/or add mapping imagery with . Runways, taxiways, navaids and X-Plane's default road and rail networks are displayed in simplified form and cannot be edited. Scenery objects from other scenery packages and “autogen” scenery objects from the default scenery are not displayed at all.

Navigate with the cursor keys or mouse. Hold down Shift for bigger steps or Ctrl for tiny steps:

Note: On a laptop hold down Fn and use the cursor keys for the ↖, ↘,  ⇞  and  ⇟  keys.

Selected objects are highlighted in pink in the main window. To select objects:

You can't select or otherwise manipulate runways, taxiways or navaids (ILS, VOR, DME etc).

If you select a single polygon you can click on an individual node (i.e. corner) to select it. The selected node is highlighted in white.

These keys affect the selected objects or the selected node. Hold down Shift for bigger steps or Ctrl for tiny steps:

Mouse click and drag	Move selected object(s), polygon node, or polygon curve control handle. Hold down Cmd to move a curve control handle independently of its pair.
W, S, A, D	Move selected object(s) or polygon node. Note: You can also use the keys on the numeric keypad if your keyboard has one - ensure that NumLock is on.
Q, E	Rotate selected object(s) about the cursor. To rotate a single object about its origin, select it and press C before rotating.
R, F	Change the selected: Facade: Height Facade node: Wall type Forest: Density Draped polygon: Texture heading Line: Open or Close the line String: Object spacing Network node: Bridge level The currently selected facade height, wall type, forest density, texture heading, line open/closed status, string object spacing, or network bridge level is shown next to a ↕ symbol in the status bar.
C	Centre the cursor on the selected object(s) or polygon node.
Shift C	Centre the cursor on the selected object and rotate the view to match its heading.
N	Select the next use in this 1°×1° region of the object that is highlighted in the list of objects.
Ctrl N	Add the next use of the highlighted object to the selection.
Ctrl Shift N	Select all uses in this 1°×1° region of the highlighted object.
Enter or	Add the object that is highlighted in the list of objects to the scenery.
Cmd Enter or	Add new polygon node next to the currently selected node, or add hole in the selected forest or draped polygon.
Delete or	Delete selected object(s) or polygon node.
Cmd Z or	Undo the last edit.
Cmd X, C, V	Cut, Copy, Paste.

List of objects

All the objects, facades etc in the scenery package folder are listed under the heading “Objects in this package” (including those that are present in the scenery package folder but are not used in the scenery). When you create a new scenery package “Objects in this package” is initially empty, but objects that have been made available by scenery libraries are listed under further headings in the drop-down list. The objects under the various lib/... headings are supplied by X-Plane's built-in libraries; the objects under the remaining headings are supplied by library packages found in your Custom Scenery folder. (Note that later versions of X-Plane come with more extensive libraries than older versions, so you should always design using the oldest version of X-Plane that you want your scenery package to work with).

You can use any of the objects in these lists in your scenery package - think of these lists as an artist's palette. You can also use the Search box to search through the available objects by name. Select one of the objects in these lists and press to place it in your scenery package.

The type of object is indicated by a symbol:

- 3D Object (.obj, .agp)

- Facade polygon (.fac)

- Forest polygon (.for)

- Draped polygon (.pol) with a repeating texture (requires X-Plane 8.50 or later)

- Draped polygon (.pol) for use as a quadrilateral orthophoto or decal (requires X-Plane 8.60 or later)

- Line polygon (.lin)

- String polygon (.str)

- Other polygon (.agb, .ags, etc)

- Road, Railway or Powerline network (requires X-Plane 10 or later)

- Exclusion region

- Missing or unreadable object or polygon

Once you place a 3D Object (denoted by the symbol ) in your scenery package you can move, rotate or delete it (see above for the keys to use) and that's about it. The other types of objects are all “polygons” of various kinds. You can click on the “nodes” (i.e. corners) of a polygon and drag to change the polygon's shape, and you can press to add new nodes. Most polygon types also have properties that can be changed with the R and F keys.

Use to copy objects from another scenery package or from a downloaded collection of scenery objects. Alternatively, just drag objects from Explorer or Finder and drop them on the list of objects. The imported objects will appear under the “Objects in this package” heading. (Don't use this to copy objects from a scenery library; just select the object from the appropriate list).

Use if you have otherwise added or modified objects in the scenery package folder, or if you have installed a new scenery library.

Preview picture

A preview of the currently selected object is shown (when available) underneath the list of objects.

You can drag the separators between the preview window and the other windows to make the preview picture larger or smaller.

Status bar

This area shows the cursor location, heading and elevation. If you have selected an object or polygon this area also shows details about it (or an average location if you have selected more than one object). If you have selected a polygon node this area shows additional details (if any) that you can change with the R and F keys, and the distance to adjacent nodes.

Road, Railway & Powerline Networks

Roads, railways and powerlines (collectively “networks”) work similarly to other kinds of polygons, but there are some additional points to bear in mind:

• In order for traffic to flow across successive segments of road or rail, the first or last node of one segment must be at exactly the same location as the first or last node of the next segment. (However the two segments don't have to be of the same type).
• When multiple roads and/or railways meet at a junction, in order for X-Plane to draw the junction correctly the first or last nodes of all the segments that meet at the junction must be in exactly the same location.

To help with this, when you drag the first or last node of a network segment it will “snap” to any nearby nodes in other segments. And if the “snapped-to” node is in the middle of its segment, that segment will be split in two.

The user's “number of roads” rendering option controls which kinds of networks they will see:

To construct a bridge over a road or railway:

• Create a four-way junction / crossroads - i.e. four segments with their first or last nodes at exactly the same location.
• Select the end node of one of the segments that you want to turn into a bridge and use the R and F keys to set the node's level to 1 or more. The current level is shown in the status bar, and higher levels result in a higher bridge.
• Repeat for the end node of the other “bridge” segment.

Note: OverlayEditor doesn't display the bridge segments as being raised, so you may have to experiment a little.

You can use to make OverlayEditor display networks from the default scenery (in outline form). But X-Plane will not join network segments in your scenery package to segments from the default scenery, and traffic will not flow between them. You can place an Exclusion region to hide network segments from the default scenery, use to pull the hidden segments into your scenery package, and then edit them.

Differences between this application and X-Plane

This application displays terrain and objects in orthogonal projection (no perspective) and in a simplified form. i.e.:

• No lights, lines, materials, shading or animation. 3D objects that only contain lights or lines are displayed as small “placeholders” so that they can be edited.
• This application can only display 3D objects, facades, draped polygons, lines, strings and networks. Other types of polygon (beaches, forests, etc) are displayed as an outline. Beach polygons cannot be edited.
• When you add a new draped polygon this application behaves differently depending on the contents of the .pol file:
  • A draped polygon (.pol) file that contains a TEXTURE statement is assumed to be intended for use as a repeating texture (requires X-Plane 8.50 or later).
  • A draped polygon (.pol) file that contains a TEXTURE_NOWRAP statement is assumed to be intended for use as a quadrilateral orthophoto or decal (requires X-Plane 8.60 or later). OverlayEditor does not allow you to add nodes or holes to orthophotos.
  X-Plane lets you use the same draped polygon (.pol) file for either purpose but you will see visual artefacts if you use a TEXTURE statement in an orthophoto/decal or use a TEXTURE_NOWRAP statement in a repeating texture.
• Network bridges can be constructed and edited, but all networks are displayed at ground level.
• Terrain textures are simplified - no beaches or overlay textures.
• No flattening of terrain around airports. Terrain is displayed as if the X-Plane “allow sloped runways” rendering setting is turned on.

X-Plane prioritises scenery packages. Prior to X-Plane 10.10 a package's priority is determined by its ASCIIbetical order in the Custom Scenery folder. Since X-Plane 10.10 a package's priority is determined by its order in the Custom Scenery/scenery_packs.ini file. You can see the order in which X-Plane prioritises your packages by looking at the file Log.txt in X-Plane's top-level folder.
X-Plane will not load or display a scenery package if it has a lower priority than a “full” DSF scenery package (i.e. one containg a terrain mesh) for the same area, but this application will not warn you about this problem.

When you open or reload a scenery package this application warns about any objects that are missing or that it can't read, but lets you edit and save the scenery package anyway. X-Plane will display an error unless you either provide implementations of missing and unreadable objects, or remove all uses of these objects from the scenery.

X-Plane supports having multiple versions of a single library object, and chooses which object to display at random. However, this application always displays the first version of an object that it comes across. Many objects in the default libraries exist in multiple versions - e.g. the library object /lib/global8/us/in_sq_90_30r.obj exists in at least eight different versions; if you use that object in your scenery package then this application will always display the same version, but X-Plane will display one of the eight versions chosen at random.

Using OverlayEditor in conjunction with other scenery tools

There are a number of other applications that can create X-Plane scenery packages. Those applications that place scenery objects work by writing “overlay” .dsf files into a scenery package folder. OverlayEditor can read and edit “overlay” .dsf files produced by other applications; but of course if you re-run the other application you may overwrite any edits that you have made using OverlayEditor.

In particular, the WED application can be used both to create X-Plane airport layouts and to place scenery objects. Like OverlayEditor it places scenery objects by writing “overlay” .dsf files, but it also writes the airport layouts to a file named apt.dat in your scenery package. You can safely use WED to create and edit airport layout(s) and OverlayEditor to place scenery objects within the same scenery package as long as you only use the File → Export apt.dat menu option in WED and avoid the File → Export Scenery Pack menu option.

Troubleshooting

OverlayEditor is too slow

OverlayEditor needs to load lots of textures and uses much more memory if the preferences are set to display terrain. Closing other applications, particularly applications like X-Plane that also make heavy use of textures, will make OverlayEditor load faster. Or you can tell OverlayEditor not to display terrain; press and select “No terrain”.

Editing is slower when the preferences are set to display terrain elevation. This is particularly noticable when editing polygons because OverlayEditor has to fit the polygons to the terrain mesh. OverlayEditor runs much faster if you tell it not to display elevation; press and select “No terrain” or “Show terrain”.

OverlayEditor complains that it “Can't read one or more objects”

Your scenery package uses objects that are either missing or unreadable. Missing or unreadable 3D objects are displayed as small “placeholders”. Missing or unreadable polygons are displayed as “placeholder” shapes.

To delete all uses of the missing or unreadable 3D object or polygon in the current 1°×1° region:

Select the 3D object or polygon in the list of objects
Press Ctrl Shift N
Press Delete or

OverlayEditor complains that it “Can't read one or more textures”

This happens when OverlayEditor fails to find or read the texture file listed in your object(s).
OverlayEditor expects the texture filename to have the correct case - edit your object to correct the texture filename.
OverlayEditor cannot read interlaced PNG files - save your PNG file in 24bit or 32bit non-interlaced format.
Then press to tell OverlayEditor to re-read your objects and textures.
Note that OverlayEditor only reports problems with textures when you load or reload a scenery package, and when you first add an object to the scenery.

My 3D object just appears as a small grey blob in OverlayEditor

OverlayEditor doesn't draw lights or lines - 3D objects that only contain lights or lines are displayed as small “placeholders”. This is a limitation of the application.

My forest/draped polygon just appears as a red outline in OverlayEditor

In X-Plane polygons must be “simple”, i.e. a polygon's sides must not intersect each other. X-Plane won't display non-simple polygons. OverlayEditor displays non-simple polygons as a bright red outline.

OverlayEditor won't let me place my object/node exactly where I want it

This is a limitation of the DSF file format as currently used by X-Plane.
Laminar's scenery tools encode DSF files with a precision of approximately 0.0000005°, which at the equator is about 5 cm or 2 inches. To avoid objects and nodes shifting when you save and re-open your scenery package, or when you view your scenery package in X-Plane, OverlayEditor doesn't let you place objects or polygon nodes with finer precision than that supported by the DSF files.

I want to remove some scenery objects from the default scenery

You can use an exclusion region:

Navigate to the area from which you want to remove the scenery objects.

Select “Exclusions” from the drop-down Objects menu.

Choose the type of object that you want to exclude.

Press Enter or .

Drag the corners of the new region as desired.

OverlayEditor doesn't display the “autogen” scenery objects, so you may have to experiment a bit.

Exclusion regions are always rectangular (you can't add or delete nodes) and can't be rotated. You can make up more complex shapes by adding multiple exclusion regions.

I want to remove some scenery objects from another scenery package

Follow the above procedure. In addition, your scenery package must have a higher priority than the other package. So you may need to rename one of the two packages to change their relative priority.

Exclusion regions exclude objects from other, lower priority, scenery packages, not from the scenery package that contains them.

I want to change the elevation of a scenery object

OverlayEditor just places scenery objects (other than network segments) directly on top of the terrain mesh. To change the apparent elevation of a 3D object you need to edit the object using a 3D modelling application.

X-Plane does not display any of my scenery objects

Check that OverlayEditor saved your package correctly:

Run OverlayEditor again, open your scenery package and check that it looks OK.

 

Check that OverlayEditor saved your package in the correct copy of X-Plane:

Press and check that the “X-Plane location” points to the copy of X-Plane that you're running.
If it doesn't, change the “X-Plane location” setting. Then, in Explorer or the Finder, move your scenery package folder to the copy of X-Plane that you're running.

 

Check your X-Plane settings:

Run X-Plane and choose Settings → Rendering Options.
Check that “number of objects” is not set to “None”.

 

Check that X-Plane found your scenery package:

Quit X-Plane. Open the file Log.txt in the top-level X-Plane folder. Your scenery package should be listed at least twice in this file; firstly in the list of scenery packages, eg:

n Custom Scenery\My package\

and secondly when X-Plane loads the DSF(s) from your scenery package, eg:

DSF load time: nnn for file Custom Scenery\My package\Earth nav data:+50-010\+51-001.dsf

If X-Plane is not loading DSFs from your package then this is probably because another package has a higher priority than your package. Look in Log.txt to see which DSF files X-Plane is loading from the Custom Scenery folder - this will tell you the name of the package that is hiding your package.
Rename one or both of the packages to change their relative priority.

Limitations

• Does not display “autogen” scenery.
• Does not display lights or lines in 3D objects.
• Does not convert or edit X-Plane 7 and earlier .env files.
• Does not edit scenery packages containing custom networks, or standard X-Plane v8 or v9 networks.
• Displays but does not edit runways, taxiways, navaids etc.
• In some cases facades may be displayed slightly differently to X-Plane - e.g. extra windows in a wall etc.
• Interlaced PNG files appear untextured.

License

This application is licensed under the GNU GPL license; either version 2 of the license, or (at your option) any later version.

Use of these tools does not impose any requirement on you to license your work under a GPL license. For the avoidance of doubt, this means that you can license any scenery that you make using these tools under commercial terms (subject to any licensing restrictions on any imported or library objects that you use).

The author would appreciate a courtesy copy of any commercial scenery that you make using these tools, but you are under no obligation.

Acknowledgements

This application uses and/or includes the following software:

• Geospatial Data Abstraction Library (GDAL) © 2000 Frank Warmerdam et al, X11/MIT licence.
• libjpeg © Tom Lane, Independent JPEG Group (IJG) et al.
• LibTIFF © 1988-1997 Sam Leffler, © 1991-1997 Silicon Graphics Inc, et al, LibTIFF License.
• Numeric Python (NumPy) © 2005 NumPy Developers, NumPy License.
• OpenJPEG © 2002-2007 Universite catholique de Louvain (UCL) et al, BSD licence.
• PROJ.4 Cartographic Projections library © 2000 Frank Warmerdam, MIT License.
• PyLZMA © 2004-2010 Joachim Bauch, © 1999-2010 Igor Pavlov, LGPL v2.1 license.
• PyOpenGL © 2005-2007 Michael C. Fletcher and Contributors, OpenGL-ctypes License.
• Python © Guido van Rossum et al, Python Software Foundation License version 2.
• Python contextlib2 © 2011 Nick Coghlan, Python Software Foundation License.
• Python Imaging Library (PIL) © 1997-2011 Secret Labs AB, © 1995-2011 Fredrik Lundh, Python Imaging Library License.
• wxPython © 1998-2005 Julian Smart, Robert Roebling et al, wxWindows Library Licence.
• XPTools © 2009 Laminar Research, MIT License.

Version 2.61 © 2006-2017 Jonathan Harris