Banner Image

Module Utils

This module contains derived utilities taken from the MIST framework, which are excellent tools to be reused in an OO environment.

Authors:

  • Grimes : Design & Programming of the MIST framework.

Contributions:

  • FlightControl : Rework to OO framework

Global(s)

Global BIGSMOKEPRESET

Global CALLSIGN

Global DCSMAP

Global FLARECOLOR

Global SMOKECOLOR

Global UTILS

Global lookup_table

#table lookup_table

Type(s)

Fields and Methods inherited from CALLSIGN Description

CALLSIGN.AWACS

CALLSIGN.Aircraft

CALLSIGN.JTAC

CALLSIGN.Tanker

Fields and Methods inherited from DCSMAP Description

DCSMAP.Caucasus

Caucasus map.

DCSMAP.NTTR

Nevada Test and Training Range map.

DCSMAP.Normandy

Normandy map.

DCSMAP.PersianGulf

Persian Gulf map.

DCSMAP.Syria

Syria map.

DCSMAP.TheChannel

The Channel map.

Fields and Methods inherited from FLARECOLOR Description

FLARECOLOR.Green

FLARECOLOR.Red

FLARECOLOR.White

FLARECOLOR.Yellow

Fields and Methods inherited from SMOKECOLOR Description

SMOKECOLOR.Blue

SMOKECOLOR.Green

SMOKECOLOR.Orange

SMOKECOLOR.Red

SMOKECOLOR.White

Fields and Methods inherited from UTILS Description

UTILS.BasicSerialize(s)

UTILS.BeaufortScale(speed)

UTILS.CelciusToFarenheit(Celcius)

Convert temperature from Celsius to Farenheit.

UTILS.CheckMemory(output)

Checks the current memory usage collectgarbage("count").

UTILS.ClockToSeconds(clock)

Convert clock time from hours, minutes and seconds to seconds.

UTILS.DeepCopy(object)

Deep copy a table.

UTILS.DisplayMissionTime(duration)

Display clock and mission time on screen as a message to all.

UTILS.DoString(s)

UTILS.FeetToMeters(feet)

UTILS.FileExists(file)

Checks if a file exists or not.

UTILS.GMTToLocalTimeDifference()

Get the time difference between GMT and local time.

UTILS.GetCallsignName(Callsign)

Get the callsign name from its enumerator value

UTILS.GetCoalitionName(Coalition)

Get the coalition name from its numerical ID, e.g.

UTILS.GetDCSMap()

Returns the DCS map/theatre as optained by env.mission.theatre

UTILS.GetDCSMissionDate()

Returns the mission date.

UTILS.GetDate()

Returns the current date.

UTILS.GetDayOfYear(Year, Month, Day)

Get the day of the year.

UTILS.GetMagneticDeclination(map)

Returns the magnetic declination of the map.

UTILS.GetMarkID()

UTILS.GetMissionDay(Time)

Returns the day of the mission.

UTILS.GetMissionDayOfYear(Time)

Returns the current day of the year of the mission.

UTILS.GetModulationName(Modulation)

Get the modulation name from its numerical value.

UTILS.GetOSTime()

Get OS time.

UTILS.GetSunRiseAndSet(DayOfYear, Latitude, Longitude, Rising, Tlocal)

Get sunrise or sun set of a specific day of the year at a specific location.

UTILS.GetSunrise(Day, Month, Year, Latitude, Longitude, Rising, Tlocal)

Get sun rise of a specific day of the year at a specific location.

UTILS.GetSunset(Day, Month, Year, Latitude, Longitude, Rising, Tlocal)

Get sun set of a specific day of the year at a specific location.

UTILS.HdgDiff(h1, h2)

Calculate the difference between two "heading", i.e.

UTILS.IsInRadius(InVec2, Vec2, Radius)

UTILS.IsInSphere(InVec3, Vec3, Radius)

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

UTILS.KmphToKnots(knots)

UTILS.KmphToMps(kmph)

UTILS.KnotsToKmph(knots)

UTILS.KnotsToMps(knots)

Convert knots to meters per second.

UTILS.MetersToFeet(meters)

UTILS.MetersToNM(meters)

UTILS.MetersToSM(meters)

UTILS.MiphToMps(miph)

