CesiumGS · lilleyse · Jun 28, 2022 · Jun 23, 2022 · Jun 24, 2022 · Jun 24, 2022
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,13 @@
 .DS_Store
 Thumbs.db
-.idea
+.idea
+
+# Ignore intermediate and output files from metanorma
+/specification/iev
+/specification/relaton
+/specification/Specification.xml
+/specification/Specification.pdf
+/specification/Specification.html
+/specification/Specification.err
+/specification/Specification.html.err
+/specification/Specification.presentation.xml
diff --git a/specification/ACKNOWLEDGEMENTS.adoc b/specification/ACKNOWLEDGEMENTS.adoc
@@ -1,34 +1,45 @@
-= Acknowledgements
+== Contributors
 
 Editors:
 
 * Patrick Cozzi, https://twitter.com/pjcozzi[@pjcozzi], link:mailto:[email protected][[email protected]]
 * Sean Lilley, https://twitter.com/lilleyse[@lilleyse], link:mailto:[email protected][[email protected]]
-* Gabby Getz, https://twitter.com/gabbygetz[@gabbygetz], link:mailto:[email protected][[email protected]]
 
 Acknowledgements:
 
+* Gabby Getz, https://twitter.com/gabbygetz[@gabbygetz]
 * Matt Amato, https://twitter.com/matt_amato[@matt_amato]
 * Erik Andersson, https://github.com/e-andersson[@e-andersson]
 * Dan Bagnell, https://github.com/bagnell[@bagnell]
 * Ray Bentley
 * Jannes Bolling, https://github.com/jbo023[@jbo023]
+* Johan Borg
 * Dylan Brown, http://www.github.com/Dylan-Brown[@Dylan-Brown]
 * Sarah Chow, https://cesium.com/team/SarahChow/[cesium.com/team/SarahChow]
 * Paul Connelly
 * Volker Coors
+* Erik Dahlström, https://github.com/erikdahlstrom[@erikdahlstrom]
 * Tom Fili, https://twitter.com/CesiumFili[@CesiumFili]
 * Leesa Fini, http://www.github.com/LeesaFini[@LeesaFini]
+* Peter Gagliardi, https://github.com/ptrgags[@ptrgags]
 * Ralf Gutbell
 * Frederic Houbie
+* Marco Hutter, https://github.com/javagl[@javagl]
+* Daniel Krupka, https://github.com/krupkad[@krupkad]
+* Ian Lilley, https://github.com/IanLilleyT[@IanLilleyT]
+* Don McCurdy, https://github.com/donmccurdy[@donmccurdy]
 * Christopher Mitchell, Ph.D., https://github.com/KermMartian[@KermMartian]
+* Shehzan Mohammed, https://github.com/shehzan10[@shehzan10]
 * Claus Nagel
 * Jean-Philippe Pons
 * Carl Reed
 * Kevin Ring, http://www.kotachrome.com/kevin/[www.kotachrome.com/kevin]
 * Scott Simmons
+* Sam Suhag, https://github.com/sanjeetsuhag[@sanjeetsuhag]
 * Rob Taglang, https://github.com/lasalvavida[@lasalvavida]
 * Stan Tillman
 * Piero Toffanin, https://github.com/pierotofy[@pierotofy]
+* Bao Tran, https://github.com/baothientran[@baothientran]
+* Samuel Vargas, https://github.com/samulus[@samulus]
 * Pano Voudouris
 * Dave Wesloh
diff --git a/specification/APPENDIX.adoc b/specification/APPENDIX.adoc
@@ -1,13 +1,14 @@
 
 :leveloffset: +1
 
-[appendix]
+[appendix,obligation=normative]
 = Properties Reference
 :leveloffset: +1
 include::PropertiesReference_3dtiles.adoc[]
 :leveloffset: -1
 
 [appendix]
