Module Utilities.Utils

From vec3.

To vec3.

Return value:

#number:

Heading in degrees.

UTILS.IasToTas(ias, altitude, oatcorr)

Convert indicated airspeed (IAS) to true airspeed (TAS) for a given altitude above main sea level.

The conversion is based on the approximation that TAS is ~2% higher than IAS with every 1000 ft altitude above sea level.

Defined in:

UTILS

Parameters:

#number ias

Indicated air speed in any unit (m/s, km/h, knots, ...)

#number altitude

Altitude above main sea level in meters.

#number oatcorr

(Optional) Outside air temperature correction factor. Default 0.017.

Return value:

#number:

True airspeed in the same unit the IAS has been given.

UTILS.IsAnyInTable(Table, Objects, Key)

Check if any object of multiple given objects is contained in a table.

Defined in:

UTILS

Parameters:

#table Table

The table.

#table Objects

The objects to check.

#string Key

(Optional) Key to check.

Return value:

#booolen:

Returns true if object is in table.

UTILS.IsInRadius(InVec2, Vec2, Radius)

Test if a Vec2 is in a radius of another Vec2

Defined in:

UTILS

Parameters:

InVec2

Vec2

Radius

UTILS.IsInSphere(InVec3, Vec3, Radius)

Test if a Vec3 is in the sphere of another Vec3

Defined in:

UTILS

Parameters:

InVec3

Vec3

Radius

UTILS.IsInTable(Table, Object, Key)

Check if an object is contained in a table.

Defined in:

UTILS

Parameters:

#table Table

The table.

#table Object

The object to check.

#string Key

(Optional) Key to check. By default, the object itself is checked.

Return value:

#booolen:

Returns true if object is in table.

UTILS.IsInstanceOf(object, className)

Function to infer instance of an object

Examples:

