CSM Simulator scenery and model visual data file structures

The following is information to accompany release 10 of the CSM 
simulator, and is intended for those who wish to experiment with 
customising the airfields and helicopter visuals within the 
simulator. 

HELICOPTER VISUALS
IF YOU WISH TO PRODUCE CUSTOM HELICOPTER VISUALS FOR YOUR SIMULATOR 
PLEASE CONTACT CSM AS, BY THE TIME YOU READ THIS, WE SHOULD BE ABLE 
TO MAKE THIS JOB QUITE A BIT EASIER. We will be happy to provide 
(free of charge) a utility and data files to help in their 
production together with the latest information regarding these 
files. The information provided here should be considered as an 
introduction only. 

CSM can be contacted by E-MAIL at:
    	CSM_LTD@COMPUSERVE.COM
or by post
	CSM ltd
	8 Littlebrook Close
	Hadfield
	Glossop
	Derbyshire
	SK13 2AW

Helicopter visuals are defined by sets of files as follows:-
HELIVIS.HBV	(the Vertex data)
HELIVIS.HBF	(the Facet data)
HELIVIS.COF	(the Colour option data)

(For a given helicopter visual HELIVIS is a common filename e.g. 
'MYHELI')

THE .HBV FILE
This file defines a set of points in space. These points make the 
ends of line, corners of surfaces etc. that go to make up the shape 
of the helicopter. The reference point is the centre of gravity of 
the model and relative to this point there are three directions. 
The three directions  are as follows:-
The "x" direction is forward along the horizontal fore/aft axis of 
the helicopter.
The "y" direction is rightwards along a horizontal axis.
The "z" axis is vertically DOWNWARDS. (don't blame us, this fits in 
with the normal convention for aircraft dynamics!)

Since the simulator scales the visual helicopter to fit the rotor 
diameter specified in the 'Dimensions' menu you can use any length 
units you like so long as you are consistent. (We use centimetres)

A typical .HBV file looks like this:

My Pod and boom Vertices data
  63  {Rotor Radius}
 -17  {Height of hub centre}
  n    x        y        z
  11   -13      2       -3
  12   -8       2       -8
  13    4       2       -8
  14    5       4       -6
  15    23      3       -1
  16    32      3        5
  17    35      1        8
  18    32      3        10
  19    19      5        13
  20    -5      6        13
  21    -13     2        1

etc, etc,

The first line is for your own reference but must not be omitted.

The second line is the rotor radius in your chosen units (e.g 
inches)

