Tacview Core Interface.txt

--------------------------------------------------------------------------------------------------------------------------------

	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.

			result = angle1 - 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 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)

Telemetry.GetTransformCount( objectHandle ) -- Tacview 1.8.6
Telemetry.GetTransformFromIndex( objectHandle , sampleIndex ) -- Tacview 1.8.6

	Use theses the functions whenever you need to enumerate the exact position samples available for the specified object.

	If you need to re-set a new position for a specified sample, simple use Telemetry.SetTransform() with the exact sample time you want to modify.

	Return value:

		same as Telemetry.GetTransform()

Telemetry.GetCalculatedTransform( objectHandle , absoluteTime ) -- Tacview 1.8.6
Telemetry.GetCurrentCalculatedTransform( objectHandle ) -- Tacview 1.8.6

	When some information such as roll, pitch, and yaw are not available, you can use this function to calculate them based on the object type and behavior.

	Note that in some cases, Tacview cannot emulated roll, pitch, yaw and will still return invalid values for those.

	Return value:

		Same as for GetTransform()

Telemetry.GetCurrentAngleOfAttack( objectHandle ) -- Tacview 1.7.3

	Returns given object angle of attack at current time.

	If aoa has been recorded, then Tacview will return the interpolated sample.
	If aoa has not been recorded, but rotation data is available, Tacview will calculate the aoa.
	If the pitch aoa cannot be calculated, then Tacview will return the absolute aoa (as opposed to the pitch aoa)

	Return value:

		angle of attack (in pitch)
		nil when no data available (or object does not exist at this time).

Telemetry.GetCurrentAngleOfSideslip( objectHandle ) -- Tacview 1.8.6

	Returns given object angle of sideslip at current time.

	If aoa has been recorded, then Tacview will return the interpolated sample.
	Otherwise valid object rotation (roll/pitch/yaw) is required to be able to calculate the sideslip.

	Return value:

		angle of sideslip
		nil when no data available (or object does not exist at this time).

Telemetry.GetVerticalGForce( objectHandle , absoluteTime ) -- Tacview 1.8.0
Telemetry.GetCurrentVerticalGForce( objectHandle ) -- Tacview 1.7.3

	Returns given object vertical g-Force at given time.

	The vertical g-Force is the g-Force which usually the most relevant to the pilot and its aircraft. This is the one displayed in the cockpit.

	If vertical g-Force has been recorded, then Tacview will return the interpolated sample.
	If vertical g-Force has not been recorded, but rotation data is available, Tacview will calculate the vertical G-Force.

	Return value:

		Vertical g-Force if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetLateralGForce( objectHandle , absoluteTime ) -- Tacview 1.8.6
Telemetry.GetCurrentLateralGForce( objectHandle ) -- Tacview 1.8.6

	Returns given object lateral (from left to right) g-Force at given time.

	If lateral g-Force has been recorded, then Tacview will return the interpolated sample.
	If lateral g-Force has not been recorded, but rotation data is available, Tacview will calculate the lateral G-Force.

	Return value:

		Lateral g-Force if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetLongitudinalGForce( objectHandle , absoluteTime ) -- Tacview 1.8.6
Telemetry.GetCurrentLongitudinalGForce( objectHandle ) -- Tacview 1.8.6

	Returns given object longitudinal (from back to front) g-Force at given time.

	If longitudinal g-Force has been recorded, then Tacview will return the interpolated sample.
	If longitudinal g-Force has not been recorded, but rotation data is available, Tacview will calculate the longitudinal G-Force.

	Return value:

		longitudinal g-Force if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetAbsoluteGForce( objectHandle , absoluteTime ) -- Tacview 1.8.0
Telemetry.GetCurrentAbsoluteGForce( objectHandle ) -- Tacview 1.8.0

	Returns given object absolute g-Force is available at current time.

	The absolute g-Force is the acceleration of the object divided by G. It is independent of the object orientation or trajectory.

	Return value:

		absolute g-Force if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetTurnRadius( objectHandle , absoluteTime ) -- Tacview 1.8.4
Telemetry.GetCurrentTurnRadius( objectHandle ) -- Tacview 1.8.4

	Returns given object turn radius in meters.

	Return value:

		turn radius if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetTurnRate( objectHandle , absoluteTime ) -- Tacview 1.8.4
