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
• 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 positions are "centered" on their reference point.

Parameters:

• offsets: (table) A list of VectorOffset3D values that represent the offset of some locations from an arbitrary reference 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.

cscAsymmetricManeuver (startPosition, initialHeading, firstRadius, endPosition, finalHeading, secondRadius, secondTurnDirection)

Determines the parameters of the shortest circle-segment-circle (CSC) path from one point and heading to a second point and heading, given a turn radius. A CSC path is a path that starts with a turn of constant radius (i.e., an arc of a circle) either right or left, followed by a straight path segment, followed by a second turn (right or left) of constant radius. The turn radii may be different. Given that an entity is using the smallest turn radius available to it, this type of path is the shortest possible path to go from one position and heading to a second position and heading.
This function assumes a 2D world, so the altitude components of the input parameters are ignored. The altitude of the output is undefined.

Parameters:

• startPosition: A Location3D of the initial position.
• initialHeading: An angle in radians representing the initial heading.
• firstRadius: The radius of the first circle in the maneuver.
• endPosition: A location3D of the goal position.
• finalHeading: An angle in radians representing the goal heading.
• secondRadius: The radius of the second circle in the maneuver.
• secondTurnDirection: A string describing the required direction of the final circle. "any" or nil means choose the shortest direction, "right" means clockwise, and "left" means counter clockwise.

Return values:

1. A boolean that is true if the first turn is to the left, and false if it is to the right.
2. A number indicating the heading at which the path leaves the first circle.
3. A location3D of the end of the straight segment, when the path starts the second circle.
4. A boolean that is true if the second turn is to the left, and false if it is to the right.
5. A number which is the path length.
6. A boolean that is true if there is an error. If there is an error, the other return values will be undefined.

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.

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.