The third line is the height of the main rotor hub (i.e. the centre 
of the rotor disk RELATIVE TO THE CENTRE OF GRAVITY. Remember that 
the C of G is your reference point for the whole heli visual(the 
centre of our co-ordinate axes)

The fourth line (the column header) is for humans! but must not be 
omitted. 
From line 5 onwards the columns of numbers are as follows:-

The first (n) column entry holds the reference number for a point 
(vertex) This is the number by which the vertex is referred when it 
is used by a line or surface in the .HBF file. Note that (for 
reasons to do with the drawing of the rotor disk) reference numbers  
start at 11.

The second (x) column entry is the horizontal distance of this 
point AHEAD of the C of G.

The third (y) column entry is the horizontal distance of this point 
to the RIGHT of the C of G.

The fourth (z) column entry is the Vertical distance of this point 
BELOW the C of G.


THE .HBF FILE
This defines what lines, triangular and rectangular surfaces (in 
this case all called 'facets') are used to make up the helicopter.

A typical .HBF file looks like this:-

Basic Pod & boom heli
No. Cors. I1 I2  I3  I4   ColOpt
1   4     14 11  12  13   1       RH rear upper fus
2   3     11 14  22  0    9       RH behind canopy (up)
3   3     11 22  21  0    9       RH behind canopy  (lower)
4   3     21 22  20  0    1       RH rear side
5   4     19 20  22  23   1       RH side
6   4     19 23  16  18   1       RH cheek
7   3     16 17  18  0    8       RH nose
8   3     16 23  15  0    2       RH canopy (front)
9   4     23 22  14  15   2       RH canopy (back)
10  4     32 31  34  33   1       LH rear upper fus
11  3     31 42  34  31   9       LH behind canopy (up)
12  3     41 42  31  0    9       LH behind canopy (lower)
13  3     41 40  42  0    1       LH rear side
14  4     40 39  43  42   1       LH side

etc, etc

The first line is the description that appears on the 'Helicopter 
visuals' menu.

The second line is a column header that must not be omitted.

From Line 3 onwards the columns are as follows:-

The first (No.) column entry
A reference number for the 'facet'

The second (Cors.) column entry
This is the number of corners (vertices) used to draw the facet so 
it is :-
    	2 for a line.
	3 for a triangular surface.
	4 for a rectangular surface.

The I1 to I4 column entries.
The next four columns (I1 to I4) give the reference numbers for the 
points (vertices) that are the ends (of the line) or corners (of 
the surface). These are the same reference numbers as used in for 
the points in the .HBV file. For a line the two unused reference 
numbers (I3 and I4) are set to zero. For a triangle I4 is zero.

THE ORDER IN WHICH THE CORNERS ARE LISTED IS IMPORTANT. YOU SHOULD 
LIST THE POINTS CLOCKWISE AROUND THE FACET AS THE FACET IS SEEN 
FROM THE "OUTSIDE". To see the significance of the "Inside" and 
"Outside" of the facet see the description of the .COF (colour 
option file)

The colour option (ColOpt.) column entry
The final column is the number of the colour option to be used in 
drawing the facet. (See the description of the .COF file)

THE .COF (Colour Option) FILE
A typical .COF for the helicopter visuals looks like this:-

Pod and Boom Colour Options
N  MnOut   MnIn
1   1       3           (Fus main*)
2   2       3           (canopy screen)
3   4       4           (side frames)
4   8       0           (Drive belt)
5   4       4           (Cooling duct)
6   1       1           (tp,fin main colour*)
7   5       5           (tp,fin flashes*)
8   6       0           (boom)
9   7       0           (boom steady)
10  10      0           (mast)
11  4       4           (swashplate)
12  8       0           (pipe)
13  9       9           (Undercarriage legs)
14  10      10          (skids)

The First (description )line and the column header are for 
reference only but must not be omitted. From line three onwards the 
columns are as follows:-

The first (N) column entry
This is the reference number for the colour option and is the 
number used in the ColOpt. column of the .HBF file.

The MnOut column entry
This is the number (1 to 10) of the palette colour to be used to 
draw the OUTSIDE FACE of a facet using this colour option.

The MnIn column entry
This is the number (1 to 10) of the palette colour to be used to 
draw the INSIDE FACE of a facet using this colour option.

NOTE: If MnOut or MnIn is set to 0 (zero) then that side of the 
facet is not drawn. For example, MnIn is set to zero to save time 
in drawing closed surfaces (completely closed bodies) by not 
drawing the inside surface. 


THE .RGB (Red Green Blue palette) DATA
This data is now stored in the helicopter set-up files (.HSD files 
in the HLIB folder) This allows each helicopter to have a distinct 
colour scheme. Separate RGB data for 'Day' and 'Night' fields is 
provided allowing each helicopter to have a distinct night lighting 
scheme. The RGB data sets the 10 basic colours from which the 
simulator produces the shaded colours with which the helicopter is 
drawn.

Airfield Data 
Introduction
Each airfield is defined by a 'field file' (with a .FLD file 
extension to its name). A .FLD file contains the list of objects 
making up the field, with their location/orientation information. 
It also states if the field is a 'Day' or a 'Night' field.
Associated with each .FLD file are other files with the same name 
as the field file but with different extensions. They are:

1) A Pilot Position Information file (.PPI extension) 
This holds the data regarding the pilots four viewpoints and is 
handled automatically by the simulator. If a field is found not to 
have a .PPI file one will be created for it.

2) A Ground Colour Palette File (with a .GCP file extension)
This defines the 12 shaded colours with which the airfield objects 
are drawn. These shaded colours are adjusted by the Airfield 
colours menu in the simulator and saved back to the .GCP file of 
the airfield currently in use. This .GCP file also defines 12 fixed 
non-shaded  'spot' colours that may also be used in drawing the 
airfield. The 12 spot colours are not adjustable by the Airfield 
palette menu in the simulator but may be pre-defined when the .GCP 
file is first set up.

3) A Ground Colour Options file (with a .GCP extension)
This file holds additional information on how the colours are to be 
used when objects are drawn. In most situations this file will 
probably not need to be modified.

HOW TO MAKE YOUR OWN AIRFIELD
a) Start by simply copying all the files of one of the existing 
fields. So, for example, if you want to make a field called 
"myfield" 
In the CSM10 folder make a copy of 'FIELD1.FLD' and call it 
'MYFIELD.FLD'
In the CSM10 folder make a copy of 'FIELD1.GCP' and call it 
'MYFIELD.GCP'
In the CSM10 folder make a copy of 'FIELD1.GCO' and call it 
'MYFIELD.GCO'
In the CSM10 folder make a copy of 'FIELD1.PPI' and call it 
'MYFIELD.PPI'

Use a text editor such as 'NotePad' to open the 'MFIELD.FLD' file.
Edit the first line to give the field a new description on the 
'select airfield' menu. So, for example change 'Standard day field 
(Field 1)' to read, say, 'My custom airfield (myfield)'

