Click or drag to resize

Getting Started

This document describes how to get started with using STK Components in your application.

Adding STK Components to an Application

In order to use STK Components in your own application, perform these steps:

  1. Obtain a valid license file (either a temporary license from AGI support or the license you purchased). The file should be named AGI.Foundation.lic (exactly). You can request a temporary development license from AGI Technical Support by e-mailing your request to support@agi.com.

  2. Add the STK Components JAR files to your project. In Eclipse, this is easily accomplished by right-clicking your project and then selecting Build Path, then Configure Build Path... Then, in the Libraries tab on the right, click Add External JARs..., navigate to the location where you unpacked the STK Components files, and select the JAR files you would like to use in your application. You can also copy the desired JARs into your project directory and use the Add JARs... button to add the JARs using a path relative to your project directory.

  3. Attach the Javadoc to the STK Components JARs. This is optional, but recommended, in order to have documentation and parameter names available when developing. In Eclipse, this is done by right-clicking your project and then selecting Build Path, then Configure Build Path... Then, in the Libraries tab on the right, for each STK Components JAR you have added, expand the plus on the left, select Javadoc location:, then click Edit... on the right. Select the Javadoc in archive radio button, then set the Archive Path field, using the Browse... button to navigate to the location where you unpacked the STK Components files, and select the agi.foundation.javadoc zip file which is in the Documentation directory. You will need to repeat these steps for each STK Components JAR file.

  4. Ensure that your AGI.Foundation.lic license file will be available at the root level of your application's classpath at runtime. In Eclipse, simply adding the license file to the root of your project's source directory will copy it to the output directory and make it available when running your application through Eclipse. Make sure that the license file appears in Eclipse by selecting your project and pressing F5, or right-clicking and choosing Refresh. When packaging your project for deployment, ensure that your license file is included at the root level of your application's JAR file. See the Licensing and Deployment topic for details and advanced scenarios.

For a detailed walkthrough of building an application with STK Components, see the Tutorial.

Insight3D®

Insight3D currently only works in a 64-bit JVM running on Microsoft Windows operating systems. See the System Requirements topic for more information. Also, due to its use of native code, some additional work is required to use the Insight3D visualization component:

Install the Microsoft Visual C++ Redistributable for Visual Studio 2017

Insight3D depends on the Microsoft Visual C++ Redistributable for Visual Studio 2017, which should be installed on any system where you intend to run your application. For convenience, the installer, vc_redist.x64.exe, is included in the root directory of your STK Components installation.

The ability to load the required dependencies from the application directory ("app-local") is also technically possible, but due to the complexity is not described here. Contact AGI support if you have a need to deploy Insight3D applications without an installer on systems that cannot install the redistributable.

Configure your JVM library path.

In addition to adding the STK Components JARs to your project, you also need to make sure that agi.foundation.graphics.native.dll is in the JVM's library path.

The easiest way to make sure that the native DLLs are in the JVM's library path is to put them in the current working directory from which you launch your application. In Eclipse, that can be accomplished by putting them directly into the root of your Eclipse project. Alternatively, you can specify the library path explicitly when launching the JVM from the command-line: java -Djava.library.path=c:\path\to\directory\containing\agi.foundation.graphics.native.dll

Enabling Features From External Libraries

Certain Insight3D features require third-party functionality from separate DLLs. Specifically, using videos as 2D textures requires FFmpeg video processing libraries (avcodec-57.dll, avformat-57.dll, avutil-55.dll, swresample-2.dll, swscale-4.dll), and MrSID imagery requires the LizardTech MrSID DSDK (Altidsdk_9.5.dll, Alb.dll).

These separate DLLs will be loaded when needed at runtime from the same directory as the Insight3D library (agi.foundation.graphics.native.dll).

Alternatively, if you don't use any functionality in Insight3D that requires the separate DLLs, you can skip this.

Event Dispatch Thread

All interaction with Insight3D types must take place in the Swing Event Dispatch Thread (EDT). This means that your main method must create your user interface using code like the following:

Java
public static void main(String[] args) {
    SwingUtilities.invokeLater(() -> new MainFrameContainingInsight3D().setVisible(true));
}