Telemetry.GetTurnRate( objectHandle , absoluteTime , dt ) -- Tacview 1.8.4
Telemetry.GetCurrentTurnRate( objectHandle ) -- Tacview 1.8.4
Telemetry.GetCurrentTurnRate( objectHandle , dt ) -- Tacview 1.8.4

	Returns given object turn rate in radian per second.
	Specify dt if you want a turn-rate over a specific period of time (typically to get instantaneous vs sustained turn-rate)

	Return value:

		turn rate if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetMachNumber( objectHandle , absoluteTime ) -- Tacview 1.8.4
Telemetry.GetCurrentMachNumber( objectHandle ) -- Tacview 1.8.4

	Returns given object Mach number at current time.

	If vertical the Mach number has been recorded, then Tacview will return the interpolated sample.
	If vertical the Mach number has not been recorded, Tacview will calculate an approximation of it.

	Return value:

		Mach number if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetTrack( objectHandle , absoluteTime ) -- Tacview 1.9.3
Telemetry.GetCurrentTrack( objectHandle ) -- Tacview 1.9.3

	Returns given object track at given time.

	Track refers to the actual path that the object has followed or is following over the ground.
	The track of an object can be influenced by several factors including its own propulsion and external influences like wind or current.
	The track is what you would plot on a map to show where the object has been.

	Return value:

		Track in radian if available.
		nil when not enough data is available (or object does not exist at this time).

Telemetry.GetGlobalNumericPropertyIndex( propertyName , autoCreate ) -- Tacview 1.7.6
Telemetry.GetGlobalTextPropertyIndex( propertyName , autoCreate ) -- Tacview 1.7.6

	Retrieve a property for the global object (0).

	If the property does not exist yet:
		- if autoCreate is true, then the property will be created and its index returned.
		- if autoCreate is false, then Telemetry.InvalidPropertyIndex will be returned.

	To optimize CPU and memory, numeric and text properties are separate in the telemetry manager.
	WARNING: Because numeric and text properties are separate, indexes for numeric and text samples may overlap and cannot be mixed.

Telemetry.GetObjectsNumericPropertyIndex( propertyName , autoCreate ) -- Tacview 1.7.5
Telemetry.GetObjectsTextPropertyIndex( propertyName , autoCreate ) -- Tacview 1.7.5

	Retrieve a property index for everything which is not the global object.
	The index returned is the same for all objects.

	If the property does not exist yet:
		- if autoCreate is true, then the property will be created and its index returned.
		- if autoCreate is false, then Telemetry.InvalidPropertyIndex will be returned.

	To optimize CPU and memory, numeric and text properties are separate in the telemetry manager.
	WARNING: Because numeric and text properties are separate, indexes for numeric and text samples may overlap and cannot be mixed.

Telemetry.GetNumericSample( objectHandle , absoluteTime , propertyIndex ) -- Tacview 1.7.5
Telemetry.GetTextSample( objectHandle , absoluteTime , propertyIndex ) -- Tacview 1.7.5

	Retrieve property numeric or text value at the given time.

	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 (this simplify the client code)

Telemetry.SetNumericSample( objectHandle , absoluteTime , propertyIndex , value ) -- Tacview 1.7.5
Telemetry.SetTextSample( objectHandle , absoluteTime , propertyIndex , value ) -- Tacview 1.7.5

	Set or re-set given numeric or text property value at the given time.
	You can set absoluteTime to Tacview.Telemetry.BeginningOfTime to declare the properties of timeless objects like waypoints.

Telemetry.GetNumericSampleCount( objectHandle , propertyIndex ) -- Tacview 1.8.0
Telemetry.GetTextSampleCount( objectHandle , propertyIndex ) -- Tacview 1.8.0

	Retrieve the number of samples currently loaded in memory for the specified object.
	This function is typically used to enumerate the object samples.

Telemetry.GetNumericSampleFromIndex( objectHandle , sampleIndex , propertyIndex ) -- Tacview 1.8.0
Telemetry.GetTextSampleFromIndex( objectHandle , sampleIndex , propertyIndex ) -- Tacview 1.8.0

	Retrieve given object telemetry data sample from its index.
	SampleIndex starts at 0 and ends at count-1.
	You can use GetNumericSampleCount() and GetTextSampleCount() to know the number of samples of a specific property.

	Return value:

		{ sampleValue , sampleTime }

		Returns nil if index is invalid

