web-server/doc/en/user/source/extensions/vectortiles/options.rst

.. _vectortiles.options:

Vector Tiles Generation Options
-------------------------------

The content of the vector tiles generated by this output format is driven by the
style used in the GetMap/GetTile request.

The style can be pretty basic. The vector tile output format considers only the following:

* Rules scale denominators and the rule filters control which features are included in the output
  (e.g., in a road layer, one can include only highways at low zoom levels)
* Feature type style and rule vendor options can provide more fine grained control over the output. 
  Inclusion of options in the rule is recommended only when trying to apply the options in a  scale dependent way.

In particular, the following vendor options can be included:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Option
     - Description
   * - vt-attributes
     - A comma separated list of attributes to be included in the output. Reducing the number of attributes helps control the tile size.
   * - vt-coalesce
     - ``true``/``false``, enables feature geometry merging when attribute values are equal. This can greatly reduce the tile size, especially when coupled with a small attribute list, which helps in finding more attribute duplicates. To perform duplicate detection, the code will run a ‘sort’ on the attributes. If the source is a database, it is best to keep the indexed ones first in the list.
   * - vt-labels
     - ``true``/``false``, enable the generation of a sidecar "<layerName>-labels" layer with label points. Meant to be used only for polygon geometries, as vector tile clients often lack the ability to compute a suitable label point.
   * - vt-label-attributes
     - A comma-separated list of attributes to include in the label layer. Typically, only the attributes needed to create the label will be included. Features will be generated only if at least one of the attribute values is not null, meaning there is a chance of creating a label.

The following SLD style, meant to be used as a "style group", demonstrates the conceptes above:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?><sld:StyledLayerDescriptor xmlns:sld="http://www.opengis.net/sld" xmlns="http://www.opengis.net/sld" xmlns:gml="http://www.opengis.net/gml" xmlns:ogc="http://www.opengis.net/ogc" version="1.0.0">
   <sld:NamedLayer>
      <sld:Name>tiger:poly_landmarks</sld:Name>
      <sld:UserStyle>
         <sld:Name>Default style</sld:Name>
         <sld:IsDefault>1</sld:IsDefault>
         <sld:FeatureTypeStyle>
         <sld:Rule>
            <sld:PolygonSymbolizer>
               <sld:Fill/>
            </sld:PolygonSymbolizer>
         </sld:Rule>
         <sld:VendorOption name="vt-coalesce">false</sld:VendorOption>
         <sld:VendorOption name="vt-attributes">CFCC</sld:VendorOption>
         <sld:VendorOption name="vt-labels">true</sld:VendorOption>
         <sld:VendorOption name="vt-label-attributes">LANAME</sld:VendorOption>
         </sld:FeatureTypeStyle>
      </sld:UserStyle>
   </sld:NamedLayer>
   <sld:NamedLayer>
      <sld:Name>tiger:tiger_roads</sld:Name>
      <sld:UserStyle>
         <sld:Name>Default style</sld:Name>
         <sld:IsDefault>1</sld:IsDefault>
         <sld:FeatureTypeStyle>
         <sld:Rule>
            <sld:MaxScaleDenominator>270000</sld:MaxScaleDenominator>
            <sld:LineSymbolizer>
               <sld:Stroke/>
            </sld:LineSymbolizer>
         </sld:Rule>
         <sld:VendorOption name="vt-coalesce">false</sld:VendorOption>
         <sld:VendorOption name="vt-attributes">NAME</sld:VendorOption>
         </sld:FeatureTypeStyle>
      </sld:UserStyle>
   </sld:NamedLayer>
   <sld:NamedLayer>
      <sld:Name>tiger:poi</sld:Name>
      <sld:UserStyle>
         <sld:Name>Default style</sld:Name>
         <sld:IsDefault>1</sld:IsDefault>
         <sld:FeatureTypeStyle>
         <sld:Rule>
            <sld:MaxScaleDenominator>135000</sld:MaxScaleDenominator>
            <sld:PointSymbolizer>
               <sld:Graphic>
               <sld:Mark>
                  <sld:Fill/>
               </sld:Mark>
               </sld:Graphic>
            </sld:PointSymbolizer>
         </sld:Rule>
         </sld:FeatureTypeStyle>
      </sld:UserStyle>
   </sld:NamedLayer>
   </sld:StyledLayerDescriptor>


Describing the salient bits:

* ``tiger_roads`` and ``poi`` are scale dependent, they won't be available in zoomed out tiles
* ``poly_landmarks`` only reports CFCC and enables polygon coaleshing, allowing to merge a few polygons with the same class
* ``poly_landmarks`` also enables a separate label layer with polygon label points (``poly_landmarks-labels``), with only the NAME attribute
* ``tiger-roads`` selects the attributes for labelling, and enables coaleshing, which helps a lot reducing the tile size, since each roads 
  is split amongs many smaller features (at intersections).
* The usage of feature coaleshing reduces the size of vector tiles by around 50%, compared to simple attribute selection, in this case. 
  Layers with more/more complex attributes will benefit more.