Add draft GeoStyler page

Author: geographika

workshop/content/docs/advanced/geostyler.md

@@ -0,0 +1,84 @@
+# Vector Styling in OpenLayers using GeoStyler
+
+!!! warning
+
+    This page is currently in a draft form. It may also require features
+    only available in the `main` MapServer branch, and not yet released in a stable version.
+
+## Overview
+
+[GeoStyler](https://geostyler.org/) is *an open-source React library that enables developers to build flexible and powerful graphical user interfaces for map-styling in the browser*.
+
+It has many different parsers that allow conversion of one style format to another. In this example, we will use the [SLD parser](https://geostyler.org/docs/usage/parsers/sld/) 
+to convert SLD created by MapServer styles into GeoStyler JSON format, which can then be used to style vector layers in OpenLayers.
+
+
+<div class="map" style="height: 600px; border: 1px solid black;">
+  <iframe src="https://mapserver.github.io/getting-started-with-mapserver-demo/geostyler.html"></iframe>
+</div>
+
+
+## Mapfile Notes
+
+### Symbols
+
+Symbols are added to the Mapfile using `INCLUDE` directives, which allows them to be loaded into the
+demo web application. The symbol `NAME` matches the `LAYER` name.
+
+### Symbol Resolution
+
+[RESOLUTION](https://mapserver.org/mapfile/map.html#mapfile-map-resolution) and [DEFRESOLUTION](https://mapserver.org/mapfile/map.html#mapfile-map-defresolution)
+are used to control the scaling of symbols in MapServer.
+
+When a WMS source has `serverType: 'mapserver', OpenLayers requests HiDPI images by adding
+`MAP_RESOLUTION` = 90 × device pixel ratio to the request (when the ratio isn't 1).
+The 90 value is [hard-coded in OpenLayers](https://github.com/openlayers/openlayers/blob/69e07d8ad933c3081cc10b8bb4a64023917661aa/src/ol/source/wms.js#L99)
+and based on the OGC standard rendering pixel size of 0.28 mm (25.4 mm per inch ÷ 0.28 mm per pixel = 90.71 pixels per inch).
+
+The device pixel ratio is a property of the browser, and can be different on different devices.
+To find your browser pixel device ratio, open the developer tools and check the `window.devicePixelRatio` value.
+
+For example, if this is `1.5`, then the `MAP_RESOLUTION` parameter sent by OpenLayers to MapServer as part of the WMS request
+will be `90 * 1.5 = 135`. The image is requested at 1.5 times the size of the map. When this parameter is sent
+by a client, it overrides the `RESOLUTION` value set in the Mapfile for that request.
+
+MapServer scales symbol sizes by `RESOLUTION / DEFRESOLUTION`. Setting both to 90 keeps symbols
+at the same visual size on any screen, matching the SLD sizes used for client-side styling.
+When `MAP_RESOLUTION` is 135, symbols are scaled by 1.5 in an image that the browser displays 1.5 times smaller.
+
+With MapServer's defaults of 72, symbols would instead be scaled by `135 / 72 = 1.875`
+in the image, so they appear 1.25 times too large on HiDPI screens.
+
+
+```scala
+RESOLUTION 90 # if no MAP_RESOLUTION is provided in a request, MapServer uses this value
+DEFRESOLUTION 90 # set to match OpenLayers default. MapServer default is 72
+```
+
+## Applying Styles with GeoStyler
+
+
+## Code
+
+!!! example
+
+    - Inbuilt OpenLayers request: <http://localhost:7000/GEOSTYLER/?template=openlayers&mode=browse&layers=all>
+    - OpenLayers and SLD viewer: <http://localhost:7001/geostyler.html>
+    - Direct `GetStyles` request: <http://localhost:7000/?map=/etc/mapserver/geostyler.map&REQUEST=GetStyles&SERVICE=WMS&VERSION=1.3.0&LAYERS=notched-rect>
+
+??? JavaScript "geostyler.js"
+
+    ``` js
+    --8<-- "geostyler.js"
+    ```
+
+??? Mapfile "geostyler.map"
+
+    ``` scala
+    --8<-- "geostyler.map"
+    ```
+
+
+## Exercises
+
+1. Play around with the `RESOLUTION` and `DEFRESOLUTION` values in the Mapfile and see how it affects the symbol sizes.

workshop/content/zensical.toml

@@ -53,7 +53,8 @@ nav = [
         { "Clusters" = "advanced/clusters.md" },
         { "SLD" = "advanced/sld.md" },
         { "STAC" = "advanced/stac.md" },
-        { "Non-EPSG CRSs" = "advanced/other-projections.md" }
+        { "Non-EPSG CRSs" = "advanced/other-projections.md" },
+        { "GeoStyler" = "advanced/geostyler.md" }
     ]},
     { "Summary" = "summary.md" },
     { "Credits and Thanks" = "credits.md" }

workshop/exercises/app/css/geostyler.css

@@ -129,3 +129,30 @@ html, body {
     .code .cm-content {
         padding-bottom: 40px;
     }
+
+    /* `display: flex` on .code would otherwise override the hidden attribute */
+    .code[hidden] {
+        display: none;
+    }
+
+/* Tabs in the bottom-right panel title bar */
+.tabs {
+    display: flex;
+    gap: 4px;
+    padding-bottom: 0;
+}
+
+.tab {
+    font: inherit;
+    color: #777;
+    background: none;
+    border: none;
+    border-bottom: 2px solid transparent;
+    padding: 0 6px 3px;
+    cursor: pointer;
+}
+
+    .tab.active {
+        color: #444;
+        border-bottom-color: #444;
+    }

workshop/exercises/app/geostyler-openlayers-parser-5.8.0.tgz

@@ -38,8 +38,12 @@
                 </div>
             </div>
             <div class="panel">
-                <div class="panel-title">SLD (applied in OpenLayers)</div>
+                <div class="panel-title tabs" role="tablist">
+                    <button class="tab active" role="tab" data-tab="sld-text">SLD</button>
+                    <button class="tab" role="tab" data-tab="geostyler-text">GeoStyler style (used by OpenLayers)</button>
+                </div>
                 <div id="sld-text" class="code"></div>
+                <div id="geostyler-text" class="code" hidden></div>
             </div>
         </section>
     </main>

workshop/exercises/app/geostyler.html

@@ -14,6 +14,7 @@ import xmlFormat from 'xml-formatter';
 import { EditorView, basicSetup } from 'codemirror';
 import { EditorState } from '@codemirror/state';
 import { xml } from '@codemirror/lang-xml';
+import { json } from '@codemirror/lang-json';
 
 const mapserverUrl = import.meta.env.VITE_MAPSERVER_BASE_URL;
 const mapfilesPath = import.meta.env.VITE_MAPFILES_PATH;
@@ -33,6 +34,7 @@ const demoLayers = [
     { id: 'notched-rect', type: 'point' },
     { id: 'square-spaced', type: 'polygon' },
     { id: 'wave', type: 'polygon' },
+    { id: 'fills', type: 'polygon' },
 ];
 
 const sldParser = new SLDParser();
@@ -72,6 +74,7 @@ function setText(view, text) {
 const classView = createViewer('class-text', mapfileLanguage);
 const symView = createViewer('sym-text', mapfileLanguage);
 const sldView = createViewer('sld-text', xml());
+const geostylerView = createViewer('geostyler-text', json());
 
 function showSld(text) {
     let formatted = text;
@@ -124,20 +127,14 @@ async function fetchSld(layerConfig) {
 
 /**
  * Convert an SLD to an OpenLayers style with GeoStyler, and apply it.
+* Returns the GeoStyler style the OpenLayers style was created from.
  */
 async function applySld(sldXmlString, vectorLayer) {
     const gs = await sldParser.readStyle(sldXmlString);
     if (gs.errors) {
         throw new Error(`Errors parsing the SLD: ${gs.errors}`);
     }
 
-    // MapServer applies the first matching CLASS, so a final CLASS without an
-    // EXPRESSION means "everything else". In SLD a rule without a filter
-    // matches every feature, so mark such rules as else rules.
-    const rules = gs.output.rules;
-    if (rules.some((r) => r.filter)) {
-        rules.filter((r) => !r.filter).forEach((r) => { r.elseRule = true; });
-    }
     console.log(`GeoStyler style for layer ${vectorLayer.get('name')}:`, gs.output);
 
     const ol = await olParser.writeStyle(gs.output);
@@ -148,6 +145,7 @@ async function applySld(sldXmlString, vectorLayer) {
     console.log(`OpenLayers style for layer ${vectorLayer.get('name')}:`, ol.output);
 
     vectorLayer.setStyle(ol.output);
+    return gs.output;
 }
 
 function createVectorLayer(layerConfig) {
@@ -206,19 +204,20 @@ function main() {
         const classFile = `${layerConfig.id}.class`;
         const symFile = `${layerConfig.id}.sym`;
 
-        const [classText, symText, sld] = await Promise.all([
+        const [classText, symText, { sld, geostylerStyle }] = await Promise.all([
             fetchText(`${includesUrl}${classFile}`)
                 .catch((error) => `# Could not load ${classFile}: ${error.message}`),
             fetchOptionalText(`${includesUrl}${symFile}`)
                 .catch(() => null),
             fetchSld(layerConfig)
                 .then(async (sldXmlString) => {
-                    await applySld(sldXmlString, vectorLayer);
-                    return sldXmlString;
+                    const style = await applySld(sldXmlString, vectorLayer);
+                    return { sld: sldXmlString, geostylerStyle: style };
                 })
                 .catch((error) => {
                     console.error(`Failed to style layer ${layerConfig.id}`, error);
-                    return `Could not load or apply the SLD: ${error.message}`;
+                    const message = `Could not load or apply the SLD: ${error.message}`;
+                    return { sld: message, geostylerStyle: null };
                 }),
         ]);
 
@@ -235,8 +234,24 @@ function main() {
         setText(symView, symText ?? '');
 
         showSld(sld);
+        setText(geostylerView, geostylerStyle
+            ? JSON.stringify(geostylerStyle, null, 2)
+            : '// No GeoStyler style: see the SLD tab for the error');
 
         mapRight.getLayers().clear();
+
+        // Tabs in the bottom-right panel: show one viewer at a time
+        const tabs = document.querySelectorAll('.tab');
+        tabs.forEach((tab) => {
+            tab.addEventListener('click', () => {
+                tabs.forEach((t) => {
+                    const active = t === tab;
+                    t.classList.toggle('active', active);
+                    document.getElementById(t.dataset.tab).hidden = !active;
+                });
+            });
+        });
+
         mapRight.addLayer(baseLayer());
         mapRight.addLayer(vectorLayer);
     }