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 2
Red Hat Enterprise Linux /CentOS 6 Update 8
Ubuntu Desktop 16.04

Recommended Hardware and Software Requirements

The following table lists the recommended hardware and software requirements.

Hardware/Software Requirements
Development disk space 1.2 GB
Deployment disk space 735MB 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

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 290 MB

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.2.0_x64.tgz The 64-bit STK shared libraries.
stk_binaries_v11.2.0_x86.tgz The 32-bit STK shared libraries.
stk_data_v11.2.0.tgz The core STK data.
stk_planetary_data_v11.2.0.tgz The optional STK data for interplanetary support.
stk_jars_v11.2.0.tgz The STK Java API jar files (including Javadoc).
stk_codesamples_v11.2.0.tgz The STK Java API jar files (including Javadoc).
stk_codesamples_v11.2.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.2.0.tgz The documentation.

Prerequisites

A few dependencies are required in order to develop and run STK Engine on Linux examples and custom applications. These dependencies depend on the CPU architecture that you are targeting:

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.

Red Hat Enterprise Linux & CentOS Package Dependencies

On RHEL & CentOS the following packages may need to be installed (if not already installed).

64-bit 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.

32-bit Installation

For all use cases:

Package Commands
32-bit Java JDK/JRE Preferably Oracle Java. See https://java.com/en/download/faq/develop.xml
32-bit libraries

sudo yum install glibc.i686
sudo yum install bzip2-libs.i686

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

Package Commands
32-bit libraries

sudo yum install libX11.i686

32-bit OpenGL Driver Preferably the native driver for your video card.
Alternatively, the mesa libraries:
sudo yum install mesa-libGL.i686
sudo yum install mesa-libGLU.i686

Ubuntu Desktop

On Ubuntu the following packages may need to be installed (if not already installed).

64-bit Installation

Package Commands
64-bit Java JDK/JRE Preferably Oracle Java. See https://java.com/en/download/faq/develop.xml.
Alternatively, openjdk:
            sudo apt-get install openjdk-7-jdk

32-bit Installation

For all use cases:

Package Commands
Support for 32-bit applications

 sudo dpkg --add-architecture i386
 apt-get update
 apt-get upgrade

32-bit libraries

sudo apt-get install libbz2-1.0:i386

32-bit Java JDK/JRE Preferably Oracle Java. See https://java.com/en/download/faq/develop.xml.
Alternatively, openjdk:
            sudo apt-get install openjdk-7-jdk:i386

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

Package Commands
32-bit OpenGL Driver

Preferably native driver for your video card.
Alternatively, the mesa libraries:    

sudo apt-get install libglu1-mesa:i386

Unpacking STK Engine

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

Depending on the CPU architecture:

And then both archives:

tar -xvf stk_data_v11.2.0.tgz
tar -xvf stk_jars_v11.2.0.tgz

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

tar -xvf stk_codesamples_v11.2.0.tgz
tar -xvf stk_documentation_v11.2.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.2.0.tgz

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

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

The top level stk11.2 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 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 in the next paragraph: New User Install & Online Data.

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 like the 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/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 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 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:
        cd <install dir>/CodeSamples/CustomApplications/Java/AWT_STK_X_Globe_View
  3. Make sure $JAVA_HOME is configured correctly. Depending on the CPU architecture you are targeting it should point to either a 32-bit or 64-bit JDK. This can be verified as follows:
  4. Once you have verified that JAVA_HOME points to the expected JDK, run the example by entering:
  5. 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:
        cd <install dir>/CodeSamples/CustomApplications/Java/AWT_STK_X_NoGraphics
  3. Make sure $JAVA_HOME is configured correctly. Depending on the CPU architecture you are targeting, it should point to either a 32-bit or 64-bit JDK. This can be verified as follows:
  4. Once you have verified that JAVA_HOME points to the expected JDK, run the example by entering:
  5. 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 set-up 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.2