Telemetry.SetTransform( objectHandle , absoluteTime , transform ) -- Tacview 1.7.5

	Set or re-set object position and rotation at the given time.

	absoluteTime is a 64-bit floating point number which represents the number of seconds elapsed to 1970-01-01T00:00:00Z

	-- non specified members will be set to the interpolated value of the preceding and following samples.
	-- it is also possible to replace only the specified members of an existing sample.

	transform
	{
		-- Spherical position

		f64 longitude;		-- (radian) Spherical position (+ is towards east)
		f64 latitude;		-- (radian) Spherical position (+ is towards north)
		f32 altitude;		-- (meters) Spherical position

		-- Rotation

		f32 roll;			-- (radian) roll axis rotation (positive when rolling the aircraft to the right)
		f32 pitch;			-- (radian) pitch axis rotation (positive when taking-off)
		f32 yaw;			-- (radian) yaw axis rotation (clockwise relative to the true north)

		-- Native coordinates, mostly used to get accurate distance and speed calculation for flat world simulators.

		f32 u;				-- (meters) Native x coordinate
		f32 v;				-- (meters) Native y coordinate
		f32 heading;		-- (radian) Heading in native coordinates system
	};

Telemetry.GetTransformTimeRange( objectHandle ) -- Tacview 1.8.0

	Retrieve the time of the first and last transform sample available for the specified object.
	This function is typically useful to enumerate object samples over its effective activity period.
	Returns nil if the object does not have any transform sample available.
	Note that Telemetry.BeginningOfTime can be returned if the object is timeless like a Bullseye.

	Return value:

	{
		firstTransformSampleTime,		-- first effective transform sample absolute time
		lastTransformSampleTime			-- last effective transform sample absolute time
	}

Telemetry.GetLifeTime( objectHandle ) -- Tacview 1.7.6

	Return absolute time of the object first appearance and its time of disappearance if applicable.
	Unlike GetTransformTimeRange(), this function may return a wider range which can goes up to Telemetry.EndOfTime if the object has never been destroyed or removed from the battlefield.
	Prefer the function GetTransformTimeRange() if you want to iterate over the object telemetry samples via a time counter.

	Return value:

	{
		lifeTimeBegin,		-- First sample absolute time
		lifeTimeEnd			-- Last sample absolute time
	}

	If the object exists from the beginning of times (e.g. a bullseye) its lifeTimeBegin is Telemetry.BeginningOfTime.
	If the object has never been destroyed or removed from the battlefield, then lifeTimeEnd is Telemetry.EndOfTime.

Telemetry.SetLifeTimeEnd( objectHandle , absoluteTime ) -- Tacview 1.7.5

	Defines the end-of-life of the specified object.
	Typically used to specify when an object has been destroyed or has been removed from the battlefield.

Telemetry.RemoveTransformSample( objectHandle , absoluteTime ) -- Tacview 1.8.7
Telemetry.RemoveTransformSampleFromIndex( objectHandle , sampleIndex ) -- Tacview 1.8.7

	Delete transform value at the specified time or index.
	This could change the life spawn of an object.

	Return value:

		true if the operation has succeeded
		false if one of the parameter is out-dated (because of real-time telemetry change for example)

Telemetry.RemoveNumericSample( objectHandle , absoluteTime , propertyIndex ) -- Tacview 1.8.0
Telemetry.RemoveNumericSampleFromIndex( objectHandle , sampleIndex , propertyIndex ) -- Tacview 1.8.0
Telemetry.RemoveTextSample( objectHandle , absoluteTime , propertyIndex ) -- Tacview 1.8.0
Telemetry.RemoveTextSampleFromIndex( objectHandle , sampleIndex , propertyIndex ) -- Tacview 1.8.0

	Delete sample value at the specified time or index.

	Return value:

		true if the operation has succeeded
		false if one of the parameter is out-dated (because of real-time telemetry change for example)

