Vector Geometry Tool Plugin Points

The Vector Geometry Tool allows you to create new Axes, Vectors, Angles, etc. whose definitions are based upon other components of the tool. Additionally, it provides several plugin points:

• Custom Script Vectors
• Custom Script Axes
• Custom Script Scalar Calculation

These plugin points are used to create Vector, Axes, and Scalar Calculation objects that cannot be created using the existing Vector Geometry Tool methods. The available inputs consist of any object within the Vector Geometry Tool and a special visibility input that can perform line-of-sight and field-of-view computations. Vector Geometry Tool objects can be accessed as inputs for other plugin points as well.

Custom vectors, Custom Axes, and Custom Scalar Calculations are initialized when loaded from a file or created within STK. They are not automatically re-initialized when the file is subsequently changed. You must force an updated script to be reloaded using the GUI by choosing to modify the Custom Vector, Custom Axes, or Custom Scalar Calculation and hitting the Reload button. You do not need to hit the reload button when the scenario is reloaded; all changes made to a script file are applied when the scenario is reloaded.

Script Source File Location

Script files that are to be used with Custom Vectors, Custom Axes, and Custom Scalar Calculations must be located in a proper directory.

Custom Vector scripts must be located in one of the following directories:

• <STK install folder>/STKData/Scripting/VectorTool/Vector
• <STK user area>/Config/Scripting/VectorTool/Vector
• <STK all users area>/STKData/Scripting/VectorTool/Vector
• <scenario folder>/Scripting/VectorTool/Vector

where <STK install folder> refers to the STK installation directory, <STK user area> refers to the STK User's directory, <STK all users area> refers to the directory that contains STK application data for all users, and <scenario folder> refers to the scenario directory.

Custom Axes scripts must be located in one of the following:

• <STK install folder>/STKData/Scripting/VectorTool/Axes
• <STK user area>/Config/Scripting/VectorTool/Axes
• <STK all users area>/STKData/Scripting/VectorTool/Axes
• <scenario folder>/Scripting/VectorTool/Axes

where <STK install folder> refers to the directory path that is the parent of STKData, <STK user area> and <STK all users area> refer to the user's configuration directories, and <scenario folder> refers to the scenario directory.

Custom Scalar Calculation scripts must be located in one of the following:

• <STK install folder>/STKData/Scripting/VectorTool/Scalar
• <STK user area>/Config/Scripting/VectorTool/Scalar
• <STK all users area>/STKData/Scripting/VectorTool/Scalar
• <scenario folder>/Scripting/VectorTool/Scalar

where <STK install folder> refers to the directory path that is the parent of STKData, <STK user area> and <STK all users area> refer to the user's configuration directories, and <scenario folder> refers to the scenario directory.

Do not place your scripts directly in the Scenario folder. Doing so may cause errors with your script.

All users running the same installed version of STK share the same <STK install folder> and thus share all the Vector, Axes, and Scalar Calculation scripts stored there; all Vector, Axes, and Scalar Calculation scripts stored relative to <STK user area> are available for use for a user of any scenario; all Vector, Axes, and Scalar Calculation scripts stored relative to <scenario folder> are only available for that scenario.

If you change the scenario directory (e.g., by loading a new scenario or saving the current scenario in a new location), then the Custom Vector/Axes/Scalar Calculation scripts will be loaded using this new scenario directory, not the old one. In particular, you will need to create the appropriate directories if you save a scenario into a new location.

Creating a Custom Script

Creating a custom script requires a function or subroutine with the same name as the file (without the file extension) that will, based on the values in an array passed into the function, return an array registering all of the inputs and outputs, or return an array of the computed values. The first element of the array passed into this method will either be “register” or “compute”. It is generally good practice to have a dedicated registration method and a dedicated compute method that get called from the initial method.

If the overall array passed into the main method is empty, then the recommended way to handle that error is to just return an empty array.

Registering the Data Elements

When registering, all of the output values returned and input elements that will be used in the compute method need to be defined in an array. Each element in the array is a string that will define everything for one input or one output. In VB, those strings are keyword-value pairs linked with an = and separated by semi-colon. For MATLAB, an array is defined for each input and output and that array alternates between the keyword and the value. For outputs, derivatives are usually registered as their own element, whereas most outputs have a Derivative option.

All data elements that get registered require three values:

• ArgumentType. Either Input or Output.
• ArgumentName. A name that you choose to help identify the element.
• Name. The string that identifies what the value is in STK.

The data elements, especially the inputs, may have other required or optional key-value pairs. For more information, see the tables below and Registration Examples.

Outputs

For the script to be useful, at least one output needs to be defined. When computed, each output must be a double array of the proper length (3 for the vector and its derivative, 4 for an axes quaternion and 3 for its derivative, etc…). For VB and MATLAB, the array for each output element is assigned to the key in the object being returned. See Computing Examples for more information.

Custom Vector

The Custom Vector has the following outputs:

The Vector refers to the x, y and z components of the Vector with respect to the Reference Axes set for the Custom Vector in the Analysis Workbench. If the derivative of the vector as observed in the Reference Axes frame is known, then the script can produce the VectorRate. If VectorRate is not used, then the Custom Vector uses a numerical approximation to compute its derivative when requested.

Custom Axes

The Custom Axes have the following outputs:

Quat refers to the quaternion describing the orientation of the Custom Axes with respect to the Reference Axes set for the Custom Vector in the Analysis Workbench. The first three elements of Quat represent the vector portion of the quaternion, while the fourth element represents the scalar part. The script may generate the angular velocity of the frame as observed by the Reference Axes, if this is known, by generating AngVel as well. If AngVel is not used, then the Custom Axes uses a numerical approximation to compute its angular velocity when requested.

Custom Scalar Calculation

The Custom Scalar Calculation has the following outputs:

Available Inputs

All objects within the Vector Geometry Tool are available as inputs to Custom Script Vector, Custom Script Axes, and Custom Script Scalar Calculations. The descriptors for each type of input are shown below.

Epoch

Epoch has a single descriptor, Name that returns a double with seconds as the unit:

Vector

The descriptors for the Vector input type are as follows:

Type, Name and RefName are all required; Source, RefSource and Derivative are optional. If the Source keyword is not specified, then a default value is used. For Custom Vectors and Custom Axes, the default value is the STK path for the object that owns the Custom Vector/Axes. The RefSource keyword works similarly. The combination of Name and Source uniquely identifies the requested Vector; the vector is then resolved into components as observed in the axes specified by RefName and RefSource when its value is computed and sent to the script. If Derivative is not set or is not Yes, then just the value is given as Double:3; if Derivative has been set to Yes, then the vector and its vector derivative are computed and the values are given as Double:6 (the first 3 specifying the vector, the last 3 its derivative). The units of the components depend on the units associated with the vector; the derivative modifies the unit to be per second.

Axes

The descriptors for the Axes input type are as follows:

Type, Name and RefName are all required; Source, RefSource and Derivative are optional. If the Source keyword is not specified, then a default value is used. For Custom Vectors and Custom Axes, the default value is the STK path for the object that owns the Custom Vector/Axes. The RefSource keyword works similarly. The combination of Name and Source uniquely identifies the requested Axes; the value of the axes is then the quaternion relating the orientation of these requested axes as observed in the axes specified by RefName and RefSource. If Derivative is not set or is not Yes, then just the quaternion is given as Double:4; if Derivative has been set to Yes, then the quaternion and the angular velocity are computed and the values are given as Double:7 (the first 4 specifying the quaternion, the last 3 its angular velocity). The angular velocity is in units of radians per second.

Angle

The descriptors for the Angle input type are as follows:

Type and Name are each required; Source and Derivative are optional. If the Source keyword is not specified, then a default value is used. For Custom Vectors and Custom Axes, the default value is the STK path for the object that owns the Custom Vector/Axes. The combination of Name and Source uniquely identifies the requested Angle. If Derivative is not set or is not Yes, then just the angle is given as Double; if Derivative has been set to Yes, then the value and its derivative are computed and the values are given as Double:2. The angle is in radians; angle rate in radians per second.

Point

The descriptors for the Point input type are as follows:

Type, Name and RefName are all required; Source, RefSource and Derivative are optional. If the Source keyword is not specified, then a default value is used. For Custom Vectors and Custom Axes, the default value is the STK path for the object that owns the Custom Vector/Axes. The RefSource keyword works similarly. The combination of Name and Source uniquely identifies the requested Point; the location of that point is then resolved into components as observed in the coordinate system specified by RefName and RefSource when its value is computed and sent to the script. If Derivative is not set or is not Yes, then just the location is given as Double:3; if Derivative has been set to Yes, then the location and its derivative are computed and the values are given as Double:6 (the first 3 specifying the location, the last 3 its derivative). The location is in meters, its derivative in meters per second.

CrdnSystem

The descriptors for the CrdnSystem input type are as follows:

Type, Name and RefName are all required; Source, RefSource and Derivative are optional. If the Source keyword is not specified, then a default value is used. For Custom Vectors and Custom Axes, the default value is the STK path for the object that owns the Custom Vector/Axes. The RefSource keyword works similarly. The combination of Name and Source uniquely identifies the requested CrdnSystem. The CrdnSystem provides the location of the origin and orientation of its axes relative to the coordinate system specified by RefName and RefSource. If Derivative is not set or is not Yes, then the script is given Double:7 where the location is the first 3 elements, and the quaternion is the last 4. If Derivative has been set to Yes, then the script is given Double:13 where the first 3 elements are location, the next 3 elements its derivative, the next 4 the quaternion and the last 3 the angular velocity. The location is in meters, its derivative in meters per second.

Plane

The descriptors for the Plane input type are as follows:

Type, Name and RefName are all required; Source, RefSource, RefType and Derivative are optional. If the Source keyword is not specified, then a default value is used. For Custom Vectors and Custom Axes, the default value is the STK path for the object that owns the Custom Vector/Axes. The RefSource keyword works similarly. The combination of Name and Source uniquely identifies the requested plane; the plane is then resolved into components as observed in the axes or coordinate system specified by RefName, RefSource and RefType when its value is computed and sent to the script. The returns for the four possible combinations of RefType and Derivative values are:

Returns from Plane Input Type

The location is in meters, its derivative in meters per second.

UserInfo

User Info has a single descriptor, Type:

UserInfo returns the parent object path; e.g., Satellite/Satellite1.

Visibility

The descriptors for the Visibility input type are as follows:

Type and TargetName are required; Name, Source, RefSource, Background and FOV are optional. If the Name keyword is not given then the Point named "Center" is used. If the Source keyword is not specified, then a default value is used. For Custom Vectors and Custom Axes, the default value is the STK path for the object that owns the Custom Vector/Axes. The TargetSource keyword works similarly.

This input provides a unitless Double value that represents a measure of visibility at the location of the Point along the direction of the Vector. The value is negative if there is no visibility; positive if there is visibility. If the Vector does not have units of distance, then the computation considers the line to infinity from the Point along the Vector direction: if the line intersects the central body associated with the Source, then a negative number results (no visibility); if the line does not intersect it, then a positive number results (visibility).

If the Vector has units of distance, the visibility is computed only within that distance from the Point. For such cases, you can further restrict when visibility is said to occur by specifying the Background keyword. Consider the case where the Target is visible from the Point along the Vector direction and within the Vector's distance: if Background is set to Space then this case will indicate visibility only if the central body of the Source is not behind the Target along the Vector direction; if Background is set to CentralBody, then this case will indicate visibility only if the central body of the source is behind the Target.

Moreover, if the Vector is a displacement vector (and thus necessarily has distance units), not only is the central body associated with the Source checked against, but so are the central bodies associated with the source objects for the origin and destination Points of the displacement vector. Finally, if the Source is a Sensor, one can set FOV to Yes and visibility will not only be measured along the Vector direction, but also within the sensor's field of view (positive still meaning 'has visibility'). Because of all the complicated options, the visibility value may not vary smoothly over time.

Registration Examples

For a custom vector in VB, a registration string for the vector output would look like this:

argStr(0) = "ArgumentType = Output ; ArgumentName = vec ; Name = Vector "
argStr(1) = "ArgumentType = Output ; ArgumentName = vecRate ; Name = VectorRate "
argStr(2) = "ArgumentType = Input ; ArgumentName = posVel ; Name = Position ; Derivative = Yes "

And the argStr array gets returned.

In MATLAB, registering is a little different. Instead of a single string, you make an array of strings; the first element being the keyword, second element being the value, the next element the next keyword, next element its value... and so on. Each input or output gets a similar array and all of those arrays are put in an output array like so:

vec = { 'ArgumentType','Output',...
        'ArgumentName',’vec’,...
        'Name','Vector'};
vecRate = { 'ArgumentType','Output',...
            'ArgumentName','vecRate',...
            'Name','VectorRate'};
posVec = {  'ArgumentType','Input',...
            'Name','Position',...
            'ArgumentName','posVel',...
            'Type','Vector',...
            'Derivative','Yes'}; 
SNR = ('ArgumentType','Input',...			
	'Name','SNR',...
	'Source','access/Place-Place1-Radar-DecisionMetric-To-Aircraft-Aircraft'...	
	'Type','Scalar');	
		

… and define all of the others data elements you are going to use in a similar fashion. Finally, you take each of those arrays and return them in an array of arrays:

output = {vec, vecRate, time, posVec, bAxes, smAngle, mnPnt, bSys};

Computing Examples

When the main method is called to compute, an array will be passed into that method where each element is either a single value (if the element is time or just a scalar), or an array of values (if it was a vector) for use when computing your custom values. For example, in VB, your compute method might look like:

Dim posVel
posVel = stateData(VB_CustomScalar_Inputs.posVel) ‘ array 3 long, same name as above

In VB, when you return values, you can assign them to the results by the same name used when you registered the outputs.

Redim returnValue(2)
' vec that is returned is an array of 3 doubles: allocate it
Redim vector(3)
Redim vectorRate(3)
' set output values
vector(0) = posVel (0) * 2 ‘ out custom vector
vector(1) = posVel (1) * 2
vector(2) = posVel (2) * 2
vectorRate(0) = posVel(3) * 2
vectorRate(1) = posVel(4) * 2
vectorRate(2) = posVel(5) * 2
returnValue(VB_CustomVector_Outputs.vec) = vector ‘ same name as was registered
returnValue(VB_CustomVector_Outputs.vecRate) = vectorRate 
VB_CustomVector_compute = returnValue

With MATLAB, once you get the methodData from the input object, you can access each data element as a property, and your custom data can be assigned to the returned object by name as well. Like VB, the names must be the same as the names the data elements were registered with.

computeData = input.methodData;
		
posVelLocal = computeData.posVel;
% modify values in the posVelLocal and assign to output
output.vec = norm(posVelLocal);