+[#json-schema]
 = JSON Schema reference
 :leveloffset: +1
 include::PropertiesReference_3dtiles_schema.adoc[]
@@ -39,11 +40,10 @@ include::Metadata/ReferenceImplementation/Schema/README.adoc[]
 :imagesdir: Metadata/Semantics
 include::Metadata/Semantics/README.adoc[]
 
-[appendix]
-include::ACKNOWLEDGEMENTS.adoc[]
-
-[appendix]
-include::LICENSE.adoc[]
+// License information is automatically inserted by Metanorma
+// when generating the OGC version of the specification.
+//[appendix]
+//include::LICENSE.adoc[]
 
 
 :leveloffset: -1
diff --git a/specification/BUILDING.md b/specification/BUILDING.md
@@ -1,11 +1,14 @@
 <!-- omit in toc -->
 # Build instructions
-
 - [Building the specification](#building-the-specification)
-  - [Asciidoctor setup](#asciidoctor-setup)
   - [Generating the properties reference](#generating-the-properties-reference)
-  - [Generating HTML and PDF with AsciiDoc](#generating-html-and-pdf-with-asciidoc)
-  - [Compressing the PDF](#compressing-the-pdf)
+  - [Building the specification with Asciidoctor](#building-the-specification-with-asciidoctor)
+    - [Asciidoctor setup](#asciidoctor-setup)
+    - [Generating HTML and PDF with AsciiDoc](#generating-html-and-pdf-with-asciidoc)
+    - [Compressing the PDF](#compressing-the-pdf)
+  - [Generating the specification with Metanorma](#generating-the-specification-with-metanorma)
+    - [Installing Metanorma locally](#installing-metanorma-locally)
+    - [Running Metanorma from its Docker container](#running-metanorma-from-its-docker-container)
 - [Notes for writing AsciiDoc in 3D Tiles](#notes-for-writing-asciidoc-in-3d-tiles)
   - [A note about section IDs](#a-note-about-section-ids)
   - [Cross-linking between files](#cross-linking-between-files)
@@ -16,15 +19,6 @@ The following is a short summary of the basic process for generating a single HT
 
 > Note: This process might be extended in the future, with details about how [wetzel](https://github.com/CesiumGS/wetzel) is used to generate the property reference. Depending on the exact process, the required toolchain might be summarized in a Docker container, similar to [Vulkan](https://github.com/KhronosGroup/Vulkan-Docs/blob/15d807ce4839d8feb523ca5c133a42a2aa448ade/BUILD.adoc), and controlled via a Makefile.
 
-### Asciidoctor setup
-
-- Install the Ruby interpreter, 2.3 or later, from http://www.ruby-lang.org/
-- Install Asciidoctor: `gem install asciidoctor`
-- In order to be able to generate PDF output: `gem install asciidoctor-pdf`
-- Install some rogue software: `gem install rouge` - no worries, that's the syntax highlighter...
-
-- A VSCode plugin for AsciiDoc syntax highlighting and preview: https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode
-
 ### Generating the properties reference
 
 The properties reference in the specification is automatically generated from the JSON schema, using [wetzel](https://github.com/CesiumGS/wetzel). It consists of two files:
@@ -53,7 +47,21 @@ node bin/wetzel.js ^
 The result of this call will be the `PropertiesReference_3dtiles.adoc` and 
 `PropertiesReference_3dtiles_schema.adoc` files that go into the `3d-tiles/specification` directory.
 
-### Generating HTML and PDF with AsciiDoc
+
+### Building the specification with Asciidoctor
+
+A plain, default version of the specification document can be created with Asciidoctor, a tool for converting AsciiDoc to HTML or PDF.
+
+#### Asciidoctor setup
+
+- Install the Ruby interpreter, 2.3 or later, from http://www.ruby-lang.org/
+- Install Asciidoctor: `gem install asciidoctor`
+- In order to be able to generate PDF output: `gem install asciidoctor-pdf`
+- Install some rogue software: `gem install rouge` - no worries, that's the syntax highlighter...
+
+- A VSCode plugin for AsciiDoc syntax highlighting and preview: https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode
+
+#### Generating HTML and PDF with AsciiDoc
 
 - Generating HTML:
   - `asciidoctor --verbose Specification.adoc --out-file Specification-1.1.0.html`
@@ -64,8 +72,7 @@ The result of this call will be the `PropertiesReference_3dtiles.adoc` and
 
 <sup>If the call does not appear to do anything, neither generate a PDF nor print an error message, make sure you typed `asciidoctor` and not just `asciidoc`</sup>
 
-
-### Compressing the PDF
+#### Compressing the PDF
 
 By default, the PDF file is large, due to the large image files being inserted uncompressed. There are tools for compressing the PDF, including a dedicated `asciidoctor-pdf-optimize` tool, but they have caveats. 
 
@@ -91,6 +98,31 @@ The process that worked for me:
 
 The main tweaking takes place via the `dPDFSETTINGS` parameter. The value can be `screen`, `ebook`, `printer`, or `prepress`. The exact effects of these parameters are summarized at https://www.ghostscript.com/doc/9.54.0/VectorDevices.htm#distillerparams
 
+### Generating the specification with Metanorma
+
+The OGC Community Standard version of the specification has to be created with Metanorma. Basic information about the toolchain and the template that is used can be found at https://github.com/opengeospatial/templates/tree/master/community_standard . For reference, the original 3D Tiles 1.0 specification is published at https://github.com/metanorma/mn-samples-ogc/tree/b3bdf688cbaf3822e00b6e3c1076ebf37530b0f6/sources/18-053r2 
+
+#### Installing Metanorma locally
+
+Don't. Don't even try.
+
+#### Running Metanorma from its Docker container
+
+1. Install Docker from https://www.docker.com/ 
+2. Pull the latest version of the Metanorma container with
+   ```
+   docker pull metanorma/metanorma:latest
+   ```
+3. In the `specification` directory of this repository, call
+  - Linux:
+     ```
+     docker run -v "$(pwd)":/metanorma -v ${HOME}/.fontist/fonts/:/config/fonts metanorma/metanorma metanorma compile --agree-to-terms -t ogc -x html,pdf Specification.adoc
+     ```
+   - Windows (**only** in PowerShell, not the standard console!):
+     ```
+     docker run -v ${pwd}:/metanorma -v ${HOME}/.fontist/fonts/:/config/fonts metanorma/metanorma metanorma compile --agree-to-terms -t ogc -x html,pdf Specification.adoc
+     ```
+  TODO Explain what these lines are doing, just to make clear that there is no `rm *` hidden in that...
 
 ## Notes for writing AsciiDoc in 3D Tiles
 

diff --git a/specification/CONFORMANCE.adoc b/specification/CONFORMANCE.adoc
@@ -0,0 +1,6 @@
+== Conformance
+
+Annex A of this document describes the Objects and Properties required to implement 3D Tiles. Conformance is relative to these elements and as partly expressed via the associated 3D Tiles xref:APPENDIX.adoc#json-schema[JSON Schema].
+
+All figures, examples, notes, and background information are informative.
+
diff --git a/specification/ImplicitTiling/AVAILABILITY.adoc b/specification/ImplicitTiling/AVAILABILITY.adoc
@@ -2,18 +2,21 @@
 = Availability Indexing
 
 [#implicittiling-converting-from-tile-coordinates-to-morton-index]
-[discrete]
 == Converting from Tile Coordinates to Morton Index
 
 A https://en.wikipedia.org/wiki/Z-order_curve[Morton index] is computed by interleaving the bits of the `(x, y)` or `(x, y, z)` coordinates of a tile. Specifically:
 
+[%unnumbered]
+[source]
 ----
 quadtreeMortonIndex = interleaveBits(x, y)
 octreeMortonIndex = interleaveBits(x, y, z)
 ----
 
 For example:
 
+[%unnumbered]
+[source]
 ----
 // Quadtree
 interleaveBits(0b11, 0b00) = 0b0101
@@ -31,9 +34,9 @@ image::figures/morton-indexing.png[Morton Order]
 
 
 [#implicittiling-availability-bitstream-lengths]
-[discrete]
 == Availability Bitstream Lengths
 
+.Availability bitstream lengths
 [cols="~,~,30%"]
 |===
 | Availability Type | Length (bits) | Description
@@ -55,20 +58,22 @@ Where `N` is 4 for quadtrees and 8 for octrees.
 
 These lengths are in number of bits in a bitstream. To compute the length of the bitstream in bytes, the following formula is used:
 
+[%unnumbered]
+[source]
 ----
 lengthBytes = ceil(lengthBits / 8)
 ----
 
 
 
 [#implicittiling-accessing-availability-bits]
-[discrete]
 == Accessing Availability Bits
 
 For tile availability and content availability, the Morton index only determines the ordering within a single level of the subtree. Since the availability bitstream stores bits for every level of the subtree, a level offset must be computed.
 
 Given the `(level, mortonIndex)` of a tile relative to the subtree root, the index of the corresponding bit can be computed with the following formulas:
 
+.Availability offsets
 [cols="~,~,30%"]
 |===
 | Quantity | Formula | Description
@@ -90,7 +95,6 @@ index of the desired child subtree relative to the root of the current subtree.
 
 
 [#implicittiling-global-and-local-tile-coordinates]
-[discrete]
 == Global and Local Tile Coordinates
 
 When working with tile coordinates, it is important to consider which tile the coordinates are relative to. There are two main types used in implicit tiling:
@@ -102,6 +106,8 @@ Global coordinates are used for locating any tile in the entire implicit tileset
 
 In binary, a tile's global Morton index is the complete path from the implicit root tile to the tile. This is the concatenation of the path from the implicit root tile to the subtree root tile, followed by the path from the subtree root tile to the tile. This can be expressed with the following equation:
 
+[%unnumbered]
+[source]
 ----
 tile.globalMortonIndex = concatBits(subtreeRoot.globalMortonIndex, tile.localMortonIndex)
 ----
@@ -111,6 +117,8 @@ image::figures/global-to-local-morton.png[,500]
 
 Similarly, the global level of a tile is the length of the path from the implicit root tile to the tile. This is the sum of the subtree root tile's global level and the tile's local level relative to the subtree root tile:
 
+[%unnumbered]
+[source]
 ----
 tile.globalLevel = subtreeRoot.globalLevel + tile.localLevel
 ----
@@ -120,6 +128,8 @@ image::figures/global-to-local-levels.png[,500]
 
 `(x, y, z)` coordinates follow the same pattern as Morton indices. The only difference is that the concatenation of bits happens component-wise. That is:
 
+[%unnumbered]
+[source]
 ----
 tile.globalX = concatBits(subtreeRoot.globalX, tile.localX)
 tile.globalY = concatBits(subtreeRoot.globalY, tile.localY)
@@ -134,11 +144,12 @@ image::figures/global-to-local-xy.png[Global to local XY coordinates]
 
 
 [#implicittiling-finding-parent-and-child-tiles]
-[discrete]
 == Finding Parent and Child Tiles
 
 The coordinates of a parent or child tile can also be computed with bitwise operations on the Morton index. The following formulas apply for both local and global coordinates.
 
+[%unnumbered]
+[source]
 ----
 childTile.level = parentTile.level + 1
 childTile.mortonIndex = concatBits(parentTile.mortonIndex, childIndex)