UTILS.MpsToKmph(mps)

UTILS.MpsToKnots(mps)

Convert meters per second to knots.

UTILS.MpsToMiph(mps)

Convert meters per second to miles per hour.

UTILS.NMToMeters(NM)

UTILS.OneLineSerialize(tbl)

Porting in Slmod's serialize_slmod2.

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

Generate a Gaussian pseudo-random number.

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

Randomize a value by a certain amount.

UTILS.ReplaceIllegalCharacters(Text, ReplaceBy)

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

UTILS.Rotate2D(a, angle)

Rotate 3D vector in the 2D (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

UTILS.SecondsOfToday()

Seconds of today.

UTILS.SecondsToClock(seconds, short)

Convert time in seconds to hours, minutes and seconds.

UTILS.SecondsToMidnight()

Cound seconds until next midnight.

UTILS.Split(str, sep)

Split string at seperators.

UTILS.TACANToFrequency(TACANChannel, TACANMode)

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

UTILS.ToDegree(angle)

UTILS.ToRadian(angle)

UTILS.VecAdd(a, b)

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

UTILS.VecAngle(a, b)

Calculate the angle between two 3D vectors.

UTILS.VecCross(a, b)

Calculate the cross product of two 3D vectors.

UTILS.VecDot(a, b)

Calculate the dot product of two vectors.

UTILS.VecHdg(a)

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

UTILS.VecNorm(a)

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

UTILS.VecSubstract(a, b)

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

UTILS.VecTranslate(a, distance, angle)

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

UTILS._MarkID

Marker index counter. Running number when marker is added.

UTILS.hPa2inHg(hPa)

Convert pressure from hecto Pascal (hPa) to inches of mercury (inHg).

UTILS.hPa2mmHg(hPa)

Convert pressure from hecto Pascal (hPa) to millimeters of mercury (mmHg).

UTILS.kg2lbs(kg)

Convert kilo gramms (kg) to pounds (lbs).

UTILS.kpairs(t, getkey, order)

UTILS.rpairs(t)

UTILS.spairs(t, order)

UTILS.tostringLL(lat, lon, acc, DMS)

UTILS.tostringMGRS(MGRS, acc)

See DCS_enum_callsigns

Field(s)

#table CALLSIGN.AWACS

AWACS

#table CALLSIGN.Aircraft

Aircraft

#table CALLSIGN.JTAC

JTAC

#table CALLSIGN.Tanker

Tanker

Function(s)

DCS map as returned by env.mission.theatre.

Field(s)

#string DCSMAP.Caucasus

Caucasus map.

#string DCSMAP.NTTR

Nevada Test and Training Range map.

#string DCSMAP.Normandy

Normandy map.

#string DCSMAP.PersianGulf

Persian Gulf map.

#string DCSMAP.Syria

Syria map.

#string DCSMAP.TheChannel

The Channel map.

Function(s)

Field(s)

Function(s)

Field(s)

Function(s)

Utilities static class.

Field(s)

#number UTILS._MarkID

Marker index counter. Running number when marker is added.

Function(s)

porting in Slmod's "safestring" basic serialize

Defined in:

UTILS

Parameter:

s

Beaufort scale: returns Beaufort number and wind description as a function of wind speed in m/s.

Defined in:

UTILS

Parameter:

speed

Convert temperature from Celsius to Farenheit.

Defined in:

UTILS

Parameter:

#number Celcius

Temperature in degrees Celsius.

Return value:

#number:

Temperature in degrees Farenheit.

Checks the current memory usage collectgarbage("count").

Info is printed to the DCS log file. Time stamp is the current mission runtime.

Defined in:

UTILS

Parameter:

#boolean output

If true, print to DCS log file.

Return value:

#number:

Memory usage in kByte.

Convert clock time from hours, minutes and seconds to seconds.

Defined in:

UTILS

Parameter:

#string clock

String of clock time. E.g., "06:12:35" or "5:1:30+1". Format is (H)H:(M)M:((S)S)(+D) H=Hours, M=Minutes, S=Seconds, D=Days.

Return value:

#number:

Seconds. Corresponds to what you cet from timer.getAbsTime() function.

Deep copy a table.

See http://lua-users.org/wiki/CopyTable

Defined in:

UTILS

Parameter:

#table object

The input table.

Return value:

#table:

Copy of the input table.

Display clock and mission time on screen as a message to all.

Defined in:

UTILS

Parameter:

#number duration

Duration in seconds how long the time is displayed. Default is 5 seconds.

porting in Slmod's dostring

Defined in:

UTILS

Parameter:

s

Defined in:

UTILS

Parameter:

feet

Checks if a file exists or not.

This requires io to be desanitized.

Defined in:

UTILS

Parameter:

#string file

File that should be checked.

Return value:

#boolean:

True if the file exists, false if the file does not exist or nil if the io module is not available and the check could not be performed.

Get the time difference between GMT and local time.

Defined in:

UTILS

Return value:

#number:

Local time difference in hours compared to GMT. E.g. Dubai is GMT+4 ==> +4 is returned.

Get the callsign name from its enumerator value

Defined in:

UTILS

Parameter:

#number Callsign

The enumerator callsign.

Return value:

#string:

The callsign name or "Ghostrider".

Get the coalition name from its numerical ID, e.g.

coaliton.side.RED.

Defined in:

UTILS

Parameter:

#number Coalition

The coalition ID.

Return value:

#string:

The coalition name, i.e. "Neutral", "Red" or "Blue" (or "Unknown").

Returns the DCS map/theatre as optained by env.mission.theatre

Defined in:

UTILS

Return value:

#string:

DCS map name.

Returns the mission date.

This is the date the mission started.

Defined in:

UTILS

Return values:

#string:

Mission date in yyyy/mm/dd format.

#number:

The year anno domini.

#number:

The month.

#number:

The day.

Returns the current date.

Defined in:

UTILS

Return values:

#string:

Mission date in yyyy/mm/dd format.

#number:

The year anno domini.

#number:

The month.

#number:

The day.

Get the day of the year.

Counting starts on 1st of January.

Defined in:

UTILS

Parameters:

#number Year

The year.

#number Month

The month.

#number Day

The day.

Return value:

#number:

The day of the year.

Returns the magnetic declination of the map.

Returned values for the current maps are:

  • Caucasus +6 (East), year ~ 2011
  • NTTR +12 (East), year ~ 2011
  • Normandy -10 (West), year ~ 1944
  • Persian Gulf +2 (East), year ~ 2011

Defined in:

UTILS

Parameter:

#string map

(Optional) Map for which the declination is returned. Default is from env.mission.theatre

Return value:

#number:

Declination in degrees.

get a new mark ID for markings

Defined in:

UTILS

Returns the day of the mission.

Defined in:

UTILS

Parameter:

#number Time

(Optional) Abs. time in seconds. Default now, i.e. the value return from timer.getAbsTime().

Return value:

#number:

Day of the mission. Mission starts on day 0.

Returns the current day of the year of the mission.

Defined in:

UTILS

Parameter:

#number Time

(Optional) Abs. time in seconds. Default now, i.e. the value return from timer.getAbsTime().

Return value:

#number:

Current day of year of the mission. For example, January 1st returns 0, January 2nd returns 1 etc.

Get the modulation name from its numerical value.

Defined in:

UTILS

Parameter:

#number Modulation

The modulation enumerator number. Can be either 0 or 1.

Return value:

#string:

The modulation name, i.e. "AM"=0 or "FM"=1. Anything else will return "Unknown".

Get OS time.

Needs os to be desanitized!

Defined in:

UTILS

Return value:

#number:

Os time in seconds.

Get sunrise or sun set of a specific day of the year at a specific location.

Defined in:

UTILS

Parameters:

#number DayOfYear

The day of the year.

#number Latitude

Latitude.

#number Longitude

Longitude.

#boolean Rising

If true, calc sun rise, or sun set otherwise.

#number Tlocal

Local time offset in hours. E.g. +4 for a location which has GMT+4.

Return value:

#number:

Sun rise/set in seconds of the day.

Get sun rise of a specific day of the year at a specific location.

Defined in:

UTILS

Parameters:

#number Day

Day of the year.

#number Month

Month of the year.

#number Year

Year.

#number Latitude

Latitude.

#number Longitude

Longitude.

#boolean Rising

If true, calc sun rise, or sun set otherwise.

#number Tlocal

Local time offset in hours. E.g. +4 for a location which has GMT+4. Default 0.

Return value:

#number:

Sun rise in seconds of the day.

Get sun set of a specific day of the year at a specific location.

Defined in:

UTILS

Parameters:

#number Day

Day of the year.

#number Month

Month of the year.

#number Year

Year.

#number Latitude

Latitude.

#number Longitude

Longitude.

#boolean Rising

If true, calc sun rise, or sun set otherwise.

#number Tlocal

Local time offset in hours. E.g. +4 for a location which has GMT+4. Default 0.

Return value:

#number:

Sun rise in seconds of the day.

Calculate the difference between two "heading", i.e.

angles in [0,360) deg.

Defined in:

UTILS

Parameters:

#number h1

Heading one.

#number h2

Heading two.

Return value:

#number:

Heading difference in degrees.

Test if a Vec2 is in a radius of another Vec2

Defined in:

UTILS

Parameters:

InVec2

Vec2

Radius

Test if a Vec3 is in the sphere of another Vec3

Defined in:

UTILS

Parameters:

InVec3

Vec3

Radius

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:

Defined in:

UTILS

Parameter:

knots

Defined in:

UTILS

Parameter:

kmph

Defined in:

UTILS

Parameter:

knots

Convert knots to meters per second.

Defined in:

UTILS

Parameter:

#number knots

Speed in knots.

Return value:

#number:

Speed in m/s.

Defined in:

UTILS

Parameter:

meters

Defined in:

UTILS

Parameter:

meters

Defined in:

UTILS

Parameter:

meters

Defined in:

UTILS

Parameter:

miph

Defined in:

UTILS

Parameter:

mps

Convert meters per second to knots.

Defined in:

UTILS

Parameter:

#number mps

Speed in m/s.

Return value:

#number:

Speed in knots.

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.

Defined in:

UTILS

Parameter:

NM

Porting in Slmod's serialize_slmod2.

Defined in:

UTILS

Parameter:

#table tbl

Input table.

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.

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.

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.

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.

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

Seconds of today.

Defined in:

UTILS

Return value:

#number:

Seconds passed since last midnight.

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).

