Changeset 917 for trunk/docs

Timestamp:

May 7, 2019, 2:17:08 PM (5 years ago)

Author:

djay

Message:

Merge prototype-v0 branch in trunk

Location:

trunk

Files:

• . (modified) (1 prop)
• docs/install/installation.rst (modified) (2 diffs)
• docs/kernel/configuration.rst (modified) (3 diffs)
• docs/kernel/hpc.rst (copied) (copied from branches/prototype-v0/docs/kernel/hpc.rst)
• docs/kernel/index.rst (modified) (1 diff)
• docs/kernel/mapserver.rst (modified) (6 diffs)
• docs/kernel/sagagis.rst (modified) (4 diffs)
• docs/services/howtos.rst (modified) (1 diff)

trunk/docs/install/installation.rst

@@ -147 +147 @@
     <http://zoo-project.org/trac/browser/trunk/zoo-project/zoo-kernel/sql/schema.sql#L34>`_.
 
+Metadata Database (Optional)
+*****************************
+
+.. _zoo_create_metadb:
+
+It is possible to use a PostgreSQL database to store metadata
+information about WPS Services. This support is optional and require
+to be activated by using the ``--with-metadb=yes`` option.
+
+To create the database for storing the metadata informations about the
+WPS Services, you may use the following command:
+
+.. code::
+
+    createdb zoo_metadb
+    psql zoo_metadb -f zoo-project/zoo-kernel/sql/zoo_collectiondb.sql
+
+In case you want to convert an existing zcfg file then, you can use
+the ``zcfg2sql`` tool from the command line. It can be found in
+``thirds/zcfg2sql`` and can be build simply by running the ``make``
+command. After compilation you only need to give it the path of the
+zcfg file you want to obtain the SQL queries required to store the
+metadata informations in the database rather than in zcfg file.
+
+For instance you may use the following command:
+
+.. code::
+
+    #Direct import in the zoo_metadb database
+    ./zcfg2sql /Path/To/MyZCFGs/myService.zcfg | psql zoo_metadb
+    #Create a SQL file for a futur import
+    ./zcfg2sql /Path/To/MyZCFGs/myService.zcfg > myService.sql
+
 
 
@@ -154 +187 @@
 If ``yaml.h`` file is not found in your ``/usr/include`` directory and
 ``libyaml.so`` is not found in ``/usr/lib``, a ``--with-yaml`` option
-can be used to specify its location. For instance, if the headeer file
+can be used to specify its location. For instance, if the header file
 lies in ``/usr/local/include`` and the shared library is located in
 ``/usr/local/lib``, you may use the following command:

trunk/docs/kernel/configuration.rst

@@ -94 +94 @@
    service providers, e.g., shared libraries with service implementations 
    (the ``serviceProvider`` parameter in the service configuration (.zcfg) file).   
+ * ``memory``: (Optional) can take the value ``load`` to ensure that
+   the value field of the inputs data will be filled by the ZOO-Kernel
+   or ``protected`` to have only the ``cache_file`` filled.
+
 
 .. warning:: 
   The ``libPath`` parameter is currently only recognized by services implemented
   in C/C++ or PHP, and may be moved to another section in future versions.
-  
+
+
+.. warning:: 
+  Depending on the ``memory`` parameter the WPS Service will receive
+  different fields (``value`` or ``cache_file``).
+   
 In case you have activated the MapServer support, please refer to
 :ref:`this specific section <kernel-mapserver-main.cfg>`. 
@@ -264 +273 @@
     hosts=localhost,127.0.0.1
 
+Optionaly, you can also define the shared url(s), meaning that even if
+the ressource requires authentication to be accessed, this
+authentifcation won't be used to define the name for storing the
+file. Hence, two user with different authentication will use the same
+file as it is considerated as shared. You can find bellow a sample
+security section containing the shared parameter. In this example,
+every requests to access the coverage using the url defined in the
+shared parameter (``myHost/cgi-bin/WCS_Server``) will be shared
+between users.
+
+.. code::
+
+    [security]
+    attributes=Authorization,Cookie,User-Agent
+    hosts=localhost,127.0.0.1
+    shared=myHost/cgi-bin/WCS_Server
 
 .. _zoo_activate_db_backend:
@@ -300 +325 @@
 to setup the database.
 
