.. _community_wpsrawdownload:
Raw data download processes
---------------------------
These processes allow download of vector and raster data in raw form, without rendering.
Download Estimator Process
+++++++++++++++++++++++++++
The *Download Estimator Process* checks the size of the file to download. This process takes in input the following parameters:
* ``layername`` : name of the layer to check
* ``ROI`` : ROI object to use for cropping data
* ``filter`` : filter for filtering input data
* ``targetCRS`` : CRS of the final layer if reprojection is needed
This process will return a boolean which will be **true** if the downloaded file will not exceed the configured limits.
Download Process
++++++++++++++++++++++
The *Download Process* calls the *Download Estimator Process*, checks the file size, and, if the file does not exceed the limits, download the file as a zip.
The parameters to set are
* ``layerName`` : the name of the layer to process/download
* ``filter`` : a vector filter for filtering input data(optional)
* ``outputFormat`` : the MIME type of the format of the final file
* ``targetCRS`` : the CRS of the output file (optional)
* ``RoiCRS`` : Region Of Interest CRS (optional)
* ``ROI`` : Region Of Interest object to use for cropping data (optional)
* ``cropToROI`` : boolean parameter to allow cropping to actual ROI, or its envelope (optional)
* ``interpolation`` : interpolation function to use when reprojecting / scaling raster data. Values are NEAREST (default), BILINEAR, BICUBIC2, BICUBIC (optional)
* ``targetSizeX`` : size X in pixels of the output (optional, applies for raster input only)
* ``targetSizeY`` : size Y in pixels of the output (optional, applies for raster input only)
* ``selectedBands`` : a set of the band indices of the original raster that will be used for producing the final result (optional, applies for raster input only)
* ``writeParameters`` : a set of writing parameters (optional, applies for raster input only). See :ref:`writing_params` below section for more details on writing parameters defintion.
The ``targetCRS`` and ``RoiCRS`` parameters are using EPSG code terminology, so, valid parameters are literals like ``EPSG:4326`` (if we are referring to a the Geogaphic WGS84 CRS), ``EPSG:3857`` (for WGS84 Web Mercator CRS), etc.
ROI Definition
++++++++++++++++++++++
A ``ROI`` parameter is a geometry object which can also be defined if three different forms:
* as ``TEXT``, in various geometry textual formats/representations
* as ``REFERENCE``, which is the textual result of an HTTP GET/POST request to a specific url
* as a ``SUPPROCESS`` result: the format produced as result of the process execution must be a compatible geometry textual format.
As noted above, in all above forms/cases ROI geometry is defined as text, in specific formats. These can be:
* ``text/xml; subtype=gml/3.1.1``: conforming to gml specs 3.1.1
* ``text/xml; subtype=gml/2.1.2``: conforming to gml specs 2.1.2
* ``application/wkt``: the WKT geometry representation
* ``application/json``: the JSON geometry representation
* ``application/gml-3.1.1``: conforming to gml specs 3.1.1
* ``application/gml-2.1.2``: conforming to gml specs 2.1.2
For example, a polygon used as ROI with the following WKT representation:
``POLYGON (( 500116.08576537756 499994.25579707103, 500116.08576537756 500110.1012210889, 500286.2657688021 500110.1012210889, 500286.2657688021 499994.25579707103, 500116.08576537756 499994.25579707103 ))``
would be represented in the following forms:
* in application/wkt: ``POLYGON (( 500116.08576537756 499994.25579707103, 500116.08576537756 500110.1012210889, 500286.2657688021 500110.1012210889, 500286.2657688021 499994.25579707103, 500116.08576537756 499994.25579707103 ))``
* in application/json: ``{"type":"Polygon","coordinates":[[[500116.0858,499994.2558],[500116.0858,500110.1012],[500286.2658,500110.1012],[500286.2658,499994.2558],[500116.0858,499994.2558]]]}``
* in text/xml:``500116.08576537756,499994.25579707103 500116.08576537756,500110.1012210889 500286.2657688021,500110.1012210889 500286.2657688021,499994.25579707103 500116.08576537756,499994.25579707103``
* in application/xml: the following xml
.. code-block:: xml
500116.08576537756,499994.25579707103 500116.08576537756,500110.1012210889 500286.2657688021,500110.1012210889 500286.2657688021,499994.25579707103 500116.08576537756,499994.25579707103
The general structure of a WPS Download request POST payload consists of two parts: the first (````) contains the input parameters for the process, and the second (````) contains details about delivering the output. A typical pseudo payload is the following:
.. code-block:: xml
gs:WPS_Process_Name_Here
First_Param_Name
(First_Param_Data)
...
...
result
Each parameter for the process is defined in its own ```` xml block. In case of simple type data, such as layerName, outputFormat, targetCRS, etc, input params xml blocks have the following form:
.. code-block:: xml
layerName
nurc:Img_Sample
Note the ```` tags wrapping the parameter value.
In case of geometry parameters, such as filter, ROI, the parameter's ```` block is different:
.. code-block:: xml
ROI
Note the ```` tag, the ``mimeType="application/wkt"`` parameter, and the ``![CDATA[]`` wrapping of the actual geometry data (in textual representation), according to the selected MIME type.
Note that if the ROI parameter is defined as WKT, you will need to specify a RoiCRS input parameter as well.
In case the ROI is defined using a REFERENCE source, the input block is slightly different:
.. code-block:: xml
ROI
Note the ```` tag replacing ```` tag, and the extra ``xlink:href="url_to_fetch_data"`` parameter, which defines the url to peform the HTTP GET request. For POST request cases, tech method is switched to POST, and a ```` tag is used to wrap POST data:
.. code-block:: xml
Filter parameter definition
++++++++++++++++++++++++++++
A ``filter`` parameter is a definition of a vector filter operation:
* as ``TEXT``, in various textual formats/representations
* as ``REFERENCE``, which is the textual result of an HTTP GET/POST request to a specific url
* as a ``SUBPROCESS`` result: the format produced as result of the process execution must be a compatible geometry textual format.
Compatible text formats for filter definitions are:
* ``text/xml; filter/1.0``
* ``text/xml; filter/1.1``
* ``text/xml; cql``
For more details on filter formats/languages, one can see :doc:`../../filter/syntax` and :doc:`../../filter/function`.
Filter parameter applies to vector data. If this is the case with input data, a sample ```` block of a filter intersecting the polygon we used earlier as an example for ROI definition would be:
.. code-block:: xml
filter
GEOMETRY
500116.08576537756,499994.25579707103 500116.08576537756,500110.1012210889 500286.2657688021,500110.1012210889 500286.2657688021,499994.25579707103 500116.08576537756,499994.25579707103
]]>
Sample request
+++++++++++++++++
Synchronous execution
^^^^^^^^^^^^^^^^^^^^^
The following is a sample WPS request for processing a raster dataset.
Suppose we want to use the North America sample imagery (**nurc:Img_Sample**) layer, to produce an **80x80** pixels downloadable **tiff** in **EPSG:4326**
Assuming that a local geoserver instance (setup for wps/wps-download support) is running, we issue a POST request to the url:
``http://127.0.0.1:8080/geoserver/ows?service=wps``
using the following payload:
.. code-block:: xml
gs:Download
layerName
nurc:Img_Sample
outputFormat
image/tiff
targetCRS
EPSG:4326
targetSizeX
80
targetSizeY
80
result
More parameters (from the parameter list above) can be used, for example, we can only select bands **0 and 2** from the original raster:
.. code-block:: xml
bandIndices
0
bandIndices
2
Or, use a **Region Of Interest** to crop the dataset:
.. code-block:: xml
ROI
RoiCRS
EPSG:32615
The result produced is a zipped file to download.
Asynchronous execution
^^^^^^^^^^^^^^^^^^^^^^
The process can also be performed asynchronously.
In this case, the second part (``wps:ResponseForm``) of the wps download payload slightly changes, by using the **storeExecuteResponse** and **status** parameters, set to **true** for the ````:
.. code-block:: xml
result
>
In case of asynchronous execution, the initial request to download data returns an xml indication that the process has successfully started:
.. code-block:: xml
gs:Download
Enterprise Download Process
Downloads Layer Stream and provides a ZIP.
Process accepted.
The response contains a ```` block indicating successfull process creation and process start time. However, the important part in this response is the **executionId=dd0d61f5-7da3-41ed-bd3f-15311fa660ba** attribute in the ```` tag. The ``dd0d61f5-7da3-41ed-bd3f-15311fa660ba`` ID can be used as a reference for this process, in order to issue new GET requests and to check process status. These requests have the form:
``http://127.0.0.1:8080/geoserver/ows?service=WPS&request=GetExecutionStatus&executionId=277e24eb-365d-42e1-8329-44b8076d4fc0``
When issued (and process has finished on the server), this GET request returns the result to download/process as a base64 encoded zip:
.. code-block:: xml
gs:Download
Enterprise Download Process
Downloads Layer Stream and provides a ZIP.
Process succeeded.
result
Zipped output files to download
UEsDBBQACAgIAFdyCEkAAAAAAAAAAAAAAAApAAAAMGEwYmJkYmQtMjdkNi00...(more zipped raster data following, ommited for space saving)...
Asynchronous execution (output as a reference)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ```` of the previous asynchronous request payload example can be modified to get back a link to the file to be downloaded instead of the base64 encoded data.
.. code-block:: xml
...
result
Note ```` contains a ```` instead of a ```` being used by previous example.
Moreover the attribute **asReference** set to **true** has been added to the ````.
This time, when issued (and process has finished on the server), the GET request returns the result to download as a link as part of ```` .
.. code-block:: xml
gs:Download
Enterprise Download Process
Downloads Layer Stream and provides a ZIP.
Process succeeded.
result
Zipped output files to download
.. _writing_params:
Writing parameters
++++++++++++++++++
The ``writeParameters`` input element of a process execution allows to specify parameters to be applied by the ``outputFormat`` encoder when producing the output file.
Writing parameters are listed as multiple ``value`` within a ```` parent element.
See the below xml containing full syntax of a valid example for TIFF output format:
.. code-block:: xml
writeParameters
128
128
JPEG
0.75
GeoTIFF/TIFF supported writing parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The supported writing parameters are:
* ``tilewidth`` : Width of internal tiles, in pixels
* ``tileheight`` : Height of internal tiles, in pixels
* ``compression`` : Compression type used to store internal tiles. Supported values are:
* ``CCITT RLE`` (Lossless) (Huffman)
* ``LZW`` (Lossless)
* ``JPEG`` (Lossy)
* ``ZLib`` (Lossless)
* ``PackBits`` (Lossless)
* ``Deflate`` (Lossless)
* ``quality`` : Compression quality for lossy compression (JPEG). Value is in the range [0 : 1] where 0 is for worst quality/higher compression and 1 is for best quality/lower compression
* ``writenodata`` : Supported value is one of true/false. Note that, by default, a `nodata TAG `_ is produced as part of the output GeoTIFF file as soon as a nodata is found in the GridCoverage2D to be written. Therefore, not specifying this parameter will result into writing nodata to preserve default behavior. Setting it to false will avoid writing that TAG.