Mod Terrain

This tool is intended to be used for modifying files, used by the Falcon 4.0 Flight Simulator. It was tested on OF setup on both 64 and 128 Segments terrains. It might work (maybe with limitations) on other Falcon setups (AF, RV) but this is yet to be tested. It will NOT work on 2-bytes terrains, only on 4-bytes. The program will NOT test for a 4-byte terrain before start working, so most probably you'll end up with messed terrain files If you try that. If there is interest for a 2-byte version, get in touch with me to create one.

The terrain in Falcon is made up from 6 Level Of Detail (LOD) pair of files. These are numbered from 0 to 5, the most detailed one being number 0. Each terrain LOD is made up of segments, which contain every time 256 (16×16) tiles. Each tile now, contains information for five things:

• Tile Offsets: 4 bytes (or 2 bytes for 2-byte terrains), which contain information about the tile graphic. That's an offset of another file that points to the final “skin” to be paint on the tile.
• Elevation Data: 2 bytes, which contains the actual elevation of the tile (in feet).
• Pal Offset: 1 byte, which points to a color from a colortabe, which is stored in “theater.map” file (you can edit this colortable with my other tool “TerrainEditor” as well). This color is used for vertex shading and fog effects in the game.
• “theta” angle: 1 byte, which contains the “theta” Normal value for the tile. This depends on the elevation of the surrounding tiles and must be recalculated after any elevation data change.
• “phi” angle: 1 byte, which contains the “phi” Normal value for the tile. This depends on the elevation of the surrounding tiles and must be recalculated after any elevation data change.

For the rest of this document, when referring to “Mapwidth” of a terrain LOD, I'll be meaning the total number of tiles across the edges (vertically or horizontally is the same as each terrain LOD is square). Moreover, all calculations on the tiles are done, taking the lower-left tile of each terrain LOD as origin and moving across the rows (horizontally to the right). When the most right tile is reached, the next one is the most left on the row above. In this manner, the last tile is the upper-right one. All files created and imported with ModTerrain program (except the TARGA images), adhere to the above rule (e.g. the first byte in the file is the lower-left tile, the second is the one on its right and so on).

The general functions that ModTerrain can perform are the following:

• Save all the terrain LOD information in separate files according to the type of information (Tile Offset, Elevation Data, Pal Offset, theta and phi), for one or more terrain LODs at a time.
• Read the previous information files (the original or modified) and merge it back into the appropriate terrain LOD.
• Read a raw Elevation data file, created for the terrain LOD 0 and merge it to all or selected terrain LODs, generating the elevation data for the appropriate terrain LOD. This can currently be done using three methods: Root Mean Square (RMS), Simple Mean and Maximum Height (more on that below).
• Calculate the Normals for all or a specific terrain LOD, with the ability to set the maximum phi angle (details below).
• Export TARGA images of one or more terrain LODs, containing the Pal Offset LOD data, along with the theater.map palette. This gives a visual representation of the real terrain shading colors for a given LOD, for every tile.
• Import a TARGA image (with an image width and height, equal to LOD 2 Mapwidth) and replace the Pal Offset tile data to all (or selected) terrain LODs, replacing the theater.map colortable (from the TARGA image palette). This allows you to edit any TARGA image (8bit - 256 color palette) and replace the terrain vertex coloring for your theater.

The raw elevation data file is just a file containing 2 bytes (short) records of elevation data (in feet) and the first record is the elevation of the lower-left tile of terrain LOD 0 (the order is as described above). The total records of this file must be (LOD 0 Mapwidth)^2 and of course the size must be 2*(Total records). During the import, these data are copied “as is” in terrain LOD 0 and for the other terrain LODs, these data are “averaged” because, all other terrain LODs have smaller Mapwidths than terrain LOD 0. This process allows us to take advantage of the maximum elevation detail Falcon can provide.

As I mentioned, I currently implement three methods for the calculation of the “average”:

