1.0 Organization and formatting updates #308

ggetz · 2018-05-11T20:33:56Z

Reorganized so the top-level README refers to the contained specification and new Q&A page
Added sections for generated property schema, still TODO once generated
Add license
Add sections to specification to conform to OGC submission. While the specification folder contents is not the exact template, sections here should be easily copied to conform to that template.
Marked sections non-normative where appropriate
Consolidated acknowledgements and ordered alphabetically by last name
Updated list of editors

Fixes #12
Fixes #153
Fixes #297
Fixes #37
Fixes #315
Fixes #37

TODO:

~~Defn list Add definition list #306~~
Schema generation Reference doc for tiles.json #37
Revise Q&As (@lilleyse can you look at this?)
Fill in attribution link TODOs
Create and link issue for post 1.0 plans
Update last edited date

lilleyse · 2018-05-11T20:50:53Z

Given the new organization we should scrub through the Cesium code base, or anywhere else really, for any https://github.com/AnalyticalGraphicsInc/3d-tiles links and fix any broken paths. After 1.0 is merged.

lilleyse

The new organization is great!

I'll take a look at the Q&A section a bit later.

lilleyse · 2018-05-11T21:12:45Z

README.md


-Created by the <a href="http://cesiumjs.org/">Cesium team</a> and built on <a href="https://www.khronos.org/gltf">glTF</a>.<br/>
+Bringing techniques from graphics research, the movie industry, and the game industry to 3D geospatial, 3D Tiles define a spatial data structure and a set of tile formats designed for 3D and optimized for streaming and rendering. 


I'm not sure this overview adds much. The first part of the sentence feels like the wrong tone. The second half is good, but could be developed further. Maybe it should be followed by a list of domains 3D Tiles may be used in - BIM/CAD, Phogrammetry, Point Clouds, etc. Or the section could be dropped?

Since this is the new landing page for 3D Tiles, I figured there should be some sort of introductory section. I'l edit the tone and add a sample of domains.

lilleyse · 2018-05-11T21:14:25Z

README.md


