initial move of mbstyle extension and documentation

Signed-off-by: Jody Garnett <jody.garnett@gmail.com>
geotools · jodygarnett · Feb 13, 2020 · Jan 13, 2020 · Jan 14, 2020 · Jan 14, 2020
commit 874d4a013a7aa896f0c87a273187231159a7b49f
diff --git a/docs/user/extension/index.rst b/docs/user/extension/index.rst
@@ -11,13 +11,14 @@ Extensions build additional functionality on top of the core services of the Geo
    complex
    graph/index
    grid
+   mbstyle/index
    ogc/index
-   wms/index
    tile-client/index
+   transform/transform
+   wms/index
    wmts/index
    validation
    xsd/index
-   transform/transform
    ysld
 
 Extensions build on top of the core concepts provided by the GeoTools library. This allows the project to take on more general topics than just being a simple geospatial library.
diff --git a/docs/user/unsupported/mbstyle/index.rst → docs/user/extension/mbstyle/index.rst b/docs/user/unsupported/mbstyle/index.rst → docs/user/extension/mbstyle/index.rst
@@ -4,13 +4,13 @@ Mapbox Styles Module
 The ``gt-mbstyle`` module is an unsupported module that provides a parser/encoder to convert between Mapbox Styles and GeoTools style objects. These docs are under active development, along with the module itself.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   spec
+   spec/index
 
 References:
 
-* https://www.mapbox.com/mapbox-gl-style-spec
+* `MapBox Style Specification <https://www.mapbox.com/mapbox-gl-js/style-spec/>`__
 
 Code Example
 ^^^^^^^^^^^^
@@ -34,7 +34,7 @@ Internally the extension provides greater access to the parsed style:
     // pull back selected layers for a provided source
     List<MBLayer> layers = mbstyle.layers( "sf:roads" );
 
-    //Which can be used to Generate a List of FeatureTypeStyles:
+    // Which can be used to Generate a List of FeatureTypeStyles:
     List<FeatureTypeStyle> fts = layer.transform( style );
 
 
@@ -43,18 +43,19 @@ Zoom level tuning
 
 The mapping between zoom levels and scale denominators is performed assuming, by default, a 512 pixels
 root tile at zoom level zero. This matches the usage of vector tiles client side.
-If a different value is to be used, it's possible to set a system variable to change the default.
+If a different value is to be used, it's possible to set a system property to change the default.
 E.g., the following would match "x4" tiles:
 
 .. code-block:: java
 
-    System.setSystemProperty("MBSTYLE_ROOT_TILE_PIXELS", "1024") 
+   System.setSystemProperty("MBSTYLE_ROOT_TILE_PIXELS", "1024") 
 
 MapBox Types
 ^^^^^^^^^^^^
-  copied from the `MapBox Style Specification <https://www.mapbox.com/mapbox-gl-js/style-spec/>`_
 
-  Color
+Quoting `MapBox Style Specification <https://www.mapbox.com/mapbox-gl-js/style-spec/>`__ :
+
+  ``Color``
 
     Colors are written as JSON strings in a variety of permitted formats: HTML-style hex values, ``rgb``, ``rgba``, ``hsl``, and ``hsla``. Predefined HTML colors names, like ``yellow`` and ``blue``, are also permitted.
 

