Getting Started with STK Engine

Note: This help system, which focuses only on STK Engine on UNIX, assumes that you are familiar with STK. To learn more about STK, see STK Desktop help.

The following sections provide information that will help get you started with STK Engine:

These sections differentiate three use cases:

System Requirements

Supported Operating Systems

The following table lists the specific distributions and versions tested, and for which installation directions are provided. Other Linux distributions are likely to work as well, assuming the required dependencies are installed and available.

Operating System Latest update or service pack tested
Red Hat Enterprise Linux /CentOS 7 Update 4
Ubuntu Desktop 16.04

Hardware and Software Requirements

The following table lists the hardware and software requirements.

Hardware/Software Requirements
Development disk space 1.76 GB
Deployment disk space 1.25 GB minimum, possibly more depending on specific application requirements
OpenGL / Video Card
  • Desktop Application
    High-end, OpenGL-compatible card (512+ MB RAM) that supports OpenGL 2.0+.
  • Compute Node, with graphics
    OpenGL 1.1+ using mesa software driver (possibly provided by xvfb)
  • Compute Node, no graphics
    No video card/GPU requirement, OpenGL not used
Java Oracle Java 1.6u43 minimum
libstdc++.so 6.0.13 minimum

If you are developing an interactive desktop application that integrates the STK Engine 2D and 3D controls, the following recommendations apply to the video card:

Optional Data Requirements

Optional Data Requirement
AGI Planetary Data 542 MB
World Terrain 252 MB
Maps 75 MB
Imagery 2.4 GB

Development Environment

While many Java Integrated Development Environments (IDE) (such as Eclipse, NetBeans, JBuilder, etc.) versions can be used with the STK Java API, our samples have been developed/tested specifically with the following IDEs and tools.

Tool Version
Eclipse 4.3
Ant 1.9

Installation

The following files are included:

File Description
stk_binaries_v11.3.0_x64.tgz The 64-bit STK shared libraries.
stk_data_v11.3.0.tgz The core STK data.
stk_planetary_data_v11.3.0.tgz The optional STK data for interplanetary support.
stk_jars_v11.3.0.tgz The STK Java API jar files (including Javadoc).
stk_codesamples_v11.3.0.tgz The STK Java API code samples (Contains all the STK Java API examples, including the examples for STK Desktop/Windows development).
stk_documentation_v11.3.0.tgz The documentation.

Prerequisites

A few dependencies are required in order to develop and run STK Engine on Linux examples and custom applications:

The following instructions assume that you are already familiar with installing java/eclipse/ant on your platform. Therefore, we expect those tools to already be up and running on your machine.

Linux Package Dependencies

The following package may need to be installed (if not already installed).

Installation

Package Commands
64-bit Java JDK/JRE

Preferably Oracle Java. See https://java.com/en/download/faq/develop.xml.

Alternatively the system default openjdk install.

Additionally, for the Desktop and Compute mode with Graphics use cases:

Package Commands
OpenGL Driver

Preferably native driver for your video card.

Additionally, the mesa library: mesa-libGLU.x86_64

Unpacking STK Engine

To install the core STK Engine files (needed both for development and deployment), issue the following commands:

tar -xvf stk_binaries_v11.3.0_x64.tgz
tar -xvf stk_data_v11.3.0.tgz
tar -xvf stk_jars_v11.3.0.tgz

To install the documentation and the code samples (only needed for development), issue the following commands:

tar -xvf stk_codesamples_v11.3.0.tgz
tar -xvf stk_documentation_v11.3.0.tgz

If your application requires inter-planetary capabilities, issue the following command to install the additional interplanetary data files:

tar -xvf stk_planetary_data_v11.3.0.tgz

This will create a top level directory structure (with additional sub-directories not explicitly listed here) similar to:

stk11.3.0/Agreements
stk11.3.0/bin
stk11.3.0/CodeSamples
stk11.3.0/Data
stk11.3.0/Databases
stk11.3.0/GPSAlmanacs
stk11.3.0/Help
stk11.3.0/Plugins
stk11.3.0/STKData

The top level stk11.3 directory is referred to as the <install dir> in the following sections.

Accessing the STK Engine Help System

The help system is provided as static html files. Using your preferred web browser open the <install dir>/Help/index.html file. For instance with firefox:

firefox <install dir>/Help/index.html

Setting Up the Environment

Three environment variables need to be set. Note that these variables can be set from the shell or at initialization in your custom Java application if it is more convenient for your specific workflow.

The path to the bin directory needs to be added to your LD_LIBRARY_PATH environment variable:

bash: export LD_LIBRARY_PATH=<install dir>/bin:$LD_LIBRARY_PATH

csh: setenv LD_LIBRARY_PATH=<install dir>/bin:$LD_LIBRARY_PATH

Two environment variables need to be set up to indicate where STK Engine reads its data from and where it stores the user specific configuration:

bash:

export STK_INSTALL_DIR=<install dir>
export STK_CONFIG_DIR=<location for user specific configuration data>

csh:

setenv STK_INSTALL_DIR=<install dir>
setenv STK_CONFIG_DIR=<location for user specific configuration data>

For the user specific configuration data, STK Engine will create automatically a sub-directory and use it to store the configuration. This directory will be named <$STK_CONFIG_DIR/STK11>. Under this directory you will find the user specific defaults, preferences, and configuration. By default, STK Engine will create a configuration allowing online access to the internet. If you are on a private network with no internet access, these defaults can be tweaked using the new user install.

Do not copy the $STK_CONFIG_DIR/STK11 directory from one location on the disk to another location, or from one user to another user. The files under this directory contain absolute paths that would break if the files are moved. Instead of copying the files, re-initialize the configuration directory at the new location using one of the methods described next.

