feat: add map components documentation

docs/KnowledgeBase/MapViewers/README.md

@@ -0,0 +1,25 @@
+---
+id: map-viewers-overview
+slug: map-viewers-overview
+title: Map viewers
+sidebar_position: 1
+tags:
+ - map-viewers
+ - viewers
+ - overview
+---
+
+There are so many map viewers out there, how do you choose the best one for your needs?
+Here we attempt to help you make this decision.
+
+Disclaimer:
+Everything written in this knowledge base is based on our research of selected well known map viewers. We do not attempt to recommend one as the best, but give you all the information we believe you need in order to make a better decision based on your use case.
+Some of the viewers may be incompatible with some of our data or services and will require additional adjustments in order to consume them (for some it may not be possible at all).
+
+So lets get started!
+
+## What is a map viewer / component?
+
+A map viewer is a visual component to help us display `geographic` data such as raster, vector, 3D and DEM. It does all of the heavy-lifting in fetching, calculating and displaying the data correctly.
+
+There are many features that a map viewer could implement, please read more about the different libraries and features [here](/docs/KnowledgeBase/MapViewers/map-components.md).

docs/KnowledgeBase/MapViewers/_category_.json

@@ -0,0 +1,3 @@
+{
+    "position": 2
+}

docs/KnowledgeBase/MapViewers/map-components.md