+
+Database section
+...............................
+
+The database section allows to configure the ZOO-Kernel to access the
+metadata information about WPS Services by using a PostgreSQL database
+in addition to the zcfg files.
+
+.. code-block:: guess
+
+        [metadb]
+        dbname=zoo_metadb
+        port=5432
+        user=username
+        host=127.0.0.1
+        type=PG
+
+This will generate strings to be passed to GDAL to connect the
+database server:
+
+.. code-block:: guess
+   
+    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
+
+
+With the previous database section, it will give the following:
+
+.. code-block:: guess
+
+    PG:"dbname=zoo_metadb host=127.0.0.1 port=5432 user=username"
+
+Please refer to this `section <zoo_create_metadb>`_ to learn how
+to setup the database.
+
 Include section
 ...............................

trunk/docs/kernel/index.rst

@@ -14 +14 @@
    orfeotoolbox
    sagagis
-
+   hpc

trunk/docs/kernel/mapserver.rst

@@ -73 +73 @@
    * `MapServer <http://mapserver/org>`__ version >= 6.0.1
 
-First download the lastest zoo-kernel by checking out the svn. Use the following command from do the directory where your previously checked out (in this example we will use ``<PREV_SVN_CO>`` to design this directory).
-
-.. code-block:: guess
-
-    cd <PREV_SVN_CO>
-    svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel-ms
-
+First download the lastest zoo-kernel by checking out the svn. Use the following command from do the directory where your previously checked out (in this example we will use ``$PREV_SVN_CO`` to design this directory).
+
+.. code-block:: guess
+
+    svn checkout http://svn.zoo-project.org/svn/trunk/ $PREV_SVN_CO
+    cd $PREV_SVN_CO
+    
 Then uncompress the MapServer archive (ie. ``mapserver-6.0.1.tar.bz2``) into ``/tmp/zoo-ms-src``, and compile it using the following command:
 
@@ -92 +92 @@
      cp mapserv /usr/lib/cgi-bin
 
-Once done, compile ZOO-Kernel with MapServer support from the ``<PREV_SVN_CO>`` directory, using the following command:
-
-.. code-block:: guess
-
-     cd zoo-kernel-ms
+Once done, compile ZOO-Kernel with MapServer support from the ``$PREV_SVN_CO`` directory, using the following command:
+
+.. code-block:: guess
+
+     cd zoo-kernel
      autoconf
      ./configure --with-python --with-mapserver=/tmp/zoo-ms-src/mapserver-6.0.1
      make
-
-You can then copy the new ZOO-Kernel to ``/usr/lib/cgi-bin`` directory, as follow:
-
-.. code-block:: guess
-
-     cp zoo_loader.cgi /usr/lib/cgi-bin
+     sudo make install
 
 
@@ -119 +114 @@
       dataPath = /var/www/temp/
       mapserverAddress=http://localhost/cgi-bin/mapserv
+
+You can also add the following lines to the ``[main]`` section, in case
+you want to use a default style for Polygon, Lines and Points vector
+layer.
+
+.. code-block:: guess
+
+      msStylePoly=STYLE COLOR 202 109 19 OUTLINECOLOR 105 105 105 WIDTH 3 END
+      msStyleLine=STYLE OUTLINECOLOR 202 109 19 WIDTH 3 END
+      msStylePoint=STYLE COLOR 202 109 19 OUTLINECOLOR 105 105 105 SYMBOL 0 SIZE 14 END
 
 The ``dataPath`` directory is mandatory and must belong to the Apache user.
@@ -175 +180 @@
 *************
 
+You have different options to define the style of the layer created
+using the data returned by your service.
+
+msStyle
++++++++
+
 The optional ``msStyle`` parameter can also be used to define a custom MapServer style block (used for vector datasource only), as follow:
 
@@ -181 +192 @@
      msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END
 
