Instructions - Coast-Line-Maker V1.1 (1st release)

© Iain Murray, 2003

About Coast-Line-Maker V1.1

Coast-Line-Maker is a utility designed to allow manipulation of the coastlines in Microsoft's Flight Simulator 2002 - existing coastal segments can be deleted or edited, and new ones added. Coast-Line-Maker also allows manipulation of other line segments, such as rivers and roads. The main features of Coast-Line-Maker were conceived as follows:

• graphic-oriented design screen, allowing easy placement of line segments
• requires no user knowledge of programming, assembler files or hex editing
• coverage over more than one LOD13 cell - Coast-Line-Maker can handle an entire LOD8 cell in one project
• automatic alignment between coastline segments and land/water polygons
• automatic generation of assembler source files, with automatic compilation and copying of new scenery BGLs to FS2002 scenery folder
• facility to rework river/stream and road segments too
• facility to save Coast-Line-Maker projects and reload them for editing

FS2002 coastlines are created in a different way from earlier versions of Flight Simulator. The world is divided in to a 768 x 512 grid of cells (called LOD8 cells) - initially water, but main land areas are set up by block filling certain cells with land. The actual land/water margin detail is then set up using a finer cell grid (32 x 32 LOD13 cells within each larger LOD8 cell) using Land & Water Masks (LWMs). These are essentially a series of polygons which are either land or water, and are used to mask out the underlying land/water to achieve the correct coast shape.

Oddly, any coastlines (i.e. beaches, waves etc.) are not defined as part of this process, but are created separately using Vectored Terrain Polygons (VTPs) - this is the same technique used to create roads etc. in the FS2002 world. Coastlines can be created either with or without breaking waves (the waves are generated automatically by FS2002 if the VTP coastline is set up correctly).

LWMs and VTPs are normally defined within scenery assembler source files, and compiled using the MS scenery compiler BGLC (part of the MS SDK for FS2002) to produce scenery BGL files for FS2002.

Coast-Line-Maker was designed to allow coastlines to be drawn graphically on the screen, and then generate the corresponding LWM and VTP assembler source files automatically - the program will even compile these assembler files and copy the resulting scenery BGL files directly to your FS2002 scenery folder.

Getting Started: Coast-Line-Maker first time setup 

• Create a new folder, and into it copy the CoastLineMaker.EXE file and the Documentation subfolder (with its contents)

This is the folder within which you should also store any background map images and your CoastLineMaker data files (which have a .CLM extension).

You will also require the following tools to complete a CoastLineMaker project, which should be copied into the same folder as above:

