From 2656a0f4ea3a99fe014adbc1faf6fbbe03b26cb1 Mon Sep 17 00:00:00 2001 From: Bert Temme Date: Wed, 7 Aug 2024 10:42:12 +0200 Subject: [PATCH] rewrite styling doc --- styling.md | 122 +++++++++++++++++++++++++++++------------------------ 1 file changed, 67 insertions(+), 55 deletions(-) diff --git a/styling.md b/styling.md index 2cd3b004..427c65d8 100644 --- a/styling.md +++ b/styling.md @@ -1,8 +1,56 @@ # Styling 3D Tiles -## Shaders +There are 2 ways to style 3D Tiles: -By default (when option --shaderscolumn is not used), the following PbrMetallicRoughness shader is used with parameters for all triangles: +1] Client side styling + +The 3D Tiles are styled on the client side (in the browser) using the CesiumJS API. + +2] Server side styling + +The 3D Tiles are styled on the server side (in the database) using a json document. + + +## Client side styling + +When using client side styling the 3D Tiles are styled in the client. In CesiumJS there is a 3D Tiles Styling Language. +For the specs of 3D Tiles Styling Language see https://github.com/CesiumGS/3d-tiles/tree/main/specification/Styling + +Example for styling buildings in a 3D Tileset based on attribute 'bouwjaar' in CesiumJS: + +``` + var buildings = new Cesium.Cesium3DTileset({ + url : './buildings/tileset.json' + }); + + buildings.style = new Cesium.Cesium3DTileStyle({ + color: { + conditions: [ + ["${feature['bouwjaar']} <= 1700", "color('#430719')"], + ["${feature['bouwjaar']} > 1700", "color('#740320')"], + ] + } + } + ); +``` + +Example for showing a subset based on a query (show only buildings with bouwjaar > 1975): + +``` +buildings.style.show = "${feature['bouwjaar']} > 1975" +``` +Remember to add attribute bouwjaar with '-a bouwjaar' when creating the 3D Tiles. + + +## Server side styling + +When using server side styling the 3D Tiles are styled in the database. +The styling is stored in a json document in a column of type json. + +The json document contains the shaders for the 3D Tiles. When the option --shaderscolumn is used, the shaders are read from the column specified in the option. + +When the option --shaderscolumn is not used, a default PbrMetallicRoughness shader is used for all triangles in the geometry, +witht following properties: - BaseColor: #FFFFFF (option --default_color) @@ -12,16 +60,16 @@ R = 255, G = 255, B = 255, A = 1 Metallic factor: 0, Roughness factor: 0.5019608 (128/255) -- Doubleside: true (hardcoded) +- Doubleside: true (option double_sided) - Alpha: 0 (hardcoded) Alternative option is to specify a shader using the ShadersColumn. -Shaderscolumn is a column of type json. In this json document the shaders are defined like PbrMetallicRoughness and +Shaderscolumn is a column of type json. In the json documents the shaders are defined like PbrMetallicRoughness and PbrSpecularGlossiness. Note: PbrSpecularGlossiness is deprecated by Khronos, so advise is to use PbrMetallicRoughness. -## JSON Structure +### JSON Structure The json must have the following structure: @@ -39,10 +87,10 @@ The json must have the following structure: } ``` -Rules for amount of shaders: +### Rules for amount of shaders -- The amount of colors in the lists for Polygon geometry types must be 1, in -which case the same color is used for all triangles in the geometry; +- The amount of colors in the lists can be 1, in which case the same color is used for all +triangles in the geometry; Example: @@ -55,13 +103,13 @@ update delaware_buildings set simple_shader = }'; ``` -- For collection types (like MultiPolygon, MultiLine or PolyhedralSurface) the number of shaders can be equal to the number of inner geometries . In this case each -inner geometry is styled with the corresponding shader. - -- For all geometries the number of shaders can be equal to the number of triangles (of the generated mesh). +- For collection types (like MultiPolygon, MultiLine or PolyhedralSurface) the number of shaders can be equal to the number of +inner geometries . In this case each inner geometry is styled with the corresponding shader. -- otherwise an exception is thrown. +- The number of shaders can be equal to the number of triangles (of the generated mesh). The amount of triangles must + be known in advance. +If the amount of colors is otherwise an exception is thrown. Example: @@ -73,7 +121,7 @@ MULTIPOLYGON Z(((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)),((2 2 0, 2 3 0, 3 3 0, 3 2 The number of shaders can be: - - 1: all triangles are styled with the same shader; +- 1: all triangles are styled with the same shader; ``` { @@ -86,7 +134,7 @@ The number of shaders can be: ``` - - 2: each square is styled with a different shader; +- 2: each square is styled with a different shader; ``` { @@ -99,9 +147,7 @@ The number of shaders can be: } ``` - - - - 4: each triangle is styled with a different shader. +- 4: each triangle is styled with a different shader. ``` { @@ -116,11 +162,7 @@ The number of shaders can be: } ``` -Warning: - -When using non triangulated geometries, the number of resulting triangles is unknown in most cases. - -## Sql +### Sql Sample query in SQL: @@ -135,7 +177,7 @@ update mytable set simple_shader = }'; ``` -## Samples +### Samples Sample for using shader PbrMetallicRoughness with BaseColor for 2 triangles: @@ -229,40 +271,10 @@ Converted to RGBA: So Diffuse Red = 230, Diffuse Green = 0, Diffuse Blue = 128, Alpha = 0 -## Remarks +### Remarks - Fallback scenario from SpecularGlossiness to MetallicRoughness shader for clients that do not support SpecularGlossiness is not supported (yet) - Shader 'unlit' is not supported (yet) -## Client side styling - -An alternative option is to style the 3D Tiles on runtime (in the client). - -Example for styling buildings in a 3D Tileset based on attribute 'bouwjaar' in CesiumJS: - -``` - var buildings = new Cesium.Cesium3DTileset({ - url : './buildings/tileset.json' - }); - - buildings.style = new Cesium.Cesium3DTileStyle({ - color: { - conditions: [ - ["${feature['bouwjaar']} <= 1700", "color('#430719')"], - ["${feature['bouwjaar']} > 1700", "color('#740320')"], - ] - } - } - ); -``` - -Example for showing a subset based on a query (show only buildings with bouwjaar > 1975): - -``` -buildings.style.show = "${feature['bouwjaar']} > 1975" -``` -Remember to add attribute bouwjaar with '-a bouwjaar' when creating the 3D Tiles. - -For the specs of 3D Tiles Styling Language see https://github.com/CesiumGS/3d-tiles/tree/main/specification/Styling