`terrainReasoningUtil`

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

Terrain Reasoning Utilities

Summary

Terrain Reasoning Utilities provide helper functions for processing the results of terrain reasoning queries.

Dependencies

Please make sure that this is preceded by these inclusions:

 require "vrfutil" 
 require "formationUtils"

Usage

require "terrainReasoningUtil"

Constants

Constant	Description
_NumElementsInGroup = 5	The number of elements in a position group returned by vrf:findPositionGroupsInArea(...)
_NumElementsInPair = 2	A textual mnemonic for a non-intuitive numerical value that indicates a limit on how many Location3Ds constitute a fighting position returned by terrain reasoning queries.
_IndexOfPairsTableInPositionGroup = 5	In a position group returned from vrf:findPositionGroupsInArea(...), in what element can one find the position pairs? E.g. local position_pairs = position_group[_IndexOfPairsTableInPositionGroup]

Function List

clampLocationToTerrain (location, offset, default)	Clamps a given location to the terrain with additional offset, or a default altitude if terrain query fails.
computeDefaultFightingPostionsFromFormation (unit, location, targetLocation, formationName)	Returns a fighting position pair based on the results of a terrain query, or a default location based on formation if the query results are empty.
extendFightingPositions (positions, additionalNumber, directionVector3D)	Add additional positions offset from the last position in the given direction (with range).
flattenPositionGroupsToPositionPairs (groupsIn, pairsOut)	Given an array of position pair groups in the form of {{group}, ...} where group is {,,,,{{,},{,}}} Return all the shoot-hide positions in the form {{,},{,}}}
laneCheckCellHasGroups (laneTable, lane, row)	Inspects a lane table at a given lane,row cell to see if it has position groups.
laneCheckValidAddress (laneTable, lane, row)	Returns true if lane and row are valid indices into table
laneFindPositionGroups (laneTable, lane, row)	Given a lane and a row index, return the position groups.
laneInsertPositionPair (laneTable, lane, row, pair)	Given a valid address, append a position pair
laneMakePositionGroup (laneTable, lane, row)	Make a new, empty position group at the given address in the lane table.
makePositionGroupLanes (numLanes, laneWidth, cellLength, origin, heading, distance, positionGroups)	Given an array of position groups and some geometric parameters, return a grid of lanes and rows with those groups.
positionGroupSorter (sideA, sideB)	Given entries {group, #}, return true if sideA[2] is less than sideB[2] else return false
printPositionGroupLanes (lanes)	Print lane metadata returned from makePositionGroupLanes(...)
printPositionGroups (groupsIn)	Iterates through a list of position groups and writes them to console.
printPositionPairs (pairsIn)	Iterates through a list of position pairs and writes them to console.
queryResultOrDefaultResult (queryResultPositionPairs, unit, location, targetLocation, formationName)	Returns either the non-empty table of position pairs from a terrain query, or a default table of position pairs.
sortGroupsLeftRight (positionGroups, origin, heading)	Sorts position groups left to right according to a reference location and a heading
sortGroupsNearFar (positionGroups, origin, heading)	Sorts position groups near to far according to a reference location and a heading

Functions

clampLocationToTerrain (location, offset, default)

Clamps a given location to the terrain with additional offset, or a default altitude if terrain query fails. given a Location3D and an optional offset # and optional default altitude #, set the altitude of that location based on a terrain height query. If the query is unable to return a result, use the optional default altitude. returns nothing

Parameters:

location: Location3D. The location to clamp to terrain.
offset: Number. How many additional meters above the terrain to clamp?
default: Number. The altitude to use if terrain is not available.

Return value:

nothing. The location is altered directly.

computeDefaultFightingPostionsFromFormation (unit, location, targetLocation, formationName)

Returns a fighting position pair based on the results of a terrain query, or a default location based on formation if the query results are empty. Create a table of positions based on formation offsets at a location.

Parameters:

unit: (SimObject) The unit to compute formation positions for.
location: (Location3D) The center of the desired unit position.
targetLocation: Location3D of a place that the formation should face (for orientation).
formationName: string containing the desired formation name.

Return value:

If the unit has a formation with the given name, a list (table) of ground-clamped Location3D position pairs in the form {{shootLocation,hideLocation}...}. If the formation name is not recognized, the table will be empty.

extendFightingPositions (positions, additionalNumber, directionVector3D)

Add additional positions offset from the last position in the given direction (with range).

Parameters:

positions: Table. A list of position pairs {{shootLocation,hideLocation}...}
additionalNumber: Number. How many more do you want?
directionVector3D: Vector3D. In what direction do you want to expand?

flattenPositionGroupsToPositionPairs (groupsIn, pairsOut)

Given an array of position pair groups in the form of {{group}, ...} where group is {,,,,{{,},{,}}} Return all the shoot-hide positions in the form {{,},{,}}}

Parameters:

groupsIn: a table of position groups in proper form
pairsOut: a table to receive the position pairs

laneCheckCellHasGroups (laneTable, lane, row)

Inspects a lane table at a given lane,row cell to see if it has position groups.

Parameters:

laneTable: Table. See makePositionGroupLanes(...)
lane: Number. Which lane in the table?
row: Number. Which row in the lane?

Return value:

Boolean. Return true if the indices are valid and cell at the given address has position groups

laneCheckValidAddress (laneTable, lane, row)

Returns true if lane and row are valid indices into table

Parameters:

laneTable: Table. See makePositionGroupLanes(...)
lane: Number. Which lane in the table?
row: Number. Which row in the lane?

Return value:

true if lane and row are both > 0 and do not exceed the number of lanes or rows in the table.