• a copy of the MS scenery compiler BGLC.EXE (from the Microsoft BGL compiler SDK available at http://zone.msn.com/flightsim/FS02DevDeskSDK15.asp)
• a copy of files TDFMacros.inc and TDFHeaders.inc - these files (by Richard Ludowise) are needed for successful compilation of the scenery and are included in the Coast-Line-Maker package 
• a copy of files Cell_Grid.inc and 192_127_Grid.txt - these files (by Richard Ludowise) from his CellGrid2.ZIP are included in the Coast-Line-Maker package 

For basic troubleshooting information for Coast-Line-Maker, please see README.TXT.

Getting Started: The Coast-Line-Maker Design Process 

A worked example of reworking a simple coast with Coast-Line-Maker is given in the accompanying Tutorial.

The best way to use Coast-Line-Maker is as follows:

• find the cell co-ordinates of your "target region"
• create a background map showing your "target region" - this can be a screen capture from FS2002 map view
• within Coast-Line-Maker, add new coastline segments where required
• within Coast-Line-Maker, add land and water polygons around the new coastline to mask off any existing land/water that is not needed
• within Coast-Line-Maker, clear existing segments which are no longer needed from cells
• within Coast-Line-Maker, add any other segments (rivers, roads etc.) if required
• save the VTP and LWM data as assembler files, assemble them with BGLC and copy the new scenery BGL files to FS2002 (Coast-Line-Maker can do this automatically for you)

The data flow of the Coast-Line-Maker design process is as follows:

Getting Started: Making a background map 

Coast-Line-Maker needs a background map upon which to draw the coastline. The best map to use is a map captured from the map view of FS2002 itself, over which is laid the LOD13 cell pattern and/or a map of the real coastline which you wish to follow. The accuracy of placement of your new coastline etc. within FS2002 will depend on the accurate drawing of the background map!

To produce this map, follow these steps:

• Open FS2002 and go to the middle of the target area in which you wish to change the coastline; note the latitude and longitude co-ordinates (see them by hitting Shift-Z or in Map View).
• Use Coast-Line-Maker's Cell Calculator (menu Help / Cell Calculator) to find the LOD8 cell containing the target co-ordinates.
• Use the CellGrid files (included as part of this package) to generate a visible grid BGL for this LOD8 cell (edit the name and content of the given 192_127_grid.txt to reflect the required LOD8 cell co-ordinates, then drag-and-drop this file onto BGLC.EXE to compile the scenery BGL); copy the grid BGL to an active FS2002 scenery folder (remember to copy the grid texture LOD8define.bmp to the corresponding texture folder too)
• Open FS2002; go to Map View in the target area to see the grid on the ground. Use the zoom controls to fill the screen with the area containing the coast to be modified (N.B. if this area is in more than one LOD8 cell, you will have to perform this process for each LOD8 cell). Use the rotate controls to get the grid running parallel to the sides of the screen. Press Alt-PrtSc to capture the screen, then paste this into your favourite bitmap drawing program (e.g. MS Paint, Paint Shop Pro etc.). Crop the image to include only the rows and columns and cells to be edited - your image should thus contain only a number of complete cells - see the Tutorial for examples of good and bad map images. 
• If required, use your art program to overlay this image with an actual map of the target area - many online maps are available, which you can download and edit together to cover your target area. Online maps are available from sites including:
  • http://www.multimap.com/
  • http://www.streetmap.co.uk/
• Save your modified image - Coast-Line-Maker will accept images in BMP, GIF or JPG format. It is suggested that you reduce the colour depth to 256 or 16 colours (especially if the image dimensions are large) in order to keep the image file size manageable. Coast-Line-Maker will accept large images - it has been tested with images 6000 x 5000 pixels!

Using Coast-Line-Maker 

• Run Coast-Line-Maker, and load the map created above as the background image. In the Background Properties dialog, enter the details required (the LOD8 co-ordinates already found, and the co-ordinates of the LOD13 cells in the top left and bottom right corners of your background image).
• Select Output / Preferences and enter a root filename (the names of the LWM and VTP assembler files will be generated from this root) and select any other preferences as required. You may also elect to compile your new files and copy them to your FS2002 scenery folder. 
• Now you are ready to draw on your coastline (you must do this before you add LWM polygons, as the coastline will be used as the edge of the polygons) - from the combo box, select one of the coastline options - usually Coastline (sand) with waves
• Click on the map at the start of your new coast segment - this will usually be at the edge of an LOD13 cell at the point where the existing coast is (as you will usually want to connect your new coast segment to an existing coast segment)
• Continue along the coast, clicking at significant turning points as you go - a segment will usually also end on the edge of an LOD13 cell. If a separate coastal segment is to be added, click on Start new segment, then click along the new segment. Note that you must place at least one coast point within each LOD13 cell which the coastline passes through ... if there is a long straight stretch of coastline, do not simply click at the start and end!
• Once a point has been placed, it cannot be drag-and-dropped to a new location. If a point is to be repositioned, select it (either by right-clicking near it on the map or by selecting it from the list) then click Edit point and enter new co-ordinates for the selected point. This is particularly useful to position points at cell edges, especially if the scale of your map makes it difficult to achieve precise positioning of the mouse over the map.
• The Current segment Width setting can be used to change the width of individual VTP segments - settings of 80 (for coastline segments) and 40 (for road segments) are similar to MS default settings. If you wish to resize a segment, enter the new width in the text box, select a point within the required segment in the list box, then click Change segment width.
• Note that land and water mask polygons are textured automatically by FS2002 - land will assume the textures of the underlying LandClass, and water will automatically assume the shimmering water texture. Also, any joins between polygons of the same type will not be visible in the simulator!
• If you are making a sea coastline, you will normally set land polygons to conform to existing terrain, and set water polygons to fixed height of 0m. If you are doing lakes etc., then water should again be a fixed height, but this time the height ASL of the lake surface. You can also rework terrain elevations to a limited degree with land polygons set to specific heights. When selecting land or water polygons, Coast-Line-Maker will automatically set the default height option for the polygon type.

Testing out your new coastline / Troubleshooting

• If you have not set Coast-Line-Maker to automatically copy the output, then manually copy the BGL file(s) generated by Coast-Line-Maker / BGLC to an active scenery subfolder in FS2002. Run FS2002, and go to your target area - you should see the new coastline that you created in Coast-Line-Maker.
• The following common problems are easily resolved:
  • if any of the coast segments are the wrong way round (i.e. the beach is on the water side and the waves are on the land side), then select a point within that coast segment and click on Reverse segment, then resave the VTP file

  

  • if the ends of your new VTP segments do not match well with existing segments, your background map is probably slightly out of alignment - the simplest fix is to nudge the misaligned segment ends the right way in Coast-Line-Maker, then resave the VTP file. If you have to nudge them quite far, you may need to reposition any adjacent LWM polygons too, and resave the LWM file
  • if the VTP segments and LWM edges do not match, you have probably repositioned the VTP segment after drawing the LWM polygon - delete the current LWM polygon and redraw to the new VTP shape, then resave the LWM file
  • if any VTP segments have unexpectedly vanished from LOD13 cells adjacent to where you placed new segments, you may have to nudge the endpoints of your segments inwards (away from the problem cell), then resave the VTP file

  

Hand editing the Coast-Line-Maker output - advanced users only

The assembler files created by Coast-Line-Maker include some parameters which are always set to the most commonly used values. However, you may wish to hand edit the assembler files using Notepad in order to create some specific features in your scenery:

• By default, adding new coast within an LOD13 cell will remove any existing coast in the cell ... if you wish to retain the existing coast in a cell, then within the VTP ASM file, edit the lines beginning with  VTPLayer to change the final "1" to a "0"
• Coast-Line-Maker requires you to consider each LOD8 cell as a separate project; if your project covers several LOD8 cells, you will thus generate several LWM BGLs and several VTP BGLs. To combine these, you could hand edit the ASM files to combine the structures of the two files, though this will require some appreciation of the structure of the two types of ASM files.

After editing, drag any modified assembler files onto BGLC.EXE to assemble the file, then manually copy the newly-generated BGL file to your FS2002 scenery folder.

Coast-Line-Maker - Caveats and Limitations

• Remember that you must place at least one VTP segment point within each LOD13 cell which the segment passes through. Where a coast segment crosses an LOD13 cell without a point in that cell, the coastal segment will be ignored when placing LWM polygons. Where a point at one end of a coast segment is placed on the edge of a cell, you should also place at least one point within that cell. During testing, most faults in the program output were due to coastal segments passing through cells with no points in those cells!

• Do not place VTP segment points precisely at LOD13 cell corners - you can place the point very close to the corner (e.g. co-ordinates 1 and 254), but avoid the corner itself (co-ordinates 0 and 255)
• Coast segments should never cross over one another - LWM polygons may be placed incorrectly if they do
• LWM segments will form themselves to coastline segments, but will ignore other segments such as rivers and roads
• Having clicked in a LOD13 cell to place an LWM polygon, Coast-Line-Maker uses a very simple algorithm to detect which of the polygons within the cell you have selected. This algorithm is not 100% accurate, so if the wrong LWM polygon is created, select it from the list, delete it and click again - try to click near the centre point of the polygon that you wish to select.
• LWM polygons should always be convex in shape, otherwise they may not be displayed correctly (this is actually a limitation of Flight Simulator itself). Any potential concave polygons should be broken down into convex shapes, using plain coast segments as edges.
• Although LWM polygons are aligned with VTP segments at the time they are drawn, they are then unconnected with the VTP points. If the latter are moved, you may need to delete previously drawn LWM polygons and redraw to align to the new VTP points.  This can be useful in that temporary VTP points can be drawn, an LWM polygon created around them, then the VTP points deleted again e.g. to split a concave polygon into convex sections, or to do fine detail in the LWM such as docks etc

• Note that Plain segments deliberately do not appear in the VTP output - they are used simply to act as the edges of the LWM polygons
• If an attempt is made to draw an LWM polygon in a cell which contains VTP points within it but none at edges, Coast-Line-Maker will draw a polygon around all the points of the first VTP segment detected (useful for drawing small islands, docks etc.)
• FS2002 will draw the LWM polygons in the order listed in Coast-Line-Maker. Careful ordering can be used to build up layer effects, such as land then a lake (water polygon) then an island (land polygon) on top of it
• If an error with BGLC is reported when saving the files, try the save again (the compilation will timeout if your machine is busy with other processes) - note that for the compilation and copy to be successful, FS2002 must not be running at the same time.

Acknowledgements and Legal Notice

Thanks to many subscribers to the AVSIM scenery design forum (especially Richard Ludowise) for helpful comments made in the forum, or to me directly. Without these comments, writing Coast-Line-Maker would not have been possible. Thanks also to Richard Ludowise for permission to use his include files (which are in the public domain) within the Coast-Line-Maker package.

The Coast-Line-Maker program is distributed as Freeware but remains © Iain Murray, 2003, all rights reserved; it may not be distributed commercially by any means without the express written permission of the author. Any sceneries created using Coast-Line-Maker are the copyright and property of the scenery author, but where such scenery is published (either commercially or as Shareware or as Freeware), the scenery author should acknowledge the use of Coast-Line-Maker in its creation; as a courtesy, the scenery author should also inform the Coast-Line-Maker author of publication.

Coast-Line-Maker should not harm your computer or any data stored on it but, if you imagine that it has, the author accepts no liability.

Go to Iain Murray's flight simulator page

Send an e-mail to Iain Murray