-If a WPS service outputs a one band raster file, then it is possible to add a ``msClassify`` parameter and set it to ``true`` in the output ComplexData ``<Default>`` or ``<Supported>`` nodes of its ``zcfg`` file. This allows ZOO-Kernel to use its own default style definitions in order to classify the raster using equivalent intervals. 
-
-.. code-block:: guess
-
-     msClassify = ....
+msClassify
+++++++++++
+
+If a WPS service outputs a one band raster file, then it is possible
+to add a ``msClassify`` parameter and set it to ``true`` in the output
+ComplexData ``<Default>`` or ``<Supported>`` nodes of its zcfg
+file. This allows ZOO-Kernel to use its own default style definitions
+in order to classify the raster using equivalent intervals.  
+
+.. code-block:: guess
+
+     msClassify = true
+
+
+msInclude
++++++++++
+
+In case you want to use another layer which use the result of your
+service, for instance to produce a `heatmap
+<https://mapserver.org/output/kerneldensity.html>`_, then you can use
+the 
+``msInclude`` and ``msLayer`` options in the output ``ComplexData``
+``<Default>`` or ``<Supported>`` nodes of its zcfg file. You can see below an
+example of use of this two options with the associated mapfile.
+
+.. code-block:: guess
+
+     msInclude = /var/data/template.map
+     msLayer = heatmap
+
+You can find below a sample ``/var/data/template.map``:
+
+.. code-block:: guess
+
+     MAP
+       SIZE 1000 500
+       EXTENT -180 -90 180 90
+       NAME "test heat"
+       IMAGETYPE "png"
+
+       WEB
+         METADATA
+           "ows_srs" "epsg:4326  epsg:3857 epsg:900913"
+           "ows_enable_request" "*"
+         END # METADATA
+       END # WEB
+       
+       PROJECTION
+         "+init=epsg:4326"
+       END # PROJECTION
+
+       LAYER
+         NAME "heatmap" # Corresponding to the msLayer defined
+         TYPE raster
+         CONNECTIONTYPE kerneldensity
+         CONNECTION "Result"
+         STATUS on
+         PROCESSING "RANGE_COLORSPACE=HSL"
+         PROCESSING "KERNELDENSITY_RADIUS=20"
+         PROCESSING "KERNELDENSITY_COMPUTE_BORDERS=ON"
+         PROCESSING "KERNELDENSITY_NORMALIZATION=AUTO"
+         OFFSITE 0 0 0
+         CLASS
+           STYLE
+             COLORRANGE  "#0000ff00"  "#0000ffff"
+             DATARANGE 0 32
+           END # STYLE
+           STYLE
+             COLORRANGE  "#0000ffff"  "#ff0000ff"
+             DATARANGE 32 255
+           END # STYLE
+         END # CLASS
+       END # LAYER
+       
+       LAYER
+         NAME "points"
+         STATUS on
+         TYPE POINT
+         #DATA "/Library/WebServer/cache//ef76ee6642c1ea704e847e28120ba1ca.zca"
+       END # LAYER
+     END # MAPFILE
+
+
+
 
 Example
@@ -216 +306 @@
      useMapserver = true
      asReference = true
-     msClassify = ....
+     msClassify = true
     </Supported>
 

trunk/docs/kernel/sagagis.rst

@@ -4 +4 @@
 ======================
 
-`SAGA GIS <http://orfeo-toolbox.org/otb/>`_ provides a comprehensive set of geoscientific methods and spatial algorithms. The optional SAGA GIS support is available since `ZOO-Project 1.5 <http://zoo-project.org>`__. It allows to execute the `SAGA Modules <http://www.saga-gis.org/saga_module_doc/2.1.4/index.html>`_ directly as ZOO WPS Services thanks to a :ref:`kernel_index` specific internal mechanism which is detailed in this section.
+`SAGA GIS <http://www.saga-gis.org/>`_ provides a comprehensive set of geoscientific methods and spatial algorithms. The optional SAGA GIS support is available since `ZOO-Project 1.5 <http://zoo-project.org>`__. It allows to execute the `SAGA Modules <http://www.saga-gis.org/saga_module_doc/2.1.4/index.html>`_ directly as ZOO WPS Services thanks to a :ref:`kernel_index` specific internal mechanism which is detailed in this section.
 
 .. note:: 
 
-   |saga| `SAGA GIS <https://www.orfeo-toolbox.org>`__ is the System for Automated Geoscientific Analyses. Learn more on official `website <http://www.saga-gis.org/en/index.html>`__.
+   |saga| `SAGA GIS <http://www.saga-gis.org/>`__ is the System for Automated Geoscientific Analyses. Learn more on official `website <http://www.saga-gis.org/en/index.html>`__.
  
 
@@ -27 +27 @@
 
    * latest `ZOO-Kernel <http://zoo-project.org/trac/browser/trunk/zoo-project/zoo-kernel>`_ trunk version