@@ -0,0 +1,134 @@
+---
+id: map-viewers-features
+slug: map-viewers-features
+title: Map viewers Features
+sidebar_position: 2
+tags:
+  - map-viewers
+---
+
+In this page we list some features that you may be interested in and show which map viewers support them.
+
+## Map viewers reviewed in this page
+
+Cesium - [Docs](https://cesium.com/learn/cesiumjs-learn/), [Playground](https://sandcastle.cesium.com/)
+
+Leaflet - [Docs](https://leafletjs.com/reference.html), [Examples](https://leafletjs.com/examples.html), [Playground](https://codesandbox.io/s/leaflet-playground-8riog)
+
+OpenLayers - [Docs](https://openlayers.org/en/latest/apidoc/), [Examples](https://openlayers.org/en/latest/examples/), [Playground](https://codesandbox.io/examples/package/openlayers)
+
+EsriJS - [Docs](https://developers.arcgis.com/javascript/latest/), [Examples](https://developers.arcgis.com/javascript/latest/sample-code/), [Playground](https://developers.arcgis.com/javascript/3/samples/playground/)
+
+iTowns - [Docs](https://www.itowns-project.org/), [Examples](http://www.itowns-project.org/itowns/examples/index.html)
+
+Mapbox - [Docs](https://docs.mapbox.com/mapbox-gl-js/guides/), [Examples](https://docs.mapbox.com/mapbox-gl-js/example/), [Playground](https://docs.mapbox.com/playground/)
+
+deck.gl - [Docs](https://deck.gl/docs), [Examples](https://deck.gl/examples)
+
+Maplibre-gl-js - [Docs](https://maplibre.org/maplibre-gl-js/docs/API/), [Examples](https://maplibre.org/maplibre-gl-js/docs/examples/)
+
+## Projections
+
+If you don't know what a `projection` is, please read more [here](/docs/KnowledgeBase/terms#mapping), or on [wikipedia 🌐](https://en.wikipedia.org/wiki/Map_projection).
+
+| **Viewer** | **EPGS:4326** | **EPSG:3857** | **Supported projections** | **Can reproject** | **Notes** |
+| ----------- | ----------- | ----------- | ----------- | ----------- |
+| Cesium | ✅ | ✅ | [Projections](https://cesium.com/learn/cesiumjs/ref-doc/MapProjection.html) | ✅ | |
+| Leaflet | ✅ | ✅ | [Projections](https://leafletjs.com/reference.html#projection) | ❌ | |
+| OpenLayers | ✅ | ✅ | [Projections](https://openlayers.org/en/latest/apidoc/module-ol_proj_Projection-Projection.html) | ✅ | Supports all EPSG |
+| EsriJS | ✅ | ✅ | [Projections](https://pro.arcgis.com/en/pro-app/latest/help/mapping/properties/list-of-supported-map-projections.htm) | ✅ | Supports all EPSG |
+| iTowns | ✅ | ❌ | [Projections](https://www.itowns-project.org/itowns/docs/tutorials/Fundamentals.html) | | |
+| Mapbox v1 | ❌ | ✅ | [Projections](https://docs.mapbox.com/mapbox-gl-js/guides/projections/) | | |
+| Mapbox v2 | ➖ Not tested yet go to projection https://docs.mapbox.com/mapbox-gl-js/api/map/ | ✅ | [Projections](https://docs.mapbox.com/mapbox-gl-js/guides/projections/) | ❌ | |
+| deck.gl | ❌ | ✅ | [Projections](https://deck.gl/docs/developer-guide/views) | | |
+| Maplibre-gl-js | ❌ | ✅ | | | |
+
+## Raster
+
+### Supported data types and protocols
+
+| **Viewer** | **WMS** | **Can read WMS capabilities** | **WMTS** | **Can read WMTS capabilities** | **Tile Layer** | **GeoTiff** | **COG** |
+| ----------- | ----------- | ----------- | ----------- | ----------- | ----------- | ----------- | ----------- |
+| Cesium | ✅ | ❌ | ✅ | ❌ | ✅ | | |
+| Leaflet | ✅ | ❌ | ✅ | ➖ Possible with package or TileLayer Hack | ✅ | | |
+| OpenLayers | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| EsriJS | ✅ | | ✅ | ✅ | | |
+| iTowns | ✅ | | ✅ | ❌ | | |
+| Mapbox v1 | ✅ | | | | | |
+| Mapbox v2 | ✅ | | | | | |
+| deck.gl | ✅ | | ➖ With package or TileLayer Hack | | | |
+| Maplibre-gl-js | ✅ | | ➖ Through templating | | | |
+
+### Features
+
+| **Viewer** | **Bounds** | **Image Bands** | **Features** |
+| ----------- | ----------- | ----------- | ----------- |
+| Cesium | ✅ (By defining the layer's rectangle) | ➖ Supports opacity (Alpha) | ✅ GPUable |
+| Leaflet | ❌ | ➖ Supports opacity (Alpha) | ✅ GPUable (only via CSS animations) |
+| OpenLayers | ✅ (BBOX extent) | ✅ | ✅ Preload tiles <br/> ✅ GPUable |
+| EsriJS | ✅ (BBOX extent) | ➖ Supports opacity (Alpha) | |
+| iTowns | | ❌ | ✅ Immersive view (Street view) <br/> ✅ GPUable |
+| Mapbox v1 | | | ✅ GPUable |
+| Mapbox v2 | | | ✅ GPUable |
+| deck.gl | | | ✅ GPUable |
+| Maplibre-gl-js | ✅ (Array of numbers) | ➖ Supports opacity (Alpha) | ✅ GPUable |
+
+## 3D
+
+| **Viewer** | **3D Tiles** | **I3S** | **Point cloud** | **Features** |
+| ----------- | ----------- | ----------- | ----------- | ----------- |
+| Cesium | ✅ | ✅ | ✅ | - Control sun and atmosphere<br/>- Custom lightings |
+| Leaflet | ❌ | ❌ | ❌ | |
+| OpenLayers | ❌ | ❌ | ❌ | |
+| EsriJS | ❌ | ✅ | ✅ | Custom lightings |
+| iTowns | ✅ | ❌ | ✅ | Sun simulation |
+| Mapbox v1 | ❌ | ❌ | ❌ | |
+| Mapbox v2 | ❌ | ❌ | ❌ | |
+| deck.gl | ✅ | ✅ | ✅ | Custom lightings |
+| Maplibre-gl-js | | | | |
+
+## DEM
+
+### Terrain
+
+| **Viewer** | **QMesh** | **Raster DEM** | **Skyline terrain** |
+| ----------- | ----------- | ----------- | ----------- |
+| Cesium | ✅ | ❌ | ✅ (With plugin) |
+| Leaflet | ❌ | ❌ | |
+| OpenLayers | ❌ | ❌ | |
+| EsriJS | ❌ | ➖ (ESRI format) | |
+| iTowns | ❌ | ✅ | |
+| Mapbox v1 | ❌ | | |
+| Mapbox v2 | ❌ | ✅ | |
+| deck.gl | ❌ | ✅ | |
+| Maplibre-gl-js | | ✅ | |
+
+## Vector
+
+### Supported data types and protocols
+
+| **Viewer** | **WFS** | **GeoJSON** | **Features** | **Drawing** |
+| ----------- | ----------- | ----------- | ----------- |
+| Cesium | ❌ No native support but feasible | ✅ | ✅ | ✅ |
+| Leaflet | ❌ No native support but feasible | ✅ | ✅ 2D<br/>❌ 3D | ✅ |
+| OpenLayers | ✅ | ✅ | ✅ 2D<br/>❌ 3D<br/>✅ OpenLayers symbology<br/>✅ Mapbox symbology adapter | ✅ With complex symbology |
+| EsriJS | ✅ | ✅ | | |
+| iTowns | ✅ | ✅ | ✅ 2D<br/>✅ 2.5D<br/>❌ 3 | ✅ Simple symbolog |
+| Mapbox v1 | | ✅ | ✅ 2D<br/>✅ 2.5D<br/>❌ 3 | ✅ With complex symbolog |
+| Mapbox v2 | | ✅ | ✅ 2D<br/>✅ 2.5D<br/>❌ 3 | ✅ With complex symbolog |
+| deck.gl | ❌ | ✅ | | |
+| Maplibre-gl-js | | | | |
+
+### Vector Tiles
+
+| **Viewer** | **Query** | **Symbology** | **OGC Vector Tiles** |
+| ----------- | ----------- | ----------- | ----------- |
+| Cesium | ❌ | ❌ | ❌ |
+| Leaflet | ❌ | | ❌ |
+| OpenLayers | ✅ | ❌ | ✅ |
+| EsriJS | ✅ | ✅ | ❌ |
+| iTowns | ✅ | ❌ | ❌ |
+| Mapbox v1 | ✅ | ✅ But for v1 | ❌ |
+| Mapbox v2 | ✅ | ✅ | ❌ |
+| deck.gl | ✅ | ❌ | ❌ |
+| Maplibre-gl-js | | ✅ | |

docs/KnowledgeBase/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Knowledge Base",
+    "position": 1,
+    "link": {
+      "type": "generated-index",
+      "description": "MapColonies Knowledge Base"
+    }
+}

docs/MapColonies/Raster/services/export.mdx

@@ -43,7 +43,7 @@ for more details view:
 - **https://www.sqlite.org/index.html**
 
 Our specification consists of the following:
-- [Terms & Abbreviations](/docs/MapColonies/terms)
+- [Terms & Abbreviations](/docs/KnowledgeBase/terms)
 - [Tiling scheme](/docs/MapColonies/Raster/overview/#raster-tiling-scheme-in-detail) (World CRS84 TileMatrixSet)
 - file extension: ".gpkg"
 

docs/MapColonies/openstreetmap/osm-carto/README.md

@@ -19,7 +19,7 @@ For more information check [Raster step by step guide](/docs/MapColonies/Raster/
 
 ## What did we do
 As this stylesheet is an open-source, we had to make a few minor changes compared to the original one.
-- We changed the stylesheet projection from Web Mercator to WGS84. See [mapping terms](/docs/MapColonies/terms#mapping).
+- We changed the stylesheet projection from Web Mercator to WGS84. See [mapping terms](/docs/KnowledgeBase/terms#mapping).
 - We modified the database insertion script to prefer names in Hebrew and English when possible.
 - We imported data from the Natural Earth dataset in places where we didn't import OSM data.
 

docusaurus.config.js

@@ -126,6 +126,12 @@ const config = {
             position: 'left',
             label: 'OGC',
           },
+          {
+            type: 'docSidebar',
+            sidebarId: 'knowledgeBaseSidebar',
+            position: 'left',
+            label: 'Knowledge base',
+          },
         ],
       },
       footer: {

sidebars.js

@@ -16,6 +16,7 @@ const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
   ogcSidebar: [{type: 'autogenerated', dirName: 'ogc'}],
   docSidebar: [{ type: 'autogenerated', dirName: 'MapColonies'}],
+  knowledgeBaseSidebar: [{ type: 'autogenerated', dirName: 'KnowledgeBase'}],
   gettingStartedSidebar: [
     {
       type: 'category',