GDAL based WCS Output Format

The gdal_translate based output format leverages the availability of the gdal_translate command to allow the generation of more output formats than GeoServer can natively produce. The basic idea is to dump to the file system a file that gdal_translate can translate, invoke it, zip and return the output of the translation.

This extension is thus the equivalent of the OGR extension for raster data.

Out of the box behaviour

Out of the box the plugin assumes the following:

  • gdal_translate is available in the path
  • the GDAL_DATA variable is pointing to the GDAL data directory (which stores the spatial reference information for GDAL)

In the default configuration the following formats are supported:

  • JPEG-2000 part 1 (ISO/IEC 15444-1)
  • Geospatial PDF
  • Arc/Info ASCII Grid
  • ASCII Gridded XYZ

The list might be shorter if gdal_translate has not been built with support for the above formats (for example, the default JPEG-2000 format relies on the JasPer-based GDAL driver).

Once installed in GeoServer, a bunch of new supported formats will be listed in the ServiceMetadata section of the WCS 2.0 GetCapabilities document, e.g. image/jp2 and application/pdf.

gdal_translate conversion abilities

The gdal_translate utility is usually able to convert more formats than the default setup of this output format allows for, but the exact list depends on how the utility was built from sources. To get a full list of the formats available by your ogr2ogr build just run:

gdal_translate --long-usage

and you’ll get the full set of options usable by the program, along with the supported formats.

For example, the above produces the following output using gdal 1.11.2 compiled with libgeotiff 1.4.0, libpng 1.6, libjpeg-turbo 1.3.1, libjasper 1.900.1 and libecwj2 3.3:

Usage: gdal_translate [--help-general] [--long-usage]
    [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/
          CInt16/CInt32/CFloat32/CFloat64}] [-strict]
    [-of format] [-b band] [-mask band] [-expand {gray|rgb|rgba}]
    [-outsize xsize[%] ysize[%]]
    [-unscale] [-scale[_bn] [src_min src_max [dst_min dst_max]]]* [-exponent[_bn] exp_val]*
    [-srcwin xoff yoff xsize ysize] [-projwin ulx uly lrx lry] [-epo] [-eco]
    [-a_srs srs_def] [-a_ullr ulx uly lrx lry] [-a_nodata value]
    [-gcp pixel line easting northing [elevation]]*
    [-mo "META-TAG=VALUE"]* [-q] [-sds]
    [-co "NAME=VALUE"]* [-stats] [-norat]
    src_dataset dst_dataset

GDAL 1.11.2, released 2015/02/10

The following format drivers are configured and support output:
  VRT: Virtual Raster
  GTiff: GeoTIFF
  NITF: National Imagery Transmission Format
  HFA: Erdas Imagine Images (.img)
  ELAS: ELAS
  AAIGrid: Arc/Info ASCII Grid
  DTED: DTED Elevation Raster
  PNG: Portable Network Graphics
  JPEG: JPEG JFIF
  MEM: In Memory Raster
  GIF: Graphics Interchange Format (.gif)
  XPM: X11 PixMap Format
  BMP: MS Windows Device Independent Bitmap
  PCIDSK: PCIDSK Database File
  PCRaster: PCRaster Raster File
  ILWIS: ILWIS Raster Map
  SGI: SGI Image File Format 1.0
  SRTMHGT: SRTMHGT File Format
  Leveller: Leveller heightfield
  Terragen: Terragen heightfield
  ISIS2: USGS Astrogeology ISIS cube (Version 2)
  ERS: ERMapper .ers Labelled
  ECW: ERDAS Compressed Wavelets (SDK 3.x)
  JP2ECW: ERDAS JPEG2000 (SDK 3.x)
  FIT: FIT Image
  JPEG2000: JPEG-2000 part 1 (ISO/IEC 15444-1)
  RMF: Raster Matrix Format
  RST: Idrisi Raster A.1
  INGR: Intergraph Raster
  GSAG: Golden Software ASCII Grid (.grd)
  GSBG: Golden Software Binary Grid (.grd)
  GS7BG: Golden Software 7 Binary Grid (.grd)
  R: R Object Data Store
  PNM: Portable Pixmap Format (netpbm)
  ENVI: ENVI .hdr Labelled
  EHdr: ESRI .hdr Labelled
  PAux: PCI .aux Labelled
  MFF: Vexcel MFF Raster
  MFF2: Vexcel MFF2 (HKV) Raster
  BT: VTP .bt (Binary Terrain) 1.3 Format
  LAN: Erdas .LAN/.GIS
  IDA: Image Data and Analysis
  LCP: FARSITE v.4 Landscape File (.lcp)
  GTX: NOAA Vertical Datum .GTX
  NTv2: NTv2 Datum Grid Shift
  CTable2: CTable2 Datum Grid Shift
  KRO: KOLOR Raw
  ARG: Azavea Raster Grid format
  USGSDEM: USGS Optional ASCII DEM (and CDED)
  ADRG: ARC Digitized Raster Graphics
  BLX: Magellan topo (.blx)
  Rasterlite: Rasterlite
  PostGISRaster: PostGIS Raster driver
  SAGA: SAGA GIS Binary Grid (.sdat)
  KMLSUPEROVERLAY: Kml Super Overlay
  XYZ: ASCII Gridded XYZ
  HF2: HF2/HFZ heightfield raster
  PDF: Geospatial PDF
  ZMap: ZMap Plus Grid

