@cityjson/cj-mcp 0.1.0

package/specs/chapters/extensions.md

@@ -0,0 +1,296 @@
+## 8\. Extensions[](#extensions)
+
+CityJSON uses [JSON Schemas](http://json-schema.org/) to document and validate its data model, including its Extensions. Schemas offer a way to validate the syntax of a JSON document, and thus the possibility to require certain JSON members. Therefore, for writing more complex Extensions, a basic familiarity with [JSON Schemas](http://json-schema.org/) is advised.
+
+A CityJSON _Extension_ is a JSON file that documents how the core data model of CityJSON is extended, and it is also used for validating the CityJSON files. This is conceptually akin to, but not conformant with, the [Application Domain Extensions (ADEs)](https://docs.ogc.org/is/20-010/20-010.html#toc66) in CityGML.
+
+A CityJSON Extension can extend the core data model in four ways:
+
+1.  Defining new properties at the root of a document
+    
+2.  Defining attributes on existing City Objects
+    
+3.  Defining a new Semantic Object
+    
+4.  Defining a new City Object, or "extending" one of the existing City Objects
+    
+
+> **Note:** While Extensions are less flexible than CityGML ADEs (inheritance and namespaces are for instance not supported, and less customisation is possible), it should be noted that the flexibility of ADEs comes at a price: the software processing an extended CityGML file will not necessarily know what structure to expect.
+
+There is ongoing work on using the ADE schemas to automatically do this, but this is currently not supported by most software. Viewers might not be affected by ADEs because the geometries are usually not changed by an ADE (although they can!). However, software parsing the XML to extract attributes and features might not work directly (and thus specific code would need to be written).
+
+CityJSON Extensions are designed in a way that they can be read and processed by standard CityJSON software, often without requiring any changes in the parsing code. This is achieved by enforcing a set of 6 simple rules (see [§ 8.7 Rules to follow to define new City Objects](#rules-to-follow-to-define-new-city-objects)) when adding new City Objects. If these are followed, then a CityJSON file containing Extensions will be seen as a "standard" CityJSON file.
+
+One of the philosophies of JSON is being "schema-less", which means that one is allowed to define new properties for the JSON objects without documenting them in a JSON schema (watch out: this does _not_ mean that JSON does not have schemas!). While this is in contrast to CityGML (and GML as a whole) where the schemas are central, the schemas of CityJSON are (partly) following that philosophy.
+
+If one wants to document the parcel area in square-meters for a `"Building"` (`"area-parcel": {"value": 437, "uom": "m2"}`), the easiest way is just to add a new member to the City Object attributes:
+
+{
+  "type": "Building",
+  "attributes": {
+    "storeysAboveGround": 2,
+    "area-parcel": {
+      "value": 437,
+      "uom": "m2"
+    }
+  },
+  "geometry": \[...\]
+}
+
+However, a regular attribute (without the `"+"` prefix) cannot be made mandatory in the core CityJSON schema. Only with an Extension can an attribute be made mandatory (see [](#case-2-defining-attributes-on-existing-city-objects)).
+
+Therefore, an _Extension_ is used for enforcing certain properties, attributes, or City Object types in CityJSON objects. An _Extension_ makes sense if it is expected that different data producers and consumers in the target domain need to exchange data, or if an additional City Object or Semantic type is required for accurately modelling the data.
+
+### 8.1. Using an Extension in a CityJSON file[](#using-an-extension-in-a-cityjson-file)
+
+An Extension should be given a name (eg "Noise") and the URL of the Extension file should be defined, including the version of the Extension that is used for this file. It is expected that the Extension is publicly available at the URL, and can be downloaded.
+
+Several Extensions can be used in a single CityJSON Object, each one is indexed by its name in the `"extensions"` JSON object. In the example below we have two Extensions: one named "Noise" and one named "Solar\_Potential".
+
+{
+  "type": "CityJSON",
+  "version": "2.0",
+  "extensions": {
+    "Noise": {
+      "url" : "https://someurl.org/noise.json",
+      "version": "2.0"
+    },
+    "Solar\_Potential": {
+      "url" : "https://someurl.org/solar.json",
+      "version": "0.8"
+    }
+  },
+  "CityObjects": {},
+  "vertices": \[\]
+}
+
+### 8.2. The Extension file[](#the-extension-file)
+
+A CityJSON Extension is a JSON object, and it **must** have the following 8 members:
+
+1.  one member with the name `"type"`. The value must be `"CityJSONExtension"`.
+    
+2.  one member with the name `"name"`. The value must be a string identifying the extension.
+    
+3.  one member with the name `"url"`. The value must be a string with the HTTP URL of the location of the schema where the JSON object is located.
+    
+4.  one member with the name `"version"`. The value must be a string identifying the version of the Extension.
+    
+5.  one member with the name `"versionCityJSON"`. The value must be a string (X.Y) identifying the version of CityJSON that uses the Extension.
+    
+6.  one member with the name `"extraAttributes"`. The value must be a JSON object. Its content is part of a JSON schema (explained below), or an empty object.
+    
+7.  one member with the name `"extraCityObjects"`. The value must be a JSON object. Its content is part of a JSON schema (explained below), or an empty object.
+    
+8.  one member with the name `"extraRootProperties"`. The value must be a JSON object. Its content is part of a JSON schema (explained below), or an empty object.
+    
+9.  one member with the name `"extraSemanticSurfaces"`. The value must be a JSON object. Its content is part of a JSON schema (explained below), or an empty object.
+    
+
+{
+  "type": "CityJSONExtension",
+  "name": "Noise",
+  "description": "Extension to model the noise",
+  "url": "https://someurl.org/noise.ext.json",
+  "version": "0.5",
+  "versionCityJSON": "2.0",
+  "extraAttributes": {},
+  "extraCityObjects": {},
+  "extraRootProperties": {},     
+  "extraSemanticSurfaces": {},     
+}
+
+> **Note:** If an element of the Extension reuses, or references, structures and/or objects defined in the schemas of CityJSON, then assume that the Extension is in the same folder as the schemas. An example would be to reuse the Solid type:
+
+"items": {
+  "oneOf": \[
+    {"$ref": "geomprimitives.json#/Solid"}
+  \]
+}
+
+### 8.3. Case 1: Adding new properties at the root of a document[](#case-1-adding-new-properties-at-the-root-of-a-document)
+
+It is allowed to add a new member at the root of a CityJSON file, but if one wants to document it in a schema, then the member’s name must start with a `"+"`. Imagine we wanted to store some census data for a given neighbourhood for which we have a CityJSON file, then we could define the extra root member `"+census"` as follows:
+
+"extraRootProperties": {
+  "+census": {
+    "type": "object",
+    "properties": {
+      "percent\_men": {
+        "type": "number",
+        "minimum": 0.0,
+        "maximum": 100.0
+      },
+      "percent\_women": {
+        "type": "number",
+        "minimum": 0.0,
+        "maximum": 100.0
+      }
+    }
+  }
+}
+
+And a CityJSON file would look like this:
+
+{
+  "type": "CityJSON",
+  "version": "2.0",
+  "extensions": {
+    "Census": {
+      "url": "https://someurl.org/census.ext.json",
+      "version": "0.7"
+    }
+  },
+  "CityObjects": {...},
+  "vertices": \[...\],
+  "+census": {
+    "percent\_men": 49.5,
+    "percent\_women": 51.5
+  }
+}
+
+### 8.4. Case 2: Defining attributes for existing City Objects[](#case-2-defining-attributes-for-existing-city-objects)
+
+It is also possible to add, and document in a schema, specific attributes, for example if we wanted to have the colour of the buildings as a RGBA value (red-green-blue-alpha):
+
+{
+  "type": "Building", 
+  "attributes": { 
+    "storeysAboveGround": 2,
+    "+colour": {
+      "rgba": \[255, 255, 255, 1\]
+    }
+  },
+  "geometry": \[...\]
+}
+
+Another example would be to store the area of the parcel of a building, and also to document the unit of measurement (UoM):
+
+{
+  "type": "Building", 
+  "attributes": { 
+    "storeysAboveGround": 2,
+    "+area-parcel": {
+      "value": 437,
+      "uom": "m2"
+    } 
+  },
+  "geometry": \[...\]
+}
+
+For these two cases, the CityJSON Extension object would look like the snippet below. Notice that `"extraAttributes"` may have several properties (the types of the City Objects are the possibilities) and then each of these has as properties the new attributes (there can be several).
+
+An extra attribute must start with a `"+"`; it is good practice to prepend the attribute with the name of the Extension, to avoid that 2 attributes from 2 different Extensions have the same name.
+
+The value of the member is a JSON schema, this schema can reference and reuse JSON objects already defined in the CityJSON schemas. Thus, the keywords of the member values are defined by the JSON Schema specification. For instance, `"additionalProperties"` is a JSON-schema keyword stating that one is not allowed to add properties to this JSON object, beyond the ones defined in the schema (eg `"value", "uom"`).
+
+"extraAttributes": {
+  "Building": {
+    "+colour": {
+      "type": "object",
+      "properties": {
+        "rgba": {
+          "type": "array",
+          "items": {"type": "number"},
+          "minItems": 4,    
+          "maxItems": 4
+        }
+      },
+      "required": \["rgba"\],
+      "additionalProperties": false
+    },
+    "+area-parcel": {
+      "type": "object",
+      "properties": {
+        "value": { "type": "number" },
+        "uom": { "type": "string", "enum": \["m2", "feet2"\] }
+      },
+      "required": \["value", "uom"\],
+      "additionalProperties": false
+    }      
+  } 
+}
+
+### 8.5. Case 3: Defining a new Semantic Object[](#case-3-defining-a-new-semantic-object)
+
+It is possible to define a new Semantic Object (besides the ones prescribed, see [§ 3.3 Semantics of geometric primitives](#semantics-of-geometric-primitives)), and document it in the Extension.
+
+New Semantic Objects must have a `"+"` as their first character, and other attributes/properties can be defined.
+
+"extraSemanticSurfaces": {
+  "+ThermalSurface": {
+    "type": "object",
+    "properties": {
+      "type": { "enum": \[ "+ThermalSurface" \] },
+      "azimuth": {"type": "number"}
+    },
+    "required": \[ "type", "azimuth" \],
+    "additionalProperties": false
+  } 
+}
+
+### 8.6. Case 4: Creating and/or extending new City Objects[](#case-4-creating-and-or-extending-new-city-objects)
+
+The creation of a new City Object is done by defining it in the CityJSON Extension object in the `"extraCityObjects"` member:
+
+"extraCityObjects": {
+  "+NoiseBuilding": {
+    "allOf": \[
+      { "$ref": "cityobjects.json#/\_AbstractBuilding" },
+      {
+        "properties": {
+          "type": { "enum": \["+NoiseBuilding"\] },
+          "attributes": {
+            "properties": {
+              "buildingLDenMin": {"type": "number"}
+            }
+          }
+        },
+        "required": \["type"\]
+      }
+    \]
+  }
+}
+
+"extraCityObjects": {
+  "+NoiseBuildingPart": {
+    "allOf": \[
+      { "$ref": "cityobjects.json#/\_AbstractBuilding" },
+      {
+        "properties": {
+          "type": { "enum": \["+NoiseBuildingPart"\] },
+          "attributes": {
+            "properties": {
+              "buildingLDenMin": {"type": "number"}
+            }
+          }
+        },
+        "required": \["type", "parents"\]
+      }
+    \]
+  }
+}
+
+Since all City Objects are documented in the [schemas of CityJSON](https://www.cityjson.org/schemas/) (in `cityobjects.schema.json`), it is basically a matter of copying the parts needed in a new file and modifying its content.
+
+A new name for the City Object must be given and it must begin with a `"+"`.
+
+Because City Objects can be of different levels (1st-level ones can exist by themselves; 2nd-level ones need to have a parent), we need to explicitly define that the `"parents"` member is mandatory for 2nd-level objects.
+
+Please note that since JSON schemas do not allow inheritance, the only way to extend a City Object is to define an entirely new one (with a new name, eg `"+NoiseBuilding"`). This is done by copying the schema of the parent City Object and extending it.
+
+### 8.7. Rules to follow to define new City Objects[](#rules-to-follow-to-define-new-city-objects)
+
+The challenge when creating Extensions to the core model is that we do not want to break the software packages (viewers, spatial analysis, etc) that already read and process CityJSON files. While one could define a new City Object and document it, if this new object does not follow the rules below then it will mean that new specific software needs to be built for it (and this would go against the fundamental ideas behind CityJSON).
+
+1.  The name of a new City Object must begin with a `"+"`, eg `"+NoiseBuilding"`.
+    
+2.  A new City Object must conform to the rules of CityJSON, ie it must contain a member `"type"`.
+    
+3.  Existing City Objects cannot be extended and have new types as children, eg it is not allowed to add a new City Object `"+Balcony"` to a `"Building"`. Instead, a new type, eg `"+FancyBuilding"`, should be created and it can have a `"+Balcony"` as a potential child.
+    
+4.  All the geometries must be in the member `"geometry"`, and cannot be located somewhere else deep in a hierarchy of a new member.
+    
+5.  The Geometry object’s boundary must be one of the eight types described in [§ 3 Geometry Objects](#geometry-objects). Similarly, the geometry appearances and templates must follow the core specification. This ensures that all the code written to process, manipulate, and view CityJSON files will be working without modifications.
+    
+6.  The reuse of types defined in CityJSON, eg `"Solid"` or semantic surfaces, is allowed.

package/specs/chapters/geometry-objects.md

@@ -0,0 +1,362 @@
+## 3\. Geometry Objects[](#geometry-objects)
+
+CityJSON defines the following 3D geometric primitives, all of which are embedded in 3D space (and therefore their vertices have _(x, y, z)_ coordinates). Similarly to the indexing mechanism of the format [Wavefront OBJ](https://en.wikipedia.org/wiki/Wavefront_.obj_file), the geometry object does not store the locations of its vertices, but points instead to a vertex in a list (member `"vertices"` in the CityJSON Object).
+
+As is the case in CityGML, only linear and planar primitives are allowed; no curves or parametric surfaces can be represented.
+
+A Geometry object is a JSON object for which the type member’s value is one of the following:
+
+1.  `"MultiPoint"`
+    
+2.  `"MultiLineString"`
+    
+3.  `"MultiSurface"`
+    
+4.  `"CompositeSurface"`
+    
+5.  `"Solid"`
+    
+6.  `"MultiSolid"`
+    
+7.  `"CompositeSolid"`
+    
+8.  `"GeometryInstance"` (this is another type with different properties, see [§ 3.4 Geometry templates](#geometry-templates))
+    
+
+A Geometry object:
+
+*   **must** have one member with the name `"type"`. The value must be a string with one of the 8 allowed Geometry types, as defined above.
+    
+*   **must** have one member with the name `"lod"`. The value must be a string with the LoD identifying the level-of-detail (LoD) of the geometry. This can be either a single digit (following the CityGML standards), or "X.Y"-formatted if the [improved LoDs by TU Delft](https://3d.bk.tudelft.nl/lod) are used.
+    
+*   **must** have one member with the name `"boundaries"`. The value is a hierarchy of arrays (the depth depends on the Geometry object) with integers. Each integer refers to an index in the `"vertices"` array of the CityJSON object, and it is 0-based (ie the first element in the array has the index "0", the second one "1", etc.).
+    
+*   **may** have one member with the name `"semantics"`. The value is a JSON Object, as defined below.
+    
+*   **may** have one member with the name `"material"`. The value is a JSON Object, as defined below.
+    
+*   **may** have one member with the name `"texture"`. The value is a JSON Object, as defined below.
+    
+
+> **Note:** There is _no_ Geometry Object for MultiGeometry. Instead, for the `"geometry"` member of a CityObject, the different geometries may be enumerated in the array (all with the same value for the member `"lod"`).
+
+### 3.1. Coordinates of the vertices[](#coordinates-of-the-vertices)
+
+A CityJSON Object must have one member named `"vertices"`. The value is an array of arrays of 3 integers representing the coordinates of each vertex of the city model. The position of a vertex in this array (0-based) is used to represent the `"boundaries"` of Geometry Objects.
+
+*   one vertex **must** be an array with exactly 3 integers, representing the _(x,y,z)_ location of the vertex before it is transformed to its real-world coordinates (with the [§ 4 Transform Object](#transform-object)).
+    
+*   the array of vertices may be empty.
+    
+*   vertices may be repeated.
+    
+
+"vertices": \[
+  \[102, 103, 1\],
+  \[11, 910, 43\],
+  \[25, 744, 22\],
+  ...
+  \[23, 88, 5\],
+  \[8523, 487, 22\]
+\]
+
+### 3.2. Arrays to represent boundaries[](#arrays-to-represent-boundaries)
+
+The depth of the hierarchy of arrays depends on the Geometry object, and is as follows.
+
+*   A `"MultiPoint"` has an array with the indices of the vertices; this array can be empty.
+    
+*   A `"MultiLineString"` has an array of arrays, each containing the indices of a LineString.
+    
+*   A `"MultiSurface"`, or a `"CompositeSurface"`, has an array containing surfaces, each surface is modelled by an array of arrays, the first array being the exterior boundary of the surface, and the others the interior boundaries.
+    
+*   A `"Solid"` has an array of shells, the first shell being the exterior shell of the solid, and the others the interior shells. Each shell has an array of surfaces, modelled in the exact same way as a MultiSurface/CompositeSurface.
+    
+*   A `"MultiSolid"`, or a `"CompositeSolid"`, has an array containing solids. Each solid is modelled as above.
+    
+
+> **Note:** JSON does not allow comments, the comments in the example below (C++ style: `//-- my comments`) are only to explain the cases, and should be removed.
+
+{
+  "type": "MultiPoint",
+  "lod": "1",
+  "boundaries": \[2, 44, 0, 7\]
+}
+
+{
+  "type": "MultiLineString",
+  "lod": "1",
+  "boundaries": \[
+    \[2, 3, 5\], \[77, 55, 212\]
+  \]  
+}
+
+{
+  "type": "MultiSurface",
+  "lod": "2",
+  "boundaries": \[
+    \[\[0, 3, 2, 1\]\], \[\[4, 5, 6, 7\]\], \[\[0, 1, 5, 4\]\]
+  \]
+}
+
+{
+  "type": "Solid",
+  "lod": "2",
+  "boundaries": \[
+    //-- exterior shell
+    \[ \[\[0, 3, 2, 1, 22\]\], \[\[4, 5, 6, 7\]\], \[\[0, 1, 5, 4\]\], \[\[1, 2, 6, 5\]\] \], 
+    //-- interior shell
+    \[ \[\[240, 243, 124\]\], \[\[244, 246, 724\]\], \[\[34, 414, 45\]\], \[\[111, 246, 5\]\] \] 
+  \]
+}
+
+{
+  "type": "CompositeSolid",
+  "lod": "3",
+  "boundaries": \[
+    \[ //-- 1st Solid
+      \[ \[\[0, 3, 2, 1, 22\]\], \[\[4, 5, 6, 7\]\], \[\[0, 1, 5, 4\]\], \[\[1, 2, 6, 5\]\] \],
+      \[ \[\[240, 243, 124\]\], \[\[244, 246, 724\]\], \[\[34, 414, 45\]\], \[\[111, 246, 5\]\] \]
+    \],
+    \[ //-- 2nd Solid
+      \[ \[\[666, 667, 668\]\], \[\[74, 75, 76\]\], \[\[880, 881, 885\]\], \[\[111, 122, 226\]\] \] 
+    \]    
+  \]
+}
+
+> **Note:** See [this tutorial](https://www.cityjson.org/dev/geom-arrays/) for further explanation on the depth of arrays of Geometry objects.
+
+### 3.3. Semantics of geometric primitives[](#semantics-of-geometric-primitives)
+
+A Semantic Object is a JSON object representing the semantics of a primitive of a geometry (e.g. a surface of a building). A Semantic Object may also represent other attributes of the primitive (e.g. the slope of the roof, or the solar potential). For surface and volumetric geometries (e.g. `MultiSurface`, `Solid` and `MultiSolid`), a primitive is a surface. If a geometry is a `MultiPoint` or a `MultiLineString`, then the primitives are its respective sub-parts: points and linestrings.
+
+A Semantic Object:
+
+*   **must** have one member with the name `"type"`. The value is one of the allowed values. These depend on the City Object (see below).
+    
+*   **may** have one member with the name `"parent"`. The value is an integer pointing to another Semantic Object of the same geometry (index of it, 0-based). This is used to explicitly represent to which wall or roof a window or door belongs to; there can be only one parent.
+    
+*   **may** have one member with the name `"children"`. The value is an array of integers pointing to other Semantic Objects of the same geometry (index of it, 0-based). This is used to explicitly represent the openings (windows and doors) of walls and roofs.
+    
+*   **may** have other members in the form of a JSON key-value pair, where the value must not be a JSON object (but a string/number/integer/boolean).
+    
+
+{
+  "type": "RoofSurface",
+  "slope": 16.4,
+  "children": \[2, 37\],
+  "solar-potential": 5
+}
+
+{
+  "type": "Window",
+  "parent": 2,
+  "type-glass": "HR++"
+}
+
+`"Building"`, `"BuildingPart"`, `"BuildingRoom"`, `"BuildingStorey"`, `"BuildingUnit"`, and `"BuildingInstallation"` can have the following semantics:
+
+*   `"RoofSurface"`
+    
+*   `"GroundSurface"`
+    
+*   `"WallSurface"`
+    
+*   `"ClosureSurface"`
+    
+*   `"OuterCeilingSurface"`
+    
+*   `"OuterFloorSurface"`
+    
+*   `"Window"`
+    
+*   `"Door"`
+    
+*   `"InteriorWallSurface"`
+    
+*   `"CeilingSurface"`
+    
+*   `"FloorSurface"`
+    
+
+For `"WaterBody"`:
+
+*   `"WaterSurface"`
+    
+*   `"WaterGroundSurface"`
+    
+*   `"WaterClosureSurface"`
+    
+
+For Transportation (`"Road"`, `"Railway"`, `"TransportSquare"`):
+
+*   `"TrafficArea"`
+    
+*   `"AuxiliaryTrafficArea"`
+    
+*   `"TransportationMarking"`
+    
+*   `"TransportationHole"`
+    
+
+It is possible to define and use other semantics, but these have to start with a `"+"`, inline with the rules defined in the [§ 8 Extensions](#extensions).
+
+{
+  "type": "+SupportingWall"
+}
+
+Because in a given City Object (say a `"Building"`) several primitives can have the same semantics (think of a complex building that has been triangulated, there can be dozens of triangles used to represent one planar surface), a Semantic Object can be declared once, and each of the primitives that are represented by it should point to it. This is achieved by first declaring all the Semantic Objects in an array, and then having an array where each primitive links to a Semantic Object (position in the array).
+
+If a Geometry object has semantics, then the Geometry object:
+
+*   **must** have one member with the name `"semantics"`, whose values are two properties: `"surfaces"` and `"values"`. Both **must** be present.
+    
+
+Also:
+
+*   the value of `"surfaces"` is an array of Semantic Objects.
+    
+*   the value of `"values"` is a hierarchy of arrays with integers. The depth depends on the Geometry object: for `MultiPoint` and `MultiLineString` this is a simple array of integers; for any other geometry type it is two less than the array `"boundaries"`. An integer refers to the index in the `"surfaces"` array of the same geometry, and it is 0-based. If one surface has no semantics, a value of `null` must be used.
+    
+
+> **Note:** For legacy reasons, we use `"surfaces"` to name the array of Semantic Objects. Nevertheless, this member is used for points and linestrings of `MultiPoints` and `MultiLineStrings`, as well.
+
+{
+  "type": "MultiSurface",
+  "lod": "2",
+  "boundaries": \[
+    \[\[0, 3, 2, 1\]\], 
+    \[\[4, 5, 6, 7\]\], 
+    \[\[0, 1, 5, 4\]\], 
+    \[\[0, 2, 3, 8\]\], 
+    \[\[10, 12, 23, 48\]\]
+  \],
+  "semantics": {
+    "surfaces" : \[
+      {
+        "type": "WallSurface",
+        "slope": 33.4,
+        "children": \[2\]
+      }, 
+      {
+        "type": "RoofSurface",
+        "slope": 66.6
+      },
+      {
+        "type": "+PatioDoor",
+        "parent": 0,
+        "colour": "blue"
+      }
+    \],
+    "values": \[0, 0, null, 1, 2\]
+  }
+}
+
+{
+   "type": "CompositeSolid",
+   "lod": "2.2",
+   "boundaries": \[
+     \[ //-- 1st Solid
+       \[ \[\[0, 3, 2, 1, 22\]\], \[\[4, 5, 6, 7\]\], \[\[0, 1, 5, 4\]\], \[\[1, 2, 6, 5\]\] \]
+     \],
+     \[ //-- 2nd Solid
+       \[ \[\[666, 667, 668\]\], \[\[74, 75, 76\]\], \[\[880, 881, 885\]\] \] 
+     \]    
+   \],
+   "semantics": {
+     "surfaces" : \[
+       {      
+         "type": "RoofSurface"
+       }, 
+       {
+         "type": "WallSurface"
+       }
+     \],
+     "values": \[
+       \[ //-- 1st Solid
+         \[0, 1, 1, null\]
+       \],
+       \[ //-- 2nd Solid get all null values
+         \[null, null, null\]
+       \]
+     \]
+   }
+ }  
+
+### 3.4. Geometry templates[](#geometry-templates)
+
+CityGML’s "ImplicitGeometries", better known in computer graphics as _templates_, are one method of compressing files since the geometries (such as benches, lamp posts, and trees) need to be defined only once. In CityJSON, they are implemented differently from what is specified in CityGML: they are defined separately in the file, and each template can be reused. By contrast, in CityGML, the geometry used for a given City Object is reused by other City Objects, there is thus no central location where all templates are stored.
+
+The Geometry Templates are defined as a JSON object that:
+
+*   **must** have one member with the name `"templates"`. The value is an array of Geometry Objects.
+    
+*   **must** have one member with the name `"vertices-templates"`. The value is an array of coordinates of each vertex of the templates (0-based indexing). The reason the vertices' indices are not global is to ensure that operations on the vertices (eg for CRS transformation, for [§ 4 Transform Object](#transform-object), or calculating the bounding box of a dataset) will not be affected by the templates (since they will often be defined locally, and translated/rotated/scaled to their final position).
+    
+
+Observe that the geometry of a template can have semantic surfaces, and that appearances can be assigned to it.
+
+"geometry-templates": {
+  "templates": \[
+    {
+      "type": "MultiSurface",
+      "lod": "2.1",
+      "boundaries": \[ 
+         \[\[0, 3, 2, 1\]\], \[\[4, 5, 6, 7\]\], \[\[0, 1, 5, 4\]\]
+      \],
+      "semantics": {
+        "surfaces" : \[
+          {
+            "type": "+Skylight",
+          },
+          {
+            "type": "+PatioDoor",
+          }
+        \],
+        "values": \[0, 0, 1\]
+      }
+    },
+    {
+      "type": "MultiSurface",
+      "lod": "1.3",
+      "boundaries": \[ 
+         \[\[1, 2, 6, 5\]\], \[\[2, 3, 7, 6\]\], \[\[3, 0, 4, 7\]\]
+      \],
+      "material": {...}
+    }
+  \],
+  "vertices-templates": \[
+    \[0.0, 0.5, 0.0\],
+    ...
+    \[1.0, 1.0, 0.0\],
+    \[0.0, 1.0, 0.0\]
+  \]
+}
+
+A given template can be used as the geometry (or as one of the geometries) of a City Object. A new JSON object of type `"GeometryInstance"` is defined, and it:
+
+*   **must** have one member with the name `"template"`, whose value is the position of the template in the `"geometry-templates"` (0-indexing).
+    
+*   **must** have one member with the name `"boundaries"`, whose value is an array containing only one vertex index, which refers to one vertex in the `"vertices"` member of a CityJSON file. (This is the reference point from which the transformations are applied, it is the "referencePoint" in CityGML.)
+    
+*   **must** have one member with the name `"transformationMatrix"`, whose value is a 4x4 matrix (thus 16 values in an array) defining the rotation/translation/scaling of the template. Note that these 16 values are ordered row-by-row, as the example below shows.
+    
+
+{
+  "type": "SolitaryVegetationObject", 
+  "geometry": \[
+    {
+      "type": "GeometryInstance",
+      "template": 0,
+      "boundaries": \[372\],
+      "transformationMatrix": \[
+        2.0, 0.0, 0.0, 0.0,
+        0.0, 2.0, 0.0, 0.0,
+        0.0, 0.0, 2.0, 0.0,
+        0.0, 0.0, 0.0, 1.0
+      \]
+    }
+  \]
+}
+
+> **Note:** The CityJSON website has a [page to help developers with Geometry Templates](https://www.cityjson.org/dev/geom-templates/), it contains simple examples, explains which transformations to apply to obtain world coordinates, and explains how matrices work (for instance, in the example above, a scaling of 2.0 is applied).