Opticks Developer Guide/Print version
The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at
https://en.wikibooks.org/wiki/Opticks_Developer_Guide
Introduction
Opticks is an open source, remote sensing application. Using Opticks you can create products from satellite and airborne imagery, video (motion imagery), Synthetic Aperture Radar (SAR), multispectral, and hyperspectral data. Opticks is also a developer framework, empowering software developers to extend its functionality. This guide helps C++ developers build capability for Opticks.
This developer guide is divided into five sections. The first section gives a general overview of features of the Opticks remote sensing development framework. The second section helps developers get started. This section describes how to download Opticks and get the necessary components to start developing with Opticks. The third section give an overview of Opticks development concepts and terminology. The fourth section describes how to setup your build environment, and the last section describes how to get started building the sample plug-ins.
Overview
Opticks supports processing almost any type of remote sensing data and makes adding capability easy. Using the plug-in architecture and public interface, you can quickly add your own processing algorithms or support for new types of remote sensing data. The plug-in architecture and public interface enable hundreds of developers to extend the capabilities of Opticks while minimizing conflicts. Opticks is also open source and licensed under LGPL 2.1. This means you can easily extend Opticks functionality, provide the capability to the open source community, or even embed it in your commercial application.
Opticks development features:
- Extensive API. Hundreds of classes with hyper-linked documentation. See the Opticks 4.1.1 API.
- LGPL v2.1 license. This license allows any plug-ins that you write to be placed under your own license, be it a commercial or open-source.
- Large development community. Over a hundred developers and twenty organizations are already developing with Opticks.
- Native Opticks functionality built using the public API. Over 150 plug-ins included in the core software.
- Software development help using the developer mailing list and mailing list archives. Ask questions of the project team members and get your development questions answered.
- Access to the full source code. Access to the Opticks source code isn't necessary to start building your own plug-ins. However, the source code is available if you want to extend the core capability or need help understanding Opticks. The source code is available on the downloads page.
Visit the Opticks site for more information: http://www.opticks.org
Getting Started
To start developing plug-ins for Opticks, you need a good understanding of how to develop C++ software using one of the C++ compilers listed below. If you need to sharpen your skills you can download one of the C++ compilers and look at free C++ online tutorials, http://www.cplusplus.com/doc/tutorial/ and http://msdn.microsoft.com/en-us/library/ms235630.aspx. Opticks also uses the Qt C++ Toolkit for much of its functionality. Qt is free for non-commercial use. You can find out information about using Qt at http://doc.trolltech.com/4.4/index.html. The free version is a little bit harder to configure, especially with Visual C++ Express, but this link has some great information about how to use Qt with Visual C++.
Once you have a good understanding of C++ and Qt, you need some basics: a computer, a C++ compiler, Python, the Opticks software, and the Opticks Software Development Kit (SDK).
The Computer
Opticks supports most modern computers running Windows XP and Windows XP x64 (64-bit windows). Opticks also supports Sun SPARC-based computers running Solaris 10. If you are going to use larger files or need support for visualization plug-ins we recommend a modern nVidia graphics card as well and Windows XP 64-bit. Below is a table showing the minimum configuration:
| Windows | Solaris | |
|---|---|---|
| Processor | Dual-Processor 2GHz Intel/AMD Processor | Dual-Processor 1.6 GHz UltraSPARC IIIi |
| RAM | 2 GB RAM | 4 GB RAM |
| Video Card | nVidia Quadro Video Card with 256MB | SUN XVR-1200 with Open GL 1.5 or later |
| Hard Drive | 5 GB or more of free disk space. | 5 GB or more of free disk space. |
| Mouse | 3 Button Mouse with Scroll Wheel | 3 Button Mouse with Scroll Wheel |
Opticks
If you haven't already downloaded the Opticks software, download and install the appropriate version for your computer: Windows 32-bit, Windows 64-bit, and Solaris SPARC.
The C++ Compiler
To create Opticks plug-ins you need a C++ compiler. Currently Opticks recommends Visual Studio 2005 Professional Edition for Windows and Sun Studio 10 for Solaris SPARC development. Microsoft Visual C++ 2005 Express Edition works but is more difficult to use and has limitations. Visual Studio 2005 Professional Edition usually costs around $500. Visual C++ 2005 Express Edition and Sun Studio 10 are free. Based on your computer and the cost, install one of the following C++ compilers:
- Microsoft Visual Studio 2005 Professional Edition (Windows)
- Microsoft Visual C++ 2005 Express Edition (Windows)
- Sun Studio 10 (Solaris SPARC)
Python
Python is a great scripting language and is necessary for multiple tasks to automate developing Opticks plug-ins.
- Python 2.5 or higher from ActiveState - Download & Install
The Opticks Software Development Kit
The Opticks Software Development Kit (SDK) contains the libraries necessary for developing plug-ins, the source code for several sample plug-ins, and Opticks API documentation. The Windows SDK supports development for both Windows 32-bit and Windows 64-bit plug-ins.
Installation for the Windows
- Download the Window SDK zip archive file.
- Unzip the file into a location such as "c:\develop\opticks" using windows explorer or WinZip.
- Download the library dependencies zip archive file.
- Unzip the file into a location such as "c:\develop\Dependencies" using windows explorer or WinZip.
- Open a command prompt and type "cd c:\develop\Dependencies" to change to the directory of the dependencies.
- Type "python dependencies.py" and python will start downloading and uncompressing the dependencies.
- Create an OPTICKSDEPENDENCIES environment variable at the Dependencies folder so the build system can find the installed dependencies.
Installation for the Solaris
- Download the Solaris SDK bzip2 compressed tar file.
- Decompressed the file into a location such as "~/develop/opticks".
- Download the library dependencies zip archive file.
- Decompressed the file into a location such as "~/develop/Dependencies".
- Create an OPTICKSDEPENDENCIES environment variable at the Dependencies folder so the build system can find the installed dependencies.
Qt is the only dependency that is not part of the download, this is because Qt can either be licensed commercially or under the terms of the GPL license. First you need to determine if Qt will be used under the commercial or GPL license, this depends on the type of development you will be doing with Opticks. Please review the developer FAQ for Qt available at http://web.archive.org/web/20070522211033/http://trolltech.com/developer/downloads/qt/faq to determine under which license you will be using Qt.
If Qt will be used under the open-source or GPL license, follow the instructions below:
- Download a pre-built binary of Qt 4.3.4 Open-Source edition available on the Opticks website at: https://opticks.ballforge.net/files/documents/8/112/Qt-4.3.4-opensource.zip.
- Put the downloaded .zip file into your OPTICKSDEPENDENCIES\packages folder. This assumes you have followed the above instructions on downloading the other required dependencies for Opticks. Rename the download .zip file from Qt-4.3.4-opensource.zip to Qt-4.3.4.zip
- Run "python dependencies.py" on the command-line. This will deploy your Qt 4.3.4 open-source edition binaries to the proper locations.
If Qt will be used under the commercial Qt license, follow the instructions below:
- Once you have purchased a commercial license, download the Qt 4.3.4 source code binaries for the Windows platform.
- Use the prebuilt binaries from TrollTech or follow these instructions on how to build Qt from the source code.
Concepts
This sections describes some of the main concepts for working with Opticks. The first section describes the plug-in architecture.
Plug-In Architecture
The Opticks plug-in architecture enables developers to easily add capability for import, processing, and export of remote sensing data. Upon startup, Opticks scans the plug-in directory for Opticks plug-ins. Any new plug-ins are automatically registered and the functionality becomes available for use. As new plug-ins become available, the Opticks main application doesn't need to be updated. This enables multiple teams of developers to quickly, independently create capability.
As shown in the diagram on the right, the plug-in architecture is made up of the Opticks main application, modules, and plug-ins. A module packages one or more plug-ins in a DLL or shared object and defines the interface through which Opticks will load a plug-in. A module is also a convenient place to put code that is shared by more than one plug-in. For example, the diagram shows the NITF importer and exporter in the same module since they share code to read and write the NITF file format.
A plug-in is implemented as a C++ class. To create a plug-in you simply inherit from one of several pre-defined plug-in class types and add your own capability. The following table shows the basic plug-in types:
- Algorithm - A general processing and exploitation algorithm.
- Exporter - A plug-in to save data.
- Georeference - A plug-in that supports adding a new type of georeferencing algorithm.
- Importer - A plug-in used to load data.
- Interpreter - Scripting language support.
- RasterPager - A plug-in for dynamically requesting raster "pixel" data.
- Viewer - A plug-in that supports basic modeless dialogs.
As shown in the diagram, Opticks provides common services to the plug-ins. These are all accessed through the common Service class. ApplicationServices, DesktopServices, ModelServices, and PlugInManagerServices are some of the main services. Check the Service documentation for a full list. Each of the services are obtained in the same way and provides methods for the plug-in to communicate with Opticks.
- ApplicationServices provides access to configuration settings and session information.
- DesktopServices gives access to Opticks’s main display mechanisms It provides capability to create workspace windows, dockable windows, and toolbars.
- ModelServices provides access to data elements within the active session.
- PlugInManagerServices provides plug-ins with the ability to access other available plug-ins.
ModuleManager
Modules are implemented through the ModuleManager class. The class is declared in the ModuleManager.h header file included in the ‘include’ directory with the Opticks software development kit (SDK). A default implementation is provided in the ModuleManager.cpp source file. The plug-in developer should take the default ModuleManager.cpp source file provided and modify it to describe the module being developed. The ModuleManager.h header file should not be modified.
There are module setting variables that are declared in ModuleManager.h and defined in ModuleManager.cpp that describe the module. These modules settings include module name, version, description, and a unique module identifier string. The ModuleManager also has a method called getPlugIn(). This method is used by Opticks to get the plug-in class. This method takes an index as an argument that specifies which plug-in should be returned, with zero indicating the first plug-in. The implementation of getPlugIn() in the default ModuleManager.cpp source file should be edited to create and return your plug-ins. The code snippet below shows a possible implementation of the getPlugIn() method for a module containing two plug-ins: an importer and an exporter.
PlugIn* ModuleManager::getPlugIn(unsigned long plugInNumber)
{
PlugIn* pPlugIn = NULL;
switch (plugInNumber)
{
case 0: // Get importer plug-in
pPlugIn = new NitfImporter();
break;
case 1: // Get exporter plug-in
pPlugIn = new NitfExporter();
break;
default:
break;
}
return pPlugIn;
}
Each plug-in shouldn't be in its own module, too many modules can significantly increase the Opticks load time.
Plug-Ins
A plug-in can be started in either interactive mode or batch mode. A plug-in executed in interactive mode typically uses a dialog to request information from the user. The user inputs are then used for further execution of the plug-in. On the contrary, a plug-in executed in batch mode should not have user interface components to obtain necessary input from the user, but rather should require those inputs to be present in the plug-in’s input argument list. This means that the plug-in may have different number of arguments in interactive mode and batch mode.
Shell classes are built for each plug-in type. These shell classes can be used as a starting point to create a plug-in. AlgorithmShell, ExporterShell, GeoreferenceShell, ImporterShell, InterpreterShell, RasterPagerShell, and ViewerShell are a few examples. The shell implements common functionality for that plug-in type. For example, the diagram below shows the NITF Exporter inheriting from the ExporterShell class. The ExporterShell implements many of the common methods. The plug-in developer should inherit from the shell class, overload the methods, and use the Opticks Services to implement their unique functionality.
Most shell classes inherit from the PlugIn and Executable interfaces. These common plug-in interfaces provide the Opticks with a standard way of interacting with the plug-in. PlugIn provides a common class used to describe the plug-in. This includes information like plug-in name, version, description, and menu location. Executable is a very powerful common interface that enables all plug-ins to be called in a common way.
The Executable interface enables Opticks to determine plug-in input and output parameters, to specify whether the plug-in is going to be run in batch or interactive mode, and to execute the plug-in. This interface enables the analyst to use the Opticks Wizard Builder to chain together algorithms and automate common tasks.
class Executable {
...
bool setBatch() = 0;
bool setInteractive() = 0;
bool getInputSpecification(PlugInArgList*& pArgList) = 0;
bool getOutputSpecification(PlugInArgList*& pArgList) = 0;
bool execute(PlugInArgList* pInArgList, PlugInArgList* pOutArgList) = 0;
bool abort() = 0;
...
}
The getInputSpecification() and getOutputSpecification() methods specify the input and output parameters of a plug-in. The setBatch() and setInteractive() methods serve two purposes, to inform the plug-in that it should be executed in batch mode or interactive mode and to query whether the mode is supported by the plug-in. The execute() method starts the plug-in and can be called by Opticks or by another plug-in. The abort() method is called by the Opticks when the user clicks the Cancel button in the progress dialog or it can be called by another plug-in.
Configuring Your Build Environment
Building an Opticks plug-in is fairly easy. The SDK contains a number of tutorials and sample plug-ins to get you started. When compiling a plug-in you need to add the following directories to your include path.
- C:\Development\Opticks\4.1.0\application\Interfaces
- C:\Development\Opticks\4.1.0\application\PlugInUtilities\Interfaces
- C:\Development\Opticks\4.1.0\application\PlugInLib
The following directories need to be added to your library path.
- C:\Development\Opticks\4.1.0\Build\Binaries-Win32-Release\lib
This should be changed to the appropriate Binaries-* directory which corresponds to the platform you are targeting.
Link with the following libraries. (these are windows names, use .so for Solaris)
- PlugInLib.lib
- PlugInUtilities.lib
Windows requires an export definition file. This is located at C:\Development\Opticks\4.1.0\application\PlugInManager\PlugInModule.def
In addition, you may need to add one or more third party libraries to the include an library paths. These are located in the C:\Development\Opticks\Dependencies directory. Common libraries needed include boost, qt, and xerces.
Compile the plug-in as a .dll (or .so on Solaris) and copy the resulting file to the PlugIns directory in your Opticks install. Note that you must compile your plug-in in release mode on Windows in order to place it in this location. Debug build must use the binaries located in C:\Development\Opticks\4.1.0\Build\Binaries-Win32-Debug.
Restart Opticks and your plug-in should load. The Opticks SDK provides a more complete build system which we suggest you use. It is more resistant to changes in the SDK, allows for location independent development, and eases configuration for of third party libraries. The rest of this chapter talks about the advanced build system.
Visual Studio Environment
On Windows, the first thing a new developer must do to properly setup their Visual Studio development environment is to create these three environment variables. The OPTICKS_HOME and OPTICKS_INSTALL point to the location of the OPTICKS release. The OPTICKDEPENDENCIES variable points to the location of the libraries Opticks depends on. To create environment variables right click on the My Computer icon on your Desktop and select properties. From the properties dialog go to the advanced tab and click on the Environment Variables button. Add a new user environment variable by clicking on the new button under the user environment variables section.
OPTICKS_HOME = C:\develop\Opticks\4.1.0 OPTICKSDEPENDENCIES = C:\develop\Dependencies\4.1.0
- Run the Opticks.exe under the Toolkit\Build\Binaries-"platform"-"config"\Bin directory. "platform" is win32 or x64 and "config is debug or release. When running the Visual Studio debugger select the debug version matching your platform.
- The first time running Opticks under any platform you must modify the plug-in path setting.
- Once Opticks starts up, go to the Tools\Options menu, select File Locations, click on the cell next to the plug-in path. Select the browse button that becomes active in the selected cell.
Change the plug-in path to: Toolkit\Build\Binaries-"platform"-"config"\PlugIns directory where "platform" and "config" match your configuration. Click Ok to accept the change and close the Options dialog. Click OK on the following message. Shutdown Opticks (File\Exit). - You should now have a properties file in your C:\Documents and Settings\username\Application Data\Opticks directory matching the configuration.
Sample Plug-ins
The source code for plug-in development consists of the class definitions for all of the interface classes between Opticks and the plug-in, the class definitions for the plug-in base classes, a module definition file, and the default ModuleManager C++ source code.
The plug-in library contains compiled code that must be linked with the plug-in at compile time. The library contains the implementation of the plug-in base classes. The library's base filename is 'PlugInLib'. The library has been compiled for Windows and Solaris. The exact name of the library file depends on the naming conventions for the different operating systems. For Windows, the library is PlugInLib.lib and for the Solaris operating systems, the library is libpluginlib.a. Regardless of the operating system being used, this library must be statically linked into the plug-in.
The toolkit contains five sample plug-ins in a single module. One of the five sample plug-ins is only available on the Windows platform. The sample module and plug-in source code are contained in the /Toolkit/SamplePlugIns directory. They demonstrate a variety of functionality that plug-in may need to implement. The module contains full source code for all plug-ins and a project file for Microsoft Visual Studio 2005.