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.

{% include-markdown "./usage_example.txt" %}

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 website). 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)