1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
|
<html>
<head>
<style type="text/css">
.fragment {
font-family: monospace
}
PRE.fragment {
border: 1px solid #CCCCCC;
background-color: #f5f5f5;
margin-top: 4px;
margin-bottom: 4px;
margin-left: 2px;
margin-right: 8px;
padding-left: 6px;
padding-right: 6px;
padding-top: 4px;
padding-bottom: 4px;
}
</style>
</head>
<body>
<h1>Airplane parameters in xml, airplane model version 2</h1>
<p>
Also see <a href="heli01.html">helicopter model, version 1</a>.
</p>
<h2>0 About this document</h2>
<p>
This document is not complete yet. It may be inaccurate or wrong, too.
</p>
<p>
This document should not provide examples. Please take a look at the files
you got when downloading/installing CRRCSim.
At the time of this writing only <tt>superzagi.xml</tt> uses more features than other files.
</p>
<p>
You need to know basics about xml files: they are structured text. Whitespace and line breaks do not
matter in most places. Just take a look at the examples and you will understand.
</p>
<p>
The files can be edited using a text editor. There are lots of them. Use something like notepad, vi,
emacs, joe...
</p>
<h3>0.1 Changes</h3>
<table border="1">
<tr><td>24.08.2008</td><td>J. W. Wulf</td>
<td>
More detailed section 2, 'Units'. AR explained. Updated CD_prof
description.
</td>
</tr>
<tr><td>25.08.2008</td><td>J. W. Wulf</td>
<td>
Example for section <tt>CG</tt>.
</td>
</tr>
<tr><td>17.09.2008</td><td>J. W. Wulf</td>
<td>
Added spoiler and flaps section.
</td>
</tr>
<tr><td>17.09.2008</td><td>J. Reucker</td>
<td>
Explained 3D node attributes.
</td>
</tr>
<tr><td>06.10.2008</td><td>Bob Parks</td>
<td>
More detailed explanations to some parameters.
</td>
</tr>
<tr><td>17.12.2009</td><td>J. Reucker</td>
<td>
Added retract section.
</td>
</tr>
<tr><td>23.12.2009</td><td>J. Reucker</td>
<td>
Added max_force attribute to spring section.
</td>
</tr>
<tr><td>27.11.2011</td><td>L. Gasparini</td>
<td>
Modified flap and spoiler section.
</td>
</tr>
<tr><td>29.12.2012</td><td>L. Gasparini</td>
<td>
Further modified flap and spoiler section.
</td>
</tr>
</table>
<h2>1 General information</h2>
</p>
The first part of the file should be quite easy to understand. It contains a
description of the model and a changelog.
Whenever you edit such a file, please add a new <tt>change</tt> section and fill
in what is needed. The example below shows a template.
</p>
<div class="fragment"><pre class="fragment">
<?xml version="1.0" encoding="iso-8859-1" ?>
<CRRCSim_airplane version="2">
<description>
<en>
This plane has been automatically converted from superzagi.air.
Please update this text if you know more about it.
</en>
</description>
<changelog>
<change>
<date>Unknown</date>
<author>CRRCSim 0.9.5</author>
<en>Automatically converted from .air file.</en>
</change>
<change>
<date>Please write date.</date>
<author>Please write your name and email.</author>
<en>Please write down what you changed.</en>
</change>
</changelog>
</pre></div>
</p>
Every text is written in english, so it is enclosed in <tt><en> </en></tt>.
If you want to add something in italian for example, you should enclosed it in <tt><it> </it></tt>.
</p>
<h2>2 Units</h2>
<p>
Some sections have an attribute <tt>units</tt>, which tells which units are used for the values in that section.
The tables below have a column named 'unit' if the unit is fixed,
otherwise they have columns like 'units=0' and 'units=1'.
</p>
<p>
For example, the section <tt>aero</tt> has attribute <tt>units</tt>. Its
documentation below tells you that you can set this attribute to '0' or
'1', which lets CRRCSim expect a value with the unit indicated by just
that table column.
</p>
<p>
There is a file called non_SI_units.txt in the CRRCSim distribution which explains some strange units.
</p>
<p>
Some parameters (especially aerodynamic coefficients) are without
dimension, so their unit is just '1' (not to be confused with 'units=0'
or 'units=1'!).
</p>
<p>
Some parameters (like filenames) of course can't be said to have a unit,
so their table entry is '-'.
</p>
<h2>3 Aerodynamics: section <tt>aero</tt></h2>
<p>
This section can stand on its own, but can also be a subsection of
<tt>config</tt>.
</p>
<h3>3.1 Subsection <tt>ref</tt></h3>
<p>
The following table explains attributes in that subsection.
</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>chord</td>
<td>reference chord</td>
<td>ft</td>
<td>m</td></tr>
<tr><td>span</td>
<td>reference span</td>
<td>ft</td>
<td>m</td></tr>
<tr><td>area</td>
<td>reference area</td>
<td>ft^2</td>
<td>m^2</td></tr>
<tr><td>speed</td>
<td>Reference speed for Re-scaling of CD_prof (speed at which
drag is <tt>aero.drag.CD_prof</tt>).</td>
<td>ft/s</td>
<td>m/s</td></tr>
</table>
<h3>3.2 Subsection <tt>misc</tt></h3>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>Alpha_0</td>
<td>baseline alpha<br>
This is the reference angle of attack (alpha) where a lot of parameters
are defined. It can be anything you want, but you have to be
consistent. Common references would be the center line of the body, the
mean camber line of the wing root airfoil or the bottom of a flat bottom
airfoil. If you are doing analysis in AVL, its probably easiest to make
this zero in the coordinates you use for the AVL model definition. In
the AVL Stability Derivative output (ST command), this is labeled "Alpha".
</td>
<td>rad</td>
<td>rad</td></tr>
<tr><td>eta_loc</td>
<td>eta_loc for stall model</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CG_arm</td>
<td>CG_arm for stall model, see below.</td>
<td>1</td>
<td>1</td></tr>
<tr><td>span_eff</td>
<td>span efficiency: Effective span, 0.95 for most planes, 0.85
flying wing.<br>
This is a measure of how well the wing is working. As mentioned, .95 is
a good value for a conventional, aft tail airplane. Some flying wings
are essentially using the outer wing as a surrogate for the horizontal
tail, so the number is lower. For a canard, it could also be low. AVL
does a good job of estimating this parameter. In the Stability
Derivative output dump, it is the parameter "e". This parameter will
vary with angle of attack and stability margin, particularly if the wing
has twist. For a glider, pick a case at relatively high CL, like near
the best glide ratio angle of attack, or near minimum sink. This
parameter only has a weak effect on the handling, so get it sort of
close and dont worry about it. (it is a big effect on efficiency).
Note that AVL tends to slightly over estimate this parameter, so you
might want to multiply the AVL value by .95 or so.
</td>
<td>1</td>
<td>1</td></tr>
</table>
<h4>3.2.1 <tt>CG_arm</tt></h4>
<p>
Email from Mark Drela, 10.01.2006:
</p>
<p>
The stall model computes the values (dCL_left, dCL_cent, dCL_right)
which represent the changes in CL due to stall.<br>
To get the stall effect on the Cm, these are multiplied
by the length CG_arm, which is the distance between
the CG and the effective point of application of dCL:<br>
dCm_stall = (0.25*dCL_left + 0.5*dCL_cent + 0.25*dCL_right)*CG_arm;
</p>
<p>
The typical value CG_arm = 0.25 means that the point of application
of the averaged dCL is 0.25*chord ahead of the CG.
</p>
<p>
This CG_arm can be deduced from airfoil data.
If dCL and dCm are the changes due to stall,
the implied CG_arm is<br>
CG_arm = dCm/dCL<br>
Typically, both dCm and dCL will be negative, so CG_arm is positive.
</p>
<p>
You can also adjust CG_arm to get a realistic simulator
pitch response due to stall. The larger CG_arm is, the more
pitch-down you will get during stall.
</p>
<h3>3.3 Subsection <tt>m</tt></h3>
<p>
These parameters deal with pitching moment, or how the airplane rotates
about the pitch axis (up or down elevator). The actual value would be
foot-pounds or Newton-meters. What we have here are coeffients, that do
not have dimensions, so we can apply them to airplanes of similar
configuration, but different sizes, airspeeds and air densities.
</p>
<p>
To take one of these coefficients and convert it to the actual moment we
would use the equation:<br>
M= 1/2 * rho * velocity^2 * wing area * wing chord * Cm
</p>
The first terms, "1/2 * rho * velocity^2" are what is called dynamic pressure, or
the ram pressure of the air. (hold your hand out a car window to feel
this!). "rho" is density of air. The moment is also proportional to the wing area (i.e. what the
pressure works on) and the chord of the wing (which is the moment arm).
The area and chord are called "reference parameters". Usually they are
the actual area and the actual mean chord of the wing, but they could
actually be any area or length, as long as you are consistent. In AVL,
these values are actually inputs to the program. What counts is that
you be consistent. They are listed in the ST dump as Sref (area) and
Cref (chord). In this file, they are <tt>aero.ref.area</tt> and
<tt>aero.ref.chord</tt>.
</p>
<p>
Note that the yaw and roll deriviatvies use the wing span as the
reference length instead of the chord. That is Bref in the AVL output
and <tt>aero.ref.span</tt> in this file.
</p>
<p>
There are several terms that add up to the total pitching moment.
</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>Cm_0</td>
<td>baseline Cm at angle_of_attack = <tt>aero.misc.Alpha_0</tt>.<br>
This is whatever the Cm is at the reference angle of attack. It
can be varied by the airfoil, the neutral setting of the elevator, twist
in the wing etc. In the AVL ST output dump, it is called "Cmtot"
</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cm_a</td>
<td>pitch-moment / alpha (pitch stability).<br>Basically,
Cm = <tt>aero.m.Cm_0</tt> + <tt>aero.m.Cm_a</tt>*(Alpha - <tt>aero.misc.Alpha_0</tt>)<br>
This is the change in pitching moment due to changes in alpha
(angle of attack). For a stable plane, this is negative, meaning if the
angle of attack increases, there is a nose down pitching moment. It is
the slope of the CM vs alpha curve, as measured near the reference angle
of attack.<br>
In the AVL ST output, this is in the "stability axis derivatives"
section, y mom row, alpha column, labeled Cma.
</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cm_q</td>
<td>pitch-moment / pitch-rate (pitch damping)<br>
q is the "non dimensional pitch rate" of the airplane.
Basically, it is related to the loop diameter divided the wing chord.
It is the pitch damping effect. Think of the tail as a long paddle
swinging through the air. The faster you rotate it, the more moment it
makes, and the moment tries to stop the rotation. For normal planes it
is mostly proportional to the tail area times the SQUARE of the moment
arm. The force varies as the tangental speed of the tail in the
rotation, and that is the angular rate times the moment arm. We take
the force, and multiply it by the moment arm to get the
pitching moment.<br>
In the AVL ST output this one is in the "pitch rate q'" column, in the
y mom. Cm row, and labeled Cmq. Its normally negative. i.e. a rotation
rate causes a moment to try to stop it.
</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cm_de</td>
<td>pitch-moment / elevator<br>
Cm delta elevator. This is the elevator sensitivity, or how much
pitching moment do you get for a unit deflection of the elevator (delta
e is "change in elevator"). The way elevator is defined (trailing edge
down is positive deflection) we want this to be negative. i.e. trailing
edge up gives a nose up moment. You need to have defined an elevator in
AVL before it will tell you what this parameter is, but the label on it
in the ST output depends on the order you defined control surfaces, so
its hard to give an example. It will be in the last block of outputs in
the ST file, the column should be labeled elevator, or whatever you
called that control in the AVL setup. The row will be "y mom Cm". If
elevator was the second control defined, it would be labeled "Cmd2"
</td>
<td>1</td>
<td>1</td></tr>
</table>
<h3>3.4 Subsection <tt>lift</tt></h3>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>CL_0</td>
<td>baseline CL at angle_of_attack = <tt>aero.misc.Alpha_0</tt></td>
<td>1</td>
<td>1</td></tr>
<tr><td>CL_max</td>
<td>positive stall limit</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CL_min</td>
<td>negative stall limit</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CL_a</td>
<td>lift slope; lift-force / alpha, round about 2 pi / (1 +
2/AR). AR=wingspan/(average chord).<br>Basically,
CL = <tt>aero.lift.CL_0</tt> + <tt>aero.lift.CL_a</tt>*(Alpha - <tt>aero.misc.Alpha_0</tt>)</td></td>
<td>1</td>
<td>1</td></tr>
<tr><td>CL_q</td>
<td>lift-force / pitch-rate</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CL_de</td>
<td>lift-force / elevator</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CL_drop</td>
<td>CL drop during stall break</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CL_CD0</td>
<td>CL at minimum profile CD: 0.30 for 7037, 0.15 MH32, 0.0 RG15, AGxx, power</td>
<td>1</td>
<td>1</td></tr>
</table>
<h3>3.5 Subsection <tt>drag</tt></h3>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>CD_prof</td>
<td>profile CD at <tt>aero.ref.speed</tt></td>
<td>1</td>
<td>1</td></tr>
<tr><td>Uexp_CD</td>
<td>CD Re-scaling exponent; scales profile CD with Reynolds number via simple power law</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CD_stall</td>
<td>drag coeff. during stalling</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CD_CLsq</td>
<td>d(CD)/d(CL^2), curvature of parabolic profile polar: 0.01 composites, 0.015 saggy ships, 0.02 beat up ship</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CD_AIsq</td>
<td>drag due to aileron deflection. d(CD)/d(aileron^2) , curvature of ail. CD influence: 0.01/(max_aileron)^2</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CD_ELsq</td>
<td>drag due to elevon deflection. d(CD)/d(elevator^2), curvature of ele. CD influence: 0.01/(max_elevator)^2 for Zagi otherwise 0</td>
<td>1</td>
<td>1</td></tr>
</table>
<h3>3.6 Subsection <tt>Y</tt></h3>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>CY_b</td>
<td>side-force / sideslip</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CY_p</td>
<td>side-force / roll-rate</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CY_r</td>
<td>side-force / yaw-rate</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CY_dr</td>
<td>side-force / rudder</td>
<td>1</td>
<td>1</td></tr>
<tr><td>CY_da</td>
<td>side-force / aileron</td>
<td>1</td>
<td>1</td></tr>
</table>
<h3>3.7 Subsection <tt>l</tt></h3>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>Cl_b</td>
<td>roll-moment / sideslip (crucial for rudder-only turns)</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cl_p</td>
<td>roll-moment / roll-rate (roll damping)</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cl_r</td>
<td>roll-moment / yaw-rate</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cl_dr</td>
<td>roll-moment / rudder</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cl_da</td>
<td>roll-moment / aileron</td>
<td>1</td>
<td>1</td></tr>
</table>
<h3>3.8 Subsection <tt>n</tt></h3>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>Cn_b</td>
<td>yaw-moment / sideslip (yaw stability)</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cn_p</td>
<td>yaw-moment / roll-rate (yaw-roll coupling)</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cn_r</td>
<td>yaw-moment / yaw-rate (yaw damping)</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cn_dr</td>
<td>yaw-moment / rudder</td>
<td>1</td>
<td>1</td></tr>
<tr><td>Cn_da</td>
<td>yaw-moment / aileron</td>
<td>1</td>
<td>1</td></tr>
</table>
<h3>3.9 Subsection <tt>flaps</tt></h3>
<p>
Lift, drag and moment coefficients are altered
when using flaps. For an example, see <tt>Skorpion.xml</tt> and <tt>Wasabi.xml</tt>.
</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>drag</td>
<td>How much drag is added when using flaps? <br>
CD = CD_without_flaps + (flap_input^2) * <tt>flap.drag</tt></td>
<td>1</td>
<td>1</td></tr>
<tr><td>lift</td>
<td>How much lift is added when using flaps? <br>
CL = CL_without_flaps + flap_input * <tt>flap.lift</tt></td>
<td>1</td>
<td>1</td></tr>
<tr><td>moment</td>
<td>How much moment is added when using flaps? <br>
Cm = Cm_without_flaps + flap_input * <tt>flap.moment</tt></td>
<td>1</td>
<td>1</td></tr>
<tr><td>eff_ratio</td>
<td>How much of the initial flap effectiveness (lift/drag/moment derivative)
is retained at the maximum deflection angle (flap_input=0.5) ? <br>
Flap effectiveness usually decreases for large deflections (> 10-20deg), e.g.
when flap are also used as landing aids (cfr. Wasabi model).
This non-linear behaviour can be simulated setting <tt>flap.eff_ratio</tt> < 1. <br>
Reasonable values of <tt>flap.eff_ratio</tt> range from 0.5 down to 0.1 for
maximum deflection from 30 to 60deg. <br>
The actual effectiveness is evaluated as:
flap.lift(@flap_input) = flap.lift * (1. - (1. - <tt>flap.eff_ratio</tt>)) * flap_input
and similarly for drag and moment. <br>
</td>
<td>1</td>
<td>1</td></tr>
</table>
<p>
Usually changing flap setting change pitching moment and thus alter
the trimmed angle of attack (AoA), so that elevator position must be adjusted
(trimmed) to either keep the angle of attack unchanged or to trim to the new desired
AoA. If you set <tt>flap.moment</tt> = 0, then the trimmed AoA will stay
constant.
</p>
<p>
Flap (camber changing flap) can also be used "mixed" with elevator, so that an elevator
input also generate a flap deflection to optimize airfoil camber for the desired lift
coefficient (e.g. flaps are lowered when elevator is pulled).
To achieve this effect the elevator should be mixed into flap input: the right amount of
mixing is model dependent.
</p>
<h3>3.10 Subsection <tt>spoiler</tt></h3>
<p>
This is similar to <tt>flap</tt>, except that the drag effect is linear not quadratic and
that there is no eff_ratio parameter (spoiler effect is linear).
</p>
<h3>3.11 Subsection <tt>retract</tt></h3>
<p>
This subsection describes how a retractable gear influences drag and lift
(similar to a spoiler). For an example, see <tt>sport.xml</tt>.
</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>drag</td>
<td>How much drag is added when the gear is not fully retracted? <br>
CD = CD_without_gear + (1.0 - retract_input) * <tt>retract.drag</tt></td>
<td>1</td>
<td>1</td></tr>
<tr><td>lift</td>
<td>How does the gear influence lift? <br>
CL = CL_without_gear + (1.0 - retract_input) * <tt>retract.lift</tt></td>
<td>1</td>
<td>1</td></tr>
</table>
<p>
Please note that <tt>retract.lift</tt> is usually a negative coefficient, because the
gear will disturb the airflow when it is not fully retracted and the wheel wells
are open.
</p>
<h3>3.12 Subsection <tt>prop</tt></h3>
<p>
This subsection describes model-dependant interaction effects between propeller
and aerodynamics. For an example, see <tt>Angel_S30E.xml</tt>.
</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>torquefactor</td>
<td>Which fraction of propeller's torque actually produce a rolling moment ? <br>
roll_torque = prop_torque * <tt>prop.torquefactor</tt></td>
<td>1</td>
<td>1</td></tr>
</table>
<p>
Please note that <tt>prop.torquefactor</tt> shall be a coefficient < 1 (default to 0.25),
because propeller's slipstream produces an aerodynamic rolling moment counteracting torque effect.
Changing the sign of <tt>prop.torquefactor</tt> to negative change the net rolling effect from rolling left
to rolling right, i.e. simulating a counterclockwise rotating propeller (seen from the cockpit).
</p>
<h2>4 Configuration: section <tt>config</tt></h2>
<p>
There can be more than one configuration for an airplane, so there may be several
<tt>config</tt> sections. Because of this, each <tt>config</tt> needs a description.
</p>
<div class="fragment"><pre class="fragment">
<config version="1">
<descr_long>
<en> Powerful motor which makes this config heavy, too.</en>
</descr_long>
<descr_short>
<en>powerful and heavy</en>
</descr_short>
</pre></div>
<p>
Additionally, instead of using the general <tt>aero</tt> section,
a <tt>config</tt> section can contain its own <tt>aero</tt>
section (see k2.xml for an example).
</p>
<h3>4.1 Subsection <tt>mass_inertia</tt></h3>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>Mass</td>
<td>Mass of airplane</td>
<td>slug</td>
<td>kg</td></tr>
<tr><td>I_xx</td>
<td></td>
<td>slug ft^2</td>
<td>kg m^2</td></tr>
<tr><td>I_yy</td>
<td></td>
<td>slug ft^2</td>
<td>kg m^2</td></tr>
<tr><td>I_zz</td>
<td></td>
<td>slug ft^2</td>
<td>kg m^2</td></tr>
<tr><td>I_xz</td>
<td></td>
<td>slug ft^2</td>
<td>kg m^2</td></tr>
</table>
<h3>4.2 Subsection <tt>sound</tt></h3>
<p>
The <tt>sound</tt> subsection contains the description of the sound
samples used for this airplane. Each sample is described in a
<tt>sample</tt> subsubsection.
</p>
<h4>4.2.1 Subsubsection <tt>sample</tt></h4>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>filename</td>
<td>name of file for engine sound</td>
<td>-</td>
<td>-</td></tr>
<tr><td>type</td>
<td>Type of sound: 0 glow engine, 1 electric engine, 2 glider sound</td>
<td>-</td>
<td>-</td></tr>
<tr><td>pitchfactor</td>
<td>This number converts from speed of propeller to pitch of engine sound.</td>
<td>s</td>
<td>s</td></tr>
<tr><td>maxvolume</td>
<td>The maximum sample volume (0.0 ... 1.0). The loudest sample should
be set to 1.0.</td>
<td>1</td>
<td>1</td></tr>
<tr><td>v_min</td>
<td>Only for type=2: minimal velocity (relative to the airplane's
"neutral" velocity) at which the sound can be heard</td>
<td>1</td>
<td>1</td></tr>
<tr><td>v_max</td>
<td>Only for type=2: velocity (relative to the airplane's
"neutral" velocity) at which the sound reaches
maximum volume.</td>
<td>1</td>
<td>1</td></tr>
<tr><td>dist_max</td>
<td>Only for type=2: distance at which the sound reaches the
minimum volume</td>
<td>ft</td>
<td>m</td></tr>
</table>
<h3>4.3 Subsection <tt>power</tt></h3>
<p>
There is a separate documentation
(<a href=../power_propulsion/power_propulsion.html><tt>../power_propulsionspower_propulsion.html</tt></a>)
which explains the power and propulsion system.
</p>
<h2>5 Graphics: section <tt>graphics</tt></h2>
<h3>5.1 Specifying a 3D model file</h3>
<p>
This section binds one or more 3D models to an XML file. The 3D model is what you actually
see on screen when loading this model XML file.
There can be more than one graphical representation for an airplane (e.g. for
different configurations or different finishs), so there may be several
<tt>graphics</tt> sections. Because of this, each <tt>graphics</tt> needs a description.
</p>
<div class="fragment"><pre class="fragment">
<graphics version="1" model="zagi.ac" >
<descr_long>
<en>Automatically converted from superzagi.air.</en>
</descr_long>
<descr_short>
<en>default</en>
</descr_short>
</pre></div>
<p>
Currently you only need to specify the name of the graphics file.
</p>
<h3>5.2 A word on 3D model files</h3>
<p>The PLIB library used in CRRCsim to display the airplane model graphics can
handle a lot of different file types. However, files in AC3D format (.ac) or
3DStudioMax format (.3ds) seem to work best. Any decent modelling tool should
be able to export at least one of these formats. AC3D, Blender and Wings3D have
been reported to work fine for creating CRRCsim models.</p>
<h3>5.3 Object names in 3D files</h3>
<p>3D modelling tools usually compose the whole <i>model</i> (the content of the
3D model file) from <i>objects</i>. An object is a group of <i>surfaces</i> (or <i>faces</i>
for short) defined by connected <i>vertices</i> (a vertex is a single point in
3D space).</p>
<p>On object level, a modelling tool usually allows the user to define arbitrary
names for single objects. These names provide better orientation while modelling.
In CRRCsim, object names are also used to manipulate objects in several ways, like
animating model parts or controlling the rendering process. Therefore the following
conventions have been defined:</p>
<ul>
<li>The object name assigned to a model part in a 3D modelling tool may
contain blanks (space characters). However, CRRCsim only uses everything
up to the first blank as the object's real name. If you assign the name
"Right wing" to an object, CRRCsim will internally refer to this
object as "Right". Therefore it is recommended to substitute blanks
by underscore characters ("Right_wing") or use CamelCase notation
("RightWing").</li>
<li>The rest of an object's name (everything after the first blank character)
is treated as additional information ("attributes")for the 3D
rendering process. An object with the name "Rotor_disc -shadow"
is internally referred to as "Rotor_disc", and the attribute
"-shadow" tells the 3D engine not to render a shadow for this
part of the model.</li>
</ul>
<h3>5.4 Object attributes</h3>
<p>
The following rendering attributes (see the preceding section) are currently
defined for 3D objects:
</p>
<table border="1">
<tr><th>Attribute</th>
<th>Description</th></tr>
<tr><td>-shadow</td>
<td>This object shall not cast a shadow.</td></tr>
</table>
<h2>6 Hard points and wheels: section <tt>wheels</tt></h2>
<p>
This section contains a number of entries, each of them describing one hard
point on the airplane. The caster angle is specified with respect to the
plane body's z-axis, a value of zero means that the wheel is oriented straight
ahead (which should be the case for most gears).
</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>percent_brake</td>
<td>Percentage of max braking applied initially</td>
<td>1</td>
<td>1</td></tr>
<tr><td>caster_angle_rad</td>
<td>wheel angle</td>
<td>rad</td>
<td>rad</td></tr>
</table>
<h3>6.1 Subsection <tt>pos</tt></h3>
<p>Position of hard point in body axes with regard to center of gravity.
Unit is feet (<tt>units="0"</tt>) or meters (<tt>units="1"</tt>).
x positive forward, y positive right, z positive down.</p>
<p>Remark: 3D modelling tools sometimes use other coordinate system
orientations. In this case the coordinates of a hard point have to
be converted into the CRRCsim coordinate system. Here's an example
for AC3D and Blender:</p>
<table border="1">
<tr>
<th>Axis in XML file</th>
<th>Axis in AC3D</th>
<th>Axis in Blender</th>
</tr>
<tr><td align="center">+X</td><td align="center">+Z</td><td align="center">-Y</td></tr>
<tr><td align="center">+Y</td><td align="center">-X</td><td align="center">-X</td></tr>
<tr><td align="center">+Z</td><td align="center">-Y</td><td align="center">-Z</td></tr>
</table>
<p>This means that a point in AC3D at X = -3.28, Y = 0.55, Z = -0.37
(this could be the right wingtip of a 2m sailplane) will result in the
following position tag:</p>
<div class="fragment"><pre class="fragment">
<pos x="-0.37" y="3.28" z="-0.55" />
</pre></div>
<p>Hardpoints may be located on animated control surfaces (e.g. on a
retractable gear). In this case, specify an additional attribute
"animation" that contains the name of the control surface
animation that controls this part of the 3D model. Example (from
sport.xml):</p>
<div class="fragment"><pre class="fragment">
<pos x="0.41677001" y="0" z="0.52499998" animation="nose_gear" />
</pre></div>
<p>In this case, the <animations> section of the file should of course
contain an element <object name="nose_gear" /> that defines
the actual movement. See section 8 for more details on animations.</p>
<h3>6.2 Subsection <tt>spring</tt></h3>
<p>This subsection defines the springiness of the hardpoint, e.g. if
a collision of this hardpoint with ground makes the plane bounce, is
damped by the hardpoint's flexibility or leads to a crash.</p>
<p>The flight dynamics model calculates the forces on each hardpoint
resulting from interaction with the ground or solid objects. If this
value exceeds the specified <tt>max_force</tt>, the plane will be
considered as crashed. The <tt>max_force</tt> attribute is optional;
if it is not specified, it will internally be set to a very high
default value so that this hardpoint will only cause a crash on
insanely high load.</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>constant</td>
<td>spring constant, has to be positive</td>
<td>slug / s^2 = lbf / ft</td>
<td>N/m</td></tr>
<tr><td>damping</td>
<td>damping, has to be positive</td>
<td>slug / s = lbf / (ft/s)</td>
<td>N/(m/s)</td></tr>
<tr><td>max_force</td>
<td>maximum force, has to be positive</td>
<td>lbf</td>
<td>N</td></tr>
</table>
<h3>6.3 Subsection <tt>steering</tt></h3>
<p>In this subsection a mapping of the hardpoint to an R/C channel can
be defined. Possible values for the "mapping" parameter are "NOTHING"
(which makes this subsection redundant), "RUDDER", "AILERON"
or "ELEVATOR". By specifying a negative value for max_angle the
coupling from the control input to the wheel will be reversed. A positive
angle should be correct for a tail wheel while a steerable nose wheel usually
needs a negative angle.</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>units=0</th>
<th>units=1</th></tr>
<tr><td>mapping</td>
<td>symbolic name of the R/C channel</td>
<td>-</td>
<td>-</td></tr>
<tr><td>max_angle</td>
<td>deflection of the wheel at full control input</td>
<td>rad</td>
<td>rad</td></tr>
</table>
<p>Example: this maps a nose wheel to the rudder channel, giving
20 degrees (= 0.349 radians) of wheel deflection at full rudder input.</p>
<div class="fragment"><pre class="fragment">
<steering mapping="RUDDER" max_angle="-0.349" />
</pre></div>
<h2>7 Center of gravity: section <tt>CG</tt></h2>
<p>
Position of center of gravity in body axes with regard to coordinates used by
<tt>wheels</tt> and the 3D graphics file.<br>
Unit is feet (<tt>units="0"</tt>) or meters (<tt>units="1"</tt>).
x positive forward, y positive right, z positive down. Example:
<div class="fragment"><pre class="fragment">
<CG units="0" x="-0.2234252" y="0" z="-0.043131893" />
</pre></div>
</p>
<p>
This section and values do not have to exist, it is optional.
However, it gives you the following advantage:
There is no need to create the 3D model (and the points in the <tt>wheels</tt> section)
around the center of gravity. You can use any reference
point and give the position of the CG using your coordinates in this section.
</p>
<p>
This also makes it possible to change the location of the CG without changing the 3D model and
<tt>wheels</tt>.
</p>
<p>
You can visually check the position of the CG using test mode, as the airplane rotates
around the center of gravity (given that throttle=0).
</p>
<h2>8 Animated parts: section <tt>animations</tt></h2>
<p>This section contains information needed to animate parts of
the model, e.g. to move the control surfaces according to stick
input. It is optional to define animations for a model; however
it is strongly recommended to make use of this feature because
it adds much to the appearance of a model.</p>
<p>To animate a part of a 3D model it is required that this part
is modelled as an independent object in the 3D model file, and
that the object has a unique name. A proper 3D modelling tool
should allow one to group surfaces to objects and give them names,
so this shouldn't be a problem.</p>
<p>The <tt><animations></tt> section contains one
<tt><animation></tt> subsection per animated object. The
<tt><animation></tt> tag must contain a <tt>type</tt>
attribute to define the kind of animation that should be created.
Currently only the type <tt>ControlSurface</tt> is implemented.</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>unit</th></tr>
<tr><td>type</td>
<td>kind of animation</td>
<td>-</td></tr>
</table>
<h3>8.1 Animation type <tt>ControlSurface</tt></h3>
<p>This kind of animation is used to rotate an object of the 3D model
around an arbitrary axis according to stick input. It can be used to
animate control surfaces like elevator or ailerons, or to animate
gears that retract with a rotational movement.</p>
<h4>8.1.1 Subsection <tt>object</tt></h4>
<p>This subsection defines the object to which the animation
is applied and the maximum amount of movement.</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>unit</th></tr>
<tr><td>name</td>
<td>name of the object in the 3D model</td>
<td>-</td></tr>
<tr><td>max_angle</td>
<td>control surface deflection at full control input</td>
<td>rad</td></tr>
</table>
<h4>8.1.2 Subsection <tt>control</tt></h4>
<p>This subsection defines how the surface interacts with the
input from the controller. <tt>mapping</tt> can be set to one
of <tt>RUDDER</tt>, <tt>ELEVATOR</tt>, <tt>AILERON</tt>,
<tt>THROTTLE</tt>, <tt>FLAP</tt>, <tt>SPOILER</tt>, <tt>RETRACT</tt>
or <tt>PITCH</tt>. There can be more than one <tt>control</tt>
section for a surface, e.g. there will be a mapping to
<tt>ELEVATOR</tt> and <tt>AILERON</tt> if the model has elevon
controls (aka "delta-mix"). The <tt>gain</tt> setting
determines the relationship of the control input to the
surface deflection. A <tt>gain</tt> value of <tt>1.0</tt> means
that the surface will travel the full <tt>max_angle</tt> from
the <tt>object</tt> section above if the associated control
is moved to its extents. Negative <tt>gain</tt> values will
reverse the surface movement.</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>unit</th></tr>
<tr><td>mapping</td>
<td>symbolic name of the R/C channel</td>
<td>-</td></tr>
<tr><td>gain</td>
<td>control surface deflection at full control input</td>
<td>-</td></tr>
</table>
<h4>8.1.3 Subsection <tt>hinge</tt></h4>
<p>To define the rotation axis of the control surface it is
mandatory to define exactly two <tt><hinge></tt> subsections.
The rotation will occur around an imaginary axis from the
first to the second hinge, and the direction of the rotation can
be determined by applying the right-hand rule to this axis.
The X/Y/Z values are kind of unit-less ("OpenGL"-units).
They can be determined by selecting a vertex close to the hinge
point in the 3D modelling tool and then transforming the
displayed vertex coordinates into the coordinate system
described below (same as with the <tt><wheel></tt>
positions described above).</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>unit</th></tr>
<tr><td>x</td>
<td>X coordinate (positive forward)</td>
<td>-</td></tr>
<tr><td>y</td>
<td>Y coordinate (positive right)</td>
<td>-</td></tr>
<tr><td>z</td>
<td>Z coordinate (positive down)</td>
<td>-</td></tr>
</table>
<p>This is an example for the animation of left and right
aileron on an 1.6m aerobatics model, giving
20 degrees (= 0.349 radians) of control surface deflection at full
aileron input, assuming that the aileron objects of the
3D model are called <tt>ail_right</tt> and <tt>ail_left</tt>:</p>
<div class="fragment"><pre class="fragment">
<animations>
<animation type="ControlSurface">
<object name="ail_right" max_angle="0.349" />
<control mapping="AILERON" gain="-1.0" />
<hinge x="-0.56" y="0.63" z="0.03" />
<hinge x="-2.64" y="0.40" z="0.02" />
</animation>
<animation type="ControlSurface">
<object name="ail_left" max_angle="0.349" />
<control mapping="AILERON" gain="-1.0" />
<hinge x="0.56" y="0.63" z="0.03" />
<hinge x="2.64" y="0.40" z="0.02" />
</animation>
</animations>
</pre></div>
<h2>9 Launch presets: section <tt>launch</tt></h2>
<p>This section is optional. It contains launch presets that will
be shown in the launch dialog of the GUI if this airplane is
currently selected. The <launch> section shall only contain
<preset> tags, each one containing the attributes that
describe the launch process like in CRRCsim's main configuration file.</p>
<table border="1">
<tr><th>Name</th>
<th>Description</th>
<th>unit</th></tr>
<tr><td>name_en</td>
<td>name of the preset for the GUI dialog</td>
<td>-</td></tr>
<tr><td>altitude</td>
<td>launch altitude above ground</td>
<td>ft</td></tr>
<tr><td>velocity_rel</td>
<td>velocity relative to the trimmed flight velocity</td>
<td>-</td></tr>
<tr><td>angle</td>
<td>launch angle (+ means "nose up")</td>
<td>rad</td></tr>
<tr><td>sal</td>
<td>simulate side-arm-launch (0: no, 1: yes)</td>
<td>-</td></tr>
<tr><td>rel_to_player</td>
<td>use launch position which is relative to player (0: no, 1: yes)</td>
<td>-</td></tr>
<tr><td>rel_front</td>
<td>launch position relative to player: forward distance (backwards negative)</td>
<td>foot</td></tr>
<tr><td>rel_right</td>
<td>launch position relative to player: distance to the right (left negative)</td>
<td>foot</td></tr>
</table>
<p>Example:</p>
<div class="fragment"><pre class="fragment">
<launch>
<preset name_en="Gap65 default (ground)" altitude="0" velocity_rel="0" angle="0.22" sal="0"
rel_to_player="1" rel_front="1" rel_right="-2" />
</launch>
</pre></div>
</body>
</html>
|