Cound seconds until next midnight.

Defined in:

UTILS

Return value:

#number:

Seconds to midnight.

Split string at seperators.

C.f. http://stackoverflow.com/questions/1426954/split-string-in-lua

Defined in:

UTILS

Parameters:

#string str

Sting to split.

#string sep

Speparator for split.

Return value:

#table:

Split text.

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.

Defined in:

UTILS

Parameter:

angle

Defined in:

UTILS

Parameter:

angle

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.

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).

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

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.

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).

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.

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.

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:

Vector rotated in the (x,z) plane.

Convert pressure from hecto Pascal (hPa) to inches of mercury (inHg).

Defined in:

UTILS

Parameter:

#number hPa

Pressure in hPa.

Return value:

#number:

Pressure in inHg.

Convert pressure from hecto Pascal (hPa) to millimeters of mercury (mmHg).

Defined in:

UTILS

Parameter:

#number hPa

Pressure in hPa.

Return value:

#number:

Pressure in mmHg.

Convert kilo gramms (kg) to pounds (lbs).

Defined in:

UTILS

Parameter:

#number kg

Mass in kg.

Return value:

#number:

Mass in lbs.

Here is a customized version of pairs, which I called kpairs because it iterates over the table in a sorted order, based on a function that will determine the keys as reference first.

Defined in:

UTILS

Parameters:

t

getkey

order

Here is a customized version of pairs, which I called rpairs because it iterates over the table in a random order.

Defined in:

UTILS

Parameter:

t

Here is a customized version of pairs, which I called spairs because it iterates over the table in a sorted order.

Defined in:

UTILS

Parameters:

t

order

acc: in DM: decimal point of minutes. In DMS: decimal point of seconds. position after the decimal of the least significant digit: So: 42.32 - acc of 2.

Defined in:

UTILS

Parameters:

lat

lon

acc

DMS

acc- the accuracy of each easting/northing. 0, 1, 2, 3, 4, or 5.

Defined in:

UTILS

Parameters:

MGRS

acc