AsciiDoc conversion experiments

specification/ACKNOWLEDGEMENTS.adoc

@@ -0,0 +1,34 @@
+= Acknowledgements
+
+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:
+
+* 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]
+* 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
+* Tom Fili, https://twitter.com/CesiumFili[@CesiumFili]
+* Leesa Fini, http://www.github.com/LeesaFini[@LeesaFini]
+* Ralf Gutbell
+* Frederic Houbie
+* Christopher Mitchell, Ph.D., https://github.com/KermMartian[@KermMartian]
+* Claus Nagel
+* Jean-Philippe Pons
+* Carl Reed
+* Kevin Ring, http://www.kotachrome.com/kevin/[www.kotachrome.com/kevin]
+* Scott Simmons
+* Rob Taglang, https://github.com/lasalvavida[@lasalvavida]
+* Stan Tillman
+* Piero Toffanin, https://github.com/pierotofy[@pierotofy]
+* Pano Voudouris
+* Dave Wesloh

specification/APPENDIX.adoc

@@ -0,0 +1,49 @@
+
+:leveloffset: +1
+
+[appendix]
+= Properties Reference
+:leveloffset: +1
+include::PropertiesReference_3dtiles.adoc[]
+:leveloffset: -1
+
+[appendix]
+= JSON Schema reference
+:leveloffset: +1
+include::PropertiesReference_3dtiles_schema.adoc[]
+:leveloffset: -1
+
+[appendix]
+:imagesdir: TileFormats/glTF
+include::TileFormats/glTF/MIGRATION.adoc[]
+
+[appendix]
+:imagesdir: ImplicitTiling
+include::ImplicitTiling/AVAILABILITY.adoc[]
+
+[appendix]
+:imagesdir: Metadata/ReferenceImplementation
+include::Metadata/ReferenceImplementation/README.adoc[]
+
+:leveloffset: +1
+
+:imagesdir: Metadata/ReferenceImplementation/PropertyTable
+include::Metadata/ReferenceImplementation/PropertyTable/README.adoc[]
+
+:imagesdir: Metadata/ReferenceImplementation/Schema
+include::Metadata/ReferenceImplementation/Schema/README.adoc[]
+
+:leveloffset: -1
+
+[appendix]
+:imagesdir: Metadata/Semantics
+include::Metadata/Semantics/README.adoc[]
+
+[appendix]
+include::ACKNOWLEDGEMENTS.adoc[]
+
+[appendix]
+include::LICENSE.adoc[]
+
+
+:leveloffset: -1

specification/BUILDING.md