• Root Mean Square (RMS) Method. The “averaged” value is derived from the formula .
• Simple Mean Method. The well known average function .
• Maximum Height Method. The “averaged” value is the maximum of all the values.
• Weighted Interpolation Method. The elevation for each point of a L file is calculated by interpolating the four corresponding values of the previous L file and by taking into account the neighboring tiles as well.

I really don't know which method gives the best result, as I haven't test all of them extensively. I use the Weighted Interpolation Method method as default, but I don't know if this is the best choice. If anybody has a better suggestion, for a better method, please let me know.

Normals for a tile, is normally a vector, perpendicular to the surface of the tile. While this usually is expressed as the length of the projection of the vector on each axis (Nx, Ny and Nz), in Falcon is expressed as two angles, theta and phi (spherical coordinates). The theta value is the angle of the added Nx and Ny projections with the West-East axis, as we see it looking the terrain from above. The phi angle, is the angle produced from the normal vector with the Up-Down axis, as we look from the side. Both theta and phi angles are “normalized” to fit in a single byte. The theta angle (range 0 to 2*pi rads) is normalized to a value from 0-255. The phi angle (range 0 to pi/2 rads) is normalized to a value from 0-63. During my tests, I found out that the original Korea theater, uses a range for phi angle between 0 to 0.52 rads (about 30 degrees) to normalize from 0-63. All values above 0.52 rads is converted to 63. With this in mind, I added a parameter for this MAX_PHI value which replaces the 0.52 rad value. This is evaluated when the program is calculating the terrain normals and ranges between 0.02 rad (1 deg) and 1.57 rad (90 deg). The actual parameter for the program is this value in rads, multiplied by 100 (e.g. for 1.57 rads you should put in the parameter 157). See usage below for more information.

ModTerrain is a command line tool. I made it this way, to be convenient for use with an installer. All the command-line arguments start with a special character, different for the usage of the argument. Some general rules are:

• All the arguments are separated by whitespace (spaces or tabs).
• Some arguments are needed only once (e.g. paths or files) and some can be used more than once (e.g. commands or switches).
• Every argument has a unique special character that must be typed before it, in order for the program to recognize it.
• Double quotes should be used to enclose paths and filenames, especially if there are spaces in-between. The special character can be inside the double quotes or outside.
• For arguments that you can specify more than one of the same type, you can either type each one with a leading special character, or type the special character in the beginning and write the arguments after (without spaces).
• The order in which you put the arguments doesn't matter.
• All paths specified, must NOT end on “\”.

The general argument list is as follows:

  ModTerrain.exe -[COMMAND(s)] %[TERRAIN_DIR] *[OUT_DIR] ~[IN_DIR] +[ELV_FILE]
                  $[IN_TGA] =[FILE_COMP(s)] #[LOD(s)] @[ELV_METHOD] ![MAX_PHI]

-[COMMAND(s)]: This section is required and actually tells to the program what to do. It consists of a minus (-) character and at least one letter of the x, t, r, e, m, n and i. More than one commands may be specified (even all of them at once). You can put the - character in front of each command (e.g. -x -t) or combine a group of commands together (e.g. -xt). The order of the commands is not taken into account and the process order is always [x][t][r][e][m][n][i].