-<a href="http://cesiumjs.org/"><img src="figures/cesium.jpg" height="40" /></a> <a href="https://www.khronos.org/gltf"><img src="figures/gltf.png" height="40" /></a>
+Additional tile formats are under development, including Vector Data (`vctr`) [[#124](https://github.com/AnalyticalGraphicsInc/3d-tiles/pull/124)] for geospatial features like points, lines, and polygons. 


Better to link directly to the vector tiles README: https://github.com/AnalyticalGraphicsInc/3d-tiles/tree/3d-tiles-next/TileFormats/VectorData

lilleyse · 2018-05-11T21:51:48Z

Q-and-A.md

+
+[glTF](https://www.khronos.org/gltf) is an open standard for 3D models from Khronos (the same group that does WebGL and COLLADA).  Cesium uses glTF as its 3D model format, and the Cesium team contributes heavily to the glTF spec and open-source COLLADA2GLTF converter.  We recommend using glTF in Cesium for individual assets, e.g., an aircraft, a character, or a 3D building.
+
+We created 3D Tiles for streaming massive geospatial datasets where a single glTF model would be prohibitive.  Given that glTF is optimized for rendering, that Cesium has a well-tested glTF loader, and that there are existing conversion tools for glTF, 3D Tiles use glTF for some tile formats such as [b3dm](TileFormats/Batched3DModel/README.md) (used for 3D buildings).


b3dm is a broken link

lilleyse · 2018-05-11T21:52:00Z

Q-and-A.md

+
+3D Tiles supports heterogeneous data by allowing different tile formats in a tileset, e.g., a tileset may contain tiles for 3D buildings, tiles for instanced 3D trees, and tiles for point clouds, all using different tile formats.
+
+3D Tiles also supports heterogeneous datasets by concatenating different tile formats into one tile using the [Composite](TileFormats/Composite/README.md) tile format.  In the example above, a tile may have a short header followed by the content for the 3D buildings, instanced 3D trees, and point clouds.


Composite - fix link

lilleyse · 2018-05-11T21:52:22Z

Q-and-A.md

+
+#### How are cracks between tiles with vector data handled?
+
+Unlike 2D, in 3D, we expect adjacent tiles to be from different LODs so, for example, in the distance, lower resolution tiles are used.  Adjacent tiles from different LODs can lead to an artifact called _cracking_ where there are gaps between tiles.  For terrain, this is generally handled by dropping _skirts_ slightly angled outward around each tile to fill the gap.  For 3D buildings, this is handled by extending the tile boundary to fully include buildings on the edge; [see above](#Quadtrees).  For vector data, this is an open research problem that we need to solve.  This could invole boundary-aware simplification or runtime stitching. 


Fix see above link.

lilleyse · 2018-05-11T22:13:50Z

specification/TileFormats/Composite/README.md

@@ -2,6 +2,8 @@



See tile formats for a list of tile formats. - link is broken in this line

lilleyse · 2018-05-11T22:19:55Z

specification/Styling/README.md

 * Gabby Getz, [@ggetz](https://github.com/ggetz)
 * Matt Amato, [@matt_amato](https://twitter.com/matt_amato)
 * Tom Fili, [@CesiumFili](https://twitter.com/CesiumFili)
 * Sean Lilley, [@lilleyse](https://github.com/lilleyse)
 * Patrick Cozzi, [@pjcozzi](https://twitter.com/pjcozzi)

-Contents:
+## Contents


Below, the Schema Reference link should be fixed.

lilleyse · 2018-05-11T22:20:43Z

specification/Styling/README.md

 * Gabby Getz, [@ggetz](https://github.com/ggetz)
 * Matt Amato, [@matt_amato](https://twitter.com/matt_amato)
 * Tom Fili, [@CesiumFili](https://twitter.com/CesiumFili)
 * Sean Lilley, [@lilleyse](https://github.com/lilleyse)
 * Patrick Cozzi, [@pjcozzi](https://twitter.com/pjcozzi)

-Contents:
+## Contents


Remove the Acknowledgments entry.

lilleyse · 2018-05-11T22:24:30Z

specification/Styling/README.md

@@ -63,6 +47,25 @@ Styles are defined with JSON and expressions written in a small subset of JavaSc

 ## Examples

+_This section is non-normative_


This note is too broad since some of the content in this section is normative including conditions and meta. Maybe the note should be Examples in this section are non-normative

lilleyse · 2018-05-11T22:26:09Z

specification/README.md

@@ -0,0 +1,749 @@
+# 3D Tiles Format Specification
+
+**Version 1.0**, May 11, 2018


Add a TODO to change this date later.

ggetz · 2018-05-31T15:02:26Z

Also replaces #312

ggetz · 2018-05-31T15:03:39Z

@lilleyse This has been updated. Last thing to look at is the Q&As.

lilleyse · 2018-05-31T15:40:08Z

Updated Q&A. It didn't require too many changes.

lilleyse · 2018-05-31T15:54:32Z

I made some tweaks to the overview in 9c7ae49

lilleyse · 2018-05-31T17:53:17Z

specification/Styling/README.md

 * [`expression`](#reference-expression)
+* [`number expression`](#reference-number-expression)
+* [`Point Cloud Style`](#reference-point-cloud-style) (root object)


What does (root object) mean?

I missed removing that. wetzel adds that to the schema object the command was run on.

lilleyse · 2018-05-31T18:00:20Z

specification/TileFormats/Batched3DModel/README.md

-##### Extras
-
-Application-specific data.
+### Property Reference


Organizationally, I think it makes the document easier to read if the property reference section is the last rather than somewhere in the middle. Same for any other READMEs.

Makes sense, I'll make them an "Appendix" and add a link from the Header section.

ggetz · 2018-05-31T20:46:48Z

@lilleyse Updated

lilleyse

Thanks @ggetz. I went through the property reference sections. Mostly minor comments.

lilleyse · 2018-05-31T21:06:42Z

specification/README.md

+  * [`Properties`](#reference-properties)
+* [`Tile`](#reference-tile)
+  * [`Bounding Volume`](#reference-bounding-volume)
+  * [`Tile Content`](#reference-tile-content)


These links aren't working.

lilleyse · 2018-05-31T21:11:52Z

specification/README.md

+
+* **Type**: `object`
+* **Required**: No
+* **Type of each property**: Extension


This line wasn't included for tileset.extensions. Which one is the preferred form?

There are other occurrences of this line to watch out for as well.

lilleyse · 2018-05-31T21:12:38Z

specification/README.md

+
+##### asset.version :white_check_mark: 
+
+The 3D Tiles version.  The version defines the JSON schema for tileset.json and the base set of tile formats.


It looks like the schema files still reference tileset.json in some places. Change all occurrences to tileset JSON.

lilleyse · 2018-05-31T21:15:32Z

specification/README.md

+
+#### Bounding Volume
+
+A bounding volume that encloses a tile or its content.  Exactly one property is required.


The Exactly one property is required sentence should be changed to say exactly one of box, region, or sphere is required, since we don't want to exclude extensions/extras

lilleyse · 2018-05-31T21:19:31Z

specification/README.md

+
+This Specification is licensed under a [Creative Commons Attribution 4.0 International License (CC BY 4.0)](http://creativecommons.org/licenses/by/4.0/).
+
+Some parts of this Specification are purely informative and do not define requirements necessary for compliance and so are outside the Scope of this Specification. These parts of the Specification are marked as being non-normative, or identified as **Implementation Notes**.


Should this sentence be in a separate section? Maybe a Notes section?

This is where it's mentioned in the Khronos documents: https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#appendix-d-full-khronos-copyright-statement

But I would be fine with moving it if there's a good argument for it.

The distinction might be that the glTF document has it under the copyright section whereas this is under the license section. I don't want it to be implied that this paragraph is part of the license.

Though speaking of, do we need a Copyright section ourselves?

lilleyse · 2018-05-31T21:50:53Z

specification/TileFormats/BatchTable/README.md

+<a name="reference-property"></a>
+##### Property
+
+A user-defined property which specifies per-feature application-specific metadata in a tile. Values either can be defined directly in the JSON as a numeric array, or can refer to sections in the binary body with a [`BinaryBodyReference`](#reference-binarybodyreference) object.


Another random schema mistake from before - change numeric array to just array

lilleyse · 2018-05-31T21:54:01Z

specification/TileFormats/Batched3DModel/README.md

+|---|----|-----------|--------|
+|**extensions**|`object`|Dictionary object with extension-specific objects.|No|
+|**extras**|`any`|Application-specific data.|No|
+|**BATCH_LENGTH**|`object`, `number` `[1]`, `number`|A [`GlobalPropertyScalar`](#reference-globalpropertyscalar) object defining a numeric property for all features. See the corresponding property semantic in [Semantics](/specification/TileFormats/PointCloud/README.md#semantics).| :white_check_mark: Yes|


Throughout, make sure all of these Semantics links point to the correct tile format. Here the link points to pnts but should be b3dm.

lilleyse · 2018-05-31T21:59:38Z

specification/TileFormats/FeatureTable/README.md

+|**extensions**|`object`|Dictionary object with extension-specific objects.|No|
+|**extras**|`any`|Application-specific data.|No|
+
+Additional properties are not allowed.


The feature table schema should allow for additional properties.

lilleyse · 2018-05-31T22:02:16Z

specification/TileFormats/Instanced3DModel/README.md

+
+Additional properties are allowed.
+
+* **JSON schema**: [featureTable.schema.json#/definitions/binaryBodyReference](../../schema/featureTable.schema.json#/definitions/binaryBodyReference)


Fix link text.

lilleyse · 2018-05-31T22:03:42Z

specification/TileFormats/PointCloud/README.md

+Additional properties are allowed.
+
+* **JSON schema**: [featureTable.schema.json#/definitions/binaryBodyReference](../../schema/featureTable.schema.json#/definitions/binaryBodyReference)


Fix link text.

ggetz · 2018-06-04T21:47:28Z

Updated. @lilleyse If you're happy with the updates, I'll go ahead and regenerate the PDF with the changes.

lilleyse

The updates to the property reference sections look great.

The changes to the spatial data structure section look good too. I made some small edits in 3e8f839. Does this section need to be sooner in the document though? (a short section early - #315). Maybe take some of the highlight here and put them in their own section right below Coordinate reference system, and link back to this main section.

lilleyse · 2018-06-04T23:25:08Z

specification/Styling/README.md

+|   |Type|Description|Required|
+|---|----|-----------|--------|
+|**defines**|`object`|A dictionary object of defined [`expression`](#reference-expression) strings mapped to a variable name that may be referenced throughout the style. If an expression references a defined variable, it is replaced with the result of the corresponding evaluated expression.|No|
+|**show**|`undefined[]`, `object`|A [`boolean expression`](#reference-boolean-expression) or [`conditions`](#reference-conditions) property which determines if a feature should be shown.|No, default: `true`|


There are a couple cases where the type is undefined[] for some reason.

lilleyse · 2018-06-04T23:30:46Z

specification/Styling/README.md

+
+Additional properties are allowed.
+
+* **Type of each property**: [`metaProperty`](#reference-metaproperty)


Since this doesn't lead to anything anymore, maybe style.metaProperty.schema.json should be removed and instead each property be of type expression?

"additionalProperties" : { "$ref" : "style.expression.schema.json" }

Same comment for style.definesProperty.schema.json

ggetz · 2018-06-05T16:18:32Z

@lilleyse This is all updated, and the latest PDF is included. Let me know if we need anything else, but I think this is ready to merge if you are good with the updates.

lilleyse · 2018-06-06T04:04:21Z

Adding some clarification to padding based on the feedback in #314

lilleyse · 2018-06-06T04:12:30Z

All the recent changes look good - take a quick look at 22565e7 - after that I also think this is good to merge.

ggetz · 2018-06-06T16:02:52Z

@lilleyse Looks good! I also added the example to be in the Padding section itself. Generated the PDF.

lilleyse · 2018-06-07T01:29:27Z

Awesome! Whew... is all I can say.

ggetz added 2 commits May 11, 2018 16:24

Reorg and formatting changes, add licence

051e78d

Future plans

5fdbc93

Fix TOC

cf8dad2

ggetz closed this May 11, 2018

ggetz reopened this May 11, 2018

lilleyse reviewed May 11, 2018

View reviewed changes

ggetz added 9 commits May 13, 2018 17:04

Reorg fixes

579502a

Add property reference

31145d8

Add styling property reference

7686e4a

Fomratting, properties

0bc4052

Property reference

58bc518

Formatting fixes

7b0e7b2

Merge branch '1.0' into 1.0-formatting

772e361

Formatting fixes

37689e6

Add talks

b0f1093

ggetz mentioned this pull request May 31, 2018

Add links to FOSS4G talks #312

Closed

Q and E edits

cacf1c3

lilleyse force-pushed the 1.0-formatting branch from aae19ad to cacf1c3 Compare May 31, 2018 15:38

Tweak overview

9c7ae49

lilleyse force-pushed the 1.0-formatting branch from b98e79b to 9c7ae49 Compare May 31, 2018 15:54

Tweak example

52b4f6f

lilleyse reviewed May 31, 2018

View reviewed changes

Move reference sections

84ae79d

lilleyse reviewed May 31, 2018

View reviewed changes

ggetz added 6 commits June 4, 2018 10:45

Update pdf

d64d31d

Fix pdf TOC

4cdee18

Fix styling property reference

5fffd6f

Upadte TileFormat schema references

7866bac

Update spatial data structures, update copyright

cd00b15

Updated tileset ref doc

c65c3b2

Small edits to spatial data structures section

3e8f839

lilleyse reviewed Jun 5, 2018

View reviewed changes

ggetz added 4 commits June 5, 2018 09:58

Update intro

fc8e5d1

Update links

39187a9

Fix styling property reference

c080472

Update specification pdf

b9a6d03

Clarify padding some more

22565e7

lilleyse mentioned this pull request Jun 6, 2018

PNTS: Unclear padding description in the specification #314

Closed

ggetz added 3 commits June 6, 2018 11:20

Tweak example wording for clarity

64cd5ed

Wording tweak

49bf1c2

Update pdf

b122329

This was referenced Jun 6, 2018

Format spec using OGC template #153

Closed

Explain 3D Tiles spatial data structure for 2D users #315

Closed

lilleyse merged commit e7400bd into 1.0 Jun 7, 2018

This was referenced Jun 7, 2018

License for the spec text #12

Closed

Reference doc for tiles.json #37

Closed

lilleyse deleted the 1.0-formatting branch June 13, 2018 12:59

lilleyse mentioned this pull request Jul 31, 2018

Merge 1.0 branch into master #327

Merged

4 tasks


		Created by the <a href="http://cesiumjs.org/">Cesium team</a> and built on <a href="https://www.khronos.org/gltf">glTF</a>.<br/>
		Bringing techniques from graphics research, the movie industry, and the game industry to 3D geospatial, 3D Tiles define a spatial data structure and a set of tile formats designed for 3D and optimized for streaming and rendering.


		<a href="http://cesiumjs.org/"><img src="figures/cesium.jpg" height="40" /></a> <a href="https://www.khronos.org/gltf"><img src="figures/gltf.png" height="40" /></a>
		Additional tile formats are under development, including Vector Data (`vctr`) [[#124](https://github.com/AnalyticalGraphicsInc/3d-tiles/pull/124)] for geospatial features like points, lines, and polygons.


		[glTF](https://www.khronos.org/gltf) is an open standard for 3D models from Khronos (the same group that does WebGL and COLLADA). Cesium uses glTF as its 3D model format, and the Cesium team contributes heavily to the glTF spec and open-source COLLADA2GLTF converter. We recommend using glTF in Cesium for individual assets, e.g., an aircraft, a character, or a 3D building.

		We created 3D Tiles for streaming massive geospatial datasets where a single glTF model would be prohibitive. Given that glTF is optimized for rendering, that Cesium has a well-tested glTF loader, and that there are existing conversion tools for glTF, 3D Tiles use glTF for some tile formats such as [b3dm](TileFormats/Batched3DModel/README.md) (used for 3D buildings).


		3D Tiles supports heterogeneous data by allowing different tile formats in a tileset, e.g., a tileset may contain tiles for 3D buildings, tiles for instanced 3D trees, and tiles for point clouds, all using different tile formats.

		3D Tiles also supports heterogeneous datasets by concatenating different tile formats into one tile using the [Composite](TileFormats/Composite/README.md) tile format. In the example above, a tile may have a short header followed by the content for the 3D buildings, instanced 3D trees, and point clouds.


		#### How are cracks between tiles with vector data handled?

		Unlike 2D, in 3D, we expect adjacent tiles to be from different LODs so, for example, in the distance, lower resolution tiles are used. Adjacent tiles from different LODs can lead to an artifact called _cracking_ where there are gaps between tiles. For terrain, this is generally handled by dropping _skirts_ slightly angled outward around each tile to fill the gap. For 3D buildings, this is handled by extending the tile boundary to fully include buildings on the edge; [see above](#Quadtrees). For vector data, this is an open research problem that we need to solve. This could invole boundary-aware simplification or runtime stitching.

		@@ -63,6 +47,25 @@ Styles are defined with JSON and expressions written in a small subset of JavaSc

		## Examples

		_This section is non-normative_

		@@ -0,0 +1,749 @@
		# 3D Tiles Format Specification

		Version 1.0, May 11, 2018


		##### asset.version :white_check_mark:

		The 3D Tiles version. The version defines the JSON schema for tileset.json and the base set of tile formats.


		#### Bounding Volume

		A bounding volume that encloses a tile or its content. Exactly one property is required.


		This Specification is licensed under a [Creative Commons Attribution 4.0 International License (CC BY 4.0)](http://creativecommons.org/licenses/by/4.0/).

		Some parts of this Specification are purely informative and do not define requirements necessary for compliance and so are outside the Scope of this Specification. These parts of the Specification are marked as being non-normative, or identified as Implementation Notes.


		Additional properties are allowed.

		* JSON schema: [featureTable.schema.json#/definitions/binaryBodyReference](../../schema/featureTable.schema.json#/definitions/binaryBodyReference)


		Additional properties are allowed.

		* Type of each property: [`metaProperty`](#reference-metaproperty)

1.0 Organization and formatting updates #308

1.0 Organization and formatting updates #308

Conversation

ggetz commented May 11, 2018 • edited Loading

lilleyse commented May 11, 2018

lilleyse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ggetz commented May 31, 2018

ggetz commented May 31, 2018

lilleyse commented May 31, 2018

lilleyse commented May 31, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ggetz commented May 31, 2018

lilleyse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ggetz commented Jun 4, 2018

lilleyse left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ggetz commented Jun 5, 2018

lilleyse commented Jun 6, 2018

lilleyse commented Jun 6, 2018

ggetz commented Jun 6, 2018

lilleyse commented Jun 7, 2018

ggetz commented May 11, 2018 •

edited

Loading