Bridge Command - World file format

World file

Please refer to the Initialisation file format (.ini) specification in conjunction with this document.

Introduction:

The world model defines the environment of a scenario, and uses a heightmap to set the terrain and bathymetry. In addition, a texture file is used to set the terrain colouring, and configuration files control how the environment is loaded, and other features such as buoys, landmarks and lights etc. A 'map' image is also used to display as a 2d view in the scenario editor and map controller.

A primary terrain must be defined, and any number of additional areas may be defined. The intention is for the primary terrain to cover the entire area defined, and for secondary terrains to be used to give higher resolution models of some areas if required. To allow the secondary terrain to be seen, the primary terrain must be below the height of the secondary in this area. The programme will prioritise the shallowest terrain when taking depth soundings, and to decide if the ship is aground.

For small details such as harbours and marinas, 3d models can be loaded into the world model. See the detail below in the landobject.ini for how land objects can be set to appear in the radar, and act as physical models that the own ship can interact with.

A variety of formats can be used for the height maps. The simplest is a greyscale png image, with black representing the deepest point, and white representing the highest point. A standard greyscale png can represent 255 shades from black to white, so if you need finer elevation steps (for example if you have high mountains within the world area), another format may be better. These are:

The world model is made up of files in a common folder. The folder name is used when loading the world model, and is found under World in the Bridge Command root folder. For example, if Bridge Command is installed in C:\Program files (x86)\Bridge Command 5.x, the files making up a world model called Atlantis would be in C:\Program files (x86)\Bridge Command 5.x\World\Atlantis. To allow users to edit or add world models without changing the overall installation, Bridge Command will look first in the user directory for a world model, and will use this in preference to the global model. The user directory can be found using the button on the Bridge Command launcher.

The terrain is loaded from two files, a height map and a texture. The shape of the terrain is generated from a height map, in which the colour of each pixel in the image is translated into a height value for that terrain location. The height map should be a greyscale PNG image, and black is low and white is high, or for better height resolution, you can use the RGB format where the height in metres is encoded as (red value * 256 + green value + blue value/ 256) - 32768.

It is recommended to use .png format for the heightmap images, as .bmp files may give inaccurate heights in some cases (depending on the exact type of .bmp images used).

Alternatively, a raw binary format is allowed. Bridge Command will load files with the standard 3dem header and binary format (.hdr and .bin). Also, height maps with the extension .f32 will be interpreted as a list of heights in metres as 32 bit floating point numbers. The benefit of both the RGB encoding and the binary format is a higher vertical resolution of height map, which may be helpful if your area includes deep sea and high mountains.

The terrain generated from the height map is coloured with a texture image, and then the additional features are loaded into the world as configured in the .ini files.

The files:

The constituent files are listed below, with their purpose. Each is dealt with in detail below

Configuration:

Height maps:

The filenames for the height map and texture files are as specified in terrain.ini. The heightmap should be in .png or raw binary format (3dem format with a .bin and .hdr file, or 32 bit floating point file with extension .f32), and the texture and map image should generally be square and power of two (2^n) sizes (512, 1024, ...). The heightmap does not have to be square, but internally Bridge Command uses square terrain models with 2^n + 1 in size (513, 1025, 2049, ...). Therefore it is less efficient to define a heightmap slightly larger than one of than this size, as it will be padded to fit the next largest square.

File details:

terrain.ini

Example

Number=2

MapImage="map.bmp"

HeightMap(1)="height.png"
Texture(1)="texture.bmp"
TerrainLong(1)=-10
TerrainLat(1)=50
TerrainLongExtent(1)=0.05010
TerrainLatExtent(1)=0.04008
TerrainMaxHeight(1)=100
SeaMaxDepth(1)=44.07

