-
Notifications
You must be signed in to change notification settings - Fork 1
/
Tacview Core Interface.txt
1783 lines (1106 loc) · 66.6 KB
/
Tacview Core Interface.txt
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
--------------------------------------------------------------------------------------------------------------------------------
Tacview 1.9.0 Lua Core Interface
Last update: 2022-12-05
--------------------------------------------------------------------------------------------------------------------------------
Tacview will automatically load any Lua script named "main.lua" found in the immediate sub-folders of:
C:\Program Files (x86)\Tacview\AddOns\
%ProgramData%\Tacview\AddOns\
%APPDATA%\Tacview\AddOns\
For example you could store your addon main script as:
%ProgramData%\Tacview\AddOns\My add-on\main.lua
At the beginning of your script you will typically retrieve the available Lua interface for which your add-on has been programmed:
Tacview = require("Tacview187") -- Request Tacview 1.8.7 API
Then you can access any of the following methods like the following:
Tacview.Log.Info("Successfully exported ", objectCount, " object(s)")
Depending on the context your script is executed in, you will have access to slightly different interfaces.
Your main.lua script will be executed in the main context. It will be granted access to all Tacview features but export and import interfaces.
While your import and export scripts will be granted access to the core features as well as respectively import or export interfaces.
To prevent multithreading issues as well as errors breaking other add-ons, each Lua add-on is loaded in its own virtual machine.
--------------------------------------------------------------------------------------------------------------------------------
Global functions
Close() -- Tacview 1.7.2
Unconditionally closes the application.
NOTE: This function does not ask the user to save his work.
--------------------------------------------------------------------------------------------------------------------------------
Settings
This interface is provided to access Tacview configuration.
If you want to save and load settings for your own addon, see AddOns.Current.Settings
Settings.SetBoolean( settingPath, newBooleanValue ) -- Tacview 1.7.2
Save a Boolean setting under the given name.
settingPath can be one of the following:
"UI.View.Grid.Visible" -- Enable/disable latitude/longitude grid
"UI.View.HUD.Visible" -- Enable/disable cockpit head-up-display
"UI.View.Overlay.Visible" -- Enable/disable all the informations displayed on top of the 3D view
"UI.View.Camera.Dogfight.Enabled" -- Enable/disable dogfight camera mode (when in external view)
"UI.View.Objects.Height.Visible" -- Enable/disable lines between the ground and each 3D object
"UI.View.Objects.LocalVectors.Visible" -- Enable/disable local vector lines for the selected objects (Heading+Course+LiftVector+PilotLineOfSight)
"UI.View.Objects.Heading.Visible" -- Enable/disable heading line for the selected objects
"UI.View.Objects.Course.Visible" -- Enable/disable course line for the selected objects
"UI.View.Objects.LiftVector.Visible" -- Enable/disable lift vector line for the selected objects
"UI.View.Objects.PilotLineOfSight.Visible" -- Enable/disable pilot line of sight for the selected objects
"UI.View.Objects.Labels.Visible" -- Enable/disable objects labels in the 3D view
Settings.GetBoolean( settingFullPath ) -- Tacview 1.7.2
Returns the current setting value or nil if the provided path does not point to a boolean setting.
See Settings.SetBoolean for the possible values of settingFullPath.
Return value:
Corresponding setting boolean value.
Settings.SetNumber( settingFullPath , newNumberValue ) -- Tacview 1.8.6
Save a number setting under the given name.
settingFullPath and newNumberValue can be one of the following:
"UI.View.HUD.Scale" = 1.0 -- Change the scale of the HUD in the 3D view
Settings.GetNumber( settingFullPath ) -- Tacview 1.8.6
Returns the current setting value or nil if the provided path does not point to a number setting.
See Settings.SetNumber for the possible values of settingFullPath.
Return value:
Corresponding setting number value.
Settings.SetString( settingFullPath , newStringValue ) -- Tacview 1.7.2
Save a string setting under the given name.
settingFullPath and newStringValue can be one of the following:
"UI.View.Terrain.Mode" -- Change the way the terrain is displayed in the 3D view
"Empty"
"Flat"
"3D"
"Full3D"
"UI.View.Camera.Mode" -- Change camera mode
"Cockpit"
"External"
"Satellite"
"Free"
"UI.View.Camera.Dogfight.Mode" -- Change dogfight camera mode (active only when "UI.View.Camera.Mode" == "External" and "UI.View.Camera.Dogfight.Enabled" == true)
"Centered"
"LookAt"
"LookForward"
Settings.GetString( settingFullPath ) -- Tacview 1.7.2
Returns the current setting value or nil if the provided path does not point to a string setting.
See Settings.SetString for the possible values of settingFullPath.
Return value:
Corresponding setting string value.
Settings.GetAltitudeUnit() -- Tacview 1.8.5
Retrieve the current unit of measure selected by the user to represent altitude.
Return value:
one of Settings.Unit
Settings.Units -- Tacview 1.8.5
Unit of measurement. Typically based on user preferences, to display output values on screen.
To simplify programing and avoid bugs, it is strongly recommended to use metric system units only
for calculations as well as file input and output.
You should convert to/from user preferences only during UI input/output operations.
Settings.Units.Meters
Settings.Units.Feet
--------------------------------------------------------------------------------------------------------------------------------
AddOns
The add-ons interface is mainly used to specify information about your add-on.
Your addon settings will be saved and restored at the next session of Tacview.
AddOns.Current.GetPath() -- Tacview 1.7.4
Retrieve the current addon root path.
This is typically where your addon dll or lua file is stored.
This function is useful to access and load your custom resources without hardcoding a path to them.
Return value:
AddOn path (e.g. "C:\ProgramData\Tacview\AddOns\Tutorial 1 - Hello World - CS\")
or nil if not applicable (typically for lua code injected over a pipe)
AddOns.Current.SetTitle( addOnTitle ) -- Tacview 1.7.2
Defines a user friendly-name in place of the folder name which is displayed by default in Tacview UI.
AddOns.Current.SetVersion( textVersionNumber ) -- Tacview 1.7.2
It is recommended to declare the version of your add-on using this function.
That way, it will be easier for the end-user to know if it's time to download an updated version of it.
AddOns.Current.SetAuthor( authorName ) -- Tacview 1.7.2
Let everyone who is the author of this brilliant add-on!
AddOns.Current.SetNotes( textNotes ) -- Tacview 1.7.2
Defines a text which will be displayed in Tacview status bar when your addon is selected in the addons menu.
A dedicated window will be available in Tacview 2.
AddOns.Current.Settings.SetBoolean( settingName , newBooleanValue ) -- Tacview 1.7.2
Save a Boolean setting under the given name.
SettingName should be set to a string which unambiguously identify your setting.
SettingName must NOT be equal to "Enabled" which is reserved by Tacview to enable/disable the addon.
AddOns.Current.Settings.GetBoolean( settingName , defaultBooleanValue ) -- Tacview 1.7.2
Returns the current setting value, or the default provided one if no value was previously saved.
Return value:
Corresponding setting boolean value.
AddOns.Current.Settings.SetString( settingName , newTextValue ) -- Tacview 1.8.2
Save a text setting under the given name.
SettingName should be set to a string which unambiguously identify your setting.
SettingName must NOT be equal to "Enabled" which is reserved by Tacview to enable/disable the addon.
AddOns.Current.Settings.GetString( settingName , defaultTextValue ) -- Tacview 1.8.2
Returns the current setting value, or the default provided one if no value was previously saved.
Return value:
Corresponding setting text value.
--------------------------------------------------------------------------------------------------------------------------------
Log
The log module is typically used to log messages and errors which can be used to diagnose specific issues.
All strings sent to the log will also be saved in the %TEMP%\Tacview.log file.
Please, use the log wisely and try to display only meaningful messages to the end-user.
Do not spam the log with internal development messages, this may confuse the user who is looking for more relevant status from other modules.
Log.Debug(...) -- Tacview 1.7.2
Use this method to help you trace and diagnose problems with your addon.
NOTE: Debug information will be displayed only when using the /Debug:On command line argument.
Log.Info(...) -- Tacview 1.7.2
This method can be used to display specific information related to your addon which might be useful to the end-user.
NOTE: Lua print() function is redirected to Log.Info().
Log.Warning(...) -- Tacview 1.7.2
Warnings can be used to notify the user of unusual circumstances like non-critical errors in input data.
Warnings will be highlighted in Tacview console to attract the user attention.
Log.Error(...) -- Tacview 1.7.2
Error messages are typically used to display critical errors which usually prevent further operation.
--------------------------------------------------------------------------------------------------------------------------------
UI.MessageBox
Message boxes can be used to display modal notifications and ask for simple questions to the user.
It is suggested to not use too many message boxes as they are breaking the productivity flow of the user.
Whenever possible, you can use the log to output most of you messages and rely on settings to choose the appropriate behavior depending on the circumstances.
UI.MessageBox.Info( textMessage ) -- Tacview 1.7.2
UI.MessageBox.Error( textMessage ) -- Tacview 1.7.2
Displays a modal notification to inform or warn the user.
UI.MessageBox.Question( textMessage ) -- Tacview 1.7.2
Displays a question and wait for the user to answer either OK or Cancel.
Depending on the OS, any other interaction than clicking OK, such as clocking the dialogbox, will return Cancel.
Return value:
One of the following constants:
UI.MessageBox.OK
UI.MessageBox.Cancel
UI.Format.AltitudeToText( altitudeInMeters ) -- Tacview 1.8.2
Format the given altitude (in meters) in format and units specified by the user.
Use this function to automatically display readable altitude numbers in your UI.
Return value:
Text which represent the altitude in the units currently selected in Tacview options
UI.Format.TextToAltitude( formatedAltitude ) -- Tacview 1.8.2
UI.Format.TextToAltitudeLocalized( formatedAltitude ) -- Tacview 1.8.3
Convert the given text into an altitude in meters.
Use this function to convert user input into an altitude number usable in Tacview telemetry.
This function will automatically recognize suffix such as "ft" or "m" for example
If no prefix is specified,
TextToAltitude will assume the altitude is in meters (appropriate to read data from files)
TextToAltitudeLocalized will assume the altitude is in the user current unit system (appropriate to read data from UI input boxes)
Return value:
Altitude in meters (double float)
or nil if given text cannot be interpreted
UI.Format.DistanceToText( distanceInMeters ) -- Tacview 1.8.2
Format the given distance (in meters) in format and units specified by the user.
Use this function to automatically display readable distance numbers in your UI.
Return value:
Text which represent the distance in the units currently selected in Tacview options
UI.Format.TextToDistance( formatedDistance ) -- Tacview 1.8.2
UI.Format.TextToDistanceLocalized( formatedDistance ) -- Tacview 1.8.3
Convert the given text into a distance in meters.
Use this function to convert user input into a distance number usable in Tacview telemetry.
This function will automatically recognize suffix such as "nm" or "km" for example
If no prefix is specified:
TextToDistance will assume the distance is in meters (appropriate to read data from files)
TextToDistanceLocalized will assume the distance is in the user current unit system (appropriate to read data from UI input boxes)
Return value:
Distance in meters (double float)
or nil if given text cannot be interpreted
UI.Format.SpeedToText( speedInMeters ) -- Tacview 1.8.3
Format the given speed (in meter per second) in format and units specified by the user.
Use this function to automatically display readable speed numbers in your UI.
Return value:
Text which represent the speed in the units currently selected in Tacview options
UI.Format.TextToSpeed( formatedSpeed ) -- Tacview 1.8.3
UI.Format.TextToSpeedLocalized( formatedSpeed ) -- Tacview 1.8.3
Convert the given text into a speed in meter per second.
Use this function to convert user input into a speed number usable in Tacview telemetry.
This function will automatically recognize suffix such as "km/h" or "kts" for example
If no prefix is specified:
TextToSpeed will assume the speed is in meters (appropriate to read data from files)
TextToSpeedLocalized will assume the speed is in the user current unit system (appropriate to read data from UI input boxes)
Return value:
Speed in meter per second (double float)
or nil if given text cannot be interpreted
UI.Format.LongitudeToText( longitudeInRadian ) -- Tacview 1.8.2
UI.Format.LatitudeToText( latitudeInRadian ) -- Tacview 1.8.2
Format the given spherical coordinate (in radian) in format and units specified by the user.
Use this function to automatically display readable latitude or longitude numbers in your UI.
Return value:
Text which represent the latitude or longitude in the units currently selected in Tacview options
UI.Format.TextToSpherical( formatedLongitudeOrLatitude ) -- Tacview 1.8.2
Convert the given text into latitude or longitude in radian.
Use this function to convert user input into an longitude or latitude number usable in Tacview telemetry.
This function will automatically recognize suffix such as "W" or "E" for example
Return value:
Latitude or longitude in radian (double float)
or nil if given text cannot be interpreted
UI.Format.AbsoluteTimeToISOText( absoluteTimeInSeconds [, outputDecimals ] ) -- Tacview 1.8.3
Format the given absolute time (seconds since 1970-01-01) in ISO format.
Use this function to automatically display readable date-time in your UI.
The optional outputDecimals boolean can be set to true if you want sub-second accuracy.
Return value:
Text which represent the absolute time in ISO date format.
UI.Format.TextToAbsoluteTime( dateTimeText ) -- Tacview 1.8.3
Convert the given text into an absolute time.
Use this function to convert user input into a date-time usable in Tacview telemetry.
NOTE: This function currently support only ISO date-time format.
If the provided text contains only time, then this function will attempt to attach it to the current telemetry date range.
Return value:
Absolute time in seconds since 1970-01-01 (double float)
or nil if given text cannot be interpreted
--------------------------------------------------------------------------------------------------------------------------------
SoundPlayer
This module can be used to play sounds so the user can hear feedback about what is going on
without looking at all the telemetry windows.
SoundPlayer.Play( fileName ) -- Tacview 1.8.4
Plays in background the sound specified by the given WAV file name.
Only one sound can be played at a time.
Any new sound will override any currently playing one.
Example:
Tacview.SoundPlayer.Play( Tacview.AddOns.Current.GetPath() .. "minimums.wav" )
SoundPlayer.Stop() -- Tacview 1.8.4
Stops playback of the sound if playback is occurring.
--------------------------------------------------------------------------------------------------------------------------------
String
String.Crc32( text )
Calculate zip compatible CRC-32 of the given text.
Note: The given text is considered as a C string terminated by a \0.
Return value:
32-bit CRC-32 of the given C string
--------------------------------------------------------------------------------------------------------------------------------
Math
This module contains all the necessary tools to convert and modify typical telemetry data.
Here, we are calling vectors, tables with three components:
{
x = number,
y = number,
z = number,
}
Math.Angle.Subtract( angle1 , angle2 ) -- Tacview 1.7.2
Substracts two radian angles.
Return value:
Difference between angle1 and angle2.
The result is normalized to ]-π,+π]
Math.Angle.NormalizePi( angle ) -- Tacview 1.8.5
Returns given angle normalized to ]-π,+π]
Math.Angle.Normalize2Pi( angle ) -- Tacview 1.8.5
Returns given angle normalized to [0,2*π[
Math.Units.FeetToMeters( value ) -- Tacview 1.8.0
Converts feet distances in meters.
Math.Units.MetersToFeet( value ) -- Tacview 1.8.7
Converts meters to feet.
Math.Units.NauticalMilesToMeters( value ) -- Tacview 1.8.0
Converts nautical miles distances in meters
Math.Units.MetersToNauticalMiles( value ) -- Tacview 1.8.7
Converts meters to nautical miles.
Math.Units.KnotsToMetersPerSecond( value ) -- Tacview 1.8.7
Converts knots to meter per second.
Math.Units.MetersPerSecondToKnots( value ) -- Tacview 1.8.7
Converts knots to meter per second.
Math.Vector.LongitudeLatitudeToCartesian( {longitude = radian , latitude = radian , altitude = meter} ) -- Tacview 1.7.2
Converts Earth spherical coordinates into cartesian coordinates.
It is possible to direcly give an object transform to this function (see Telemetry.GetCurrentTransform).
Longitude and latitude are in radian.
Altitude is in meter.
Return value:
A vector which is a the cartesian position in global Earth space.
Math.Vector.CartesianToLongitudeLatitude( {x = number , y = number , z = number} ) -- Tacview 1.7.5
Converts cartesian coordinates into Earth spherical coordinates.
Return value:
A table which contains the { longitude = ... , latitude = ... , altitude = ...}
Longitude and latitude are in radian.
Altitude is in meter.
Math.Vector.BearingRangeAltitudeToLongitudeLatitude( referenceLongitude , referenceLatitude , bearing , range , altitude ) -- Tacview 1.8.0
Retrieve longitude, latitude and altitude relative to given reference point.
- Longitude and latitude are expressed in radian.
- Bearing is expressed in degrees relative to true north.
- Range is expressed in meters.
- Altitude is expressed in meters.
Return value:
Position of the target point as {longitude = number , latitude = number , altitude = number}
Math.Vector.LongitudeLatitudeToBearingRangeAltitude( referenceLongitude , referenceLatitude , referenceAltitude , targetLongitude , targetLatitude , targetAltitude ) -- Tacview 1.8.7
Retrieve BRA of the target point relative to a reference point on earth.
- Longitude and latitude are expressed in radian.
- Altitude is expressed in meters.
The range returned is the true 3D range. If you want a 2D range,
then you can specify identical altitude for both objects (either 0.0 or the average altitude of the two objects).
Return value:
BRA of the target point {bearing = number , range = number , altitude = number}
- Bearing is expressed in radian relative to true north.
- Range is expressed in meters.
- Relative Altitude is expressed in meters.
Math.Vector.Add( vector1 , vector2 ) -- Tacview 1.7.2
Adds two 3D vectors.
Return value:
A vector wich is the sum of vector1 and vector2.
Math.Vector.Subtract( vector1 , vector2 ) -- Tacview 1.7.2
Substracts two 3D vectors.
Return value:
A vector which is the difference between vector1 and vector2.
Math.Vector.Multiply( factor , vector ) -- Tacview 1.7.5
Multiplies a scalar value by a specified vector.
Return value:
Scaled vector.
Math.Vector.Normalize( vector ) -- Tacview 1.7.2
Normalize the given vector.
Return value:
Normalized vector.
This function is safe and a nul vector is the vector is nul.
Math.Vector.GetLength( vector ) -- Tacview 1.8.0
Retrieve the length of given vector.
Math.Vector.GetDistance( pt1 , pt2 ) -- Tacview 1.8.0
Retrieve the distance between given 3D cartesian points.
Math.Vector.GetDistanceBetweenObjects( ObjectTransform1 , ObjectTransform2 ) -- Tacview 1.8.4
Retrieve the distance between two objects.
This function gives the most accurate result,
considering projection errors when – for example – analyzing data from a flight simulator such as DCS World or Falcon.
In that case native coordinates will be used to calculate the distance.
Math.Vector.GetDistanceOnEarth( longitude1 , latitude1 , longitude2 , latitude2 , altitude ) -- Tacview 1.8.0
Retrieve the distance between the specified coordinates on earth at the given above sea level altitude.
longitude1 , latitude1 , longitude2 , latitude2 are all in radian.
altitude is in meters ASL.
Math.Vector.AngleBetween( vector1 , vector2 ) -- Tacview 1.7.2
Calculate the angle between two *normalized* vectors.
DO NOT forget to normalize the vectors before calling GetAngle!
NOTE: If you want an accurate quadran calculation, you may want to use the function with three parameters.
Return value:
Angle in radian between the two given vectors.
Which corresponds to ArcCos( DotProduct( vector1, vector2) )
Math.Vector.AngleBetween( vector , referenceVector1 , referenceVector2 ) -- Tacview 1.7.2
Calculate the angle between using two normalized vectors.
DO NOT forget to normalize the vectors before calling GetAngle!
Unlike AngleBetween( vector1 , vector2 ), this function gives the correct quadran.
Return value:
Angle in radian between the two given vectors.
Which corresponds to ArcTan( DotProduct( vector, referenceVector1 ), DotProduct( vector, referenceVector2 ) )
Math.Vector.LocalToGlobal( objectTransform , localCoordinates ) -- Tacview 1.7.2
Converts the given point from an object local coordinates into Earth cartesian coordinates.
You can direcly pass to this function, the objectTransform table coming from Telemetry.GetCurrentTransform()
Where localCoordinates is a vector.
objectTransform =
{
-- If xyz are not specified, they will be calculated from longitude, latitude, and altitude.
x = cartesianPositionX, -- meters
y = cartesianPositionY, -- meters
z = cartesianPositionZ, -- meters
-- If either longitude or latitude is not specified, they will be calculated from xyz.
longitude = sphericalLongitude, -- radian
latitude = sphericalLatitude, -- radian
altitude = absoluteAltitude, -- (meters) required only if xyz are not specified
roll = objectRoll, -- radian
pitch = objectPitch, -- radian
yaw = objectYaw, -- radian
}
localCoordinates =
{
x = localCartesianPositionX, -- meters
y = localCartesianPositionY, -- meters
z = localCartesianPositionZ, -- meters
}
Return value:
{ x = ... , y = ... , z = ... } -- coordinates as a vector in Earth global cartesian space.
or
returns nil if not enough data is provided.
--------------------------------------------------------------------------------------------------------------------------------
Events
You can register callbacks for different kind of events in Tacview.
Events.DocumentLoaded.RegisterListener( function ) -- Tacview 1.8.2
Tacview will call the given function as soon as a document has been loaded/merged.
This is useful to trigger post load processing, especially to automatize the cleanup of new data.
OnDocumentLoaded( fileNames )
Called right after more telemetry data has been loaded via the File->Load/Merge option.
Called once at the end of a real-time telemetry recording.
fileNames lists the full path of all the files which have just been loaded separated by a vertical bar '|' character.
This file list may be empty if this call is the result of a generic or real-time telemetry update.
Events.DocumentUnload.RegisterListener( function ) -- Tacview 1.8.2
Tacview will call the given function right before unloading the current document.
Because the telemetry data will become invalid right after,
this callback gives the opportunity to your addon to cleanup any data such as object handles.
OnDocumentUnload()
Called right before the telemetry data becomes invalid (purged).
Events.Shutdown.RegisterListener( function ) -- Tacview 1.8.0
Tacview will call the given function as soon as the corresponding add-on is unloaded.
This can be handy to complete operations in progress and to release appropriate external resources.
Note that you do not have to explicitly free Tacview resources (like menus), because this is done for you automatically.
OnShutdown()
Called right before the Lua add-on is unloaded.
--------------------------------------------------------------------------------------------------------------------------------
Context
This contains all the information relative the telemetry representation on screen.
NOTE: See Lua Main Interface for additional functions.
Context.GetAbsoluteTime() -- Tacview 1.7.5
Retrieves the current telemetry time in seconds since 1970-01-01 (this parameter is useful to talk with the Telemetry module)
Context.GetDocumentPath() -- Tacview 1.8.7
Retrieve the full path (directory + file name) of the current document if applicable.
This path could be the name of the last file merged if several documents have been loaded together.
Returns nil if no document has been loaded yet.
--------------------------------------------------------------------------------------------------------------------------------
StaticObjects
StaticObjects.GetObjectHandleByName( objectName ) -- Tacview 1.8.0
Retrieve static object handle from its name.
The name of the object can be defined via the <name> xml tag in kml files.
Names are case sensitive. It is recommended to use unique names.
This function will return the first matching object.
Beware that object handles are volatile and may not be preserved the next time your addon is being called by Tacview.
Return value:
handle of the static object
or nil of no object correspond to the given name
StaticObjects.SetVisible( staticObjectHandle , isVisible ) -- Tacview 1.8.0
Show or hide given object.
You can use StaticObjects.GetHandleByName() to retrieve the handle of the object you would like to show/hide.
StaticObjects.IsPointInside( staticObjectHandle , longitude , latitude , altitude ) -- Tacview 1.9.0
Check if the given coordinates are located inside or outside of the specified object.
The object must be a 2D or extruded polygon.
The altitude is verified only if the object is an extruded polygon. It is ignored for 2D polygons.
Return value:
true is the given coordinates are inside the specified object.
false in all other cases (including errors).
--------------------------------------------------------------------------------------------------------------------------------
Telemetry
This module is the heart of Tacview.
Use the telemetry manager to read and write any data for any dynamic object.
Telemetry.BeginningOfTime -- Tacview 1.7.5
Telemetry.EndOfTime -- Tacview 1.7.5
Constants representing special time stamps.
BeginningOfTime is typically used to create timeless objects like waypoints, bullseyes, or buildings.
NOTE: If you want to know the time of the first and last sample of the telemetry data, use Telemetry.GetDataTimeRange()
Telemetry.InvalidPropertyIndex -- Tacview 1.7.5
Constant used to detect invalid properties.
Telemetry.Tags -- Tacview 1.7.3
Enumeration of bits used to defined object types.
-- Domain
Telemetry.Tags.Air
Telemetry.Tags.Ground
Telemetry.Tags.Sea
Telemetry.Tags.Space
Telemetry.Tags.Weapon
Telemetry.Tags.Sensor
Telemetry.Tags.Navaid
Telemetry.Tags.Abstract
Telemetry.Tags.Misc
-- Attributes
Telemetry.Tags.Static
Telemetry.Tags.Heavy
Telemetry.Tags.Medium
Telemetry.Tags.Light
Telemetry.Tags.Minor
-- Basic Type
Telemetry.Tags.FixedWing
Telemetry.Tags.Rotorcraft
Telemetry.Tags.Spacecraft
Telemetry.Tags.Armor
Telemetry.Tags.AntiAircraft
Telemetry.Tags.Vehicle
Telemetry.Tags.Watercraft
Telemetry.Tags.Human
Telemetry.Tags.Biologic
Telemetry.Tags.Missile
Telemetry.Tags.Rocket
Telemetry.Tags.Bomb
Telemetry.Tags.Torpedo
Telemetry.Tags.Projectile
Telemetry.Tags.Beam
Telemetry.Tags.Decoy
Telemetry.Tags.Building
Telemetry.Tags.Bullseye
Telemetry.Tags.Waypoint
-- Specific Type
Telemetry.Tags.Tank
Telemetry.Tags.Warship
Telemetry.Tags.AircraftCarrier
Telemetry.Tags.Submarine
Telemetry.Tags.Infantry
Telemetry.Tags.Parachutist
Telemetry.Tags.Shell
Telemetry.Tags.Bullet
Telemetry.Tags.Grenade -- Tacview 1.8.8
Telemetry.Tags.Flare
Telemetry.Tags.Chaff
Telemetry.Tags.SmokeGrenade
Telemetry.Tags.Aerodrome
Telemetry.Tags.Container
Telemetry.Tags.Shrapnel
Telemetry.Tags.Explosion
Telemetry.AllGivenTagsActive( objectTags , activeTagsCombination ) -- Tacview 1.8.0
Telemetry.AnyGivenTagActive( objectTags , activeTagsCombination ) -- Tacview 1.8.0
Helpers to know if all or any of the combination of tags match given object tags.
You can retrieve current object tags (which defines the type of an object) with the Telemetry.GetCurrentTags function.
Return value:
true or false depending on the match
Telemetry.Property -- Tacview 1.7.6
List of the most commonly referenced property names.
These constants are helpers. You are NOT limited to these when requested property indexes.
For example, you can still manually call: Tacview.Telemetry.GetObjectsNumericPropertyIndex("Fuel", false)
-- Text properties (Tacview 1.7.6)
Telemetry.Property.Text.CallSign
Telemetry.Property.Text.Event
Telemetry.Property.Text.Name
-- Text properties (Tacview 1.8.0)
Telemetry.Property.Text.Color
Telemetry.Property.Text.FocusedTarget
Telemetry.Property.Text.LockedTarget
Telemetry.Property.Text.Pilot
-- Numeric properties (Tacview 1.7.6)
Telemetry.Property.Numeric.Disabled
Telemetry.Property.Numeric.EngagementRange
-- Numeric properties (Tacview 1.8.0)
Telemetry.Property.Numeric.IAS
Telemetry.Property.Numeric.Importance
Telemetry.Property.Numeric.MinRange
Telemetry.Property.Numeric.MaxRange
-- Numeric properties (Tacview 1.9.0)
Telemetry.Property.Numeric.TriggerPressed
Telemetry.Property.Numeric.HeartRate
Telemetry.Property.Numeric.SpO2
Telemetry.Clear() -- Tacview 1.7.2
Purge all telemetry data currently loaded in memory.
This function does not warn the user, nor it gives him the opportunity to save any data.
This function does not interrupt or stop any recording in progress. It simply purges all the data recorded up to that point.
Telemetry.Load( fileName ) -- Tacview 1.8.0
This function merges given file data with any data already loaded in memory.
Call Telemetry.Clear() before loading new data if you do not want to merge.
Return value:
true if given file has been successfully loaded
Telemetry.IsEmpty() -- Tacview 1.7.6
Tells if no at all telemetry is currently loaded in memory.
This include intemporal data.
Telemetry.IsLikeEmpty() -- Tacview 1.7.6
Tells if no significant telemetry is currently loaded in memory.
For example, if no data or only intemporal data is loaded this function returns true.
Otherwise it returns false.
Telemetry.GetDataTimeRange() -- Tacview 1.7.6
Retrieve the extend of the telemetry data currently loaded in memory.
This excludes any intemporal samples like bulleyes position for example.
Return value:
{
beginTime, -- first sample absolute time
endTime -- last sample absolute time
}
Telemetry.GetCurrentObjectHandle( objectId ) -- Tacview 1.7.2
Telemetry.GetObjectHandle( objectId , absoluteTime ) -- Tacview 1.8.6
Retrieves the handle of the specified object at the current update time.
If there are several objects with the same id (for example a player which has spawned in the same aircraft multiple time during the same session),
the telemetry manger will return the object which is the most appropriate for the current time frame.
Unlike Ids, objects handles uniquely identify each object currently loaded in memory.
Return value:
objectHandle (integer)
Telemetry.GetCurrentOrCreateObjectHandle( objectId ) -- Tacview 1.7.5
Retrieves the handle of the specified object at the current update time.
If the give object id is not found, then a new object will be created at the current update time with the given id.
Unlike Ids, objects handles uniquely identify each object currently loaded in memory.
Return value:
objectHandle (integer)
Telemetry.GetOrCreateObjectHandle( objectId , absoluteTime ) -- Tacview 1.7.5
Retrieves the handle of the specified object at the specified time.
If the give object id is not found, then a new object will be created at the specified time with the given id.
Unlike Ids, objects handles uniquely identify each object currently loaded in memory.
To create a timeless object like a waypoint, you can use the following:
local newObjectHandle = Tacview.Telemetry.GetOrCreateObjectHandle( objectId , Tacview.Telemetry.BeginningOfTime )
Return value:
objectHandle (integer)
Telemetry.GetCurrentTags( objectHandle ) -- Tacview 1.7.3
Return given object tags as a bit field.
Return value:
Each bit of the returned integer corresponds to a specific tag.
The combination of these tags defines the current object type.
The object type can evolve over time and be refined depending on available telemetry at this point.
Telemetry.GetCurrentShortName( objectHandle ) -- Tacview 1.7.2
Return given object short name at the current update time.
Return value:
Text which typically correspond to the NATO code or any other appropriate short designation for the object.
Telemetry.GetTransform( objectHandle , absoluteTime ) -- Tacview 1.7.5
Telemetry.GetCurrentTransform( objectHandle ) -- Tacview 1.7.2
Returns given object position/rotation at the current update or specified time.
Some objects (typically bullets) may not have all the information available.
For example, the rotation information may not be available for all aircraft.
Native coordinates correspond the original coordinates in the source flight simulator (typically for BMS and DCS).
For performance reasons, angles retrieved by the telemetry manager are *NOT* always normalized between ]-π,+π]
Do not forget to normalize angles before displaying then as text to the final user!
Return value:
ObjectTransform =
{
time = sample_absolute_time, -- (seconds) This effective absolute time of this sample may be different from current update time if the object does not exist yet, or anymore...
x = cartesianPositionX, -- (meters) Cartesian position (ALWAYS AVAILABLE)
y = cartesianPositionY, -- (meters) Cartesian position (ALWAYS AVAILABLE)
z = cartesianPositionZ, -- (meters) Cartesian position (ALWAYS AVAILABLE)
longitude = sphericalLongitude, -- (radian) Spherical position (ALWAYS AVAILABLE)
latitude = sphericalLatitude, -- (radian) Spherical position (ALWAYS AVAILABLE)
altitude = absoluteAltitude, -- (meters) Spherical position (ALWAYS AVAILABLE)
roll = objectRoll, -- (radian) roll axis rotation (if rotationIsValid == true)
pitch = objectPitch, -- (radian) pitch axis rotation (if rotationIsValid == true)
yaw = objectYaw, -- (radian) yaw axis rotation (if rotationIsValid == true)
u = nativePositionX, -- (meters) Native x coordinate (if nativeCoordinatesAreValid == true)
v = nativePositionY, -- (meters) Native y coordinate (if nativeCoordinatesAreValid == true)
heading = nativeHeadingToNorth, -- (radian) Heading in native coordinates system (if nativeCoordinatesAreValid == true & rotationIsValid == true)
rotationIsValid = boolean, -- Set to true if rotation information is valid (otherwise the data may be emulated)
nativeCoordinatesAreValid = boolean, -- Set to true if native coordiantes are valid (otherwise u, v and heading are set to zero)
}
Return value:
value , validity
validity is set to false if the value does not really apply for the given time (typically if the object does not exist at the given time)
even when validity is set to false, the value is valid and usable (to simplify client code)