diff --git a/docs/KnowledgeBase/MapViewers/README.md b/docs/KnowledgeBase/MapViewers/README.md new file mode 100644 index 000000000..0df4a9b5f --- /dev/null +++ b/docs/KnowledgeBase/MapViewers/README.md @@ -0,0 +1,87 @@ +--- +id: map-viewers-overview +slug: map-viewers-overview +title: Map viewers +sidebar_position: 1 +tags: + - map-viewers + - viewers + - overview +--- + +## 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](./map-components-comparison.md). + +## Choosing a map viewer + +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! + +## Most commonly used map viewers + +### Cesium πŸ†“ + +A complete platform for 3D geospatial data – handling everything from optimization to visualization to analytics. CesiumJS is an open source JavaScript library for world-class 3D mapping. + +Read more [here](https://cesium.com/learn/cesiumjs-learn/) and try out the [playground](https://sandcastle.cesium.com/). + +### Leaflet πŸ†“ + +Designed with simplicity, performance and usability in mind. It works efficiently across all major desktop and mobile platforms, can be extended with lots of plugins, has a beautiful, easy to use and well-documented API and a simple, readable source code that is a joy to contribute to. + +Leaflet is the leading open-source JavaScript library for mobile-friendly interactive maps. Weighing just about 42 KB of JS, it has all the mapping features most developers ever need. + +Read more [here](https://leafletjs.com/reference.html), see some [examples](https://leafletjs.com/examples.html) and try out the [playground](https://codesandbox.io/s/leaflet-playground-8riog). + +### OpenLayers πŸ†“ + +An open-source JavaScript library for displaying map data in web browsers as slippy maps. It provides an API for building rich web-based geographic applications similar to Google Maps and Bing Maps. + +Read more [here](https://openlayers.org/en/latest/apidoc/), see some [examples](https://openlayers.org/en/latest/examples/) and try out the [playground](https://codesandbox.io/examples/package/openlayers). + +### ArcGIS JS SDK πŸ’° + +ArcGIS is a family of client, server and online geographic information system (GIS) software developed and maintained by Esri. + +Use ArcGIS Maps SDK for JavaScript to build compelling web apps that unlock your data’s potential with interactive user experiences and stunning 2D and 3D visualizations. + +Read more [here](https://developers.arcgis.com/javascript/latest/), see some [examples](https://developers.arcgis.com/javascript/latest/sample-code/) and try out the [playground](https://developers.arcgis.com/javascript/3/samples/playground/). + +### iTowns πŸ†“ + +ITowns is a javascript framework for 3D geographic data visualisation. It can display a wide range of data such as ortho-images, Digital Elevation Models (DEM) or 3D models. + +ITowns is based on Three.js, which is a javascript library that implements WebGL to render sophisticated 3D Geometry on a webpage. + +Read more [here](https://www.itowns-project.org/) and see some [examples](http://www.itowns-project.org/itowns/examples/index.html). + +### Mapbox GL JS πŸ†“ + πŸ’° + +A client-side JavaScript library for building web maps and web applications with Mapbox's modern mapping technology. You can use Mapbox GL JS to display Mapbox maps in a web browser or client, add user interactivity, and customize the map experience in your application. + +Read more [here](https://docs.mapbox.com/mapbox-gl-js/guides/), see some [examples](https://docs.mapbox.com/mapbox-gl-js/example/) and try out the [playground](https://docs.mapbox.com/playground/). + +### deck.gl πŸ†“ + +A GPU-powered framework for visual exploratory data analysis of large datasets. + +deck.gl APIs are designed to reflect the reactive programming paradigm. Whether using Vanilla JS or the React interface, it can handle efficient WebGL2/WebGPU rendering under heavy data load. + +While deck.gl works standalone without a base map, it plays nicely with your favorite base map libraries such as Google Maps, Mapbox, ArcGIS, MapLibre, and more. Where the base map library permits, deck.gl may interleave with 3D map layers to create seamless visualizations. + +Read more [here](https://deck.gl/docs) and see some [examples](https://deck.gl/examples). + +### Maplibre-gl-js πŸ†“ + +A TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser. The customization of the map comply with the MapLibre Style Spec. It is part of the MapLibre ecosystem, with a counterpart for Android, iOS and other platforms called MapLibre Native. + +Read more [here](https://maplibre.org/maplibre-gl-js/docs/API/) and see some [examples](https://maplibre.org/maplibre-gl-js/docs/examples/). diff --git a/docs/KnowledgeBase/MapViewers/_category_.json b/docs/KnowledgeBase/MapViewers/_category_.json new file mode 100644 index 000000000..37b1b6e59 --- /dev/null +++ b/docs/KnowledgeBase/MapViewers/_category_.json @@ -0,0 +1,3 @@ +{ + "position": 2 +} diff --git a/docs/KnowledgeBase/MapViewers/map-components-comparison.md b/docs/KnowledgeBase/MapViewers/map-components-comparison.md new file mode 100644 index 000000000..f9f3ffc59 --- /dev/null +++ b/docs/KnowledgeBase/MapViewers/map-components-comparison.md @@ -0,0 +1,143 @@ +--- +id: map-viewers-comparison +slug: map-viewers-comparison +title: Map viewers comparison +sidebar_position: 2 +tags: + - map-viewers + - map-components + - cesium + - leaflet + - openlayers + - arcgis + - itowns + - mapbox + - deck.gl + - maplibre +--- + +In this page we list some features that you may be interested in and show which map viewers support them. + +:::caution +Not all mentioned featuresare supported by MapColonies. +To see supported features please browse the documentation. +::: + +## Projections and Coordinate Systems + +:::danger +The only supported `Coordinate System` in our project is `WGS84` (`EPSG:4326`) with a `tiling scheme` of `1x2`. +::: + +:::info +If you don't know what a `Coordinate System` or `projection` is, you can find the defenition [here](../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 | +| ArcGIS JS SDK | βœ… | βœ… | [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 | βœ… | [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 | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | βœ… | +| ArcGIS JS SDK | βœ… | | βœ… | βœ… | βœ… | | | +| iTowns | βœ… | | βœ… | ❌ | βœ… | | | +| Mapbox v1 | βœ… | | | | | | | +| Mapbox v2 | βœ… | | | | | | | +| deck.gl | βœ… | | βž– With package or TileLayer Hack | | | | | +| Maplibre-gl-js | βœ… | | βž– Through templating | | | | | + +### Features + +| **Viewer** | **Bounds** | **Image Bands** | **Alpha** | **GPU** | **Features** | +| ----------- | ----------- | ----------- | ----------- | ----------- | ----------- | +| Cesium | βœ… | ❌ | βœ… | βœ… | | +| Leaflet | ❌ | ❌ | βœ… | βœ… | | +| OpenLayers | βœ… | βœ… | | βœ… | Preload tiles | +| ArcGIS JS SDK | βœ… | ❌ | βœ… | βœ… | | +| iTowns | | ❌ | | βœ… | Immersive view (Street view) | +| Mapbox v1 | | | | βœ… | | +| Mapbox v2 | | | | βœ… | | +| deck.gl | | | | βœ… | | +| Maplibre-gl-js | βœ… | ❌ | βœ… | βœ… | | + +:::info +Image bands means that the map viewer let's us control the RGB scales of the displayed layers. +::: + +## 3D + +| **Viewer** | **3D Tiles** | **I3S** | **Point cloud** | **Features** | +| ----------- | ----------- | ----------- | ----------- | ----------- | +| Cesium | βœ… | βœ… | βœ… | - Control sun and atmosphere
- Custom lightings | +| Leaflet | ❌ | ❌ | ❌ | | +| OpenLayers | ❌ | ❌ | ❌ | | +| ArcGIS JS SDK | ❌ | βœ… | βœ… | Custom lightings | +| iTowns | βœ… | ❌ | βœ… | Sun simulation | +| Mapbox v1 | ❌ | ❌ | ❌ | | +| Mapbox v2 | ❌ | ❌ | ❌ | | +| deck.gl | βœ… | βœ… | βœ… | Custom lightings | +| Maplibre-gl-js | | | | | + +## DEM + +| **Viewer** | **QMesh** | **Raster DEM** | **Skyline terrain** | +| ----------- | ----------- | ----------- | ----------- | +| Cesium | βœ… | ❌ | βœ… (With plugin) | +| Leaflet | ❌ | ❌ | | +| OpenLayers | ❌ | ❌ | | +| ArcGIS JS SDK | ❌ | βž– (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
❌ 3D | βœ… | +| OpenLayers | βœ… | βœ… | βœ… 2D
❌ 3D
βœ… OpenLayers symbology
βœ… Mapbox symbology adapter | βœ… With complex symbology | +| ArcGIS JS SDK | βœ… | βœ… | | | +| iTowns | βœ… | βœ… | βœ… 2D
βœ… 2.5D
❌ 3 | βœ… Simple symbolog | +| Mapbox v1 | | βœ… | βœ… 2D
βœ… 2.5D
❌ 3 | βœ… With complex symbolog | +| Mapbox v2 | | βœ… | βœ… 2D
βœ… 2.5D
❌ 3 | βœ… With complex symbolog | +| deck.gl | ❌ | βœ… | | | +| Maplibre-gl-js | | | | | + +### Vector Tiles + +| **Viewer** | **Query** | **Symbology** | **OGC Vector Tiles** | +| ----------- | ----------- | ----------- | ----------- | +| Cesium | ❌ | ❌ | ❌ | +| Leaflet | βž– With [plugins](https://leafletjs.com/plugins.html#vector-tiles) | | ❌ | +| OpenLayers | βœ… | ❌ | βœ… | +| ArcGIS JS SDK | βœ… | βœ… | ❌ | +| iTowns | βœ… | ❌ | ❌ | +| Mapbox v1 | βœ… | βœ… But for v1 | ❌ | +| Mapbox v2 | βœ… | βœ… | ❌ | +| deck.gl | βœ… | ❌ | ❌ | +| Maplibre-gl-js | | βœ… | | + +:::info +OGC added `vector tiles` support in their [OGC Tiles API 🌐](https://ogcapi.ogc.org/tiles/) (still in it's early stages).
+Read more about [clients supporting Tiles API 🌐](https://github.com/opengeospatial/ogcapi-tiles/blob/master/implementations.adoc#clients). +::: diff --git a/docs/KnowledgeBase/_category_.json b/docs/KnowledgeBase/_category_.json new file mode 100644 index 000000000..945afee18 --- /dev/null +++ b/docs/KnowledgeBase/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Knowledge Base", + "position": 1, + "link": { + "type": "generated-index", + "description": "MapColonies Knowledge Base" + } +} diff --git a/docs/MapColonies/terms.md b/docs/KnowledgeBase/terms.md similarity index 100% rename from docs/MapColonies/terms.md rename to docs/KnowledgeBase/terms.md diff --git a/docs/MapColonies/Raster/services/export.mdx b/docs/MapColonies/Raster/services/export.mdx index 1a5332f8a..c9e9ff3c6 100644 --- a/docs/MapColonies/Raster/services/export.mdx +++ b/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" diff --git a/docs/MapColonies/openstreetmap/osm-carto/README.md b/docs/MapColonies/openstreetmap/osm-carto/README.md index 5db153525..f79450c50 100644 --- a/docs/MapColonies/openstreetmap/osm-carto/README.md +++ b/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. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 82d6816ec..4cbb4c5cd 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -130,6 +130,12 @@ const config: Config = { position: 'left', label: 'OGC', }, + { + type: 'docSidebar', + sidebarId: 'knowledgeBaseSidebar', + position: 'left', + label: 'Knowledge base', + }, ], }, footer: { @@ -167,6 +173,10 @@ const config: Config = { label: 'Blog', to: '/blog', }, + { + label: 'Knowledge base', + to: '/docs/KnowledgeBase/terms', + }, ], }, ], diff --git a/sidebars.js b/sidebars.js index e1f6c2fdf..0d911c885 100644 --- a/sidebars.js +++ b/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',