The full list of formats that gdal_translate is able to support is available on the GDAL site. Mind that this output format can handle only outputs that are file based and that do support creation. So, for example, you won’t be able to use the PostGIS Raster output (since it’s database based) or the Arc/Info Binary Grid (creation not supported).

Customisation

If gdal_translate is not available in the default path, the GDAL_DATA environment variable is not set, or if the output formats needs tweaking, a gdal_translate.xml configuration file can be created to customize the output format. The file should be put inside a gdal folder in the root of the GeoServer data directory.

Note

GeoServer will automatically detect any change to the file and reload the configuration, without a need to restart.

The default configuration is equivalent to the following xml file:

<ToolConfiguration>
  <executable>gdal_translate</executable>
  <environment>
    <variable name="GDAL_DATA" value="/usr/local/share/gdal" />
  </environment>
  <formats>
    <Format>
      <toolFormat>JPEG2000</toolFormat>
      <geoserverFormat>GDAL-JPEG2000</geoserverFormat>
      <fileExtension>.jp2</fileExtension>
      <singleFile>true</singleFile>
      <mimeType>image/jp2</mimeType>
      <type>binary</type> <!-- not really needed, it's the default -->
      <option>-co</option>
      <option>FORMAT=JP2</option>
    </Format>
    <Format>
      <toolFormat>PDF</toolFormat>
      <geoserverFormat>GDAL-PDF</geoserverFormat>
      <fileExtension>.pdf</fileExtension>
      <singleFile>true</singleFile>
      <mimeType>application/pdf</mimeType>
      <formatAdapters>
             <GrayAlphaToRGBA/>
             <PalettedToRGB/>
      </formatAdapters>
    </Format>
    <Format>
      <toolFormat>AAIGrid</toolFormat>
      <geoserverFormat>GDAL-ArcInfoGrid</geoserverFormat>
      <fileExtension>.asc</fileExtension>
      <singleFile>false</singleFile>
    </Format>
    <Format>
      <toolFormat>XYZ</toolFormat>
      <geoserverFormat>GDAL-XYZ</geoserverFormat>
      <fileExtension>.txt</fileExtension>
      <singleFile>true</singleFile>
      <mimeType>text/plain</mimeType>
      <type>text</type>
    </Format>
  </formats>
</ToolConfiguration>

The file showcases all possible usage of the configuration elements:

  • executable can be just gdal_translate if the command is in the path, otherwise it should be the full path to the executable. For example, on a Linux box with a custom build GDAL library might be:

    <executable>/usr/local/bin/gdal_translate</executable>

  • environment contains a list of variable elements, which can be used to define environment variables that should be set prior to invoking gdal_translate. For example, to setup a GDAL_DATA environment variable pointing to the GDAL data directory, the configuration might be:

    <environment>
 <variable name="GDAL_DATA" value="/usr/local/share/gdal" />
</environment>

  • Format defines a single format, which is defined by the following tags:

    • toolFormat: the name of the format to be passed to gdal_translate with the -of option (case insensitive).
    • geoserverFormat: is the name of the output format as advertised by GeoServer
    • fileExtension: is the extension of the file generated after the translation, if any (can be omitted)
    • option: can be used to add one or more options to the gdal_translate command line. As you can see by the JPEG2000 example, each item must be contained in its own option tag. You can get a full list of options by running gdal_translate --help or by visiting the GDAL web site). Also, consider that each format supports specific creation options, listed in the description page for each format (for example, here is the JPEG2000 one).
    • singleFile: if true the output of the conversion is supposed to be a single file that can be streamed directly back without the need to wrap it into a zip file
    • mimeType: the mime type of the file returned when using singleFile. If not specified application/octet-stream will be used as a default.
    • formatAdapters: transformations on the coverage that might need to be applied in order to successfully encode the output. The transformations are applied only if their input conditions are met.

The available format adapters are:

  • GrayAlphaToRGBA: expands a gray image with alpha channel to RGBA (mandatory for geospatial PDF for example)
  • PallettedToRGB: expands a paletted image RGB(A) (mandatory for geospatial PDF for example)