laneFindPositionGroups (laneTable, lane, row)

Given a lane and a row index, return the position groups. If no valid positions are in that cell, attempt to find positions in the next row. That means check one row ahead in same lane. If nothing is found, check one row ahead in adjacent lanes. If still nothing is found, fill the requested cell with a stub group of position pairs. Returns groups, or nil if lane or row are not valid indices for the lane table.

Parameters:

laneTable: Table. See makePositionGroupLanes(...)
lane: Number. Which lane in the table?
row: Number. Which row in the lane?

Return value:

Table or nil. If not nil, then it is an array of position groups in the form returned from vrf:findPositionGroupsInArea(...)

laneInsertPositionPair (laneTable, lane, row, pair)

Given a valid address, append a position pair

Parameters:

laneTable: Table. See makePositionGroupLanes(...)
lane: Number. Which lane in the table?
row: Number. Which row in the lane?
pair: Table. A list (array, table) of 2 elements, each Location3D, as in {shootLocation,hideLocation}

laneMakePositionGroup (laneTable, lane, row)

Make a new, empty position group at the given address in the lane table. Given a cell address in lane table Check that it is missing positions If it is missing positions, make one. Returns groups at that cell.

Parameters:

laneTable: Table. See makePositionGroupLanes(...)
lane: Number. Which lane in the table?
row: Number. Which row in the lane?

Return value:

Table. A list of position groups at that address, can be zero. List in form of vrf:findPositionGroupsInArea(...)

makePositionGroupLanes (numLanes, laneWidth, cellLength, origin, heading, distance, positionGroups)

Given an array of position groups and some geometric parameters, return a grid of lanes and rows with those groups. Arrange those groups left to right, near to far, in a grid. Lanes are arranged left to right according to the direction from the given origin. The return array of lanes is a series of tables within tables. lanes = { -- metadata related to the creation of the lane array lanes.width = # laneWidth meters ,lanes.length = # cellLength ,lanes.origin = Location3D origin ,lanes.heading = # heading ,lanes.distance = # distance ,lanes.count = # lanes ,lanes.rows = # numRows ,[1] = { -- the first lane { -- row 1 } ... } ,[#] = { ... } }

Parameters:

numLanes: is how many lanes to return.
laneWidth: # in meters for width left to right for one lane
cellLength: # in meters for the back to front length of a cell (row cell) in a lane
origin: Location3D of the starting point
heading: # in radians the direction to face away from origin, used to determine left/right, forward.
distance: # meters the overall length of the lanes, from origin to target. distance / cellLength determines the number of cells in a lane.
positionGroups: results from a terrain query. A table in form of {{,<#>,<#>,<#>,{{,},...},...}

Return value:

, [2] = ... [#] = } where is a list of groups in the form returned by vrf:findPositionGroupsInArea(...)

positionGroupSorter (sideA, sideB)

Given entries {group, #}, return true if sideA[2] is less than sideB[2] else return false

Parameters:

sideA: {group, #} Where group is a position group in a list returned from vrf:findPositionGroupsInArea(...) and # is a distance
sideB: {group, #} Where group is a position group in a list returned from vrf:findPositionGroupsInArea(...) and # is a distance

printPositionGroupLanes (lanes)

Print lane metadata returned from makePositionGroupLanes(...)

Parameters:

lanes: Table. See makePositionGroupLanes(...)

printPositionGroups (groupsIn)

Iterates through a list of position groups and writes them to console.

Parameters:

groupsIn: a table in form of {{,<#>,<#>,<#>,{{,},...},...}

printPositionPairs (pairsIn)

Iterates through a list of position pairs and writes them to console.

Parameters:

pairsIn: a table of shoot-hide position pairs in the form {{Location3D,Location3D},...}

queryResultOrDefaultResult (queryResultPositionPairs, unit, location, targetLocation, formationName)

Returns either the non-empty table of position pairs from a terrain query, or a default table of position pairs. Create a table of positions based on formation offsets at a location.

Parameters:

queryResultPositionPairs: list (table) of position pairs returned from a terrain reasoning query, in form {{shootLocation3D, hideLocation3D},...}
unit: SimObject of the unit to compute formation positions for.
location: Location3D of the place where the formation will be positioned.
targetLocation: Location3D of a place that the formation should face (for orientation).
formationName: string containing the desired formation name.

Return value:

If #queryResultPositionPairs is greater than zero, returns queryResultPositionPairs, else computeDefaultFightingPostionsFromFormation(...)

sortGroupsLeftRight (positionGroups, origin, heading)

Sorts position groups left to right according to a reference location and a heading

Parameters:

positionGroups: Table. A list of position groups, as returned from vrf:findPositionGroupsInArea(...).
origin: Location3D. Reference point.
heading: Number. Heading in radians from the reference point.

Return value:

Table. Position groups ordered left to right based on pivot location. See vrf:findPositionGroupsInArea(...).

sortGroupsNearFar (positionGroups, origin, heading)

Sorts position groups near to far according to a reference location and a heading

Parameters:

positionGroups: Table. A list of position groups, as returned from vrf:findPositionGroupsInArea(...).
origin: Location3D. Reference point.
heading: Number. Heading in radians from the reference point.

Return value:

Table. Position groups ordered near to far based on pivot location. See vrf:findPositionGroupsInArea(...).

VR-Forces Lua Documentation

terrainReasoningUtil

Terrain Reasoning Utilities

Summary

Dependencies

Usage

Constants

Function List

Functions

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Parameters:

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Return value:

Parameters:

Return value:

Parameters:

Return value:

`terrainReasoningUtil`