diff --git a/deegree-services/deegree-webservices-handbook/src/main/sphinx/conf.py b/deegree-services/deegree-webservices-handbook/src/main/sphinx/conf.py index e534ee76d8..43cb99eec9 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/sphinx/conf.py +++ b/deegree-services/deegree-webservices-handbook/src/main/sphinx/conf.py @@ -91,7 +91,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'nature' +html_theme = 'theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -99,18 +99,18 @@ #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = '.' # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +#html_logo = 'images/logo-deegree.png' # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 diff --git a/deegree-services/deegree-webservices-handbook/src/main/sphinx/filterencoding.rst b/deegree-services/deegree-webservices-handbook/src/main/sphinx/filterencoding.rst new file mode 100644 index 0000000000..f2e5a21e12 --- /dev/null +++ b/deegree-services/deegree-webservices-handbook/src/main/sphinx/filterencoding.rst @@ -0,0 +1,378 @@ +.. _anchor-configuration-filter: + +=============== +Filter Encoding +=============== + +deegree makes extensive use of the OGC Filter Encoding standard. Within deegree there are implementations +of the versions 1.1.0 and 2.0.0 of this standards and several extensions and additional functions. +This chapter is meant to explain the filter capabilities of deegree which can +be used within :ref:`anchor-configuration-renderstyles` and :ref:`anchor-configuration-wfs´ requests. + +^^^^^^^^^^^^^^^^ +Filter Operators +^^^^^^^^^^^^^^^^ + +The purpose of FE is to have a standardized way for defining selection criteria on data. +This requires the definition of operators for the creation of filter expressions. Within this section, +the supported operators are explained. Additionally there is information about deegree specific behaviour. +Depending on the version of FE, syntax may differ. In the following, FE 1.1.0 syntax is used. + +____________________ +Arithmetic operators +____________________ + +FE enables the use of the following arithmetic operators: + + * Add: used for addition + * Sub: used for substraction + * Mul: used for multiplication + * Div: used for division + +**Example:** + +.. code-block:: xml + + + app:ID + 15 + + +____________________ +Logical operators +____________________ + +FE enables the use of the following logical operators: + + * And: Links two conditions with AND + * Or: links two conditions with OR + * Not: negates a condition + +**Example:** + +.. code-block:: xml + + + app:ID + 15 + + +____________________ +Comparison operators +____________________ + +deegree has implementations for the following list of comparison operators: + + * PropertyIsEqualTo: Evaluates if a property value equals to another value. + * PropertyIsNotEqualTo: Evaluates if a property value differs from another value. + * PropertyIsLessThan: Evaluates if a property value is smaller than another value. + * PropertyIsGreaterThan: Evaluates if a property value is greater than another value. + * PropertyIsLessThanOrEqualTo: Evaluates if a property value is smaller than or equal to another value. + * PropertyIsGreaterThanOrEqualTo: Evaluates if a property value is greater than or euqal to another value. + * PropertyIsLike: Evaluates if a property value is like another value. It compares string values which each other. + * PropertyIsNull: Evaluates if a property value is NULL. + * PropertyIsBetween: Evaluates if a property value is between 2 defined values. + +**Example:** + +.. code-block:: xml + + + SomeProperty + 100 + + +_________________ +Spatial operators +_________________ + +With deegree you can make use of the following spatial operators: + + * Equals: Evaluates if geometries are identical + * Disjoin: Evaluates if geometries are spatially disjoined + * Touches: Evaluates if geometries are spatially touching + * Within: Evaluates if a geometry is spatially within another + * Overlaps: Evaluates if geometries are spatially overlapping + * Crosses: Evaluates if geometries are spatially crossing + * Intersects: Evaluates if geometries are spatially intersecting. This is meant as the opposite of disjoin. + * Contains: Evaluates if a geometry spatially contains another. + * DWithin: Evaluates if a geometry is within a specific distance to another. + * Beyond: Evaluates if a geometry is beyond a specific distance to another. + * BBOX: Evaluates if a geometry spatially intersects with a given bounding box. + +**Example:** + +.. code-block:: xml + + + Geometry + + + + ... + + + + + +.. tip:: For further reading on spatial operators, please refer to the OGC Simple Features Specification For SQL. + +^^^^^^^^^^^^^^^^^^ +Filter expressions +^^^^^^^^^^^^^^^^^^ + +For the use within map styles or WFS requests, filter expressions can be constructed from the above operators to select specific data. +This section gives some examples for the use of such filter expressions. + +_________________________ +Simple filter expressions +_________________________ + +----------------------------- +Comparative filter expression +----------------------------- + +.. code-block:: xml + + + + SomeProperty + 100 + + + +This filter expressions shows, how filter expressions with a comparative filter are constructed +In the concrete example, the property SomeProperty is evaluated, if it equals to the value of "100". + +------------------------- +Spatial filter expression +------------------------- + +.. code-block:: xml + + + + Geometry + + + + ... + + + + + + +This filter expressions shows, how filter expressions with a spatial filter are constructed. In the concrete case, the defined filter looks up, +if the property geometry overlaps with the define polygon of ... + +___________________________ +Advanced filter expressions +___________________________ + +------------------------- +Multiple filter operators +------------------------- + +.. code-block:: xml + + + + + DEPTH + 30 + + + + Geometry + + 13.0983 31.5899 + 35.5472 42.8143 + + + + + + +This more complex filter expressions shows, how to make use of combinations of filter operators. +THe given filter expression evaluates if the value of the property DEPTH is smaller than "30" AND if the +geometry property named Geometry is spatially disjoint with the given envelope. + + +------------------------------ +PropertyIsLike with a function +------------------------------ + +.. code-block:: xml + + + + name + + FALkenstrasse + + + + +This example shows, how functions can be used within filter expressions. Within the given example, the "name" property is evaluated, if it is like +the Literal FAlkenstrasse. Using a function for the evaluation of the Literal means, that the value is processed with the function before the +filter operator handles it. In the concrete case this means a normalization of the value (Which is not usable by default with deegree). + +.. tip:: Please note, the use of functions within PropertyIsLike filter operators is only possible with FE 2.0. This is the reason for the FE 2.0 notation. + + +^^^^^^^^^^^^^^^^^^^ +Custom FE functions +^^^^^^^^^^^^^^^^^^^ +Besides the filter capabilities described above, FE defines Functions to be used within filter expressions. +deegree offers the capability to use a nice set of custom FE functions for different purposes. +These are explained within the following chapter. + +____ +Area +____ + +The area function is the first in a row of custom geometry functions which can be used within deegree. With the area function it is possible to get the area of a geometry property. If multiple geometry nodes are selected, multiple area values are calculated. + +.. code-block:: xml + + + app:geometry + + +______ +Length +______ + +This function calculates the length of a linestring/perimeter of a polygon. If multiple geometry nodes are selected, multiple length values are calculated. + +.. code-block:: xml + + + app:geometry + + +________ +Centroid +________ + +This function calculates the centroid of a polygon. If multiple geometry nodes are selected, multiple centroids are calculated. + +.. code-block:: xml + + + app:geometry + + +_____________ +InteriorPoint +_____________ + +This function calculates an interior point within a polygon. If multiple geometry nodes are selected, multiple centroids are calculated. Useful to place text on a point within a polygon (centroids may not actually be a point on the polygon). + +.. code-block:: xml + + + app:geometry + + +___________________________ +IsPoint, IsCurve, IsSurface +___________________________ + +Takes one parameter, which must evaluate to exactly one geometry node. + +This function returns true, if the geometry is a point/multipoint, curve/multicurve or surface/multisurface, respectively. + +.. code-block:: xml + + + app:geometry + + +_______________ +GeometryFromWKT +_______________ + +Useful to create a constant geometry valued expression. + +.. code-block:: xml + + + EPSG:4326 + POINT(0.6 0.7) + + +____________ +MoveGeometry +____________ + +Useful to displace geometries by a certain value in x and/or y direction. + +To shift 20 geometry units in y direction: + +.. code-block:: xml + + + app:geometry + 0 + 20 + + +____ +iDiv +____ + +Integer division discarding the remainder. + +.. code-block:: xml + + + app:count + 20 + + +____ +iMod +____ + +Integer division resulting in the remainder only. + +.. code-block:: xml + + + planArt + + +_________ +ExtraProp +_________ + +Access extra (hidden) properties attached to feature objects. The availability of such properties depends on the loading/storage mechanism used. + +.. code-block:: xml + + + planArt + + +_______________ +GetCurrentScale +_______________ + +The GetCurrentScale function takes no arguments, and dynamically provides you with the value of the current map scale denominator (only to be used in GetMap requests!). The scale denominator will be adapted to any custom pixel size you may be using in your request, and is the same scale denominator the WMS uses internally for filtering out layers/style rules. + +Let's have a look at an example: + +.. code-block:: xml + + ... + + + 500000 + + + + ... + +In this case, the stroke width will be one pixel for scales around 500000, and will get bigger as you zoom in (and the scale denominator gets smaller). Scale denominators above 500000 will yield invisible strokes with a width of zero. diff --git a/deegree-services/deegree-webservices-handbook/src/main/sphinx/glossary.rst b/deegree-services/deegree-webservices-handbook/src/main/sphinx/glossary.rst index d1bb13d17d..43511fecb9 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/sphinx/glossary.rst +++ b/deegree-services/deegree-webservices-handbook/src/main/sphinx/glossary.rst @@ -4,8 +4,32 @@ Glossary .. glossary:: + CS-W + Catalogue Service for the Web + + FE + Filter Encoding + GML Geography Markup Language + SE + Symbology Encoding + + SLD + Styled Layer Descriptor + + WCS + Web Coverage Service + WFS Web Feature Service + + WMS + Web Map Service + + WMTS + Web Map Tiling Service + + WPS + Web Processing Service \ No newline at end of file diff --git a/deegree-services/deegree-webservices-handbook/src/main/sphinx/index.rst b/deegree-services/deegree-webservices-handbook/src/main/sphinx/index.rst index 1d6f3e6c57..c913af47a1 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/sphinx/index.rst +++ b/deegree-services/deegree-webservices-handbook/src/main/sphinx/index.rst @@ -22,9 +22,9 @@ deegree Webservices layers themes renderstyles + filterencoding serverconnections processproviders crs restapi javamodules - diff --git a/deegree-services/deegree-webservices-handbook/src/main/sphinx/intro.rst b/deegree-services/deegree-webservices-handbook/src/main/sphinx/intro.rst index 8510977255..6b2915862b 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/sphinx/intro.rst +++ b/deegree-services/deegree-webservices-handbook/src/main/sphinx/intro.rst @@ -18,6 +18,7 @@ Characteristics of deegree WFS deegree WFS is an implementation of the `OGC Web Feature Service specification `_. Notable features: +* Official OGC reference implementation fo WFS 1.1.0 and WFS 2.0.0 Simple * Implements WFS standards 1.0.0, 1.1.0 and 2.0.0 [#f1]_ * Fully transactional (even for rich data models) * Supports KVP, XML and SOAP requests @@ -40,6 +41,7 @@ Characteristics of deegree WMS deegree WMS is an implementation of the `OGC Web Map Service specification `_. Notable features: +* Official OGC reference implementation for WMS 1.1.1 * Implements WMS standards 1.1.1 and 1.3.0 [#f2]_ * Extensive support for styling languages SLD/SE versions 1.0.0 and 1.1.0 * High performance and excellent scalability diff --git a/deegree-services/deegree-webservices-handbook/src/main/sphinx/renderstyles.rst b/deegree-services/deegree-webservices-handbook/src/main/sphinx/renderstyles.rst index 1cf23b8575..e1ac5f39d3 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/sphinx/renderstyles.rst +++ b/deegree-services/deegree-webservices-handbook/src/main/sphinx/renderstyles.rst @@ -6,9 +6,8 @@ Map styles Style resources are used to obtain information on how to render geo objects (mostly features, but also coverages) into maps. The most common use case is to reference them from a layer configuration, in order to describe how the layer is to be rendered. This chapter assumes the reader is familiar with basic SLD/SE terms. The style configurations do not depend on any other resource. -In contrast to other deegree configurations the style configurations do not have a custom format. You can use standard SLD or SE documents (1.0.0 and 1.1.0 are supported), with a couple of deegree specific extensions, which are described below. Please refer to the StylesConfiguration_ wiki page for examples, and to the SLD_ and SE_ specifications for reference. +In contrast to other deegree configurations the style configurations do not have a custom format. You can use standard SLD or SE documents (1.0.0 and 1.1.0 are supported), with a couple of deegree specific extensions, which are described below. Please refer to the SLD_ and SE_ specifications for reference. Additionally this page contains specific examples below. -.. _StylesConfiguration: http://wiki.deegree.org/deegreeWiki/deegree3/WorkspaceConfiguration/StylesConfiguration .. _SLD: http://www.opengeospatial.org/standards/sld .. _SE: http://www.opengeospatial.org/standards/se @@ -24,6 +23,540 @@ In deegree terms, each SLD or SE file will create a *style store*. In case of an .. tip:: When defining styles, take note of the log file. Upon startup the log will warn you about potential problems or errors during parsing, and upon rendering warnings will be emitted when rendering is unsuccessful eg. because you had a typo in a geometry property name. When you're seeing an empty map when expecting a fancy one, check the log before reporting a bug. deegree will tolerate a lot of syntactical errors in your style files, but you're more likely to get a good result when your files validate and you have no warnings in the log. +^^^^^^^^ +Overview +^^^^^^^^ + +From the point of view of the Symbology Encoding Standard, there are 5 kinds of symbolizations, which can be present in a map image: + * **Point symbolizations** + * **Line symbolizations** + * **Polygon symbolizations** + * **Text symbolizations** + * **Raster symbolizations** + +The first 4 symbolizations usually represent vector feature objects. Raster symbolization is used to visualize raster data. This documentation chapter describes, how those +symbolizations can be realized using OGC symbology encoding. It will lead from the underlying basics to some more complex constructions for map visulization. + +^^^^^^ +Basics +^^^^^^ + +________________ +General Layout +________________ + +The general structure of an SE-Style contains: + +.. code-block:: xml + + + + + +It is constructed like this: + +.. code-block:: xml + + + plan:yourFeatureType + + ... + + + +.. Tip:: Before you start, always remember that every style is read top-down. So be aware the second will overpaint the first one, the third overpaints the second and so on + +___________________ +Symbolization Rules +___________________ + +Every specific map visualization needs its own symbolization rule. Rules are defined within the **** element. Each rule can consist of at least one symbolizer. +Every rule has its own name and description elements. The description elements are used to create the legend caption from it. + +Depending on the type of symbolization to create, one of the following symbolizers can be used: + + * + * + * + * + * + +Symbolizers can have an uom-attribute (units of measure), which determines the unit of all values set inside the Symbolizer. The following values for UoM are supported within deegree: + + * uom="pixel" + * uom="meter" + * uom="mm" + +The default value is "pixel". + +Within every symbolizer (except rastersymbolizers), a geometry property used for the rendering, can be specified with the **** element. +If there is no geometry specified the first geometry property of the FeatureType will be used. + +Each of the (Vector-)Symbolizer-elements has its dimensions, which are described in more detail below: + + * **** has only one dimension: the -element (to style the stroke). + * **** has two dimensions: the (to sytle the stroke of the polygon) and the -element (to style the inside of the polygon). + * **** can also contain both dimensions: the (to style the stroke of the point) and the -element (to style the inside of the point). + * **** has three dimensions: the