UTILS.IsInstanceOf( 'some text', 'string' ) will return true
UTILS.IsInstanceOf( some_function, 'function' ) will return true
UTILS.IsInstanceOf( 10, 'number' ) will return true
UTILS.IsInstanceOf( false, 'boolean' ) will return true
UTILS.IsInstanceOf( nil, 'nil' ) will return true
UTILS.IsInstanceOf( ZONE:New( 'some zone', ZONE ) will return true
UTILS.IsInstanceOf( ZONE:New( 'some zone', 'ZONE' ) will return true
UTILS.IsInstanceOf( ZONE:New( 'some zone', 'zone' ) will return true
UTILS.IsInstanceOf( ZONE:New( 'some zone', 'BASE' ) will return true
UTILS.IsInstanceOf( ZONE:New( 'some zone', 'GROUP' ) will return false

Defined in:

UTILS

Parameters:

object

is the object to be evaluated

className

is the name of the class to evaluate (can be either a string or a Moose class)

Return value:

#boolean:

UTILS.IsLoadingDoorOpen(unit_name)

(Helicopter) Check if one loading door is open.

Defined in:

UTILS

Parameter:

#string unit_name

Unit name to be checked

Return value:

#boolean:

Outcome - true if a (loading door) is open, false if not, nil if none exists.

UTILS.KiloMetersToFeet(kilometers)

Defined in:

UTILS

Parameter:

kilometers

UTILS.KiloMetersToNM(kilometers)

Defined in:

UTILS

Parameter:

kilometers

UTILS.KiloMetersToSM(kilometers)

Defined in:

UTILS

Parameter:

kilometers

Defined in:

UTILS

Parameter:

knots

Defined in:

UTILS

Parameter:

kmph

UTILS.KnotsToAltKIAS(knots, altitude)

Convert knots to altitude corrected KIAS, e.g.

for tankers.

Defined in:

UTILS

Parameters:

#number knots

Speed in knots.

#number altitude

Altitude in feet

Return value:

#number:

Corrected KIAS

Defined in:

UTILS

Parameter:

knots

Defined in:

UTILS

Parameter:

#number knots

Speed in knots.

Return value:

#number:

Speed in m/s.

UTILS.LoadFromFile(Path, Filename)

Function to save an object to a file

Defined in:

UTILS

Parameters:

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

Return values:

#boolean:

outcome True if reading is possible and successful, else false.

#table:

data The data read from the filesystem (table of lines of text). Each line is one single #string!

UTILS.LoadSetOfGroups(Path, Filename, Spawn, Structured, Cinematic, Effect, Density)

Load back a SET of groups from file.

Defined in:

UTILS

Parameters:

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

#boolean Spawn

If set to false, do not re-spawn the groups loaded in location and reduce to size.

#boolean Structured

(Optional, needs Spawn=true)If true, and the data has been saved as structure before, remove the correct unit types as per the saved list.

#boolean Cinematic

(Optional, needs Structured=true) If true, place a fire/smoke effect on the dead static position.

#number Effect

(Optional for Cinematic) What effect to use. Defaults to a random effect. Smoke presets are: 1=small smoke and fire, 2=medium smoke and fire, 3=large smoke and fire, 4=huge smoke and fire, 5=small smoke, 6=medium smoke, 7=large smoke, 8=huge smoke.

#number Density

(Optional for Cinematic) What smoke density to use, can be 0 to 1. Defaults to 0.5.

Return values:

Core.Set#SET_GROUP:

Set of GROUP objects. Returns nil when file cannot be read. Returns a table of data entries if Spawn is false: { groupname=groupname, size=size, coordinate=coordinate, template=template }

#table:

When using Cinematic: table of names of smoke and fire objects, so they can be extinguished with COORDINATE.StopBigSmokeAndFire( name )

UTILS.LoadSetOfStatics(Path, Filename)

Load back a SET of statics from file.

Defined in:

UTILS

Parameters:

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

Return value:

Core.Set#SET_STATIC:

Set SET_STATIC containing the static objects.

UTILS.LoadStationaryListOfGroups(Path, Filename, Reduce, Structured, Cinematic, Effect, Density)

Load back a stationary list of groups from file.

Defined in:

UTILS

Parameters:

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

#boolean Reduce

If false, existing loaded groups will not be reduced to fit the saved number.

#boolean Structured

(Optional, needs Reduce = true) If true, and the data has been saved as structure before, remove the correct unit types as per the saved list.

#boolean Cinematic

(Optional, needs Structured = true) If true, place a fire/smoke effect on the dead static position.

#number Effect

#number Density

(Optional for Cinematic) What smoke density to use, can be 0 to 1. Defaults to 0.5.

Return values:

#table:

Table of data objects (tables) containing groupname, coordinate and group object. Returns nil when file cannot be read.

#table:

When using Cinematic: table of names of smoke and fire objects, so they can be extinguished with COORDINATE.StopBigSmokeAndFire( name )

UTILS.LoadStationaryListOfStatics(Path, Filename, Reduce, Dead, Cinematic, Effect, Density)

Load back a stationary list of statics from file.

Defined in:

UTILS

Parameters:

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

#boolean Reduce

If false, do not destroy the units with size=0.

#boolean Dead

(Optional, needs Reduce = true) If Dead is true, re-spawn the dead object as dead and do not just delete it.

#boolean Cinematic

(Optional, needs Dead = true) If true, place a fire/smoke effect on the dead static position.

#number Effect

#number Density

(Optional for Cinematic) What smoke density to use, can be 0 to 1. Defaults to 0.5.

Return values:

#table:

Table of data objects (tables) containing staticname, size (0=dead else 1), coordinate and the static object. Dead objects will have coordinate points {x=0,y=0,z=0}

#table:

When using Cinematic: table of names of smoke and fire objects, so they can be extinguished with COORDINATE.StopBigSmokeAndFire( name ) Returns nil when file cannot be read.

UTILS.MetersToFeet(meters)

Defined in:

UTILS

Parameter:

meters

UTILS.MetersToNM(meters)

Defined in:

UTILS

Parameter:

meters

UTILS.MetersToSM(meters)

Defined in:

UTILS

Parameter:

meters

UTILS.MiphToMps(miph)

Defined in:

UTILS

Parameter:

miph

UTILS.MpsToKmph(mps)

Defined in:

UTILS

Parameter:

mps

UTILS.MpsToKnots(mps)

Convert meters per second to knots.

Defined in:

UTILS

Parameter:

#number mps

Speed in m/s.

Return value:

#number:

Speed in knots.

UTILS.MpsToMiph(mps)

Convert meters per second to miles per hour.

Defined in:

UTILS

Parameter:

#number mps

Speed in m/s.

Return value:

#number:

Speed in miles per hour.

UTILS.NMToKiloMeters(NM)

Defined in:

UTILS

Parameter:

UTILS.NMToMeters(NM)

Defined in:

UTILS

Parameter:

UTILS.OneLineSerialize(tbl)

Serialize a given table.

Defined in:

UTILS

Parameter:

#table tbl

Input table.

Return value:

#string:

Table as a string.

UTILS.PlotRacetrack(Coordinate, Altitude, Speed, Heading, Leg, Coalition, Color, Alpha, LineType, ReadOnly)

Helper function to plot a racetrack on the F10 Map - curtesy of Buur.

Defined in:

UTILS

Parameters:

Core.Point#COORDINATE Coordinate

#number Altitude

Altitude in feet

#number Speed

Speed in knots

#number Heading

Heading in degrees

#number Leg

Leg in NM

#number Coalition

Coalition side, e.g. coaltion.side.RED or coaltion.side.BLUE

#table Color

Color of the line in RGB, e.g. {1,0,0} for red

#number Alpha

Transparency factor, between 0.1 and 1

#number LineType

Line type to be used, line type: 0=No line, 1=Solid, 2=Dashed, 3=Dotted, 4=Dot dash, 5=Long dash, 6=Two dash. Default 1=Solid.

#boolean ReadOnly

UTILS.PrintTableToLog(table, indent)

Defined in:

UTILS

Parameters:

table

indent

UTILS.RandomGaussian(x0, sigma, xmin, xmax, imax)

Generate a Gaussian pseudo-random number.

Defined in:

UTILS

Parameters:

#number x0

Expectation value of distribution.

#number sigma

(Optional) Standard deviation. Default 10.

#number xmin

(Optional) Lower cut-off value.

#number xmax

(Optional) Upper cut-off value.

#number imax

(Optional) Max number of tries to get a value between xmin and xmax (if specified). Default 100.

Return value:

#number:

Gaussian random number.

UTILS.Randomize(value, fac, lower, upper)

Randomize a value by a certain amount.

Defined in:

UTILS

Parameters:

#number value

The value which should be randomized

#number fac

Randomization factor.

#number lower

(Optional) Lower limit of the returned value.

#number upper

(Optional) Upper limit of the returned value.

Return value:

#number:

Randomized value.

Usages:

UTILS.Randomize(100, 0.1) returns a value between 90 and 110, i.e. a plus/minus ten percent variation.

UTILS.Randomize(100, 0.5, nil, 120) returns a value between 50 and 120, i.e. a plus/minus fivty percent variation with upper bound 120.

UTILS.RemoveMark(MarkID, Delay)

Remove an object (marker, circle, arrow, text, quad, ...) on the F10 map.

Defined in:

UTILS

Parameters:

#number MarkID

Unique ID of the object.

#number Delay

(Optional) Delay in seconds before the mark is removed.

UTILS.ReplaceIllegalCharacters(Text, ReplaceBy)

Replace illegal characters [<>|/?*:\] in a string.

Defined in:

UTILS

Parameters:

#string Text

Input text.

#string ReplaceBy

Replace illegal characters by this character or string. Default underscore "_".

Return value:

#string:

The input text with illegal chars replaced.

UTILS.Rotate2D(a, angle)

Rotate 3D vector in the 2D (x,z) plane.

y-component (usually altitude) unchanged.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

#number angle

Rotation angle in degrees.

Return value:

Vector rotated in the (x,z) plane.

UTILS.Round(num, idp)

From http://lua-users.org/wiki/SimpleRound use negative idp for rounding ahead of decimal place, positive for rounding after decimal place

Defined in:

UTILS

Parameters:

num

idp

UTILS.SaveSetOfGroups(Set, Path, Filename, Structured)

Function to save the state of a set of Wrapper.Group#GROUP objects.

Defined in:

UTILS

Parameters:

Core.Set#SET_BASE Set

of objects to save

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

#boolean Structured

Append the data with a list of typenames in the group plus their count.

Return value:

#boolean:

outcome True if saving is successful, else false.

Usage:

We will go through the set and find the corresponding group and save the current group size and current position.
The idea is to respawn the groups **spawned during an earlier run of the mission** at the given location and reduce 
the number of units in the group when reloading the data again to restart the saved mission. Note that *dead* groups 
cannot be covered with this.
**Note** Do NOT use dashes or hashes in group template names (-,#)!
The data will be a simple comma separated list of groupname and size, with one header line.
The current task/waypoint/etc cannot be restored.

UTILS.SaveSetOfStatics(Set, Path, Filename)

Function to save the state of a set of Wrapper.Static#STATIC objects.

Defined in:

UTILS

Parameters:

Core.Set#SET_BASE Set

of objects to save

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

Return value:

#boolean:

outcome True if saving is successful, else false.

Usage:

We will go through the set and find the corresponding static and save the current name and postion when alive.
The data will be a simple comma separated list of name and state etc, with one header line.

UTILS.SaveStationaryListOfGroups(List, Path, Filename, Structured)

Function to save the state of a list of groups found by name

Defined in:

UTILS

Parameters:

#table List

Table of strings with groupnames

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

#boolean Structured

Append the data with a list of typenames in the group plus their count.

Return value:

#boolean:

outcome True if saving is successful, else false.

Usage:

We will go through the list and find the corresponding group and save the current group size (0 when dead).
These groups are supposed to be put on the map in the ME and have *not* moved (e.g. stationary SAM sites). 
Position is still saved for your usage.
The idea is to reduce the number of units when reloading the data again to restart the saved mission.
The data will be a simple comma separated list of groupname and size, with one header line.

UTILS.SaveStationaryListOfStatics(List, Path, Filename)

Function to save the state of a list of statics found by name

Defined in:

UTILS

Parameters:

#table List

Table of strings with statics names

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file.

Return value:

#boolean:

outcome True if saving is successful, else false.

Usage:

We will go through the list and find the corresponding static and save the current alive state as 1 (0 when dead).
Position is saved for your usage. **Note** this works on UNIT-name level.
The idea is to reduce the number of units when reloading the data again to restart the saved mission.
The data will be a simple comma separated list of name and state etc, with one header line.

UTILS.SaveToFile(Path, Filename, Data)

Function to save an object to a file

Defined in:

UTILS

Parameters:

#string Path

The path to use. Use double backslashes \\ on Windows filesystems.

#string Filename

The name of the file. Existing file will be overwritten.

#table Data

The LUA data structure to save. This will be e.g. a table of text lines with an \n at the end of each line.

Return value:

#boolean:

outcome True if saving is possible, else false.

UTILS.SecondsOfToday()

Seconds of today.

Defined in:

UTILS

Return value:

#number:

Seconds passed since last midnight.

UTILS.SecondsToClock(seconds, short)

Convert time in seconds to hours, minutes and seconds.

Defined in:

UTILS

Parameters:

#number seconds

Time in seconds, e.g. from timer.getAbsTime() function.

#boolean short

(Optional) If true, use short output, i.e. (HH:)MM:SS without day.

Return value:

#string:

Time in format Hours:Minutes:Seconds+Days (HH:MM:SS+D).

UTILS.SecondsToMidnight()

Cound seconds until next midnight.

Defined in:

UTILS

Return value:

#number:

Seconds to midnight.

UTILS.ShuffleTable(t)

Shuffle a table accoring to Fisher Yeates algorithm

Defined in:

UTILS

Parameter:

#table t

Table to be shuffled.

Return value:

#table:

Shuffled table.

UTILS.Split(str, sep)

Split string at seperators.

C.f. split-string-in-lua.

Defined in:

UTILS

Parameters:

#string str

Sting to split.

#string sep

Speparator for split.

Return value:

#table:

Split text.

UTILS.TACANToFrequency(TACANChannel, TACANMode)

Converts a TACAN Channel/Mode couple into a frequency in Hz.

Defined in:

UTILS

Parameters:

#number TACANChannel

The TACAN channel, i.e. the 10 in "10X".

#string TACANMode

The TACAN mode, i.e. the "X" in "10X".

Return value:

#number:

Frequency in Hz or #nil if parameters are invalid.

UTILS.TableShow(tbl, loc, indent, tableshow_tbls)

Returns table in a easy readable string representation.

Defined in:

UTILS

Parameters:

tbl

table to show

loc

indent

tableshow_tbls

Return value:

Human readable string representation of given table.

UTILS.TasToIas(tas, altitude, oatcorr)

Convert true airspeed (TAS) to indicated airspeed (IAS) for a given altitude above main sea level.

The conversion is based on the approximation that TAS is ~2% higher than IAS with every 1000 ft altitude above sea level.

Defined in:

UTILS

Parameters:

#number tas

True air speed in any unit (m/s, km/h, knots, ...)

#number altitude

Altitude above main sea level in meters.

#number oatcorr

(Optional) Outside air temperature correction factor. Default 0.017.

Return value:

#number:

Indicated airspeed in the same unit the TAS has been given.

UTILS.ToDegree(angle)

Defined in:

UTILS

Parameter:

angle

UTILS.ToRadian(angle)

Defined in:

UTILS

Parameter:

angle

UTILS.ToStringBRAANATO(FromGrp, ToGrp)

Create a BRAA NATO call string BRAA between two GROUP objects

Defined in:

UTILS

Parameters:

Wrapper.Group#GROUP FromGrp

GROUP object

Wrapper.Group#GROUP ToGrp

GROUP object

Return value:

#string:

Formatted BRAA NATO call

UTILS.Vec2Add(a, b)

Calculate the total vector of two 2D vectors by adding the x,y components of each other.

Defined in:

UTILS

Parameters:

Vector in 2D with x, y components.

Vector in 2D with x, y components.

Return value:

Vector c=a+b with c(i)=a(i)+b(i), i=x,y.

UTILS.Vec2Dot(a, b)

Calculate the dot product of two 2D vectors.

The result is a number.

Defined in:

UTILS

Parameters:

Vector in 2D with x, y components.

Vector in 2D with x, y components.

Return value:

#number:

Scalar product of the two vectors a*b.

UTILS.Vec2Hdg(a)

Calculate "heading" of a 2D vector in the X-Y plane.

Defined in:

UTILS

Parameter:

Vector in 2D with x, y components.

Return value:

#number:

Heading in degrees in [0,360).

UTILS.Vec2Norm(a)

Calculate the euclidean norm (length) of a 2D vector.

Defined in:

UTILS

Parameter:

Vector in 2D with x, y components.

Return value:

#number:

Norm of the vector.

UTILS.Vec2Rotate2D(a, angle)

Rotate 2D vector in the 2D (x,z) plane.

Defined in:

UTILS

Parameters:

Vector in 2D with x, y components.

#number angle

Rotation angle in degrees.

Return value:

Vector rotated in the (x,y) plane.

UTILS.Vec2Substract(a, b)

Calculate the difference between two 2D vectors by substracting the x,y components from each other.

Defined in:

UTILS

Parameters:

Vector in 2D with x, y components.

Vector in 2D with x, y components.

Return value:

Vector c=a-b with c(i)=a(i)-b(i), i=x,y.

UTILS.Vec2Translate(a, distance, angle)

Translate 2D vector in the 2D (x,z) plane.

Defined in:

UTILS

Parameters:

Vector in 2D with x, y components.

#number distance

The distance to translate.

#number angle

Rotation angle in degrees.

Return value:

Translated vector.

UTILS.VecAdd(a, b)

Calculate the total vector of two 3D vectors by adding the x,y,z components of each other.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

Vector in 3D with x, y, z components.

Return value:

Vector c=a+b with c(i)=a(i)+b(i), i=x,y,z.

UTILS.VecAngle(a, b)

Calculate the angle between two 3D vectors.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

Vector in 3D with x, y, z components.

Return value:

#number:

Angle alpha between and b in degrees. alpha=acos(ab)/(|a||b|), ( denotes the dot product).

UTILS.VecCross(a, b)

Calculate the cross product of two 3D vectors.

The result is a 3D vector.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

Vector in 3D with x, y, z components.

Return value:

Vector

UTILS.VecDist2D(a, b)

Calculate the distance between two 2D vectors.

Defined in:

UTILS

Parameters:

Vector in 2D with x, y components.

Vector in 2D with x, y components.

Return value:

#number:

Distance between the vectors.

UTILS.VecDist3D(a, b)

Calculate the distance between two 3D vectors.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

Vector in 3D with x, y, z components.

Return value:

#number:

Distance between the vectors.

UTILS.VecDot(a, b)

Calculate the dot product of two vectors.

The result is a number.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

Vector in 3D with x, y, z components.

Return value:

#number:

Scalar product of the two vectors a*b.

UTILS.VecHdg(a)

Calculate "heading" of a 3D vector in the X-Z plane.

Defined in:

UTILS

Parameter:

Vector in 3D with x, y, z components.

Return value:

#number:

Heading in degrees in [0,360).

UTILS.VecNorm(a)

Calculate the euclidean norm (length) of a 3D vector.

Defined in:

UTILS

Parameter:

Vector in 3D with x, y, z components.

Return value:

#number:

Norm of the vector.

UTILS.VecSubstract(a, b)

Calculate the difference between two 3D vectors by substracting the x,y,z components from each other.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

Vector in 3D with x, y, z components.

Return value:

Vector c=a-b with c(i)=a(i)-b(i), i=x,y,z.

UTILS.VecTranslate(a, distance, angle)

Translate 3D vector in the 2D (x,z) plane.

y-component (usually altitude) unchanged.

Defined in:

UTILS

Parameters:

Vector in 3D with x, y, z components.

#number distance

The distance to translate.

#number angle

Rotation angle in degrees.

Return value: