Plug-In Scripts
CONTENTS
INTRODUCTION .................................................................................... 2
INSTALLATION...................................................................................... 4
Installation for Matlab Users......................................................... 4
Installation for VBScript Users ...................................................... 4
Installation for Perl Users............................................................. 5
SCRIPTING ENVIRONMENTS ................................................................... 6
Matlab Environment.................................................................... 7
VBScript Environment ................................................................. 7
Perl Environment........................................................................ 8
FUNCTION SIGNATURES......................................................................... 8
Matlab Functions ........................................................................ 9
VBScript Functions.................................................................... 11
Perl Functions .......................................................................... 18
ASTROGATOR PLUG-IN POINTS ............................................................. 27
Custom Functions ..................................................................... 27
Calculation Objects ................................................................... 27
Custom Engine Models .............................................................. 30
Propagators ............................................................................. 33
Information on Arguments ......................................................... 37
VECTOR GEOMETRY TOOL PLUG-IN POINTS ............................................ 40
Script Source File Location ......................................................... 40
Custom Vector ......................................................................... 41
Custom Axes ........................................................................... 41
Available Inputs ....................................................................... 42
ATTITUDE SIMULATOR PLUG-IN POINTS................................................. 48
Script Source File Location ......................................................... 48
Outputs .................................................................................. 48
Inputs..................................................................................... 50
Inputs Available from the Vector Geometry Tool............................ 52
ACCESS CONSTRAINT PLUG-IN POINTS.................................................. 53
Script Source File Location ......................................................... 54
Additional Calling Modes ............................................................ 54
Constraint Property Panel .......................................................... 55
Inputs and Outputs................................................................... 55
The Status Output .................................................................... 57
Information on Constraint Plug-In Point Arguments ....................... 57
COMM PLUG-IN POINTS ....................................................................... 60
Source Transmitter Model .......................................................... 60
Receiver Model......................................................................... 63
2
Plug-In Scripts
Custom Antenna Gain ............................................................... 65
Absorption Loss Model............................................................... 66
Rain Loss Model ....................................................................... 68
Antenna Multibeam Selection Strategy......................................... 69
CommSystem Link Selection Strategy.......................................... 71
Comm Constraint ..................................................................... 74
TROUBLESHOOTING ............................................................................ 77
Syntax Errors........................................................................... 77
Checking for Proper Registration of Inputs and Outputs.................. 78
Checking for Valid values........................................................... 78
Using STK/Connect ................................................................... 79
Further Matlab Issues................................................................ 79
INDEX ............................................................................................... 80
Introduction
Plug-In Scripts provide a method for incorporating customer-specific, non-generic
modeling into STK computations. Users create scripts (written in either Matlab, Perl
or VBScript) that are executed at specified times during a computation to integrate
their own models within STK's computational framework. Plug-In Scripts provide a
simple-to-use mechanism for customizing STK while
its generic
computational algorithms.
leveraging
Python version 2.4 is also supported.
For example, consider modeling the forces on the International Space Station (ISS). The
ISS has large solar panel arrays that rotate to align with the Sun as it travels in its orbit.
Thus, the area of the vehicle that is exposed to atmospheric drag varies periodically over
each orbit due to the changing orientation of the solar panels. Normally, STK/Astrogator
assumes a constant area when computing the drag force (like almost all orbit
propagators). It is not that the computations involved with varying drag area are
difficult—they are not—rather, the reason that most integrators don't handle varying
area is that there is no generic model of variable satellite area for a user to choose. Every
satellite's drag area is very much dependent on its moving surfaces, their attitudes, and
the satellite's own attitude: that is, it is highly specific to the satellite and not generic at
all.
How can you customize your models without re-writing the software for each case?
Answer: By using Plug-In Scripts. The user can create a Plug-In Script that just
models the surface area as a function in time and have STK/Astrogator calculate the
drag force using this new surface area model. Because the user has complete control
over the script, the model can be as complicated or as simple as the user needs it to
Plug-In Scripts
3
be. The remaining aspects of integrating the orbit ephemeris (computing the drag
force based on the area computed within the script, computing other forces,
numerically integrating the equations of motion, maintaining accuracy using a step
error control method, etc.) are handled automatically by STK. This allows the user
complete flexibility in modeling just the task at hand without requiring the
development and testing of other supporting code.
Each Plug-In Script chooses its own inputs and outputs from a group of available
variables. The outputs of a Plug-In Script define its intended use: for example, a
script that outputs force model parameters can be used as an Propagator Plug-In
Script but not as an Access Constraint Plug-In Script. Because each Plug-In Script
has a very specific task, its possible outputs have been limited by design (but even
then there are still quite a few). The inputs to a script are another matter entirely:
calling user created scripts during computations would be of little use if the inputs
that were needed to create the outputs were unavailable. The Plug-In Points
described below provide a very large number of possible inputs: in many cases,
virtually all ephemeris and attitude related data from any object in the scenario can
be accessed as an input.
By providing all the required input data and leveraging existing computational
algorithms, Plug-In Scripts provide a simple, elegant, quick solution for customizing
models within STK.
The ISS example above is specific to one particular problem. Plug-In Scripts can be
used in many other computations to provide customization of many different models.
Plug-In Scripts are available for each of the following areas:
Table 1. Plug-In Script Applications
Application
Tasks Performed by Scripts
Astrogator Propagator Modeling additional forces (e.g., lift), atmospheric
Astrogator Engine
Model
Astrogator Calc
Objects
Vector Geometry Tool
Custom Vector
Vector Geometry Tool
Custom Axes
Access Constraint
Attitude Simulator
density, time-varying parameters.
Modeling engine thrust, mass flow rate, and Isp.
Modeling a user-specific computation.
Modeling a time-varying vector.
Modeling time-varying axes.
Modeling a visibility constraint that is utilized
during access computations.
Modeling external torques and implementing
attitude control laws.
4
Plug-In Scripts
Installation
The following sections contain installation instructions for Matlab, VBScript and Perl
users.
Installation for Matlab Users
STK Plug-In Scripts require Matlab 6. To use Matlab scripts, one must first perform
the STK/Matlab installation. After installation, run Matlab and, at the command
prompt, run agiInit. Then follow the steps to complete the installation.
Note to PC Users
It is important that the Matlab executable and dll's be on the user's path
environmental variable. The installation process for Matlab 6 does this;
however, if the user has uninstalled a previous version of Matlab, the old
Matlab path information may still be present in the path environmental
variable. Moreover, the old dll's may still be present on the user's system even
after uninstall. If the old path information and the old dll's are present on your
system, then the proper Matlab 6 versions may not be accessible from STK. To
remedy this problem, you will need to manually change the path
environmental variable to point to the Matlab 6 installation.
The Matlab debugger can be used to debug a Matlab function when the function is
called directly from Matlab itself; however, it is not compatible with functions called
from outside Matlab: using the Matlab debugger with STK Matlab Plug-In Scripts
can cause both programs to hang or to crash.
Note
If Matlab was started by STK, then the proper manner to close Matlab is also
from STK. To close Matlab, open the application Basic Properties window, go
to the Matlab Tab, and click the Disconnect button to close Matlab. In fact, the
quit command in Matlab will not quit Matlab if STK has opened it. The only
way to quit Matlab once started by STK is to quit STK, use the Disconnect
button as described above or to use the command 'quit force' at the Matlab
prompt.
Installation for VBScript Users
VBScript is automatically installed with Microsoft Windows and is available free.
There is no further installation step required.
Plug-In Scripts
5
The VBScript functionality in Windows is enabled through the file atl.dll. To use
STK Plug-In Scripts, you must have a copy of VBScript delivered with Windows NT
(or later). Users who have upgraded from Windows 98 to Windows NT, 2000 or XP
may not have upgraded to the correct version of atl.dll. The latest version can be
downloaded free of charge from Microsoft at its website:
http://activex.microsoft.com/controls/vc/atl.cab
Once the new software is installed, you need to register AgScript.dll as a COM
server. Open a Command Prompt and change directories until you are in the
directory containing the STK executables and dll's. The AgScript.dll is in this
directory. Now run:
regsvr32 AgScript.dll
One must be alert to distinguish between VBScript (Visual Basic Scripting Edition),
VB (Visual Basic), and VBA (Visual Basic for Applications). Some keywords and
functionality available in VB/VBA are not available in VBScript. Moreover, several
VBScript books document features that are not available in VBScript (but are
available in VB/VBA). Users may want to purchase a VBScript book that is careful
about this distinction.
If you use the MS Script Debugger, which Microsoft makes available free of
charge to debug VBScript scripts (see http:/msdn/microsoft.com/scripting), a
syntax error in the script will cause the debugger to stop at that error.
However, in general, the MS Script Debugger cannot be used to debug scripts
while they are being used by STK.
Installation for Perl Users
STK Plug-In Scripts require version 5.6.1 of Perl, which is available free. For PC
users, the version of Perl from ActiveState (www.activestate.com) is required. Perl
Plug-In Scripts were developed using build 628 of ActiveState's version of Perl—later
builds should be compatible. Contact AGI at support@stk.com if you need assistance.
Please note that you may need to set an environmental variable to enable STK Plug-
In Scripts to work with Perl. If you experience errors trying to use Perl (with a
message indicating that a file could not be found anywhere along the include path
variable given by @INC), set a system environmental variable AGPERL_LIB_PATH
to the following:
.;[Perl_Install_Directory]/lib;[Perl_Install_Directory]/site/lib
where [Perl_Install_Directory] is the directory where Perl is installed on your
computer. Directories (separated by semicolons on a PC, separated by colons on
UNIX) in the variable AGPERL_LIB_PATH are added to the include path @INC
when Perl is started. On UNIX, AGPERL_LIB_PATH should be set in the user's
.cshrc file.
6
Plug-In Scripts
After installing the correct version of Perl, you will need to copy the Perl module
STKUtil.pm from the /Connect/PERL_LIB directory into a directory
that is on the Perl library search path (i.e. a directory path contained in @INC).
Typically, users will copy
[Perl_Install_Directory]/lib, where
[Perl_Install_Directory] is the directory where Perl is installed on your computer.
The STKUtil module exports several utility functions that users may want to use in
their own scripts. To use the module, include the line
use STKUtil qw(printOut getInputArray);
the
file
to
near the top of the file. The getInputArray function is a user convenience
function for translating between references to an array and the array itself: this is
useful for dealing with inputs to Perl scripts from STK (see the section of Function
Signatures for Perl). The printOut function can be used to print out lines of text;
on a PC, it pops up a message box containing the text that the user must dismiss.
Note
On PC only, you cannot use standard input (stdin), standard output (stdout),
and standard error (stderr) to print out any messages. Instead you can print
to a file or use printOut (or use Win32::MsgBox() directly) to pop messages up
in a dialog box on the screen.
Scripting Environments
By convention, the extension of the filename determines the language to be used:
Table 2. Languages and Extensions
Extension
.m
.dll
.vbs
.pl
Language
Matlab
Matlab compiled code
VB Script
Perl
The name of the function that is called by a Plug-In script is based on the filename.
For example, the name of the function called when using the filename
C:\stk\user1\VB_ForceModel_Eval.vbs is VB_ForceModel_Eval.
Plug-In Scripts
7
Note
This convention is the same as the Matlab convention for dealing with user
defined functions (i.e., .m files). This convention was chosen to avoid name
collisions since Matlab and VBScript do not understand the concept of
namespaces.
Matlab Environment
Only one copy of Matlab is opened by STK for use with Plug-In Scripts. All Matlab
Plug-In Scripts share the same workspace environment. STK does not connect to
Matlab until some Matlab Plug-In Script attempts to execute a script. This may occur
during application start-up or when loading scenario files, depending on the Plug-In
Point being used.
VBScript Environment
Only one copy of a VBScript engine is opened by STK for use with VBScript Plug-In
Scripts. All VBScript Plug-In Scripts share the same workspace environment. STK
does not create a VBScript environment until some VBScript Plug-In Script attempts
to execute a script. This may occur during application start-up or when loading
scenario files, depending on the Plug-In Point being used.
As part of the creation process, all VBScript files (i.e. files with extension .vbs) within
certain directories are automatically loaded into the workspace. Users may add their
own VBScript files to these directories and they will be automatically loaded as well.
The directories are:
(i) /STKData/Scripting/Init
(ii) /Scripting/Init
where refers to the directory path that is the parent of STKData,
and refers to the user's configuration directory. A success or failure
message will be written for each of the files found and loaded.
Note
This mechanism allows users to create certain VBScript utilities that other
VBScript scripts may utilize, since there is no internal mechanism in VBScript
to load and execute another script.
8
Plug-In Scripts
Perl Environment
Only one copy of the Perl interpreter is opened by STK for use with Perl Plug-In
Scripts. All Perl Plug-In Scripts share the same workspace environment. STK does
not create a Perl environment until some Perl Plug-In Script attempts to execute a
script. This may occur during application start-up or when loading scenario files,
depending on the Plug-In Point being used.
As part of the creation process, all Perl files (i.e.,files with extension .pl) within
certain directories are automatically loaded into the workspace. Users may add their
own Perl files to these directories, and they will be automatically loaded as well. The
directories are:
(i) /STKData/Scripting/Init
(ii) /Scripting/Init
where refers to the directory path that is the parent of STKData,
and refers to the user's configuration directory. A success or failure
message will be written for each of the files found and loaded.
Function Signatures
Every script function has the same signature, takes one input argument and returns
one output argument. In VBScript and Perl, the input and output arguments are
arrays; in Matlab, each argument is a Matlab Struct.
Each script function is called for at least two purposes:
1) to register a list of requested inputs and outputs for the compute function; and
2) to compute the outputs based upon the inputs.
The registration process for a Plug-In Script occurs as an initialization step; if the
script successfully initializes, then it can provide the requested inputs and handle the
requested outputs when asked to compute. The list of requested inputs and outputs
cannot be changed until another
is performed. To aid
computational efficiency, the initialization process for a Plug-In Script is performed
as infrequently as possible: some Plug-In Scripts initialize only when the STK
application starts up (e.g. some calls made for Access Constraint Plug-In Points);
some re-initialize only when the user requests them to be re-initialized (e.g. Vector
Geometry Tool Plug-In Points); others re-initialize every time a computational
process starts (Astrogator Plug-In Points).
initialization step
The available input and output arguments depend on the Entry Point of the Plug-In
point itself. Some Entry Points have no inputs or outputs, but others can have many
inputs and outputs. See the documentation for each Entry Point of each Plug-In
point for the list of available inputs and outputs.