Bridge Command - World file format

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

Introduction:

The world model is comprised of a minimum of 7 files residing in a common folder. Of these, there are at least 3 image files, and there are 5 plain text files. The folder name is used when loading the world model, and is found under World in the Bridge Command 4.7 root folder. For example, if Bridge Command 4.7 is installed in C:\Program files\Bridge Command 4.7GPL, the files making up a world model called Atlantis would be in C:\Program files\Bridge Command 4.7GPL\World\Atlantis.

The key component in a world model is a 'terrain', which represents the topography and bathymetry of the area modelled. To this, individual features are added, such as buoys, landmarks, navigation lights etc.

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. The programme will prioritise the highest numbered terrain when taking depth soundings, and to decide if the ship is aground.

Each terrain is loaded from two image 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 value taken is from the red channel of an RGB (ie. standard colour) image, or the value of a greyscale image. Black is low and white is high.

The terrain generated from the height map is coloured with a texture image of the same dimensions as the heightmap, and then the additional features are loaded into the world as configured in the 5 text files.

Additionally, another image of the same dimensions as the primary heightmap is defined for the background for the radar screen, and is used to give the impression of a radar 'echo' from the landscape in the radar screen.

The files:

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

Plain text:

Images:

For the primary terrain, 3 image files are specified in terrain.ini, and 2 for each subsequent terrain. The filenames are as specified in terrain.ini, and can be in bmp, png or jpeg format. The images required for all terrains are the heightmap image and texture image. For the primary terrain, a radar image is also required. Images must be square, and have a width and height of 2^n, where n is a positive integer (ie. 2,4...128,256,512,1024,2048...)

File details:

Terrain.ini

Contains 2 general variables, and a set of 9 variables for each terrain defined. The global variables are Number and RadarImage. Number is set to an integer value of 1 or greater, and is the number of terrain areas to be defined in the next section of the file. RadarImage is set to the filename of the radar image. This must be enclosed in double quotation marks (eg. RadarImage="radar.jpg" would be acceptable).

The nine variables for each terrain are

Note that the # character should be replaced by the terrain number in question, starting with 1 for the primary terrain. HeightMap(#)takes the filename of the heightmap image file, as a text string. Texture(#) is the same, but takes the filename of the texture image. The remaining variables are numerical. TerrainLong(#) takes the longitude of the south west corner of the terrain area, TerrainLat(#) takes the latitude of this point. These are both in decimal degrees, with North and East as positive (the convention in Bridge Command 4.0. TerrainLongExtent(#) and TerrainLatExtent(#) take the extent of the terrain in decimal degrees in the East-West and North-South directions respectively. TerrainMaxHeight(#) takes the height in metres represented by a pure white pixel on the heightmap image. SeaMaxDepth(#) is equivalent, and takes the depth of sea in metres represented by a pure black pixel. Both are with respect to the same horizontal datum, and both should be positive values. TerrainHeightMapSize(#) takes the image size in pixels of the height/texture maps (which should be the same, and must both be square images). The image size must be a power of two (2,4...128,256,512,1024,2048...).

Example Terrain.ini, setting up one (primary) terrain:
Number=1

RadarImage="radar.bmp"
HeightMap(1)="height.bmp"
Texture(1)="texture.bmp"
TerrainLong(1)=-123.00
TerrainLat(1)=37.333
TerrainLongExtent(1)=1
TerrainLatExtent(1)=1
TerrainMaxHeight(1)=786
SeaMaxDepth(1)=882
TerrainHeightMapSize(1)=1024
Buoy.ini

Contains 1 general variable, and a set of 3 or 4 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 (By default C:\Program files\Bridge Command 4.7GPL. 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 optional variable is RCS, which sets the buoy's radar cross section in metres squared. If not set, a default value will be used.

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. The first three variables for each object, Type(#), Long(#) and Lat(#) are defined as for buoys, except that the available land objects are located in the LandObject folder under Models in the Bridge Command 4.7 root folder. The additional two variables, Rotation(#) and HeightCorrection(#) allow for the model to be rotated about its vertical axis, and moved up or down. If the optional setting Absolute(#) is set as 1, then the object will be loaded at a height relative to chart datum, not relative to the local ground level. Rotation(#) is specified in degrees. An anticlockwise rotation, as viewed from the top, is positive. HeightCorrection(#) allows for a model to be moved up or down, so it sits properly on the land. A positive HeightCorrection(#) moves the object upwards, and is in metres.

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, and there are 11 variables for each light defined. The global variable is 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. The last variable is Floating(#),

The last variable is Floating(#), which should be set to 1 if the light should maintain its height above the water (if it is a buoy's light for example), and to 0 if it should be at the defined hight relative to the land at its position.

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

RadarReflector.ini

This is an optional file, which specifies fixed radar reflectors in the environment. For example, if you have a lighthouse in the sea, if you do not add a radar reflector at its location, it will not appear on the radar picture. It is also used to add RACONs to buoys.

There is one general variable, and there are two or three variables for each radar reflector defined. The global variable is Number, which as usual sets the number of radar reflectors to be defined. This can be zero, in which case no radar reflectors are defined, and nothing further is required in this file. The variable names for each reflector are:

Long(#) and Lat(#) set the reflector's position in the usual way. Instead of Long(#) and Lat(#), Buoy(#) may be defined, which links the reflector to the buoy chosen. So setting Buoy(#)=4 would place the radar reflector on buoy 4, as defined in Buoy.ini. In general, this option will be used with the RACON option, to add a RACON to a buoy. If the RACON option is specified, this should be one or two letters, giving the RACON code, which will be shown in morse code on the radar display. RCS is an optional variable, which sets the reflector's effective radar cross section in metres squared. If not set, a default value of 5 will be used.

Example RadarReflector.ini
Number=2

Buoy(1)=2
Height(1)=3
RACON(1)="B"

Long(2)=50.2
Lat(2)=-34.6
Height(2)=5
RCS(2)=2
Description.ini

This is optional, and is the simplest file, just a plain text file of up to 12 lines in which you can describe the world area. This is displayed when the user is selecting which world model to load. This file is not strictly required, but useful if you want to put in some information for the user. Each line should be a maximum of 57 characters for all of the content to be visible.

Thumb.bmp

This is optional, and is a thumbnail image that will be displayed to the user when selecting the world model.

Conclusion

If you have any questions, please ask the author - send me an email.

James Packer - 19th March 2009