PB-1796: Format and organize pages in Visualize Data section

.vitepress/config.mts

@@ -147,13 +147,18 @@ function visualizeDataItems(): DefaultTheme.SidebarItem[] {
   return [
     { text: "WMS", link: "/docs/wms" },
     { text: "WMTS", link: "/docs/wmts" },
+    { text: "XYZ", link: "/docs/xyz" },
     {
       text: "Mapbox Vector Tiles",
       link: "/docs/mapbox-vector-tiles",
     },
     {
-      text: "3D",
-      link: "/docs/3d",
+      text: "Terrain Service",
+      link: "/docs/terrain-service",
+    },
+    {
+      text: "3D Tiles",
+      link: "/docs/3d-tiles",
     },
   ];
 }

docs/3d-tiles.md

@@ -0,0 +1,70 @@
+# 3D Tiles
+
+This service provides 3D tiles through a RESTful API, implementing the [Cesium 3D Tiles specification](https://github.com/CesiumGS/3d-tiles).
+
+<ApiCodeBlock url="https://3d.geo.admin.ch/<LayerName>/<Version>/<Time>/<Z>/<X>/<Y>.b3dm" method="GET" />
+
+Use the following parameters to define your request:
+
+| Parameter | Example                          | Description                                                                                                                                                                             |
+| --------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| layerName | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer. Possible values are: `ch.swisstopo.swissbuildings3d.3d`, `ch.swisstopo.swisstlm3d.3d`, `ch.swisstopo.swissnames3d.3d`, `ch.swisstopo.vegetation.3d` |
+| Version   | v1                               | API version. `v1` means tiles generated with 3D Tiles                                                                                                                                   |
+| Time      | 20240501                         | Date of tileset generation in (ISO-8601, e.g. YYYYMMDD)                                                                                                                                 |
+| Z         | 7                                | Zoom level                                                                                                                                                                              |
+| X         | 54                               | Tile column index                                                                                                                                                                       |
+| Y         | 21                               | Tile row index                                                                                                                                                                          |
+
+A 3D tile request for swissBUILDINGS3D dataset:
+
+```http
+curl -o demo.b3dm https://3d.geo.admin.ch/ch.swisstopo.swissbuildings3d.3d/v1/20240501/7/54/21.b3dm
+```
+
+## Metadata
+
+The `tileset.json` file describes the available set of tiles.
+It can be used directly by [CesiumJS](https://github.com/CesiumGS/cesium).
+
+<ApiCodeBlock url="https://3d.geo.admin.ch/<LayerName>/<Version>/<Time>/tileset.json" method="GET" />
+
+| Parameter       | Example                          | Description                                                                                                                                                                             |
+| --------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Time (optional) | 20201203                         | Date of tile generation in (ISO-8601).                                                                                                                                                  |
+| layerName       | ch.swisstopo.swissbuildings3d.3d | The technical name of the 3D layer. Possible values are: `ch.swisstopo.swissbuildings3d.3d`, `ch.swisstopo.swisstlm3d.3d`, `ch.swisstopo.swissnames3d.3d`, `ch.swisstopo.vegetation.3d` |
+
+A metadata request for the Vegetation dataset:
+
+<ExampleCodeBlock
+request="curl https://3d.geo.admin.ch/ch.swisstopo.vegetation.3d/v1/tileset.json"
+example='{
+  "asset": {
+    "version": "1.0",
+    "extras": {
+      "ion": {
+        "georeferenced": true,
+        "movable": false
+      }
+    }
+  },
+  "geometricError": 54.7213621044866,
+  "root": {
+    "boundingVolume": {
+      "region": [
+        0.10395173048091878, 0.799669540091651, 0.18307746929258154,
+        0.83441919811829, -10003.500000067055, 2799.070391970873
+      ]
+    },
+    "geometricError": 54.7213621044866,
+    "refine": "ADD",
+    "children": [...]
+  }
+}'
+/>
+
+## Example: Cesium
+
+An example Cesium application using terrain tiles, 3D buildings and WMTS.
+
+<iframe height="600" style="width: 100%;" scrolling="no" title="Geoadmin Terrain, Buildings and WMTS CesiumJS integration" src="https://codepen.io/geoadmin/embed/zBEYGE?default-tab=js%2Cresult&editable=true&zoom=0.5" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+</iframe>

docs/mapbox-vector-tiles.md

@@ -1,65 +1,136 @@
 # Mapbox Vector Tiles
 
-A RESTFul implementation of [Mapbox Vector
-Tiles](https://www.mapbox.com/vector-tiles). See
-[description](https://www.geo.admin.ch/en/geo-services/geo-services/portrayal-services-web-mapping/vector_tiles_service.html)
-
-The service provides both _tiles_ and _styles_ that the customer can
-use.
-
-### GetStyle
-
-A current (latest version) style request is in the following form:
-
-    GET <Scheme>://<ServerName>/styles/<layername>/style.json
-
-example of current maplibre styles of light base map and imagery base
-map:
-
-- <https://vectortiles.geo.admin.ch/styles/ch.swisstopo.basemap.vt/style.json>
-- <https://vectortiles.geo.admin.ch/styles/ch.swisstopo.lightbasemap.vt/style.json>
-- <https://vectortiles.geo.admin.ch/styles/ch.swisstopo.imagerybasemap.vt/style.json>
-
-### GetTile
+This service delivers vector map tiles and styles through a RESTful API, implementing the [Mapbox Vector Tiles specification](https://www.mapbox.com/vector-tiles).
+
+::: tip
+[The corresponding page on geo.admin.ch](https://www.geo.admin.ch/en/vector-tiles-service-available-services-and-data) lists the available datasets and styles.
+:::
+
+## GetStyle
+
+To get the style of certain layer:
+
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/styles/{layerName}/style.json" method="GET" />
+
+| **Parameter** | **Description**              |
+| ------------- | ---------------------------- |
+| layerName     | Layer to perform the request |
+
+A GetStyle request for the Light Base Map dataset:
+
+<ExampleCodeBlock
+request="curl https://vectortiles.geo.admin.ch/styles/ch.swisstopo.lightbasemap.vt/style.json"
+example='{
+  "version": 8,
+  "id": "0197406a-5d2f-7168-bee5-f191641499b7",
+  "name": "lightbasemap_v1.19.0",
+  "sources": {
+    "relief_v1.0.0": {
+      "url": "https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/tiles.json",
+      "type": "vector"
+    },
+    "base_v1.0.0": {
+      "url": "https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json",
+      "type": "vector"
+    }
+  },
+  "layers": [...],
+  "metadata": {...},
+  "glyphs": "https://vectortiles.geo.admin.ch/fonts/{fontstack}/{range}.pbf",
+  "sprite": "https://vectortiles.geo.admin.ch/styles/ch.swisstopo.lightbasemap.vt/sprite/sprite",
+  "bearing": 0,
+  "pitch": 0,
+  "center": [8.349961425056108, 46.81133904939108],
+  "zoom": 7.2512975045452235,
+  "transition": {...}
+}'
+/>
+
+## GetTile
 
 A tile request is in the following form:
 
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>/<zoomlevel>/<x>/<y>.pbf
-
-example of one pbf tile:
-
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/7/67/44.pbf>
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/7/67/44.pbf>
-
-### GetTileSets
-
-MBTiles for storing tiled map data in SQLite databases for immediate or
-offline usage and for efficient transfer. A MBtileSet request is in the
-following form:
-
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>/<LayerName>.mbtiles
-
-example of the .mbtiles file:
-
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles>
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/ch.swisstopo.relief.vt.mbtiles>
-
-### Available datasets and styles as mapbox vector tiles
-
-The list of current datasets and styles is available visiting the
-[official service
-description](https://www.geo.admin.ch/en/vector-tiles-service-available-services-and-data)
-
-### Metadata Service
-
-Each tileset has a corresponding metatdata <span
-class="title-ref">json</span> file that describes the available set of
-tiles. The URL of the metadata <span class="title-ref">json</span> file
-is :
-
-    GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>.json
-
-example of tileset:
-
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json>
-- <https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/tiles.json>
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{zoomLevel}/{x}/{y}.pbf" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
+| zoomLevel     | 7                    | Zoom level (integer)                        |
+| x             | 67                   | Tile column (X coordinate in the tile grid) |
+| y             | 44                   | Tile row (Y coordinate in the tile grid)    |
+
+A GetTile request for one `.pbf` tile in the Relief dataset:
+
+```http
+curl -o demo.pbf https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.relief.vt/v1.0.0/7/67/44.pbf
+```
+
+## GetTileSets
+
+MBTiles for storing tiled map data in SQLite databases for immediate or offline usage and for efficient transfer.
+A MBtileSet request is in the following form:
+
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/{layerName}.mbtiles" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
+
+A GetTileSet request for a `.mbtiles` file in the Base Map dataset:
+
+```http
+curl -o demo.mbtiles https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/ch.swisstopo.base.vt.mbtiles
+```
+
+## Metadata
+
+Each tileset has a corresponding metadata json file that describes the available set of tiles.
+The URL of the metadata file is:
+
+<!-- GET <Scheme>://<ServerName>/tiles/<LayerName>/<version>.json -->
+<ApiCodeBlock url="https://vectortiles.geo.admin.ch/tiles/{layerName}/{version}/tiles.json" method="GET" />
+
+| **Parameter** | **Example**          | **Description**                             |
+| ------------- | -------------------- | ------------------------------------------- |
+| layerName     | ch.swisstopo.base.vt | The technical name of the vector tile layer |
+| version       | v1.0.0               | Version of the tileset                      |
+
+A Metadata request for the Base Map dataset:
+
+<ExampleCodeBlock
+request="curl https://vectortiles.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/tiles.json"
+example='{
+  "basename": "tiles/ch.swisstopo.base.vt/v1.0.0",
+  "name": "Basiskarte_v1.0.0",
+  "description": "A tileset showcasing all SwissTopo layers.",
+  "attribution": "© swisstopo",
+  "version": "v1.0.0",
+  "format": "pbf",
+  "minzoom": 0,
+  "maxzoom": 14,
+  "scale": 1,
+  "vector_layers": [...],
+  "profile": "mercator",
+  "scheme": "xyz",
+  "bounds": [...],
+  "center": [...],
+  "tilejson": "2.0.0",
+  "tiles": [
+    "https://vectortiles0.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles1.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles2.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles3.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf",
+    "https://vectortiles4.geo.admin.ch/tiles/ch.swisstopo.base.vt/v1.0.0/{z}/{x}/{y}.pbf"
+  ]
+}
+'
+/>
+
+## Example: MapLibre
+
+An example using MapLibre to display the Light Base Map:
+
+<iframe height="600" style="width: 100%;" scrolling="no" title="Maplibre Vector Tiles" src="https://codepen.io/geoadmin/embed/GvgLvj?default-tab=js%2Cresult&editable=true" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
+</iframe>