New User Install, Online Data & Proxy

By default STK Engine initializes transparently the user configuration the first time an application exercising engine is run for a specific user. The default configuration configures STK Engine to allow access to the internet for downloading additional data, such as Bing imagery, databases, TLE files, and other data from the AGI Web site during an STK session.

This default is not appropriate if your machine does not have internet access. On a network with no internet access, STK Engine will try to connect to the AGI data sources, possibly incurring delays at startup. To prevent that situation, turn online access off. This can be done using the <install dir/bin/stkxnewuser> command line utility, or from your custom application code.

To turn off online access using the command line utility:

<install dir>/bin/stkxnewuser --allowOnline=no

The stkxnewuser utility can also be used to reinitialize the user configuration to the default settings. It uses the $STK_CONFIG_DIR to determine where to store the user information.

Turning off online access can also be achieved programmatically at startup in your custom application using the following interfaces and methods:

IAgSTKXApplication app = …;
app.executeCommand(“SetOnlineOperations / Off”);

It is also possible that your network provides access to the internet but behind a proxy that requires authentication. In that case your custom application will need to configure the proxy at startup using the following snippet:

IAgSTKXApplication app = …;
app.setOnlineOptions(
                        <useProxy?>, <server>, <port>, <user>, <password>, <save password?>);

Out of the box the code samples included in this version do not configure a proxy. So if you are in this situation and want to enable online access when running the code samples, you will need to add this snippet code to the example initialization.

Obtaining and Registering AGI Licenses

STK Engine uses flexlm for licensing. You can either use node locked or network licenses.

Node-locked License

You will need your flexlm Host ID to register AGI product licenses using node locked licenses.  Run the following command to get this information:

<install dir>/bin/aglmhostid

Do not use the system hostid command on linux.

Network License

Note: License Server v11.13 or higher is required.

Network licenses are also supported. Configuring a Network License Server explains how to get the license server up and running in your organization.

License File Deployment

When you request a license, you will receive a .lic file. You need to copy that file to one of the locations where STK Engine looks for that information:

Testing the Installation

Use the following procedure to verify that the development environment was set up correctly.

Check Native Library Setup

The first step to verify that your installation is functional is to verify that the native libraries required by STK Engine are available on your system.

To verify that the dependencies required for computations are available issue the following command:

ldd -r <install dir>/bin/libagstkxengine.so | grep "not found"

In the case of the Desktop application and/or Compute node with graphics use cases, also verify that the native libraries required for graphics are available. Issue the following command:

ldd -r <install dir>/bin/libagstkobjectgfx.so | grep "not found"

The above commands should not find any match, and just return without printing any output. If missing dependencies are reported, the missing libraries need to be installed using the package management tools for your linux distribution (i.e., yum or apt-get).

Once the above test successfully passes, run connectconsole, a small utility that can be used to exercise STK Engine through Connect. Start the utility using (note that the option is specified using two dashes; i.e. --):

<install dir>/bin/connectconsole --noGraphics

If you do not have a license yet, it will return the following message:
             E: Failed to enable connect (80040001: License check failed)
Once you have a license, it will return the following messages and wait for Connect commands:

<install dir>/bin/connectconsole  --noGraphics
2016-03-10 15:14:15.534 I: STK/CON: Initializing STK/CON module.
2016-03-10 15:14:15.535 I: STK/CON: Accepting connection requests

You can exit using CTRL-C. This indicates that all the required dependencies and shared libraries are available.

At this point, if your application requires using the STK Engine 2D & 3D controls and graphics support, you might also want to check that OpenGL is working. If everything is set-up correctly, the command below will open a new scenario with a 2D and 3D view.

<install dir>/bin/connectconsole --new

Now that you have verified that all the shared libraries are available and functional, the next step is to verify that the Java examples work properly.

Verifying Setup of Java Code Samples

For the Desktop and Compute mode with Graphics use cases:

  1. Open a new shell window. Make sure that you have set up the environment variables in the shell window, as described above.

  2. Go to the samples directory by entering:

  3. cd <install dir>/CodeSamples/CustomApplications/Java/AWT_STK_X_Globe_View
  4. Make sure $JAVA_HOME is configured correctly. It should point to the 64-bit JDK. This can be verified as follows:
  5. $JAVA_HOME/bin/java -d64 -version It should print out the version number and no error.
  6. Once you have verified that JAVA_HOME points to the expected JDK, run the example by entering:
  7. ant run

    The example will be compiled and then run. An application will open. In the scenario menu use the New Scenario option to create a new scenario. The application will display a new 3D view as shown below.

Alternatively, for the Compute mode with no graphics use case:

  1. Open a new shell window. Make sure that you have set up the environment variables in the shell window, as described above.

  2. Go to the samples directory by entering:

  3. cd <install dir>/CodeSamples/CustomApplications/Java/AWT_STK_X_NoGraphics
  4. Make sure $JAVA_HOME is configured correctly; it should point to a 64-bit JDK. This can be verified as follows:

  5. $JAVA_HOME/bin/java -d64 -Djava.awt.headless=true -version If this is a 64-bit jvm it should print out the version number and no error. If it is not a 64-bit jvm it will return an error (the error message will be similar to: “Running a 64-bit JVM is not supported on this platform.”).
  6. Once you have verified that JAVA_HOME points to the expected JDK, run the example by entering:
  7. ant run

    The example will be compiled and then run. The application will compute access between a facility and a satellite, and will output the results to the console.

This demonstrates that your environment is fully setup and ready for development. This concludes the installation instructions. For the next step you can explore the documentation and the other examples. See Configuring Eclipse Projects and Configuring the Samples with the Eclipse IDE.

STK Engine for UNIX 11.3.0