Telemetry.DeleteObject( objectHandle ) -- Tacview 1.7.5

	Remove the specified object from the telemetry manager.
	This operation is safe: The corresponding handle will remain valid until the next effective purge (typically when loading a new telemetry file) so the other modules will not crash if they attempt to reference the object afterward.
	However, any data related to this object will be freed.

Telemetry.GetObjectCount() -- Tacview 1.7.6

	Retrieve the total number of objects currently active in the telemetry manager.
	Typically used to enumerate all objects.

Telemetry.GetObjectHandleByIndex( index ) -- Tacview 1.7.6

	Retrieve an object by its index.
	NOTE: The index goes from 0 to GetObjectCount() - 1.

	Return value:

		The object handle or nil if the index is out of range.

Telemetry.GetObjectId( objectHandle ) -- Tacview 1.7.6

	Retrieve given object id.

	Beware that object ids can be recycled and cannot uniquely identify objects.
	For that reason, avoid using them, unless it is for telemetry injection (event creation) or export.

Telemetry.GetCurrentParentHandle( childObjectHandle ) -- Tacview 1.8.8

	Retrieve given object parent handle (if any).

	This function will either return the handle of the object's parent as per the object's "Parent" property,
	or the handle of the object which Tacview determines is most likely to be the parent. 

Telemetry.OnLoadStart( mergeWithExistingData ) -- Tacview 1.8.5

	Notifies Tacview that telemetry data is going to be loaded.

	You should call this function whenever your addon is going to load any significant amount of data in the telemetry manager.

	This will give Tacview the opportunity to:

		- if mergeWithExistingData is false:
			- ask the user if currently loaded data needs to be saved
			- purge any telemetry data currently loaded in memory
			- prepare data and UI layers to receive new data (to avoid any undefined behaviors from tools and addons)

		- if mergeWithExistingData is true:
			- prepare data and UI layers to receive new data (to avoid any undefined behaviors from tools and addons)

	NOTE: You must call Telemetry.OnLoadEnd() after the loading is complete (whether it is a success or a failure).

	Return value:

		Returns true if you can process with the loading of new data.
		Returns false if the operation has been canceled by the user or if it is not possible because of other operations currently in progress.

	Typical use:

	if ( Telemetry.OnLoadStart( false ) )

		local fileNames = UI.MessageBox.GetOpenFileName( ... )

		if ( CustomImport( fileNames ) )

			-- Success
			Telemetry.OnLoadEnd( fileNames[1] )

		else

			-- Failed to load the data
			Telemetry.OnLoadEnd()

		end

	end

Telemetry.OnLoadEnd( documentName ) -- Tacview 1.8.5

	Notifies Tacview that telemetry loading process is complete (whether it is a success or a failure).

	You must call Telemetry.OnLoadStart() prior to this function.

	Whenever the loading process is complete, call this function to notify Tacview about the success or failure of the operation.

	If the operation is successful, set documentName to the file name loaded.
	If you have loaded multiple files, then you can use the name of the first file for example.
		- Tacview will start an analysis of the newly loaded data and display relevant information in the UI so the user can start debriefing with the new data.

	If the operation has failed, then do not pass any file name to the function.
		- Tacview will reset the UI to a stable empty document state.

Telemetry.GetAbsoluteBearing( sourceObjectHandle , sourceTime , targetObjectHandle , targetTime , autoMagneticDeclination )

	Retrieve the bearing from source object to target object at given time.
	Set autoMagneticDeclination to true if you want Tacview to automatically returns the bearing relative to the magnetic north at the location of the source object.

	Return value:

		Bearing from sourceObject to targetObject in radian (including magnetic declination if requested)
		nil if the objects do not exist at given time.

Telemetry.GetRange2D( sourceObjectHandle , sourceTime , targetObjectHandle , targetTime )

	Retrieve the 2D distance (view from the top) between two objects at given time.

	Return value:

		Distance between the two objects in meters.
		nil if the objects do not exist at given time.

--------------------------------------------------------------------------------------------------------------------------------
Database

	The database contains a list of definition of all the real and fictional objects known by Tacview from a typical Cessna plane to military ships.

Database.Reload -- Tacview 1.8.3

	Reload the whole database and update the UI accordingly.
	Should be called whenever your addon has made a significant change to the database content.

	Return value:

		false if there were some error(s) during the reload.
		return true otherwise.

