FeatureSet
(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)
A FeatureSet is an object that contains a set of features. A FeatureSet is created through a vrf: function that queries the terrain and gets features with specified attributes. The Lua script can then call FeatureSet methods to get information about the features in the set.
Because querying the terrain and gathering desired features may take a long time, the vrf: functions that create FeatureSets do not necessarily finish filling the set when they return a FeatureSet object. Queries can only be made of the FeatureSet when the isLoaded() method returns true. Therefore, the Lua script should create a FeatureSet in the script's init() or tick() function, and then check isLoaded() on succeeding ticks until it returns true.
A FeatureSet is similar to a vector in that the features in it are referenced by an index. Lua scripts cannot use bracket notation (i.e., fs[index]), but all of the methods that identify a particular feature in the set take an index as their first argument. The first feature is at index 1, and the last at getFeatureCount().
Function List
| getFeatureAttributeNames (index) | Returns a vector list of all attribute names for the particular feature index. |
| getFeatureAttributeValue (index, attribute) | Returns an attribute value for the specified index and attribute name. |
| getFeatureCount () | Returns the number of features in the feature set. |
| getFeatureType (index) | Returns a string of the type of feature (point, line, area). |
| getLocation3D (index) | Returns the location of the feature. |
| getLocations3D (index) | Returns a vector of points for the particular feature. |
| hasAttributeNamed (index, attribute) | Returns true if there is an attribute named on the particular feature. |
| isAreaFeature (index) | Returns true if the feature at the particular index is an area feature. |
| isLinearFeature (index) | Returns true if the feature at the particular index is a linear feature. |
| isLoaded () | Returns true if the feature set is fully loaded with features. |
| isPointFeature (index) | Returns true if the feature at the particular index is a point feature. |
Functions
- getFeatureAttributeNames (index)
-
Returns a vector list of all attribute names for the particular feature index. This function is intended to be used while developing a script, to show the programmer what attribute names are provided by the terrain database.
Will throw an exception if index is out of range or if feature set is not loaded.Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features
Return value:
- List of names (table of strings) of attributes that can be used to retrieve data for a feature.
-
- getFeatureAttributeValue (index, attribute)
-
Returns an attribute value for the specified index and attribute name. Will throw an exception if the index is out of range or if the feature set is not loaded
Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features. -
attribute: Name (string) of attribute to get feature value for.
Return value:
- Value of attribute. This can be a number or a string, depending on the attribute.
-
- getFeatureCount ()
-
Returns the number of features in the feature set.
Return value:
- Returns the number of features or throws an exception if the feature set is not loaded.
- getFeatureType (index)
-
Returns a string of the type of feature (point, line, area). Will throw an exception if index is out of range or feature set is not loaded.
Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features
Return value:
- Return type (string) of feature (point, line, area)
-
- getLocation3D (index)
-
Returns the location of the feature. If a multi-point feature (i.e., a line or area), returns the first point. Will throw an exception if the index is out of range, the feature set is not loaded.
Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features
Return value:
- Location3D of the feature.
-
- getLocations3D (index)
-
Returns a vector of points for the particular feature. If a point feature returns a vector of 1 point. Will throw an exception if the index is out of range, the feature set is not loaded.
Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features
Return value:
- Vector (table) of Location3Ds describing the feature.
-
- hasAttributeNamed (index, attribute)
-
Returns true if there is an attribute named on the particular feature.
Parameters:
-
index: 1-based index of feature to look up. Use getFeatureCount for number of available features. -
attribute: Name (string) of the attribute to check for existence of.
Return value:
- Returns true if the feature has the given attribute.
-
- isAreaFeature (index)
-
Returns true if the feature at the particular index is an area feature. Will throw an exception if index is out of range or feature set is not loaded.
Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features
Return value:
- True if feature set is an area feature
-
- isLinearFeature (index)
-
Returns true if the feature at the particular index is a linear feature. Will throw an exception if index is out of range or feature set is not loaded.
Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features
Return value:
- True if feature set is a linear feature
-
- isLoaded ()
-
Returns true if the feature set is fully loaded with features. Operations performed on a feature set that is not loaded will throw an exception.
Return value:
- True if feature set is loaded or false if not.
- isPointFeature (index)
-
Returns true if the feature at the particular index is a point feature. Will throw an exception if index is out of range or feature set is not loaded.
Parameters:
-
index: 1-based index of feature to look up. See getFeatureCount for number of available features.
Return value:
- True if feature set is a point feature.
-