Creating X-Plane custom sceneries with ogxp_basemesh.py
ogxp_basemesh.py creates X-Plane custom sceneries based on a variety of raster and vector input data sources. The following guide will use Shemya Island (PASY Eareckson Air Station) in the Aleutians as an example of creating a custom scenery with ogxp_basemesh.py.
IMPORTANT FIRST STEPS
1) Download the following datasets prior to running ogxp-basemesh.py:
a) X-Plane xes land class files for MeshTool versions 2 and 3. Available from:
MeshTool 3 (v10 textures) http://dev.x-plane.com/update/misc/MeshTool3/
Place these in a ‘/xes_3’ subfolder.
MeshTool 2 (v9 textures) http://dev.x-plane.com/update/misc/MeshTool2/
Place these in a ‘/xes_2’ subfolder.
You can download just the files needed for a project, or for convenience use wget to download entire set.
b) The global OSM water polygon shapefile. Available from:
2) Set your ogxp_tools environment paths with ogxp_set_path.py PRIOR to running ogxp_basemesh.py.
For the xes path choose the folder that contains the ‘/xes_2’ and ‘/xes_3’ subfolders.
The presence of certain directories in the root of your project working directory are important argument switches for ogxp_basemesh.py:
If this directory is present, ogxp_basemesh.py will look for a polygon shapefile forming a sea mask. This shapefile will set the sea level ‘TERRAIN_WATER’ terrain type for the DSF tile and delineate the coastline.
This shapefile should be sufficiently large to cover the entire intended project area.
If this directory is not present, ogxp_basemesh.py will get the appropriate sea mask from the OSM water polygon shapefile in the OSM directory path set previously by ogxp_set_path.py.
If this directory is present, ogxp_basemesh.py will use the DEM file(s) found here to create the input DEM for MeshTool.
There is a lot of flexibility here. You can use as many custom DEM files as you wish. They do not need to be the same resolution. They do not need to fully cover the project area. In fact, they can only cover a small area where added relief detail is required. They can overlap DSF degree grid boundaries.
They should, however, have valid values over the entire DEM. That is, they should not have NULL data values.
The DEM strategy of ogxp_basemesh.py is the following:
- Use the default X-Plane Global Scenery elevation raster as a base layer.
- Stack and seamlessly merge any custom DEMs found in the ‘/dtm’ directory on top of the base DEM. Custom DEM(s) can completely cover the DSF tile. In this case, the default X-Plane elevation raster will have no impact on the DEM created by ogxp_basemesh.py for input to MeshTool.
If the ‘/dtm’ directory is not present, ogxp_basemesh.py will use the elevation raster contained in the X-Plane Global Scenery for the relevant DSF tile. This can be either the default 3 arcsecond (1201 x 1201) elevation data or 1 arcsecond (3601 x 3601) elevation data found in the HD meshes from www.alpilotx.net.
If this directory is present, ogxp_basemesh.py will look for a polygon shapefile defining inland water areas (lakes, dams, rivers, etc.)
Each polygon feature in the shapefile can have an elevation attribute. The default name for this field is ‘elev’ (note: if a different name is used it should match the elevation field name in any shapefiles defining flat runways.). If you just want to add these polygons as TERRAIN_WATER textures and not do any DEM elevation or vertex Z updating, the shapefile does not have to have an elevation attribute.
For inland water shapefiles with elevation, you can switch off DEM elevation or vertex Z updating by having a flag value of 9999 as the elevation and these polygons will only be added as TERRAIN_WATER textures. This is useful for delineating rivers where elevation is not constant.
This directory holds the polygon shapefiles defining areas where a bivariate spline or ramp surface is applied to the DSF mesh vertices (as well as input DEM if this option is selected). Each shapefile has a corresponding ‘_cpt.txt’ control point file.
Details for collecting control points as well as format of the ‘_cpt.txt’ file are covered later in this guide.
It is strongly recommended that spline or ramp surfaces be previewed with ogxp_spline_surface_preview.py prior to running ogxp_basemesh.py.
SHEMYA ISLAND TUTORIAL
Working directory with data inputs that will used to create an X-Plane custom scenery:
QGIS workspace view showing orthoimages, sea mask polygon that will define coastline an water in DSF, runway polygons, and fade polygon that will define alpha fade around island.
Zoom in of Shemya and Nizki islands showing same data inputs.
The following sequential dialog prompts are identified by the .cfg file attribute name:
[mdir] Set working directory
[scenery] Enter the scenery name. This is the name of the folder that will appear in the X-Plane Custom Scenery directory.
[addflt] Prompt for adding flat runways. The default is ‘No’.
If ‘Yes’ is selected, pick one or more polygon shapefiles [airf_list] with an integer attribute containing the elevation in meters of the polygon. The DSF vertex elevation (and optionally input DEM) under the polygons will be updated based on the elevation attribute field in the shapefile.
[z_field] Dialog for ‘Enter elevation data field name’. The default name is ‘elev’.
This is the name of the elevation field in the polygon shapefiles delineating flat runways and inland water.
[addslp] Prompt for adding sloped runways. The default is ‘Yes’.
Creates bivariate spline or ramp surface (depending on number of control points) in the DSF mesh based on the boundary polygon shapefile and accompanying control point file (comma-delimited longitude, latitude, z in meters).
The minimum number of control points for creating a spline surface is 9. Two controls points will yield a ramp surface based on the slope between these points. Typically used for single runways with on control point at the high end and one control point at the low end. Therefore, the valid number of control points is n=2 or n>=9.
Name of boundary shapefile:
Name of control point file is shapefile name + ‘_cpt.txt’:
Control point file contents (comma-delimited longitude,latitude,z in meters):
Strategy for control point selection for runways:
Sets of 3 or 4 points (forming a line perpendicular to the runway) placed at intervals along the runway work very well. Be sure to place several points well away from the runway to provide sufficient context for the interpolation function. These points will not appear in the final mesh. They are only there to help define the spline surface. Imagine the runway is a dining room table and you are stretching a table cloth over it.
[burnair] Prompt for burning elevation updates in DEM. default=’No’
If ‘Yes’, elevation values from flat runways, sloped runway spline function and inland water will be burned into the input DEM for MeshTool.
‘No’ means that these values will not be burned into the input DEM but they will be applied on DSF mesh vertices.
Experience has shown that the actual difference for the resulting DSF is slight. It is mainly a convenience option to have a raster DEM with all the elevation updates carried out by ogxp_basemesh.py.
[meshres] Dialog for DEM resolution. Initial value = ‘0.0003’.
Enter the desired resolution in decimal degrees for the DEM that ogxp_basemesh.py will create as the input DEM for MeshTool.
Your choice will largely be determined by:
- if present, the resolution of the high resolution DEM(s) in the ‘dem’ folder in your working directory.
- how much terrain detail you would like to capture in your DSF.
The benefit of higher DEM resolution is potentially more detailed relief representation in the DSF mesh (the cost, of course, is more mesh triangles which can effect sim performance). But this is only true if you have a high resolution DEM that contains meaningful information at that resolution. Let’s say you have a nominal 20m resolution, or 0.0002 degree, DEM as your custom DEM input. It would be meaningless to enter 0.0001 degrees as your DEM resolution for ogxp_basemesh.py – four times as many pixels but no additional information.
Also keep in mind that MeshTool’s meshing algorithm (based on the CGAL library) is very good at culling unnecessary triangles over areas of low relief while maintaining mesh density over high relief. The sensitivity of this behavior is determined by the MeshTool parameters covered below.
For example, even if you have a 0.0001 resolution DEM, such as the USGS NED, you will still get very good relief representation in the DSF mesh by running a 0.0002 or 0.0003 resolution setting in ogxp_basemesh.py.
Note that the limit for MeshTool is 10,000 x 10,000 rows and columns for an input DEM, or a 0.0001 degree resolution.
X-Plane’s default elevation grid posting follows the DTED schema based on 3 and 1 arcsecond resolutions over a 1 x 1 degree block. 3 arcsecond is the default Global Scenery data resolution while 1 arcsecond is the HD mesh resolution.
While not necessary, if you want to keep with this schema, enter 0.000833333333 for 3 arcsecond (roughly 90m) or 0.000277777778 for 1 arcsecond (roughly 30m).
[negelev] Prompt for ‘Does scene have important below sea level elevation?’, default=‘No’
Choose ‘Yes’ if the project area has significant below sea level elevation, (e.g. Death Valley, Dead Sea, Danakil Depression, Netherlands etc.) that needs to be retained.
Default ‘No’ yields 0m minimum in DEM created by ogxp_basemesh.py. This cleans the spurious negative elevation values often found in SRTM or SRTM-derived elevation datasets.
[forcesea] Prompt for ‘Force sea vertices to 0m elevation?’, default=‘Yes’
The default ‘Yes’ will force all sea vertices to 0 elevation. This is particularly useful along coastlines with sheer cliffs and prevents water textures from appearing incorrectly on the cliff faces.
[en_coast] Prompt for ‘Enhanced coastal relief?’, default=’No’
If ‘Yes’ is selected, this option will add additional contour lines along coastlines. This can enhance sea cliff effects in certain cases. Beware the triangle cost.
[addbrk] Prompt for ‘Add additional breaklines?’, default=’No’
If ‘Yes’ is selected, this option will prompt for polygon shapefiles where additional vertices are to be imposed in the DSF mesh. This is useful for creating areas of mesh densification for subsequent editing of vertex elevation.
[post] Dialog for ‘Densification grid posting:’, ’10, 20, 40, 80 or 160’, initial value = ’20’
Nominal grid spacing in meters for vector grid created over sloped runways and break line polygons. Valid values are 10, 20, 40, 80 or 160. A smaller number yields a denser mesh with more vertices (and triangles). 20 or 40 usually yields a good result.
[add_deg] Prompt for ‘Additional surrounding degree squares?’, default=’No’
Selecting ‘Yes’ will bring up dialog to enter any additional DSF tiles to process beyond those that intersect with orthoimagery and/or AOI shapefile. List additional tiles separated by comma: ‘+30+040,+30+041…’
[MT_ver3] Prompt for ‘MeshTool 3?’, default=‘No’
This prompt allows you to choose either MeshTool v2 or the new MeshTool v3.
MeshTool 3 will produce X-Plane v10 land classes and polygon and network assets that will match surrounding default v10 Global Scenery DSF tiles.
MeshTool 2 will produce X_Plane v9 land classes and polygon and network assets that will NOT match surrounding default v10 Global Scenery DSF tiles.
The MeshTool 3 included by default with ogxp_tools is a custom recompile that retains v2 shapefile behavior. See discussion here in ogxp_tools dependencies.
[meshparam] Dialog for ‘MeshTool parameters’, initial value = ‘150000 4’
In this dialog you can adjust the target vertex count and vertical error for MeshTool as described in the MeshTool documentation.
Essentially, the lower the vertical error, the more tightly MeshTool will follow the elevation values in the input DEM. The cost, of course, is more vertices and mesh triangles.
The first number sets a rough limit on total points per DSF tile. Otherwise, in an attempt to meet the vertical error demand the total number of points could balloon into millions of points which would render an incredibly slow or un-loadable DSF.
I have run a 1 million point DSF but this is rarely justified in terms of terrain representation. Remember, as with DEM resolution beware the point at which new information stops and wasteful pixel or point redundancy occurs.
[submeter] Prompt for ‘Preserve sub-meter Z precision?’, default=‘yes’
Selecting ‘Yes’ to this option will preserve sub-meter vertex Z precision. If you are adding sloped runways with spline surface (option 4 above), you must select ‘Yes’ here to preserve smooth rolling runways.
[copy_assets] Prompt for ‘Copy v10 assets?’, default=‘No’
Selecting ‘Yes’ will copy X-Plane v10 polygon and network assets from the default Global Scenery v10 DSF to the custom scenery DSF being created by ogxp_basemesh.py.
[strip_AG] Prompt for ‘Strip autogen but leave road network?’, default=‘Yes’
Selecting ‘Yes’ will strip v10 autogen textures but leave transportation network.
[strip_beach] Prompt for ‘Remove default beach polygons?’, default=‘Yes’
Selecting ‘Yes’ will remove default beach polygons from custom DSF created by ogxp_basemesh.py.
[add_beach] If ‘Yes’ to removing default beach polygons, prompt for ‘Calculate new beach polygons?’, default=‘Yes’
Selecting ‘Yes’ will produce new beach polygons along your entire coastline input.
[spec_beach] If ‘Yes’ to ‘Calculate new beach polygons?’, prompt for ‘’Specify beach type?’, default=‘Yes’.
Selecting ‘No’ will set your new custom beach polygons to the most common beach type in the default v10 DSF.
[beach_id] If ‘Yes’ to ‘Specify beach type?’, prompt for ‘Enter beach type’, ‘Beach type (1-25):’, initial value = ’10’
This is useful if you have a customized coastlines.dds and beach.bch in your ‘/X-Plane 10/Resources/default scenery/900 beaches’ directory and you know the type number.
[water_brk] If ‘/inland_water’ directory with shapefiles found in your project working directory, prompt for ‘Flatten elevation under inland water?’, default=‘No’
Selecting ‘Yes’ will treat the water polygons like flat runways and update DSF vertex elevation (and optionally input DEM) under the polygons based on the elevation attribute field in the shapefile.
Note that elevation attribute field must be the same name specified earlier in:
[iw_burn] Prompt for ‘Burn transparency for inland water?’, default=’no’
Selecting yes will create an alpha transparency over inland water polygons. The effect is to mix the orthoimage with the default X-Plane water texture.
[burnval] If ‘yes’ to iw_burn, prompt for ‘Percent transparency’, default=’50’
[seamless] Prompt for ‘Force same Z and normals for coincident vertices?’, default=’no’
Selecting ‘Yes’ will ensure same Z and normals for coincident vertices. This can help reduce artifacts along DSF borders. Note that this is option is set internally by default when using MeshTool 3.
[imagef_list] Dialog for ‘Pick orthoimage(s) or shapefile of AOI:’
Select the input orthoimages for the scenery project. The combined extents of the selected images will define the list of DSF tiles that will be processed.
Optionally, if no orthoimagery will be processed, select polygon shapefiles to define the
project area and generate the list of DSF tiles that will be processed.
Orthoimagery must be georeferenced. GeoTIFF format is strongly recommended
though other ogr/GDAL-supported formats such as BMP/bpw, JPEG/jpw, IMG, etc.
should be supported as well.
If orthoimagery is to cover X-Plane water (either opaquely or with alpha transparency), ‘_top_’ should be in orthoimage filename (i.e. ‘shemya_top_.tif’).
You can now have a higher resolution orthoimage be added as an overlay over your base orthoimage. For example, a 50cm resolution image can be placed over a 1m resolution image over an airport or city or town. Simply put ‘_hr_’ in the filename of the high resolution image and ogxp_basemesh will know how to process (i.e. ‘shemya_hr_.tif’). The default visibility range is 0 – 2000 ft.
[proc_image] Prompt for ‘Process orthoimagery?’, default=‘Yes’
Select ‘Yes’ to tile orthoimagery for use in X-Plane 10.
The remaining prompts and dialogs define the various image processing options
provide by ogxp_basemesh.py.
[setrans] Prompt for ‘Set border tile alpha fade transparency?’, default=’No’
Selecting ‘Yes’ will create an alpha transparency fade along the edge tiles of each
orthoimage so as to not have a hard edge between orthoimagery and surrounding DSF
textures. ‘No’ will leave a hard edge. Non-border tiles are not turned into alpha
channel .dds so as to reduce file size.
Custom border fade operations can be carried out via tile lists. See Selective orthoimage tile processing.
[seatrans] Prompt for ‘Transparent hard?’, default=‘No’
Selecting ‘Yes’ will open dialog to select a polygon shapefile. Areas under the polygons
will be 100% transparent with no soft fade along the edge.
[blurtrans] Prompt for ‘Transparent blur?’, default=‘No’
Selecting ‘Yes’ will open dialog to select a polygon shapefile. Areas under the polygons
will have transparency fade along the polygon edge. Fade
direction is 100% alpha from inside the polygon to 0% or no alpha towards outside of
[blur_w] If ‘yes’ to blurtrans, prompt for ‘Set blur fade width in pixels’, default=’100’
Sets the blur width in pixels along polygon boundary.
[mklit] Prompt for ‘Make night LIT textures?’, default=’No’
Selecting ‘Yes’ will produce LIT textures for each image tile and add the appropriate LIT
statement in the custom scenery .ter terrain files.
[brightcon] Dialog for ‘Set Brightness/Contrast’, ‘B%,C%’, initial value = ‘0%,0%’
Enter percent values as in the initial value string to adjust image tile brightness and/or
contrast. Valid range is -100 to 100.
[tilesize] Dialog for ‘Tile size’, ‘4096, 2048 or 1024’, initial value = ‘2048’
Enter either 4096, 2048 or 1024 to set the image tile size. Recommended size is 2048.
[resize] Prompt for ’Resize input image to even multiple of 4096, 2048 or 1024?’, default=‘no’
If ‘Yes’ is selected the image will be resampled to an even row and column multiple of
the selected tile size.
This is only useful if you will lose any useful imagery along the bottom and right edges
of your input orthoimagery as a result of the tiling process cropping any bottom and right
edge pixels that are less than the tile size dimensions.
As this is a resampling process there will be some degradation from the source image.
For islands where you you have sufficient imagery to cover the island but the tiling
process will crop the island, it is usually recommended to just pad the image with
sufficient pixels using ogxp_pad_imagery.py.
ogxp_basemesh.py will now create the custom scenery based on the data inputs
and selected processing options.
During processing the terminal or shell window will show the status of processing along
with the progress of certain operations.
When ogxp_basemesh.py completes you will find your custom scenery in the XPlane
10 Custom Scenery directory:
Open up X-Plane 10 and … well, you know what to do:
In addition to your completed custom scenery, ogxp_basemesh.py creates some files in
your working directory that are useful for interpreting the results of the scenery creation
In the root of the working directory you will find a ‘/textures’ folder if the processing
orthoimagery option was selected. This folder contains the orthoimage tiles in GeoTIFF
format (together with ‘.tfw’ World files) as well as the converted ‘.dds’ format.
if the processing orthoimagery option was selected, you will find in the root of the
working directory a shapefile index of the orthoimage tiles created for the scenery
Each DSF tile that is processed by ogxp_basemesh.py is processed in its own directory:
Inside these DSF tile directories you will find (in addition to many other intermediate or
temporary files) the following files (using DSF tile +52+174 as an example):
– the final DSF version in text format prior to conversion to binary and transfer to your XPlane
10 Custom Scenery directory.
– a comma-delimited file of all the vertices where Z was changed and new normals
– the input DEM created by ogxp_basemesh.py as input to MeshTool.
– the MeshTool command line used for this DSF tile.
– the MeshTool script file used for this DSF tile.
minmax_’min_elev’ _ ‘max_elev’.txt (i.e. ‘minmax_0.0_81.0.txt’)
– the minimum and maximum input DEM elevation
Inside the slope_runways directory you will find:
‘shapefile’_change_result.txt (i.e. ‘PASY_change_result.txt’)
– a comma-delimited file of all the vertices under the polygon where Z was updated
according the bivariate spline or ramp function.
‘shapefile’_b_spline.tif (i.e. ‘PASY_b_spline.tif’)
– a GeoTIFF of the spline or ramp surface.
PROJECT CONFIGURATION FILE
ogxp_basemesh.py can also be driven by project ‘.cfg’ file. The file is created in the root
of the working directory of a new project from the responses to the prompts and dialogs
If a ‘.cfg’ file is present in the working directory when ogxp_basemesh.py is run, those
parameters will used for scenery generation and all prompts and dialogs will be skipped.
If a .cfg file AND a ‘/textures’ directory are present in the working directory when
ogxp_basemesh.py is run, image processing and tiling will be skipped and
ogxp_basemesh.py will use the parameters in the .cfg file.
This functionality saves time when running multiple iterations of a project.You can tweak
a few parameters without having to go through all the prompts and image processing
The .cfg file is also a record of the inputs and parameters used for that scenery project.