Database.InvalidPropertyIndex -- Tacview 1.8.2

	Constant used to detect invalid properties.

Database.GetNextRecord( recordHandle , recordType ) -- Tacview 1.8.2

	Use this function to enumerate all records which match the given object type.
	To start the enumeration, use 0 for the recordHandle.
	Then re-use the returned values to enumerate the following records.
	You can use any combination of Telemetry.Tags to define a type as complex as you want.

	Return value:

		new recordHandle (integer)
		0 if no more data matching the requested type

Database.GetRecordId( recordHandle ) -- Tacview 1.8.2

	Retrieve the unique id for the given record.

	Return value:

		text identifier (nil or empty means invalid record)

Database.GetRecordPriority( recordHandle ) -- Tacview 1.8.2

	Retrieve the priority for the given database record.

	Return value:

		priorty (float)
		0.0 to 0.5 are the lowest priorities which correspond to the data defined in first (typically Tacview default database)
		1.0 and greater are typically used for user definitions (loaded over Tacview definition to override default definitions)

Database.GetTextPropertyIndex( propertyName ) -- Tacview 1.8.2
Database.GetNumericPropertyIndex( propertyName ) -- Tacview 1.8.2

	Retrieve the index of the given property in the database.
	The index returned is the same for all entries.

		return Database.InvalidPropertyIndex if the propertyName is invalid or not found in the database.

Database.GetRecordTextValue( recordHandle , propertyIndex ) -- Tacview 1.8.2
Database.GetRecordNumericValue( recordHandle , propertyIndex ) -- Tacview 1.8.2

	Retrieve property text or numeric value from the property index.

	Return value:

		value or nil if no data available for this record.

--------------------------------------------------------------------------------------------------------------------------------
Terrain

	The following functions can be used to customize the terrain as well as to retrieve some information about it.

Terrain.GetElevation( longitude , latitude ) -- Tacview 1.7.5

	Retrieve given point elevation in meter.
	Longitude and latitude are in radian.

Terrain.GetMagneticDeclination( longitude , latitude , altitude ) -- Tacview 1.9.3

	Retrieve magnetic declination at the specified location at the current time.
	Longitude and latitude are in radian, altitude in meters.

	Return value:

		Magnetic declination in radian.
		You can substract it to a true north heading to get the corresponding magnetic heading.

Terrain.AddCustomTexture( textureId , layerId , fileName , filter , topLeftLongitude , topLeftLatitude , topRightLongitude , topRightLatitude , bottomRightLongitude , bottomRightLatitude , bottomLeftLongitude , bottomLeftLatitude ) -- Tacview 1.8.7

	Declare a new custom texture which will be visible by default.

	Each custom texture is uniquely identified via its text textureId.

	Use layerId to display the texture only when data from a specific source is loaded,
	leave it blank to load the texture regardless of the simulator. It is not currently possible to specify multiple layers for one texture.

	Currently supported layers:

		- "Real World"
		- "DCS World"
		- "Falcon 4"
		- "IL2"
		- "EECH"

	NOTE: X-Plane and Microsoft Flight Simulator / P3D will use the "Real World" layer.

	FileName is a case sensitive name of the texture file stored in %ProgramData%\Tacview\Data\Terrain\Textures\ or %APPDATA%\Tacview\Data\Terrain\Textures\

	Currently supported file format/extension:

		- webp
		- png
		- jpg/jpeg
		- tga

	Use the filter parameter to choose the way the texture is overlaid onto the terrain:
		- nil: original (using texture native alpha channel when available for blend)
		- "Translucent": 50% translucent picture
		- "AdaptiveGreyScale": adaptive grey scale layer
		- "AdaptiveColor": adaptive color layer

	When fully qualitied such as "IL2-BoS.png", Tacview will load the image with the specified filter.

	If the file name is specified without any extension (e.g. "DCS-Caucasus4Tacview-v1"), Tacview will attempt to load any image starting with
	the name followed by a special character specifying the way the texture will be displayed:

		- T: 50% translucent picture
		- B: adaptive grey scale layer
		- C: adaptive color layer

	For example:

		"IL2-BoS.png" will load the file "\Data\Terrain\Textures\IL2-BoS.png"
		"DCS-Caucasus4Tacview-v1" will load the file "\Data\Terrain\Textures\DCS-Caucasus4Tacview-v1T.png" and display it half translucent over the base layer.

	The texture coordinates are in radian, and the projection will be quadratic.

	NOTE: Tacview will automatically cache any declared texture, there is no need to explicitly load/unload a texture.

	NOTE: Because of the way Tacview manages files resources, it will not be able to display a new picture which did not exist on the disk
	before the application start. A work around that limitation, is to provide a full path for your texture file, this will bypass Tacview file manager and
	directly load the data. The picture will still be cached, this will not degrade loading performances.