You can make a night field simply by changing the next line to read 
'Night' rather than 'Day'

Now save 'MYFIELD.FLD' file. If you are using a word processor for 
your editing make sure that you save it as a text file and NOT as a 
word processor file!

If at this point you now fly the simulator you will find your field 
has been added to the airfield list (and is of course exactly like 
the field you originally copied! - but its a start!!)

To modify the field further you will need to understand the 
structure of the files a little more.

THE STRUCTURE OF THE AIRFIELD FILES

THE PALETTE DATA
Each field has an associated palette file. So, for example, the 
field defined by "FIELD1.FLD" takes its palette data from a file 
called "FIELD1.GCP"  Since the simulator includes the means of 
adjustment of the ground colours this information is included for 
completeness only.

A typical .GCP file is as follows:-

Field 1 Ground RGB data 	
No.    Red(0-63)  Green(0-63)  Blue(0-63)
 1     30             20             10
 2     55              0              0
 3     55             20              0
 4     55             55              0
 5      7             30              7
 6     10             25             55
 7     25              5             30
 8     15             15             15
 9     61             61             61
10     15             18              5
11      3             18             15
12     40             40             40
13     20             14              7
14     60              0              0
15     60             35              0
16     55             55              0
17      0             60              0
18      0              0             60
19     15              0             45
20     20             20             20
21     63             63             63
22      0              0              0
23      0             25              0
24     30             60             30

The first two lines of header are for human use and are ignored by 
the simulator. The following 24 lines break down into two sets of 
12. Lines 1 to 12 define the "shaded" colours as set up by the 
"Adjust Ground Colour" menu in the simulator. Grading of these 
colours to account for lighting is automatic. The entries from 13 
to 24 provide 12 non-shaded colours that may also be used in 
drawing the field. They are of use for example for lights on night 
fields as such lights will not shade with the direction of the 
moonlight! Unless you want to use 'special' spot colours this file 
can usually left as it is.

COLOUR OPTIONS
Each field has an associated COLOUR OPTION file. For example, 
FIELD1.FLD has its colour options stored in a file called 
"FIELD1.GCO"
A typical .GCO file looks like this:-

Field1 ground Colour Options file
N   Graded   MnOut   MnIn
1     1       1       1   (graded brown)
2     1       2       2   (graded red)
3     1       3       3   (graded orange)
4     1       4       4   (graded yellow)
5     1       5       5   (graded green)
6     1       6       6   (graded blue)
7     1       7       7   (graded violet)
8     1       8       8   (graded grey)
9     1       9       9   (graded white)
10    1       10      10  (graded yellow/green)
11    1       11      11  (graded blue/green)
12    1       12      12  (graded light grey)
13    1       1       0   (single sided graded brown)
14    1       2       0   (                    red)
15    1       3       0   (                    orange)
16    1       4       0   (                    yellow)
17    1       5       0   (                    green)
18    1       6       0   (                    blue)
19    1       7       0   (                    violet)
20    1       8       0   (                    grey)
21    1       9       0   (                    white)
22    1       10      0   (                    yellow/green)
23    1       11      0   (                    blue/green)
24    1       12      0   (                    light grey)
25    0       1       1   (spot brown)
26    0       2       2   (spot red)
27    0       3       3   (spot orange)
28    0       4       4   (spot yellow)
29    0       5       5   (spot green)
30    0       6       6   (spot blue)
31    0       7       7   (spot violet)
32    0       8       8   (spot grey)
33    0       9       9   (spot white)
34    0       10      10  (spot black}
35    0       11      11  (spot dk. green)
36    0       12      12  (spot lt. green)
37    1       4       1   (Yellow out,brown in)

The first column is the reference number of the colour option. The 
"Shaded" column is set to 1 if the colours in the option are to be 
taken from the 12 shaded colours and set to 0 if the colours are to 
be taken from the 12 'spot' colours. the "MnOut" column is the 
reference number for the colour on the outside surface of an object 
drawn with this colour option while the "MnIn" column is the 
reference number for the colour on the inside surface of the object 
drawn with this option. The comments in brackets are for human 
reference only and are ignored by the simulator. Note that for 
closed buildings etc drawing time can be saved by ignoring the 
inside surfaces. If the MnIn of an option is set to zero then a 
wall using that colour option will not be drawn if the "inside" 
face of the wall faces the viewpoint. In the above colour option 
file example entries 1 to 12 are options that give objects the same 
graded colours on both sides. Options 13 to 24 are single sided 
shaded options for drawing closed buildings etc. The options from 
25 to 36 will render objects in double sided non-shaded (spot) 
colours. Entry 37 is for the tunnel walls giving different inside 
and outside colours for the tunnel.


