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

pathUtil

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

pathUtil is a collection of utility functions that help with path planning and ground-clamping points on a route. To use, require this file and refer to the module in the function calls:
local pathUtil = require "pathUtil"
airRoute = pathUtil.pathUtilMakeAirRoute(rawRoute, ...


Function List

Functions

closestPointOnPath (path, testPt, do2D, lookup)

Find the closest segment of the given path to the given point.

Parameters:

• path: table of Location3D (or other, see below)
• testPt: Location3D The test point to analyze.
• do2D: bool (optional) If true, the path and points are all treated as if their altitude = 0. Defaults to false. Parameter must be present if lookup function is used.
• lookup:

Return values:

1. onPath bool When false, indicates that the test point does not project onto any of the path segments.
2. index integer The index of the path segment containing the projection of the test point.
3. segmentPosition number The position along the segment of the test point projection.
4. location Location3D The location of the projection of the test point.
5. distance number The distance of the test point to the closest point on the path.

computePositionOnPath (path, index, segmentPosition, distance)

Find location along path. Given a distance, a path, and a position along the path, find the position that is distance farther along the path.

Parameters:

• path: A table of Location3D
• index: integer An index into the path.
• segmentPosition: number The distance of the input position beyond the path point given by the index. Can be negative.
• distance: number. The distance along the path from the given position that deterines a new position. Can be negative.

Return values:

1. onPath boolean If false, the new position is beyond the end of the path.
2. newLocation Location3D The location of the result. If beyond the end of the path, it will be on an extension of the last segment (or first, if distance is negative).
3. newIndex number. The index of the last vertex before the location, i.e. the vertex with the smaller index on the segment where the new position is.
4. newPosition number The distance from the newIndex vertex of the new position.

distanceOfPointToSegment (pt1, pt2, testPt)

Determine the distance of a point to a line segment and its projection onto the segment.

Parameters:

• pt1: Location3D First point of segment.
• pt2: Location3D Second.
• testPt: Location3D Point to analyze. Return:

Return values:

1. isProjectionBetweenPoints bool True if the projection of the point onto the line containing the segment is between the two points.
2. distance number The distance of the testPt from the line segment.
3. projection Location3D The location of the projection of the testPt if it is between the end points, or one of the endpoints otherwise.
4. segmentPosition number The distance from pt1 to pt2 where the projection falls on the segment (ranges from 0.0 to ).

locationListFromPathPart (pathPart)

Returns a list of vertex locations given a path part from a multi-part path. These can be used in other path util functions.

Parameters:

• pathPart: A path part that is an element in a multi-part path, where a multi-part path is the structure returned from vrf:computePathThroughFeatures().

Return value:

A list (table) of Location3D.

pathUtilMakeAirRoute (points, offset)

Given points, intersect each segment with the terrain. If the segment is blocked, insert a new point clamped to offset above terrain.

Parameters:

• points: is a table of Location3D
• offset: is a double indicating a height to raise the points above the terrain.

Return values:

1. a table of Location3D describing the new route.
2. boolean flag indicating that terrain was available and the operation was completed. If the operation was not completed, repeat it in a subsequent call.

pathUtilMakePointsClampedToTerrain (points, offset, clampFirst, clampLast)

Clamp the points to the terrain, using the given offset. Given a set of points and an offset, intersect the terrain and set the Altitude component of each point at the terrain altitude + offset. Note that altitude will correspond to the first intersection with the terrain at that location, irrespective of surface (water, rooftop, etc.) Returns new table of points, and boolean "true" to indicate that all the points were clamped. Caller might have to repeat calls to this to get a complete answer, because terrain tiles might not be finished loading. Input:

Parameters:

• points: Table of Location3D()
• offset: Number. Height in meters above the terrain to offset each route point.
• clampFirst: Boolean. Optional. If false, then the first point in the path is left unchanged. Default true.
• clampLast: Boolean. Optional. If false, then the last point in the path is left unchanged. Default true.

Return values:

1. Table of Location3D().
2. Boolean indicating whether terrain data was found for all points.

pathUtilReducePoints (points, thresholdMeters, interpolateFlag)

Reduce Path Vertices.

Parameters:

• points: A table of Location3Ds
• thresholdMeters: A number indicating the minimum distance desired between points.
• interpolateFlag: boolean

Return value:

Table of Location3D that is the input list after removing those that are too close together

printPointsToConsole (printFcn, points)

Print points to vrf object console

Parameters:

• printFcn: print function (from vrfutil.lua): printDebug, printVerbose, printInfo, printWarn, or printError
• points: A table of Location3Ds