Terrain.ShowCustomTexture( textureId ) -- Tacview 1.8.7
Terrain.HideCustomTexture( textureId ) -- Tacview 1.8.7

	Show or hide previously declared custom texture either in \Data\Terrain\Textures\CustomTextureList.xml or via Terrain.AddCustomTexture()
	textureId is a text which uniquely identify the texture.

--------------------------------------------------------------------------------------------------------------------------------
Path

Path.GetDirectoryName( path ) -- Tacview 1.8.7

	Retrieve the name of the directory contained in the provided path.

	For example:

		Path.GetDirectoryName("C:\MyDir\MySubDir\myfile.ext")

			will returns -> "C:\MyDir\MySubDir\"

Path.GetFileName( path ) -- Tacview 1.8.7

	Returns the file name and extension of the specified path string.

	For example:

		Path.GetDirectoryName("C:\MyDir\MySubDir\myfile.ext")

			will returns -> "myfile.ext"

Path.GetSpecialDirectoryName( directoryId ) -- Tacview 1.9.0

	Retrieve the full path of a particular directory.

	Because special folders locations my vary depending on the username and language, it is strongly
	Recommended to use this function to retrieve the property location of a specific folder.
	Otherwise, if you hardcode paths, your addon may not work on some systems or with some specific settings.

	directoryId could be one of the following:

		"UserApplicationData"
		"UserDocuments"
		"UserSavedGames"
		"SystemApplicationData"
		"Temp"

	NOTE:

		Use this function mainly to output data or read external data.
		DO NOT use this function to locate and read your addon resources. Use instead: AddOns.Current.GetPath()

	Example:

		Path.GetSpecialDirectoryName( "SystemApplicationData" ) would return "C:\ProgramData\" on some systems.

--------------------------------------------------------------------------------------------------------------------------------
Directory

Directory.CreateDirectory( directoryName ) -- Tacview 1.8.7

	Creates all directories and subdirectories in the specified path unless they already exist.

	returns true if successful

Directory.Delete( directoryName [, recursive ] ) -- Tacview 1.8.7

	if recursive is true, then deletes the specified directory and any subdirectories and files in the directory.
	otherwise delete the directory only if it is empty.

	returns true if successful

Directory.GetFiles( directoryName [, recursive ] ) -- Tacview 1.8.7

	Returns the names of files (including their paths) in the specified directory.

--------------------------------------------------------------------------------------------------------------------------------
RemoteControl

	Remote controls can be used to control aircraft as well as mission triggers.
	You can create as many remote controls as required for your needs.
	It is also possible to send commands to the four default remote controls of Tacview via a dedicated API.

RemoteControl.GetHandle( remoteControlIndex ) -- Tacview 1.8.7

	Retrieves one of the default remote controls of Tacview.
	This could be handy to use the connection parameters provided by the user.
	Otherwise, it is easier to simply create you own brand new remote controls via the functions listed below.

	There are currently 4 default remote controls (from 0 to 3).

	Return value:

		corresponding remote control handle.
		nil if the index is invalid.

RemoteControl.Create() -- Tacview 1.8.7
RemoteControl.Delete( remoteControlHandle ) -- Tacview 1.8.7

	Creates a new custom remote control. Returns the newly created remote-control handle.

	Unlike for the default remove controls, no UI will be displayed,
	if you need a UI, you can use Tacview dialog boxes API to create a custom one.