-   * SAGA GIS (`SAGA-GIS 2.1.4  <http://saga-gis.org>`_ )
-   * libLAS-1.2 (`LibLAS-1.2  <https://github.com/libLAS/libLAS-1.2>`_ )
+   * `SAGA GIS  <http://saga-gis.org>`_  (7.2.0)
 
 Installation steps
 ...........................
 
-.. Note:: These installation steps were successfully tested on Ubuntu 14.4 LTS 
-
-Download lastest ZOO-Kernel code from SVN.
-
-.. code-block:: guess
-
-    svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel
-
-Then compile ZOO-Kernel using the needed configuration options as shown bellow:
+Compile ZOO-Kernel using the configuration options as shown bellow:
 
 .. code-block:: guess
@@ -47 +38 @@
      cd zoo-kernel
      autoconf
-     ./configure  --with-saga=/usr/local/
+     ./configure  --with-saga=/usr/local/ --with-saga-version=7
      make
 
-And copy the newly created zoo_loader.cgi to ``/usr/lib/cgi-bin`` :
-
+And copy the newly created zoo_loader.cgi to ``/usr/lib/cgi-bin``.
+     
+.. note::
+   
+    The ``--with-saga-version`` option let you set the major
+    version number of SAGA-GIS.  
+     
 .. code-block:: guess
 
@@ -62 +58 @@
 ****************************
 
-Building the `saga2zcfg
-<http://zoo-project.org/trac/browser/trunk/thirds/otb2zcfg >`_ utility is required to activate the available SAGA-GIS Modules as WPS Services. This can be done using the following command:
+Building the
+`saga2zcfg <http://zoo-project.org/trac/browser/trunk/thirds/saga2zcfg>`_
+utility is required to activate the available SAGA-GIS Modules as WPS
+Services. This can be done using the following command: 
 
 .. code-block:: guess

trunk/docs/services/howtos.rst

@@ -439 +439 @@
   }
 
+
+R
+----------
+
+ZOO API
+*********
+
+For using the R language from the ZOO-Project, you have first to copy
+``minimal.r`` in the same directory as the ZOO-Kernel.
+
+The ZOO-API is available from a R script and provide access to a
+global zoo environment which contains both static variables and also
+the dictionaries for outputs and conf:
+
+:int zoo[["SERVICE_SUCCEEDED"]]:
+   Value to return in case your service end successfully.
+:int zoo[["SERVICE_FAILED"]]:
+   Value to retrun in case of failure.
+
+The ZOO-API provides the following functions:
+
+:string ZOOTranslate(String s):
+   This function call the internal ZOO-Kernel function responsible for
+   searching a translation of ``s`` in the zoo-services dictionary.
+
+:void ZOOUpdateStatus(ZMaps conf,String pourcent):
+   This function call the updateStatus ZOO-Kernel function responsible
+   for updating the status of the running service (only usefull when
+   the service has been called asynchronously).
+
+
+R ZCFG requirements
+**********************************
+
+.. Note:: For each Service provided by your ZOO R Services Provider,
+          the ZCFG File must be named the same as the R function name
+          (it is case-sensitive).
+
+The ZCFG file should contain the following :
+
+serviceType
+   R 
+serviceProvider
+    The name of the R file to use as a ZOO Service Provider. For instance, if your
+    script, located in the same directory as your ZOO Kernel, was named ``my_module.r`` then
+    you should use ``my_module.r``.
+
+
+R Data Structure used
+********************************
+
+The three parameters of the function are passed to the R function as
+R dictionaries.
+
+The specificity of the R language make that it was easier to use
+global variales than passing parameters by reference as we do in
+other progamming languages. It is the reason why you will have to
+access outpus by using the global variable as for the main
+configuration dictionary. 
+
+Sample ZOO R Services Provider
+******************************************
+
+.. code-block:: javascript
+
+    source("minimal.r")
+                
+    hellor <- function(a,b,c) {
+        # Set the result
+        zoo[["outputs"]][["Result"]][["value"]] <<- ZOOTranslate(paste("Hello",b[["S"]][["value"]],"from the R World!",sep=" "))
+        # Return SERVICE_SUCCEEDEED
+        return(zoo[["SERVICE_SUCCEEDEED"]])
+    }
+