• -x : Extracts terrain components (specified by =[FILE_COMP]) from terrain files (specified by #[LODs]).
• -t : Extracts a TARGA image from from terrain files (specified by #[LODs]) comprised by Pal Offset of each terrain LOD and the palette from “theater.map” file.
• -r : Imports terrain components (specified by =[FILE_COMP]) into terrain files (specified by #[LODs]).
• -e : Imports raw elevation data (specified by +[ELV_FILE]) into terrain files (specified by #[LODs]).
• -m : Generates “Theater.mea” file in %[TERRAIN_DIR] from L0 elevation data.
• -n : Fixes the Normals for terrain files (specified by #[LODs]) using ![MAX_PHI].
• -i : Imports a TARGA Image into terrain files (specified by #[LODs]) replacing Pal_Offset values, and also replaces “theater.map”'s palette.

%[TERRAIN_DIR]: Specifies the terrain directory to be used to read or write to Theater.Lx/Theater.Ox/Theater.map files. It is required by all commands but if it is omitted, the current theater's terrain dir of a Falcon 4 installation will be used. If there is not a Falcon 4 installation available (and a path is not specified) an error will occur.

*[OUT_DIR]: Specifies a directory for output for the [x][t] commands. If omitted while these commands are specified, the current directory (the one that ModTerrain was launched from) will be used.

~[IN_DIR]: Specifies a directory for input for the [r] command which contains the required files to import. If omitted while this command is specified, the current directory (the one that ModTerrain was launched from) will be used. The files to be imported must be named like “Theater.(#)#&” where (#)# is the file type identifier (t, e, p, 1x, 2x or xx) and & is the terrain LOD number (0, 1, 2, 3, 4 or 5).

+[ELV_FILE]: Specifies a file to be used with the [e] command. If omitted while this command is specified, an error will occur. This file is just raw data of elevation. The size of this file must be ((Seg*16*4)^2)*2 where Seg=Theater's Segments (64 or 128). This file is produced by the [x] command along with [=e] and [#0] switches.

$[IN_TGA]: Specifies a file to be used with the [i] command. If omitted while this command is specified, an error will occur. The file is a standard TARGA file and must be 8bit Indexed with a palette of 256 colors. It must be square with Width=Height=((Seg*16)^2)*2 where Seg=Theater's Segments (64 or 128), that is, the dimensions of the L2 file. This file is produced by the [t] command along with the [#2] switch.

=[FILE_COMP(s)]: It can be any of these letters/numbers: t, e, p, x, 1, 2. This switch can be used with the [x] and [r] commands and specifies which terrain file components will be processed (either exported or imported). When this switch is not present and any of the above commands are specified, all components will be processed (same as =tepx12). The components which are read/written for every switch are:

• [t] Tile Offset (4 bytes records)
• [e] Elevation data (2 bytes records)
• [p] Pal Offsets (1 byte records)
• [1] theta (1 byte records)
• [2] phi (1 byte records)
• [x] theta-phi (2 byte records, one byte for each)

#[LOD(s)]: It can be any of these numbers 0, 1, 2, 3, 4, 5. This switch can be used with all commands except the -[m] (MEA FILE) and specifies which theater files will be processed. When this switch is not present, all LOD files will be processed (same as #012345).

@[ELV_METHOD]: It can be only one of the numbers 1, 2, 3. This switch is used with [e] command and specifies the method to calculate the elevation for every LOD. The meaning of every number is:

• @1 : Root Mean Square (RMS) Method.
• @2 : Simple Mean Method.
• @3 : Maximum Height Method.
• @4 : Weighted Interpolation Method.

When this switch is not present, while the above command is specified, the Weighted Interpolation Method will be used (same as @4).

![MAX_PHI]: This switch is used with the [n] command to specify the maximum phi angle. The range is integers between 2 and 157. When omitted and the above command is specified, the default value is 52 (0.52 rad ~ 30 deg).

ModTerrain.exe -en +"C:\Korea\NewElv.raw"

Will put the NewElv.raw elevation data, in all terrain LODs and fix the normals. Since TERRAIN_DIR is not specified, a falcon installation is assumed. RMS Method is assumed and max phi 0.52 rad.

ModTerrain.exe -xt *"C:\Output" %"C:\Falcon\terrdata\terrain" #23 =te

Will export Tile and elevation data, along with TARGA images of Pal Offset data for LODs 2 and 3. All files will be written to “C:\Output” folder and theater data will be retrieved from “C:\Falcon\terrdata\terrain” folder.

ModTerrain.exe "~C:\Temp" #2 =x "%C\Falcon\terrdata\terrain" -r

Will import theta and phi values in terrain LOD 2 located in “C\Falcon\terrdata\terrain”. The program will look for the file “theater.xx2” in folder “C:\Temp” (the position of the special characters inside the double quotes is not a typo).