RemoteControl.Connect( remoteControlHandle , address , port , password , userName) -- Tacview 1.8.7
RemoteControl.Disconnect( remoteControlHandle ) -- Tacview 1.8.7

	Connects the specified remote control to a simulator.
	Make sure the appropriate Tacview exporter (for DCS, MSFS, XPL, P3D) is installed on the simulator system.
	Password will be ignored by the host simulator if the connection is not protected.
	Username may be displayed on screen and stored in logs as a reference.

	Return value:

		true if the connection operation is in progress.

	NOTE: This is an asynchronous operation, a return of true does not mean the connection has been established yet.
	You must IsActive() or GetStatus() once par update to know if the connection is successful or have been dropped.

	The connection should be instantaneous. Otherwise:
	 - The exporter is not installed or not running on the target system.
	 - The remote control feature of the exporter is not enabled in the options (it is off by default).
	 - The connection is protected by a password, and the password provided is incorrect.
	 - A firewall issue (check if this work on your local system via 127.0.0.1)

	The default port for Tacview remote controls is 42675.
	You can change it in DCS World control panel.
	There is currently no way to change it for FSX/XPL.

	Example:

		RemoteControl.Connect( remoteControlHandle, "127.0.0.1", 42675, "", "Viper" )

RemoteControl.IsActive( remoteControlHandle ) -- Tacview 1.8.7

	Returns true if the specified remote control is currently establishing a connection or the connection is active.

RemoteControl.GetStatus( remoteControlHandle ) -- Tacview 1.8.7

	Returns the detailed status of the connection:

RemoteControl.Status

	Contains the following constants identifying the remote control status:

	-- Operation not yet (never) started

	NotStarted

	-- Connection in progress IsActive()==true

	Connecting
	Connected

	-- End of connection (success)

	DisconnectedByRemotePeer
	CanceledByLocalPeer

	-- End of connection (failure)

	UnsupportedProtocol
	WrongPassword
	ConnectionFailed

RemoteControl.GetPeerName( remoteControlHandle ) -- Tacview 1.8.7

	Retrieve the name of the user currently flying in the simulator the remote control is connected to.

RemoteControl.SendCommand( remoteControlHandle , command , [ parameter ] ) -- Tacview 1.8.7

	Send the specified command to a simulator via a connected remote control.
	Note that not all commands are supported by all simulators.

	The command is a text string containing an instruction followed by parameter when applicable:

		-- General control

			"General.Pause"		-- Pauses the simulator
			"General.Resume"	-- Resume the simulation

			"General.Respawn"	-- Respawn current user

		-- Aircraft systems

			"FlightControl.Flaps.Up"
			"FlightControl.Flaps.Down"

			"System.LandingGear.Up"
			"System.LandingGear.Down"

			"System.Eject"
			"System.Smoke"

		-- Flight controls

			"Axis.Roll.Value,<value>"
			"Axis.Pitch.Value,<value>"
			"Axis.Yaw.Value,<value>"
			"Axis.Throttle.Value,<value>"

		-- Mission commands

			"Custom.Command,<flag_number>,<flag_value>"

	parameter is optional and used to specify the argument of the command when applicable

		float used to specify axis value (generally from -1.0 to +1.0)
		integer used to specify flag id to set

	Flight control values are floats: -1 is full left/down, +1 is full right/up.

		To prevent jittering, controls values will remain in the requested position for 0.5 second after the last injection.
		If you want the control to go to neutral instantaneously, you must then explicitly inject 0.0.

		After 0.5 seconds, the simulator may return the control to its previous position.
		Which could be centered or any position the physical joystick connected to the simulator could be for example.

		Examples:

			RemoteControl.SendCommand( remoteControlHandle , "System.LandingGear.Up" )
			RemoteControl.SendCommand( remoteControlHandle , "Axis.Pitch.Value" , 0.25 )		-- slight pitch up
			RemoteControl.SendCommand( remoteControlHandle , "Axis.Throttle.Value" , 1 )		-- 100% throttle

	Mission commands will set corresponding numeric flags to the specified values

		If you want to set the flag 33 to 127 send the following command:

			"Custom.Command,33,127"

		Then, in your simulator (typically DCS World for now), you can define a trigger which is going to do something
		(such as trigging a patrol) as soon as the flat number 33 is set to the value 127.