diff --git a/docs/user/extension/mbstyle/spec/LICENSE.md b/docs/user/extension/mbstyle/spec/LICENSE.md
@@ -0,0 +1,27 @@
+Copyright (c) 2016, Mapbox
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of Mapbox GL JS nor the names of its contributors
+      may be used to endorse or promote products derived from this software
+      without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/docs/user/extension/mbstyle/spec/footer.txt b/docs/user/extension/mbstyle/spec/footer.txt
@@ -0,0 +1,10 @@
+.. note::
+
+   This `Mapbox Style Specification <https://www.mapbox.com/mapbox-gl-style-spec>`__ document was started from the BSD `github.com/mapbox/mapbox-gl-js <https://github.com/mapbox/mapbox-gl-js>`__  repository.
+
+   The specification is reproduced here with details on the GeoTools MBStyle implementation. Where appropriate examples have been changed to reference `GeoWebCache <http://geowebcache.org/>`__.
+
+   Documentation :download:`BSD <LICENSE.md>` license:
+
+   .. literalinclude:: LICENSE.md
+      :language: text
diff --git a/docs/user/extension/mbstyle/spec/index.rst b/docs/user/extension/mbstyle/spec/index.rst
@@ -0,0 +1,22 @@
+Mapbox Style Specification
+==========================
+
+A Mapbox style is a document that defines the visual appearance of a map: what data to draw, the order to draw it in, and how to style the data when drawing it. A style document is a `JSON <http://www.json.org/>`__ object with specific root level and nested properties. This specification defines and describes these properties.
+
+The intended audience of this quick reference includes:
+
+- Advanced designers and cartographers who want to write styles by hand.
+- GeoTools developers using the gt-mbstyle extension
+- Authors of software that generates or processes Mapbox styles.
+
+Feature support is provided for the `Mapbox GL JS <https://www.mapbox.com/mapbox-gl-js/api/>`__, the `Open Layers Mapbox Style utility <https://npmjs.com/package/ol-mapbox-style>`__ and the GeoTools mbstyle module.
+
+.. toctree::
+   :maxdepth: 1
+
+   root
+   light
+   sources
+   spec
+
+.. include:: footer.txt
diff --git a/docs/user/extension/mbstyle/spec/light.rst b/docs/user/extension/mbstyle/spec/light.rst
@@ -0,0 +1,127 @@
+.. _light:
+
+Light
+-----
+
+A style's ``light`` property provides global light source for that style.
+
+.. code-block:: javascript
+
+    "light": {
+      "anchor": "viewport",
+      "color": "white",
+      "intensity": 0.4
+    }
+
+anchor
+~~~~~~
+
+*Optional* :ref:`types-enum`. *One of* map, viewport. *Defaults to* viewport.
+
+
+Whether extruded geometries are lit relative to the map or viewport.
+
+
+map
+    The position of the light source is aligned to the rotation of the
+    map.
+
+viewport
+    The position of the light source is aligned to the rotation of the
+    viewport.
+
+.. code-block:: javascript
+
+    "anchor": "map"
+
+.. list-table::
+   :widths: 19, 27, 27, 27
+   :header-rows: 1
+
+   * - Support
+     - Mapbox
+     - GeoTools
+     - OpenLayers
+   * - basic functionality
+     - >= 0.27.0
+     - Not yet supported
+     - Not yet supported
+
+color
+~~~~~
+
+*Optional* :ref:`types-color`. *Defaults to* ``#ffffff``
+
+Color tint for lighting extruded geometries.
+
+
+.. list-table::
+   :widths: 19, 27, 27, 27
+   :header-rows: 1
+
+   * - Support
+     - Mapbox
+     - GeoTools
+     - OpenLayers
+   * - basic functionality
+     - >= 0.27.0
+     - Not yet supported
+     - Not yet supported
+
+intensity
+~~~~~~~~~
+
+*Optional* :ref:`types-number`. *Defaults to* 0.5.
+
+Intensity of lighting (on a scale from 0 to 1). Higher numbers will
+present as more extreme contrast.
+
+.. list-table::
+   :widths: 19, 27, 27, 27
+   :header-rows: 1
+
+   * - Support
+     - Mapbox
+     - GeoTools
+     - OpenLayers
+   * - basic functionality
+     - >= 0.27.0
+     - Not yet supported
+     - Not yet supported
+
+position
+~~~~~~~~
+
+*Optional* :ref:`types-array`. *Defaults to* 1.15,210,30.
+
+Position of the light source relative to lit (extruded) geometries, in
+[r radial coordinate, a azimuthal angle, p polar angle] where r
+indicates the distance from the center of the base of an object to its
+light, a indicates the position of the light relative to 0° (0° when
+``light.anchor`` is set to ``viewport`` corresponds to the top of the
+viewport, or 0° when ``light.anchor`` is set to ``map`` corresponds to
+due north, and degrees proceed clockwise), and p indicates the height of
+the light (from 0°, directly above, to 180°, directly below).
+
+.. code-block:: javascript
+
+    "position": [
+      1.5,
+      90,
+      80
+    ]
+
+.. list-table::
+   :widths: 19, 27, 27, 27
+   :header-rows: 1
+
+   * - Support
+     - Mapbox
+     - GeoTools
+     - OpenLayers
+   * - basic functionality
+     - >= 0.27.0
+     - Not yet supported
+     - Not yet supported
+
+.. include:: footer.txt