Jenkins Build Status

Resource | master | dev | ------------ | ------------- | ------------- OSSIM Build Centos7 | | Batch Test| | RPMS Build Centos7 | | RPMS Publish Centos7 | |

Welcome to OSSIM

OSSIM is an open source, C++ (mostly), geospatial image processing library used by government, commercial, educational, and private entities throughout the solar system. It has been in active development since the last millenium. This repository contains the full OSSIM package including core library, applications, tests, and build system. It does not contain the OSSIM plugins and other OSSIM-related code such as java-bindings (ossim-oms), and GUI. Those are available for individually cloning. Refer to the root github page for ossimlabs.

Quick links:

What to Get
How to Build
How to Test
OSSIM Command Line Utility
Doxygen Source Code Documentation

Relationship between Repositories (What to Get)

The principal repository is this one (ossim), containing not only the core classes but also the command line utility applications code as well as the cmake build system files and related scripts. This repository must be cloned first before attempting to work with other ossim-* repositories.

The remaining ossim-* repositories are independent of each other and can be cloned in any order. However, it will be necessary to re-run the build script (linux version) or at least regenerate makefiles with the cmake script (linux version) before building. This must be done each time a new ossim-* repository is added to the ossimlabs build. See below for detailed build instructions.

Branching Scheme and Pull Requests

The "master" branches (for all OSSIM family repos) contain the most stable code. It is periodically merged with "dev" branch. If you don't plan on developing code, but want to build from source, this is the branch you want. For bleeding edge development, use the "dev" branch. This branch serves as the parent to all feature branches and is frequently merged with those feature branches once those branches are tested by the developers responsible for them.

If you want to contribute code, you'll need to:

create your own feature branch from dev,
test your modification,
then create a pull request.

The moderators will review the request and merge your changes to "dev". At that point, the automated continuous integration system (Jenkins) will get triggered to perform a build and test. If there are any failures, your merge commit will be backed out.

How to Build

The easy way is to just run the script in ossim/scripts/build.sh. This approach should work for the default build configuration. This currently works for both linux and Mac. We hope to soon have a Windows build.bat file and world peace. Assuming all dependencies were met and no compile/link errors occured, this script will generate all build binaries under a sibling directory to the ossim repo directory, namely, ossim/../build. See the section on environment variables below for options on customizing the build location.

This repository provides the CMAKE infrastructure necessary to build the OSSIM core library and related plugins and applications. Throughout this document, reference is made to the local, top-level directory containing this repository. We'll call this directory simply ossim-dev-home. (In fact, you'll find the shell variable OSSIM_DEV_HOME used throughout the various scripts in this and other repositories.

The following 3rd-party SDKs are needed in order to build the core ossim library:

libtiff-devel (preferably version 4.x for BigTIFF support)
OpenThreads-devel
libjpeg-devel
libgeos-devel (on later Debian / Ubuntu versions, libgeos++-dev)

(Mac users: use MacPorts to install dependencies)

Plugins will require additional 3rd-party packages.

Building OSSIM and related repos from source is a two-step process: first create the make files using CMake, then run make to build the binaries. Scripts are available for Linux/Mac and (soon) Windows to run CMake with default settings. You can run the script from any working directory and default settings will be used for creating the default build environment. It is possible to override specific defaults for your own custom requirements or preferences.

Presently, the default setting is to disable the building of all plugins. If you want specific plugin libraries to be built, you'll need to edit your cmake script at cmake/scripts/ossim-cmake-config.sh (or similar .bat file for Windows). Scroll down to the "Plugins" section and set the corresponding variables to "ON". Note that you could also define those variables in your shell environment in lieu of editing the script.

Creating the Makefiles

Creating a Default Build Environment

The cmake configuration scripts are available in the cmake/scripts subdirectory. Assuming no OSSIM environment variables are available to override the defaults, the "out-of-source" build directory will be created under the same parent directory ossim-dev-home as this repo. The linux/Mac script ossim/scripts/build.sh, if run in an interactive shell will query for the build type. If the script is run as part of a batch process, "Release" is assumed. If the build directory does not exist, it will be created.

Customizing the Build

There are two ways to customize the build: via environment variables and by directly editing the cmake configuration script.

Environment Variables

The CMake system will locally define certain environment variables that live for the lifetime of the cmake config script execution. The following shell variables, if defined, are referenced to override the default settings.

The developer has the option to override the default build directory location by setting the environment variable OSSIM_BUILD_DIR prior to running the cmake config script. If not present, the build directory will be located just under ossim-dev-home as described above.

Another defaulted environment variable is OSSIM_INSTALL_PREFIX. This variable as two distinct functions. First, it indicates where to install the OSSIM SDK when running make install. Second, it serves to specify a path to SDKs that OSSIM depends on. The CMake system will scan OSSIM_INSTALL_PREFIX for the presence of dependency packages such as GeoTiff, JPEG, and others. This secondary purpose of OSSIM_INSTALL_PREFIX used to be handled by the now obsolete environment variable OSSIM_DEPENDENCIES. It is a reasonable consolidation since the OSSIM install will need to include these dependencies if they are not available in their standard installation locations (/usr/lib, /usr/local/lib, etc.), so placing these SDKs in the final OSSIM install directory prior to building OSSIM makes sense. If no override is defined for OSSIM_INSTALL_PREFIX, then the cmake config script will default to $OSSIM_DEV_HOME/install. You can populate that directory with non-standard installs of the OSSIM dependencies prior to running the script. If the directory does not exist, it is created by the script. Obviously, in that case, all OSSIM dependencies will be expected to be found in standard system install folders.

As already mentioned, you can enable the building of specific plugins by defining the corresponding environment variable: BUILD_<NAME>_PLUGIN=ON.

NOTE: For legacy reasons, OSSIM_DEPENDENCIES is still scanned for dependency SDKs. New dependencies however should be "installed" in OSSIM_INSTALL_PREFIX.

Editing the CMake Config Script

The default configuration relies on the presence of the OSSIM repositories under the ossim-dev-home to decide whether to include those in the build (with the exception of the plugins, which default to "OFF"). You may want to selectively exclude certain applications from the build without having to hide the workspaces from CMake. The flags enabling those are defined in the script. Simply set the corresponding variable to "OFF" and rerun the script. Likewise, for the plugins, you can modify the default ("OFF") by changing the corresponding variables in the script to "ON".

There are other flags available that direct CMake to generate project files for IDEs such as Eclipse and Visual Studio. You can also specify multi-threaded builds, non-standard output directories, and more. Feel free to experiment, but know that you'll be voiding the warranty.

How do I know what dependencies are needed?

The CMake system will attempt to locate all necessary dependency SDKs in the system's standard install directories. On linux, this includes, but not limited to, /usr and /usr/local. If it cannot find them, the script will exit with an error message indicating th

Ossim

Install / Use

README