GDAL Image Formats

GeoServer can leverage the ImageI/O-Ext GDAL libraries to read selected coverage formats. GDAL is able to read many formats, but for the moment GeoServer supports only a few general interest formats and those that can be legally redistributed and operated in an open source server.

The following image formats can be read by GeoServer using GDAL:

Installing GDAL extension

From GeoServer version 2.2.x, GDAL must be installed as an extension. To install it:

  • Navigate to the GeoServer download page

  • Find the page that matches the version of the running GeoServer.

    Warning

    Be sure to match the version of the extension with that of GeoServer, otherwise errors will occur.

  • Download the GDAL extension. The download link for GDAL will be in the Extensions section under Coverage Format.

../../_images/downloadextension.png
  • Extract the files in this archive to the WEB-INF/lib directory of your GeoServer installation. On Windows You may be prompted for confirmation to overwrite existing files, confirm the replacement of the files
../../_images/overwrite.png

Moreover, in order for GeoServer to leverage these libraries, the GDAL (binary) libraries must be installed through your host system’s OS. Once they are installed, GeoServer will be able to recognize GDAL data types. See below for more information.

Installing GDAL native libraries

The ImageIO-Ext GDAL plugin for geoserver master uses ImageIO-Ext 1.1.13 whose artifacts can be downloaded from here.

Browse to the native and then gdal directory for the Image IO-Ext download link. Now you should see a list of artifacts that can be downloaded. We need to download two things now:

  1. The CRS definitions
  2. The native libraries matching the target operating system (more details on picking the right one for your windows installation in the “Extra Steps for Windows Platforms” section)

Let’s now install the CRS definitions.

  • Click on the “gdal_data.zip” to download the CRS definitions archive.
  • Extract this archive on disk and place it in a proper directory on your system.
  • Create a GDAL_DATA environment variable to the folder where you have extracted this file. Make also sure that this directory is reachable and readable by the application server process’s user.

We now have to install the native libraries.

  • Assuming you are using a 64 bit Ubuntu 11 Linux Operating System (for instance), click on the linux folder and then on “gdal192-Ubuntu11-gcc4.5.2-x86_64.tar.gz” to download the native libraries archive (Before doing this, make sure to read and agree with the ECWEULA if you intend to use ECW).

  • If you are using a Windows Operating System make sure to download the archive matching your Microsoft Visual C++ Redistributables and your architecture. For example on a 64 bit Windows with 2010 Redistributables, download the gdal-1.9.2-MSVC2010-x64.zip archive

  • Extract the archive on disk and place it in a proper directory on your system.

    Warning

    If you are on Windows, make sure that the GDAL DLL files are on your PATH. If you are on Linux, be sure to set the LD_LIBRARY_PATH environment variable to refer to the folder where the SOs are extracted.

    Note

    The native libraries contains the GDAL gdalinfo utility which can be used to test whether or not the libs are corrupted. This can be done by browsing to the directory where the libs have been extracted and performing a gdalinfo command with the formats options that shows all the formats supported. The key element of GDAL support in GeoServer is represented by the JAVA bindings. To test the bindings, the package contains a Java version of the gdalinfo utility inside the “javainfo” folder (a .bat script for Windows and a .sh for Linux), it is very important to run it (again, with the formats options) to make sure that the Java bindings are working properly since that is what GeoServer uses. An error message like Can’t load IA 32-bit .dll on a AMD 64-bit platform in the log files indicates a mixed version of the tools, please go through the installation process again and pick the appropriate versions. More details on troubleshooting are provided in the Note on running GeoServer as a Service on Windows section below.

Once these steps have been completed, restart GeoServer. If all the steps have been performed correctly, new data formats will be in the Raster Data Sources list when creating a new data store in the Stores section as shown here below.

../../_images/newsource.png

GDAL image formats in the list of raster data stores

If new formats do not appear in the GUI and you see the following message in the log file:

it.geosolutions.imageio.gdalframework.GDALUtilities loadGDAL WARNING: Native library load failed.java.lang.UnsatisfiedLinkError: no gdaljni in java.library.path

that means that the installations failed for some reason.

Extra Steps for Windows Platforms

There are a few things to be careful with as well as some extra steps if you are deploying on Windows.

As stated above, we have multiple versions like MSVC2005, MSVC2008 and so on matching the Microsoft Visual C++ Redistributables. Depending on the version of the underlying operating system you’ll have to pick up the right one. You can google around for the one you need. Also make sure you download the 32 bit version if you are using a 32 bit version of Windows or the 64 bit version (has a “-x64” suffix in the name of the zip file) if you are running a 64 bit version of Windows. Again, pick the one that matches your infrastructure.

Note on running GeoServer as a Service on Windows

Note that if you downloaded an installed GeoServer as a Windows service you installed the 32 bit version.

Simply deploying the GDAL ImageI/O-Ext native libraries in a location referred by the PATH environment variable (like, as an instance, the JDK/bin folder) doesn’t allow GeoServer to leverage on GDAL, when run as a service. As a result, during the service startup, GeoServer log reports this worrysome message:

it.geosolutions.imageio.gdalframework.GDALUtilities loadGDAL WARNING: Native library load failed.java.lang.UnsatisfiedLinkError: no gdaljni in java.library.path

Taking a look at the wrapper.conf configuration file available inside the GeoServer installation (at bin/wrapper/wrapper.conf), there is this useful entry:

# Java Library Path (location of Wrapper.DLL or libwrapper.so) wrapper.java.library.path.1=bin/wrapper/lib