@@ -0,0 +1,110 @@
+<!-- omit in toc -->
+# Build instructions
+
+- [Building the specification](#building-the-specification)
+  - [Asciidoctor setup](#asciidoctor-setup)
+  - [Generating HTML and PDF with AsciiDoc](#generating-html-and-pdf-with-asciidoc)
+  - [Compressing the PDF](#compressing-the-pdf)
+- [A note about section IDs](#a-note-about-section-ids)
+- [Cross-linking between files](#cross-linking-between-files)
+
+## Building the specification 
+
+The following is a short summary of the basic process for generating a single HTML- or PDF file containing the whole specification.
+
+> 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 HTML and PDF with AsciiDoc
+
+- Generating HTML:
+  - `asciidoctor --verbose Specification.adoc --out-file Specification-1.1.0.html`
+- Generating PDF:
+  - `asciidoctor-pdf --verbose --trace --attribute scripts=cjk --attribute pdf-theme=default-with-fallback-font Specification.adoc --out-file Specification-1.1.0.pdf`
+
+    > Note: The last call is derived from https://asciidoctor.org/docs/asciidoctor-pdf/#support-for-non-latin-languages and handles Japanese characters. Without them, the call could just be `asciidoctor -r asciidoctor-pdf -b pdf Specification.adoc -o Specification-1.1.0.pdf`
+
+<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
+
+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. 
+
+The process that worked for me:
+
+- Download GhostScript **not later than 9.20** from https://github.com/ArtifexSoftware/ghostpdl-downloads/releases/tag/gs920  
+  - This is the latest version that did not contain the so-called ""bugfix"" from https://bugs.ghostscript.com/show_bug.cgi?id=699830 that apparently caused more harm than good.
+
+  - Run the following command: 
+    ```
+    "C:\Program Files\gs\gs9.20\bin\gswin64.exe" ^
+      -dPrinted=false ^
+      -sDEVICE=pdfwrite ^
+      -dCompatibilityLevel=1.4 ^
+      -dPDFSETTINGS=/ebook ^
+      -dNOPAUSE ^
+      -dBATCH ^
+      -dDetectDuplicateImages ^
+      -sOutputFile=Specification-1.1.0-compressed.pdf ^
+      Specification-1.1.0.pdf   
+    ```
+    (This is a Windows .BAT file. On Linux, replace the `^` with `\`)
+
+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
+
+
+## A note about section IDs
+
+The automatic naming for `#anchors` based on section titles is different for Markdown and AsciiDoc. While the latter _can_ be configured to some extent, this would still cause problems when generating a single HTML document. While an anchor may be something like `#overview` _locally_ (in the single `.adoc` file viewn on GitHub), the name may be `#overview_7` when creating a single HTML document. Therefore, unique identifiers for the sections have been inserted. These identifiers follow the pattern
+
+_`<directoryName>`_ `-` _`<markdownAnchor>`_
+
+where `directoryName` is the full directory name in lowercase (with subdirectories separated by `-`), and `markdownAnchor` is the section title as a markdown anchor. For example, the section
+
+`./Metadata/ReferenceImplementation/README.md -> == Overview`
+
+received the ID 
+
+`[#metadata-referenceimplementation-overview]`
+
+
+## Cross-linking between files 
+
+Two `adoc` files that are contained in sibling directories cannot trivially link to each other. When there are two files
+
+    \ImplicitTiling\README.adoc
+    \Matadata\README.adoc
+
+and they should link to each other, then it is not possible to write
+
+    See xref:../Metadata/README.adoc#anchor[Metadata]
+
+in the first one. (See https://github.com/asciidoctor/asciidoctor/issues/650, https://github.com/asciidoctor/asciidoctor/issues/844, https://github.com/asciidoctor/asciidoctor/issues/3136, https://github.com/asciidoctor/asciidoctor/issues/3276 ...)
+
+In order to create links between documents that work in GitHub **and** in the single HTML/PDF file, the following workaround can be used:
+
+1. At the top of the `ImplicitTiling/README.adoc`, insert this:
+
+    ```
+    ifdef::env-github[]
+    :url-specification-metadata: ../Metadata/
+    endif::[]
+    ifndef::env-github[]
+    :url-specification-metadata:
+    endif::[]
+    ```
+
+2. Then, use the following pattern for links:
+
+    `See xref:{url-specification-metadata}README.adoc#anchor[An example]`
+
+This will cause the _relative_ link to be used when the file is viewn on GitHub, and the "unqualified" link to be used inside the single HTML/PDF document. 

specification/ImplicitTiling/AVAILABILITY.adoc

@@ -0,0 +1,158 @@
+[#implicittiling-availability-indexing]
+= 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:
+
+----
+quadtreeMortonIndex = interleaveBits(x, y)
+octreeMortonIndex = interleaveBits(x, y, z)
+----
+
+For example:
+
+----
+// Quadtree
+interleaveBits(0b11, 0b00) = 0b0101
+interleaveBits(0b1010, 0b0011) = 0b01001110
+interleaveBits(0b0110, 0b0101) = 0b00110110
+
+// Octree
+interleaveBits(0b001, 0b010, 0b100) = 0b100010001
+interleaveBits(0b111, 0b000, 0b111) = 0b101101101
+----
+
+.An example for the computation of the Morton index based on the tile coordinates on three levels of a quadtree
+image::figures/morton-indexing.png[Morton Order]
+
+
+
+[#implicittiling-availability-bitstream-lengths]
+[discrete]
+== Availability Bitstream Lengths
+
+[cols="~,~,30%"]
+|===
+| Availability Type | Length (bits) | Description
+
+| Tile availability
+| `+(N^subtreeLevels - 1)/(N - 1)+`
+| Total number of nodes in the subtree
+
+| Content availability
+| `+(N^subtreeLevels - 1)/(N - 1)+`
+| Since there is at most one content per tile, this is the same length as tile availability
+
+| Child subtree availability
+| `+N^subtreeLevels+`
+| Number of nodes one level deeper than the deepest level of the subtree
+|===
+
+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:
+
+----
+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:
+
+[cols="~,~,30%"]
+|===
+| Quantity | Formula | Description
+
+| `levelOffset`
+| `+(N^level - 1) / (N - 1)+`
+| This is the number of nodes at levels `+1, 2, ... (level - 1)+`
+
+| `tileAvailabilityIndex`
+| `levelOffset + mortonIndex`
+| The index into the buffer view is the offset for the tile's level plus the morton index for the tile
+|===
+
+Where `N` is 4 for quadtrees and 8 for octrees.
+
+Since child subtree availability stores bits for a single level, no levelOffset is needed, i.e. `childSubtreeAvailabilityIndex = mortonIndex`, where the `mortonIndex` is the Morton
+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:
+
+* *global coordinates* - coordinates relative to the implicit root tile.
+* *local coordinates* - coordinates relative to the root of a specific subtree.
+
+Global coordinates are used for locating any tile in the entire implicit tileset. For example, template URIs use global coordinates to locate content files and subtrees. Meanwhile, local coordinates are used for locating data within a single subtree file.
+
+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:
+
+----
+tile.globalMortonIndex = concatBits(subtreeRoot.globalMortonIndex, tile.localMortonIndex)
+----
+
+.Illustration of how to compute the global Morton index of a tile, from the global Morton index of the root of the containing subtree, and the local Morton index of the tile in this subtree
+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:
+
+----
+tile.globalLevel = subtreeRoot.globalLevel + tile.localLevel
+----
+
+.Illustration of how to compute the global level of a tile, from the glonal level of the root of the containing subtree, and the local level of the tile in this subtree
+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:
+
+----
+tile.globalX = concatBits(subtreeRoot.globalX, tile.localX)
+tile.globalY = concatBits(subtreeRoot.globalY, tile.localY)
+
+// Octrees only
+tile.globalZ = concatBits(subtreeRoot.globalZ, tile.localZ)
+----
+
+.Illustration of the computation of the global tile coordinates, from the global coordinates of the containing subtree, and the local coordinates of the tile in this subtree.
+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.
+
+----
+childTile.level = parentTile.level + 1
+childTile.mortonIndex = concatBits(parentTile.mortonIndex, childIndex)
+childTile.x = concatBits(parentTile.x, childX)
+childTile.y = concatBits(parentTile.y, childY)
+
+// Octrees only
+childTile.z = concatBits(parentTile.z, childZ)
+----
+
+Where:
+
+* `childIndex` is an integer in the range `[0, N)` that is the index of the child tile relative to the parent.
+* `childX`, `childY`, and `childZ` are single bits that represent which half of the parent's bounding volume the child is in in each direction.
+
+.Illustration of the computation of the coordinates of parent- and child tiles
+image::figures/parent-and-child-coordinates.png[Parent and child coordinates]