Access Constraint Plugin Points
STK already provides numerous Access constraints that can be used to model visibility between objects. However, new mission proposals often involve new visibility requirements that cannot be readily configured using the existing Access constraints. While this is a prime motivator for incorporating new constraints directly into the STK software, non-generic constraints are rarely added. Access Constraint plugin scripts provide a method for adding these customized constraints directly into visibility computations.
The access constraint plugin script functionality is designed to be a seamless extension of the basic constraint processing.
When configured for an object, STK processing will utilize the plugin script when computing Access between objects. The plugin script appears as a Min/Max constraint to the rest of the STK processing.
An access constraint plugin script processes inputs (which it has requested) and returns a single result (a double), for each access processing step. The value provides a (continuous) measure of visibility between the FromObject and the ToObject at each requested sample time. This value is utilized by the access algorithms during sampling to predict and detect whether the value crosses the Min or Max value set for the constraint. The classic example of a visibility constraint value is the elevation angle of the ToObject with respect to the FromObject (which of course is already a constraint that STK provides).
The script may request input data from either object involved in an Access computation, using the descriptors that are documented below. Many of the keyword Names use the prefix "from" or "to" to indicate from which object the data should be obtained. In this context, "from" refers to the object on which this plugin constraint has been applied and "to" refers to the other object: this association of "from" and "to" is independent of the manner in which Access is computed. For example, if this plugin constraint is set on MyFacility, then the from Object is MyFacility even when the Access is computed from MySatellite to MyFacility.
There are three steps to utilizing an access constraint plugin script:
- The script must be written to conform to a well-defined calling convention.
- The script source file must be placed in a specific directory path, which is searched at STK application startup.
- A particular object's constraints must be configured to use the plugin script by setting the Min and/or Max value in the Constraint Property page.
The first two steps make the constraint available for certain classes of objects.
The user interface for access constraint plugins does not follow STK default units.
Script Source File Location
The script source files must reside in the proper directory search path to be able to utilize the plugin script functionality. They must be located in one of the following directories:
- <STK install folder>/STKData/Scripting/Constraints
- <STK user area>/Config/Scripting/Constraints
- <STK all users area>/STKData/Scripting/Constraints
where <STK install folder> refers to the STK installation directory, <STK user area> refers to the STK User's directory, and <STK all users area> refers to the directory that contains STK application data for all users.
Do not place your scripts directly in the Scenario folder. Doing so may cause errors with your script.
Additional Calling Modes
In addition to the standard register and compute calling modes for plugin scripts, constraint Plugin Points utilize two additional modes: GetConstraintDisplayName and GetAccessList.
During STK application start-up, the Scripting/Constraints directories are searched for plugin scripts. Each script is called in GetConstraintDisplayName and GetAccessList calling modes, and then the constraint is registered as an available constraint in the STK application. Registration of constraints happens only once, on application start-up: while editing the script file will affect subsequent calls in the register and compute calling modes, GetConstraintDisplayName and GetAccessList are never called after registration, and any edits to these functions during an STK session have no effect.
Get Constraint Display Name Method
The GetConstraintDisplayName mode is used to ask the script for a String containing the name of the constraint (this name is used on the Constraint Property page, for save/load, and for STK Connect). It is not passed a methodData parameter. The methodData value is undefined. The name may contain underscores but spaces and special characters are not allowed. The alphabetic case of the returned value is utilized.
Get Access List Method
The GetAccessList method is called with a String methodData value containing an STK class name (i.e., the class name of a FromObject). The method is expected to return a String value containing a list of STK classes that are allowed to be a ToObject when used with this constraint. The output String is a list of STK classes separated by commas, e.g.
Satellite,Facility,GroundVehicle
The returned class names are case sensitive and must exactly match valid class names to be implemented. The GetAccessList method is called once for each class that is registered in STK, with a different class name as the input each time. This call has been provided so that the script can restrict applicability of its computations to certain FromObject/ ToObject class pairs (e.g. if the script's value is computed assuming that both the FromObject and the ToObject are fixed on the earth, then the script can restrict its applicability to the Facility, Place, and Target classes).
Constraint Property Page
When the plugin script constraint is configured properly, it will appear in the Constraints Plugin properties page, under the name given by the GetConstraintDisplayName call, for the object classes that it indicated in the GetAccessList method call. The Constraints Plugin properties page will list all Plugin constraints available for the Class. Select a constraint and set a Min and/or Max value for the constraint. Click Apply before leaving the page.
Inputs and Outputs
The Access Constraint Plugin Point has the following available inputs and outputs:
|
Keyword
|
ArgumentType
|
Name
|
RefName
|
|---|---|---|---|
| Value | Output | Status | --- |
| Value | Output | Result | --- |
| Value | Output | maxRelMotion | --- |
| Value | Input | Epoch | --- |
| Value | Input | fromObjectPath | --- |
| Value | Input | toObjectPath | --- |
| Value | Input | fromCbName | --- |
| Value | Input | toCbName | --- |
| Value | Input | range | --- |
| Value | Input | timeDelay | --- |
| Value | Input | fromPosition | Fixed Inertial |
| Value | Input | toPosition | Fixed Inertial |
| Value | Input | fromRelPosition | Fixed Inertial |
| Value | Input | toRelPosition | Fixed |
| Value | Input | fromVelocity | Fixed Inertial |
| Value | Input | toVelocity | Fixed Inertial |
| Value | Input | fromRelVelocity | Fixed Inertial |
| Value | Input | toRelVelocity | Fixed Inertial |
| Value | Input | fromAngularVelocity | Fixed Inertial |
| Value | Input | toAngularVelocity | Fixed Inertial |
| Value | Input | fromQuaternion | Fixed Inertial |
| Value | Input | toQuaternion | Fixed Inertial |
| Value | Input | fromCbAppSunPosition | Fixed Inertial |
| Value | Input | toCbAppSunPosition | Fixed Inertial |
Using the Vector Geometry Tool as an Input Source
In addition to the descriptors shown above, all Vector Geometry Tool inputs are also available for a constraint plugin script.
Moreover, when creating Vector Geometry Tool descriptors, you can use the notation “Access/toObj” and “Access/fromObj” as the value for the keywords Source and RefSource. Example:
Type = Axes ; Name = Body ; Source = Access/toObj.
For information on requesting an input from the Vector Geometry Tool, see Vector Geometry Tool Plugin Points.
When using an Access plugin constraint as a Figure of Merit, the use of Access/toObj and Access/fromObj should be avoided since the plugin will not be re-initilialized for each new Coverage Asset before computing to that asset. Instead, the plugin will be initialized for all assets *before* computing for any, effectively resolving the object names using the last asset being considered.