Output format options

[m-mohr]

As mentioned by @jdries in a recent discussion, there is no way to specify additional output format options. Therefore it seems reasonable to move the output_format query parameter to the body or even include it in the process graph. We already have something similar for the POST /services endpoint with the args in the body.

Examples for output format options could be:

• PNG: color map, bit depth, dithering level, transparency, ...
• JPEG: compression level, ...
• GeoTIFF: block size, compression options, ...
• Time series: ...

Example for the process graph:

{
  process_id: "export",
  args: {
    output_format: "jpeg",
    compression_level: 0.9,
    collections: [...]
  }
}

Example in the body:

{
  process_graph: {...},
  view: {...},
  output: {
    format: "jpeg",
    compression_level: 0.9
  },
  ...
}

Maybe it is also possible to add it to the query (depends on how extensive the options can be):
...?format=jpeg&compression_level=0.9

[jdries]

For me it's entirely acceptable to put the output parameters in the body.
Putting them in the process graph make less sense to me, as the result of an export is usually not usable as input to another node.

[m-mohr]

Yes, that's probably the better choice to have it in the body or query string, might also depend on the API endpoint. Query string for GET (download / queue), body for POST (execute)?

Regarding the options we might want to get inspired by GDAL or even make a (mostly?) compatible interface regarding the options.

Example (compatible to GDAL; comments are only present to explain the options in this example):

{
  "output":{
    "format":"GTiff", // GDL File format code for GeoTiff
    "tiled": true, // GDAL option to force creation of tiled TIFF files (true would translate to yes for GDAL)
    "compress": "jpeg", // GDAL option to compress the GeoTIFF using JPEG (instead of deflate)
    "photometric": "YCBCR", // GDAL option to use YCBCR color space instead of RGB, which makes the image much smaller with JPEG compression
    "jpeg_quality": 80 // GDAL option for JPEG compression level
    // All other options should default to the GDAL defaults?!
  }
}

Example for PNG:

{
  "output":{
    "format":"PNG", // GDL File format code for PNG
    "worldfile": true, // Force creation of a world file, which is delivered as an individual file during the download request. Probably won't work with the /execute endpoint though.
    // All other options should default to the GDAL defaults?!
  }
}

We would need to come up with our own definitions for formats not supported by GDAL, e.g. custom time series.

Even if GDAL is not supported we should enforce implementations to use these conventions. Of course, they might not support every option or add custom options, depending how they handle files as they might not use GDAL at all.

By the way: We don't want to "create" web services (wms, tms, wcs, ...) using this endpoint, do we?

[m-mohr]

Added with PR #35. Additional documentation might be needed though.

[ghost]

IMHO the definition of the output format makes more sense in the process graph itself.
If you have complex process graphs you might want to export intermediate results and statistical analysis data. It is more flexible to have dedicated export processes, in which you can set the export format directly.
With export processes one can export many different formats in a single process graph. The following process will export all its inputs as GTiff files somewhere within a process graph and pipes the inputs upstream to the next process, so that further processing is possible with the same data:

        "process_id": "raster_export",
        "format": "GTiff",
        "imagery": {
            "process_id": "get_data",
            "data_id": "nc_spm_08.landsat.raster.elevation",
            "imagery": {
                "process_id": "get_data",
                "data_id": "nc_spm_08.landsat.raster.slope"
            }
        }

[m-mohr]

Interesting idea, @mundialis-dev. Would you mind copying this into a separate issue?