To allow the GDAL native DLLs to be loaded, you have two options:

  1. Move the native DLLs to the referenced path (bin/wrapper/lib)
  2. Add a wrapper.java.library.path.2=path/where/you/deployed/nativelibs entry just after the wrapper.java.library.path1=bin/wrapper/lib line.

Adding support for ECW and MrSID on Windows

If you are on Windows and you want to add support for ECW and MrSID there is an extra step to perform.

Download and install ECW and MrSID from GeoSolutions site

In the Windows packaging ECW and MrSID are built as plugins hence they are not loaded by default but we need to place their DLLs in a location that is pointed to by the GDAL_DRIVER_PATH environment variable. By default the installer place the plugins in C:\Program Files\GDAL\gdalplugins.

../../_images/gdal_driver_path.png

GDAL internally uses an environment variable to look up additional drivers (notice that there are a few default places where GDAL will look anyway). For additional information, please see the GDAL wiki.

Restart GeoServer, you should now see the new data sources available

../../_images/ecw_mrsid_sources.png

Configuring a DTED data store

../../_images/gdaldtedconfigure.png

Configuring a DTED data store

Configuring a EHdr data store

../../_images/gdalehdrconfigure.png

Configuring a EHdr data store

Configuring a ERDASImg data store

../../_images/gdalerdasimgconfigure.png

Configuring a ERDASImg data store

Configuring a JP2MrSID data store

../../_images/gdaljp2mrsidconfigure.png

Configuring a JP2MrSID data store

Configuring a NITF data store

../../_images/gdalnitfconfigure.png

Configuring a NITF data store

Supporting vector footprints

Starting with version 2.9.0, GeoServer supports vector footprints. A footprint is a shape used as a mask to hide those pixels that are outside of the mask, hence making that part of the parent image transparent. The currently supported footprint formats are WKB, WKT and Shapefile. By convention, the footprint file should be located in the same directory as the raster data that the footprint applies to.

Note

In the examples of this section and related subsections, we will always use .wkt as extension, representing a WKT footprint, although both .wkb and .shp are supported too.

For example, supposing you have a MrSID file located at /mnt/storage/data/landsat/N-32-40_2000.sid to be masked, you just need to place a WKT file on the same folder, as /mnt/storage/data/landsat/N-32-40_2000.wkt Note that the footprint needs to have same path and name of the original data file, with .wkt extension.

This is how the sample footprint geometry looks:

../../_images/masking.png

A sample geometry stored as WKT, rendered on OpenJump

Once footprint file has been added, you need to change the FootprintBehavior parameter from None (the default value) to Transparent, from the layer configuration.

../../_images/footprintbehavior.png

Setting the FootprintBehavior parameter

The next image depicts 2 layer previews for the same layer: the left one has no footprint, the right one has a footprint available and FootprintBehavior set to transparent.

../../_images/gdalmasks.png

No Footprint VS FootprintBehavior = Transparent

External Footprints data directory

As noted above, the footprint file should be placed in the same directory as the raster file. However in some cases this may not be possible. For example, the folder containing the raster data may be read only.

As an alternative, footprint files can be located in a common directory, the footprints data directory. The subdirectories and file names under that directory must match the original raster path and file names. The footprints data directory is specified as a Java System Property or an Environment Variable, by setting the FOOTPRINTS_DATA_DIR property/variable to the directory to be used as base folder.

Example

Suppose you have 3 raster files with the following paths:

  • /data/raster/charts/nitf/italy_2015.ntf
  • /data/raster/satellite/ecw/orthofoto_2014.ecw
  • /data/raster/satellite/landsat/mrsid/N-32-40_2000.sid

They can be represented by this tree:

/data
 \---raster
     +---charts
     |   \---nitf
     |           italy_2015.ntf
     |
     \---satellite
         +---ecw
         |       orthofoto_2014.ecw
         |
         \---landsat
             \---mrsid
                     N-32-40_2000.sid

In order to support external footprints you should

  1. Create a /footprints (as an example) directory on disk
  2. Set the FOOTPRINTS_DATA_DIR=/footprints variable/property.
  3. Replicate the rasters folder hierarchy inside the specified folder, using the full paths.
  4. Put the 3 WKT files in the proper locations:
  • /footprints/data/raster/charts/nitf/italy_2015.wkt
  • /footprints/data/raster/satellite/ecw/orthofoto_2014.wkt
  • /footprints/data/raster/satellite/landsat/mrsid/N-32-40_2000.wkt

Which can be represented by this tree:

/footprints
 \---data
     \---raster
         +---charts
         |   \---nitf
         |           italy_2015.wkt
         |
         \---satellite
             +---ecw
             |       orthofoto_2014.wkt
             |
             \---landsat
                 \---mrsid
                         N-32-40_2000.wkt

Such that, in the end, you will have the following folders hierarchy tree:

+---data
|   \---raster
|       +---charts
|       |   \---nitf
|       |           italy_2015.ntf
|       |
|       \---satellite
|           +---ecw
|           |       orthofoto_2014.ecw
|           |
|           \---landsat
|               \---mrsid
|                       N-32-40_2000.sid
|
\---footprints
    \---data
        \---raster
            +---charts
            |   \---nitf
            |           italy_2015.wkt
            |
            \---satellite
                +---ecw
                |       orthofoto_2014.wkt
                |
                \---landsat
                    \---mrsid
                            N-32-40_2000.wkt

Note the parallel mirrored folder hierarchy, with the only differences being a /footprints prefix at the beginning of the path, and the change in suffix.

Previous: ArcGrid