HOW GROUND FEATURES ARE DEFINED

Each feature (e.g. a runway, building, mast, etc.) has its shape 
defined using information held in two files. So, for example, the 
shape of the masts used in the simulator is defined by the two 
files 'MAST.VTX' and 'MAST.GRF'. Vertex (or co-ordinate)information 
defining where, say, corners or points are located is stored in the 
vertex file (with a .VTX file extension). How the vertices are 
linked by lines or surfaces is defined by the ground feature file 
(with a .GRF file extension). 


Structure of the Vertex files (.VTX)
Entries contain the following information.
A reference number, k,  (this number is used by the accompanying 
.GRF file to refer to the points)
N - northern ordinate of the point with respect to reference point
E - Eastern ordinate of the point with respect to reference point
D - Vertical ordinate of point with respect to reference point 
(NOTE:  up is NEGATIVE)
The reference point can be any convenient point such as the centre 
of the feature at ground level.

Structure of the Ground Feature Files (.GRF)These files specify a 
feature (hut, runway etc.) usually made up of several components 
(one per line). 
Components are either:-
1.  'Mats' on the ground or other objects (like high clouds, 
distant 
mountains etc.) behind which the aircraft can't fly and into which 
it can't 
crash.
or
2. 'Walls' that are overlap with other walls and behind which the 
aircraft 
can fly. The aircraft can also crash into 'walls'

For the best use of computer performance 'mats' should be used 
where possible.

Each line of the file defines one component and for each component 
specifies:-

a) The component reference number (human reference only)

b) Component Type:
			1= a 'mat'
			2= a 'wall'

c) number of corners (4 max.)
d-g) Four vertex reference numbers for the component. 	These 
identify 
which vertices in the 						
		accompanying .VTX file are used to draw this 	
						component.

h) The colour option to be used to draw this object (see the colour 
option 
(.cof) file description)

'Mat' components will be draw in the order listed so components 
overlying other components should be listed after the component 
they cover. For correct views in follow mode mats should only be 
used for objects flat on the ground. 
Walls are ordered at run time and therefore cover other components 
as required.

HOW THE FIELD LAYOUT IS DEFINED

A field layout is defined by a 'Field' file (with a .FLD file 
extension). Multiple copies of any feature defined by .GRF and .VTX 
file pairs can be used and located anywhere on the field. The 
simulator looks for all .FLD files present in the simulator 
directory and makes these available on the 'select airfield' menu.

A typical .FLD file looks like this:-

FIELD 1 (standard)
Day
INFO in the form:- item file name (CR)
North,East,and Vert. Loc. (space sep)(CR), then rotation
mount1
  8500.0  1300.0     0.0
  0
mount1
  7000.0   600.0     0.0
  0
mount1
  5500.0  -100.0     0.0
  0
runway
   -30.0     0.0     0.0
 90

The  first line of the file is a description of the field that 
appears on the field menu. 
The second line defines if the field is a "Day" or "Night" field. 
(Note this line must be added to a V9 field for it to be used in 
V10)
This is followed by two information lines that are skipped over by 
the simulator. Thus, the feature entries start at line 5 of the 
file. 

Feature Entries in the field file Starting with the fifth line the 
file lists the features that make up the flying field. Each feature 
is  specified using three lines in the file as follows:-

First line of a feature entry:  Name of object file (there must 
always be a .VTX and a .GRF file of this name in the simulator 
directory)

Second line of a feature entry:  The N, E, and D offsets of feature 
reference point from the field centre
Third line of a feature entry:  The rotation (in degrees) of the 
object

Example
runway
50	25	0
90	

this will put down a runway 50 metres north and 25 metres east of 
the field centre and at ground level. It will be rotated 90 degrees 
so it points east/west (the normal direction of the runway is 
north/south)

remember that the vertical co-ordinate system in the simulator uses 
negative values for height so to set an object  5 meters above the 
ground the 'D' value is -5. 

'Mat' type objects are drawn in the order listed so if you wish to 
have several mountains overlapping put the most distant one in the 
..FLD file first followed by the next most distant one etc.

To get an idea of the file structures of .VTX and .GRF files look 
at a simple example such a 'smallbox.vtx' and 'smallbox.grf' that 
define a 1.2 metre square on the ground (used to put the squares in 
the helicopter FAI area).  Experiment with the values given by say 
changing the positions of the points in the .VTX file. Then try 
adding the diagonal lines by adding extra entries to the .GRF file.

Note:
When editing the files do not leave blank lines in the file or at 
the end of the file as this may cause a file reading error.
In creating your own objects make sure your files have the same two 
line headers as those supplied with the simulator.

