VR-Forces Lua Documentation

• Table of Contents

• !HowToPrint
• !Set Catalog
• !Task Catalog
• AerodromeObject
• AirRefuelSupplier
• AsyncJob
• ComponentSystem
• Detonation
• ExtendableArtPart
• FeatureGeometry
• FeatureSet
• Location3D
• LocationReference
• ScriptAnimationModel
• SensorGimbal
• SimObject
• SwingingArtPart
• SystemAttribute
• TranslatableArtPart
• TranslatableStream
• Vector3D
• VectorGeoc3D
• VectorOffset3D
• WeaponInfo
• aggregateUtils
• airportDataUtils
• behaviorEngine
• componentSystemUtil
• contactsUtils
• dataFileUtils
• displayGraphUtil
• embarkationUtil
• engagementUtil
• formationUtils
• fsm
• fsm2
• iffUtils
• lightDataUtils
• msgUtil
• munitionLauncherUtils
• parseUtil
• pathUtil
• spatialUtil
• taskVisualizationUtil
• terrainReasoningUtil
• this
• threatLevelUtil
• unitUtil
• vrf
• vrfutil
• weaponUtils

spatialUtil

(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)

Functions that compute things in space using points, vectors, etc.
To use functions in this package, reference spatialUtil, e.g. spatialUtil.fn(arg). For example,

 require "spatialUtil"  
 a, b, c, d, e, f = spatialUtil.cscManeuver(u, v, w, x, y) 

Function List

Functions

centerOffsets (offsets)

Computes a list of position offsets from a given list of offsets such that the new offsets are relative to the center of the bounding extent of the positions.

Parameters:

• offsets: (table) A list of VectorOffset3D values that represent the offset of some locations from an arbitrary location.

Return value:

(table) A list of recomputed VectorOffset3D values for these same locations, but referenced to the center of the bounding volume containing the locations.

checkBackward (referenceLocation, directionLocation, testLocation)

Given a reference location, direction location and a location to check, return true if the location to check is away from the direction going from reference to direction location. Also provide the distance backward.

Parameters:

• referenceLocation: Location3D.
• directionLocation: Location3D. A point defining a direction from the referenceLocation.
• testLocation: Location3D. The location whose direction from reference will be tested.

Return values:

1. isBackward (bool) True if the testLocation is backwards from the referenceLocation relative to the directionLocation.
2. distanceBack (number) The distance that the testLocation is behind the referenceLocation, i.e. backwards along the direction defined by directionLocation. This will be 0 if the testLocation is not behind the referenceLocation.

cscManeuver (initialPosition, initialHeading, finalPosition, finalHeading, radius)

Determines the parameters of the shortest circle-segment-circle (CSC) path, with the first and second circles having the same radius. See cscAsymmetricManeuver for parameter documentation.
Reference: Dubins path (https://en.wikipedia.org/wiki/Dubins_path)

Parameters:

• initialPosition:
• initialHeading:
• finalPosition:
• finalHeading:
• radius: The radius of both circles.

findBetterIntercept2D (segmentOnePoints2D, segmentTwoPoints2D, origin2D)

Computes the closest projection from origin to either of the two segments, and a number identifying the closest segment.

Parameters:

• segmentOnePoints2D: Table of two Location3D. Represents line segment 1.
• segmentTwoPoints2D: Table of two Location3D. Represents line segment 2.
• origin2D: Location3D The point whose projection is being tested.

Return value:

Location3D, number. Intercept without altitude, in which segment (1 or 2). Nil if error.

findInterceptAndSegment2D (points, origin)

Finds the closest projection of a point onto a multiline. Nil intercept, empty table on return for error. Intercept is with segment containing point closest to origin.

Parameters:

• points: Table of Location3D. A list of Location3D points defining a multiline, i.e. a sequence of connected line segments.
• origin: Location3D. A Location3D whose projection will be found.

Return values:

1. Location3D The 2D intercept (zero altitude).
2. Table of two integers, which are indices into the multiline defining the vertices of the segment that had the closest projected point.

getLocationsFromOffsets (refLocation, refHeading, offsets)

Computes locations for a set of offsets from the given reference location, give a reference heading.

Parameters:

• refLocation: (Location3D) A reference location that the offsets are taken from.
• refHeading: (real) A reference heading.
• offsets: (table) A list of VectorOffset3D, relative to the unit location.

Return value:

(table) A list of Location3Ds corresponding to the input offset list.

makeRectangleAroundLineSegment2D (startLocation, endLocation, depthMargin, widthMargin)

Given two locations and two margins, make a rectangle around the line segment.

Parameters:

• startLocation: one endpoint in a line segment.
• endLocation: the other endpoint in a line segment.
• depthMargin: is the projection forward (and back).
• widthMargin: is the additional projection left (and right). The overall depth will be 2x depthMargin. The overall width will be 2x widthMargin + distance between the points. The rectangle is in latitude and longitude, altitude is ignored.

Return value:

an array of points (table) as four corners containing the line segment, with margins.

makeTrimmedRoute (routePoints, startPoint, endPoint)

Make an array of points that is a subset of the given array of points, i.e. clip a route.

Parameters:

• routePoints: Array of Location3D repesenting the vertices of a route.
• startPoint: Location3D representing the location where movement will begin, typically the position of a unit or start point for a march overlapping the route.
• endPoint: Location3D representing the location where movement will end, typically a release point for a march overlapping the route.

Return value:

array of Location3D, which is the subset of routePoints containing startPoint and endPoint, ordered in the direction of start to end. startPoint and endPoint do not have to be points in routePoints. They can be near the route. Intercepts on the route will be calculated. The routePoints are typically traversed from routePoint[1] to the last. startPoint and endPoint will be used to determine traversal direction. If it looks flipped, the return result will be the subset of routePoints in reverse order.

positionOrder (positions, heading)

Find the order of locations along a given direction

Parameters:

• positions: A list (table) of location3D.
• heading: The direction along which positions are to be sorted, in radians.

Return value:

A list of indices (table of integers) into the positions list. The first index in the list points to the position that is first along the given direction; the last index points to the position that is farthest along the given direction.