VR-Forces Lua Documentation

• Table of Contents

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

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.

cscAsymmetricManeuver (initialPosition, initialHeading, firstRadius, finalPosition, finalHeading, secondRadius)

Determines the parameters of the shortest circle-segment-circle (CSC) path from one point and heading to a second point and heading, given a minimum 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. 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:

• initialPosition: 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.
• finalPosition: 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.

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)

returns the better intercept from origin to either of the two segments, and a number identifying the segment chosen. @param @param

Parameters:

• segmentOnePoints2D:
• segmentTwoPoints2D:
• origin2D:

Return value:

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

findBetterIntercept2D (segmentOnePoints2D, segmentTwoPoints2D, origin2D)

returns the better intercept from origin to either of the two segments, and a number identifying the segment chosen. @param @param

Parameters:

• segmentOnePoints2D:
• segmentTwoPoints2D:
• origin2D:

Return value:

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

findIntercept2D (points, origin)

Finds the intercept with the given multipoint line and distance to the intercept. 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, from start to end.
• origin: Location3D. A Location3D from which to determine intercept to line.

Return value:

Location3D, number. Location3D of the 2D intercept (zero altitude). Number is the distance in meters. Nil if error.

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.