HeightMap(2)="detail.png"
Texture(2)="detailTexture.png"
TerrainLong(2)=-9.992284795
TerrainLat(2)=50.006875322
TerrainLongExtent(2)=0.006250292
TerrainLatExtent(2)=0.005000234
TerrainMaxHeight(2)=100
SeaMaxDepth(2)=44.07

If the .f32 format is used, two additional parameters, TerrainHeightMapRows and TerrainHeightMapColumns are needed to specify the shape of the binary matrix.

Note that if you are using a 3dem .bin and .hdr file, set the HeightMap name as the .hdr file. In this case, the entries TerrainLong, TerrainLat, TerrainLongExtent and TerrainLatExtent are not required, as they are included in the .hdr file from 3dem.

buoy.ini

Contains 1 general variable, and a set of 3 to 6 variables for each buoy defined. The global variable is Number, which is the number of buoys to be defined in the file. This can be zero, in which case no buoys are defined, and nothing further is required in this file. The three required variables for each buoy are Type(#), Long(#) and Lat(#). Type(#) takes the buoy type, as a text string. This must correspond to an available buoy model as defined in the Models\Buoy folder under the Bridge Command root directory. Long(#) and Lat(#) take respectively the buoy's Longitude and Latitude in standard decimal degrees. Note that only the buoy model and its location is specified here - if the buoy has a light attached, it must be specified in light.ini, as specified below. The first optional variable is RCS(#), which sets the buoy's radar cross section in metres squared. If not set, a default value will be used. The second optional variable is Grounded(#). If set to 1, this means that the 'buoy' will not respond to wave or tide, for example for a post. The third optional variable is HeightCorrection, which adjusts the vertical position of the buoy, and is set in metres, with a positive value moving the 'buoy' higher. Again this is useful for adjusting the height of a post.

Note that a folder Models/Buoy can be created in the world model folder to hold buoys required for this world model.

Example buoy.ini, setting up three buoys:
Number=3

Type(1)="Port"
Long(1)=-4.135
Lat(1)=52.407

Type(2)="RY"
Long(2)=-4.299
Lat(2)=55.004
RCS(2)=3.5

Type(3)="Mooring"
Long(3)=-4.505
Lat(3)=52.702
landobject.ini

The analog of buoy.ini, but for fixed objects, either on land or ground based object at sea (breakwaters etc). Contains 1 general variable, and a set of 5 to 6 variables for each land object defined.

Number sets the number of objects to be defined.This can be zero, in which case no land objects are defined, and nothing further is required in this file.

Note that a folder Models/LandObject can be created in the world model folder to hold land objects required for this world model.

Example landobject.ini
Number=5

Type(1)="lighthouse"
Lat(1)=33.30200
Long(1)=-118.31758
Rotation(1)=0
HeightCorrection(1)=64.62
Absolute(1)=1

Type(2)="lighthouse"
Lat(2)=33.40618
Long(2)=-118.36655
HeightCorrection(2)=21.64
Rotation(2)=0
Absolute(2)=1

Type(3)="lighthouse"
Lat(3)=33.46322
Long(3)=-118.49170
HeightCorrection(3)=22.86
Rotation(3)=0
Absolute(3)=1

Type(4)="lighthouse"
Lat(4)=33.47873
Long(4)=-118.60573
HeightCorrection(4)=23.16
Rotation(4)=0
Absolute(4)=1

Type(5)="lighthouse"
Lat(5)=33.42338
Long(5)=-118.51390
HeightCorrection(5)=121.92
Rotation(5)=0
Absolute(5)=1
light.ini

This specifies navigation lights in the environment. These can either be floating, maintaining its height above the water level - the location of these are defined by selecting the buoy number (as in buoy.ini) to which the light should be attached, or fixed. Fixed lights can be set to be either above the surrounding land height, or at an absolute height (Above the programme datum - equivalent to Chart datum). The position of fixed lights are defined by their latitude and longitude. There is one general variable, Number which as usual sets the number of lights to be defined. This can be zero, in which case no lights are defined, and nothing further is required in this file. The variable names for each light are:

Long(#) and Lat(#) set the light's position in the usual way. Height(#) sets the height in metres above the water for a 'floating' light or above the ground for a fixed one. If Absolute(#)=1 is set, then the height will be above chart datum.

Red(#), Green(#) and Blue(#) together set the colour of the light, in terms of an RGB colour code, where each takes a value between 0 and 255, with 0 showing none of that colour and 255 being fully bright in that colour. (Tip - use a painting/photo editing programme such as MS Paint to find the RGB values, using the 'Define custom colors' dialog box, accessed in MS Paint by double clicking on the colour selector at the bottom). Range(#) sets the range of the light in nautical miles, within which the light can be seen.

Sequence(#) is set as a text sequence of 'L' and 'D's. The case is not significant. Each character represents a quater of a second of the sequence, and 'L' represents the light being on, and 'D' is off. When the end of the sequence is reached, the sequence restarts. So for example, Sequence(#)="LLLDDDDDD" represents 0.75 seconds where the light is on, followed by 1.5 seconds where it is off, then restarting with 0.75s of light and so on. So for a fixed (constant) light, Sequence(#)="L" is all that is required, and to get a light occulting with 1s of light and 1s of darkness, Sequence(#)="LLLLDDDD" would work. The optional variable PhaseStart(#) sets which 'step' the light starts on, and should be given as an integer between 1 and the length of the sequence. For example, if you want two lights synchronised, you can give them the same sequence and set both to have a PhaseStart(#) of 1.

To allow for sector lights, a light start and end angle are defined by StartAngle(#) and EndAngle(#). The light is visible between the StartAngle(#) bearing and EndAngle(#), going clockwise. Therefore, StartAngle(#)=0 and EndAngle(#)=90 would show a light shining between North and East, as seen on a chart or from above the light. For an all round light, StartAngle(#)=0 and EndAngle(#)=360 should be used. The EndAngle(#) value must be greater than the StartAngle(#). Therefore, angles can be defined in the range 0-720, so a light shining northwards and visible 20 degrees on either side would be defined by a StartAngle(#) of 340 and an EndAngle(#) of 380.

Example light.ini
Number=2

Buoy(1)=2
Height(1)=8
Red(1)=0
Green(1)=255
Blue(1)=0
Range(1)=20
Sequence(1)="lldddd"
StartAngle(1)=45
EndAngle(1)=315

Long(2)=50.2
Lat(2)=-34.6
Height(2)=3
Red(2)=255
Green(2)=0
Blue(2)=0
Range(2)=20
Sequence(2)="lllldd"
StartAngle(2)=0
EndAngle(2)=360
tide.ini

Bridge Command defines the tide in terms of it's harmonic constituents, which each have an amplitude, speed and offset. This means that any tide of any complexity can be modelled. Currently there is only one set of tidal characteristics, which apply across all of the environment model. The amplitude is set in metres, and is half the range of the component. The speed is set in degrees/hour, where one full period is 360 degrees. So for example, the main component of a tide, which has approximately two highs and two lows in a 25 hour period would have a speed of around 28.8 degrees/hour. The offset is how much the tidal component is shifted in degrees, relative to a component that had a peak at 0000 on the morning of the 1st January 1970 (used as Bridge Command's time reference point).

Harmonic 0 sets the constant part of the tide, and all other components set the time-varying parts, which have a mean height of zero.

There is one general variable, and there are 3 variables for each harmonic. The global variable is Harmonics, which defines the number of harmonic components modelled. Then for # = 0 to Harmonics, more three more variables must be set, which are:

Example tide.ini:

Harmonics=4

Amplitude(0)=3.40480

Amplitude(1)=1.68500
Offset(1)=319.23
Speed(1)=28.984104

Amplitude(2)=0.60460
Offset(2)=206.87
Speed(2)=30.000000

Amplitude(3)=0.31850
Offset(3)=408.04
Speed(3)=28.439730

Amplitude(4)=0.17370
Offset(4)=411.51
Speed(4)=30.082137

tidalstream.ini

This is an optional file, and defines the tidal stream by specifying the speed and direction at one or more positions, at each hour before and after high tide.

There are three general variables, number to set the number of locations where the tidal stream will be defined, then MeanRangeSprings and MeanRangeNeaps specifying the mean tidal range at springs and neaps. These are used to calculate how to interpolate between the neaps and springs speeds.

For each location where the tidal stream is specified, the speed and direction must be given for each hour from 6 hours before high tide to 6 hours after high tide. For each hour, the direction of tidal flow is defined with Direction (the direction the tide is flowing to), and the speed (in knots) is defined for springs with SpeedS and neaps with SpeedN.

Example tidalstream.ini:

Number=2
MeanRangeSprings=5
MeanRangeNeaps=2

Long(1)=-9.9688
Lat(1)=50.0091

SpeedN(1,-6)=0.1
SpeedN(1,-5)=0.5
SpeedN(1,-4)=1
SpeedN(1,-3)=1.5
SpeedN(1,-2)=1
SpeedN(1,-1)=0.15
SpeedN(1,0)=0.1
SpeedN(1,1)=0.2
SpeedN(1,2)=1.2
SpeedN(1,3)=1.5
SpeedN(1,4)=1
SpeedN(1,5)=0.6
SpeedN(1,6)=0.2

SpeedS(1,-6)=0.2
SpeedS(1,-5)=1.1
SpeedS(1,-4)=2.0
SpeedS(1,-3)=2.8
SpeedS(1,-2)=2
SpeedS(1,-1)=0.35
SpeedS(1,0)=0.12
SpeedS(1,1)=0.43
SpeedS(1,2)=3.0
SpeedS(1,3)=4.0
SpeedS(1,4)=2.8
SpeedS(1,5)=2
SpeedS(1,6)=0.5

Direction(1,-6)=300
Direction(1,-5)=330
Direction(1,-4)=340
Direction(1,-3)=350
Direction(1,-2)=340
Direction(1,-1)=330
Direction(1,0)=260
Direction(1,1)=190
Direction(1,2)=180
Direction(1,3)=170
Direction(1,4)=180
Direction(1,5)=190
Direction(1,6)=260

Long(2)=-9.9701
Lat(2)=50.0113

SpeedN(2,-6)=0.1
SpeedN(2,-5)=0.5
SpeedN(2,-4)=1
SpeedN(2,-3)=1.5
SpeedN(2,-2)=1
SpeedN(2,-1)=0.15
SpeedN(2,0)=0.1
SpeedN(2,1)=0.2
SpeedN(2,2)=1.2
SpeedN(2,3)=1.5
SpeedN(2,4)=1
SpeedN(2,5)=0.6
SpeedN(2,6)=0.2

SpeedS(2,-6)=0.2
SpeedS(2,-5)=1.1
SpeedS(2,-4)=2.0
SpeedS(2,-3)=2.8
SpeedS(2,-2)=2
SpeedS(2,-1)=0.35
SpeedS(2,0)=0.12
SpeedS(2,1)=0.43
SpeedS(2,2)=3.0
SpeedS(2,3)=4.0
SpeedS(2,4)=2.8
SpeedS(2,5)=2
SpeedS(2,6)=0.5

Direction(2,-6)=300
Direction(2,-5)=330
Direction(2,-4)=340
Direction(2,-3)=350
Direction(2,-2)=340
Direction(2,-1)=330
Direction(2,0)=260
Direction(2,1)=190
Direction(2,2)=180
Direction(2,3)=170
Direction(2,4)=180
Direction(2,5)=190
Direction(2,6)=260

Conclusion

If you have any questions, please ask the author - send me an email, or ask on the Forum