Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Section structure and link pass #673

Merged
merged 7 commits into from
Mar 16, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions Q-and-A.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ No, 3D Tiles is a general spec for streaming massive heterogeneous 3D geospatial

[glTF](https://www.khronos.org/gltf) is an open standard for 3D models from Khronos (the same group that does WebGL and COLLADA). CesiumJS 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 CesiumJS 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 CesiumJS has a well-tested glTF loader, and that there are existing conversion tools for glTF, 3D Tiles often use glTF for tile content. Tiles may reference glTF models directly — with [`3DTILES_content_gltf`](./extensions/3DTILES_content_gltf) — or glTF models may be embedded in other tile formats such as [Batched 3D Model](./specification/TileFormats/Batched3DModel/README.md).
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 CesiumJS has a well-tested glTF loader, and that there are existing conversion tools for glTF, 3D Tiles often use glTF for tile content. Tiles may reference glTF models directly, using the [glTF Tile Format](./specification/TileFormats/glTF/README.md).

Taking this approach allows us to improve CesiumJS, glTF, and 3D Tiles at the same time. As new features and compression methods arrive in glTF, they benefit 3D models in CesiumJS, the glTF ecosystem, and 3D Tiles.

Expand Down Expand Up @@ -91,7 +91,7 @@ See [#15](https://github.com/CesiumGS/3d-tiles/issues/15).

#### 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 Quadtrees](./specification/README.md#Quadtrees). For vector data, this is an open research problem that we need to solve. This could involve boundary-aware simplification or runtime stitching.
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 Quadtrees](./specification/README.md#quadtrees). For vector data, this is an open research problem that we need to solve. This could involve boundary-aware simplification or runtime stitching.

#### When using replacement refinement, can multiple children be combined into one request?

Expand All @@ -111,4 +111,4 @@ See [#11](https://github.com/CesiumGS/3d-tiles/issues/11).

#### What compressed texture formats does 3D Tiles use?

3D Tiles reference glTF tile content ([`3DTILES_content_gltf`](./extensions/3DTILES_content_gltf)), and the glTF format officially supports PNG, JPEG, and KTX2 / Basis Universal compressed textures ([`KHR_texture_basisu`](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_texture_basisu)). Additional texture compression methods may be added to glTF in the future, as [glTF extensions](https://github.com/KhronosGroup/glTF/tree/main/extensions). Texture compression is generally applied offline, as it is often prohibitively expensive to do in JavaScript and Web Workers.
3D Tiles reference glTF content via the [glTF Tile Format](./specification/TileFormats/glTF/README.md), and the glTF format officially supports PNG, JPEG, and KTX2 / Basis Universal compressed textures ([`KHR_texture_basisu`](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_texture_basisu)). Additional texture compression methods may be added to glTF in the future, as [glTF extensions](https://github.com/KhronosGroup/glTF/tree/main/extensions). Texture compression is generally applied offline, as it is often prohibitively expensive to do in JavaScript and Web Workers.
10 changes: 0 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,16 +34,6 @@ Bringing techniques from the field of 3D graphics and built on [glTF](https://gi

Please provide spec feedback by [submitting issues](https://github.com/CesiumGS/3d-tiles/issues). For questions on implementation, generating 3D Tiles, or to showcase your work, join the [Cesium community forum](https://community.cesium.com/). A list of resources for developers, including blog posts and presentations that explain the concepts and applications of 3D Tiles, can be found on the [3D Tiles Resources](./RESOURCES.md) page.

### Upcoming

[3D Tiles Next](./next) is a set of new capabilities for the future of 3D Tiles. Provided as draft extensions to the [3D Tiles 1.0](../specification) specification, these features may be incorporated into 3D Tiles 2.0 in the future.

- [Tile Content](./next#tile-content): glTF 2.0 assets may be used directly as tile content, without intermediate formats, improving interoperability with 3D content and tooling ecosystems. Tiles may reference multiple contents — for organization, styling, and filtering — and contents may be collected into groups similar to map layers in mapping applications.
- [Implicit Tiling](./next#implicit-tiling): Common subdivision schemes and spatial index patterns may be declared without listing bounding volumes exhaustively. Reduces tileset size, and enables new optimizations including faster traversal, raycasting, random access, and spatial queries.
- [Metadata](./next#metadata): Metadata in 3D Tiles gains more expressiveness and flexibility, with a well-defined type system, new encoding options (e.g. JSON or binary), and a range of granularity options. Metadata may be associated with high-level objects like tilesets, tiles, or tile content groups, or with individual vertices and texels on glTF 2.0 geometry.

A curated list of resources for developers can be found on the [3D Tiles Next Resources](./next/RESOURCES.md) page.

Comment on lines -37 to -46
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be replaced by a more formal version history. That's what this checkbox in #651 was about:

  • Add version history (include deprecations)

Doesn't have to hold up this PR though.

## 3D Tiles Ecosystem

| Tool | Description |
Expand Down
2 changes: 1 addition & 1 deletion extensions/3DTILES_bounding_volume_S2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ For the cell IDs in the example above, the tokens are:

## Bounding Volume

An S2 cell describes 4 positions on the surface of the WGS84 ellipsoid forming the corners of a geodesic quadrilateral. To form a bounding volume, the quadrilateral is extruded along normals to the ellipsoid. `minimumHeight` determines the height of the bottom surface of the bounding volume, while `maximumHeight` determines the height of the top surface. Both `minimumHeight` and `maximumHeight` are expressed in meters above (or below) the ellipsoid. A tile's [`transform`](../../specification#tile-transforms) property will be ignored when this extension is used for describing a tile's `boundingVolume`. Tiles using this extension must maintain [spatial coherence](../../specification/README.md#bounding-volume-spatial-coherence). This extension may be applied to the [`tile.boundingVolume`](../../specification/schema/tile.schema.json) or the [`content.boundingVolume`](../../specification/schema/content.schema.json) objects.
An S2 cell describes 4 positions on the surface of the WGS84 ellipsoid forming the corners of a geodesic quadrilateral. To form a bounding volume, the quadrilateral is extruded along normals to the ellipsoid. `minimumHeight` determines the height of the bottom surface of the bounding volume, while `maximumHeight` determines the height of the top surface. Both `minimumHeight` and `maximumHeight` are expressed in meters above (or below) the ellipsoid. A tile's [`transform`](../../specification/README.md#tile-transforms) property will be ignored when this extension is used for describing a tile's `boundingVolume`. Tiles using this extension must maintain [spatial coherence](../../specification/README.md#bounding-volume-spatial-coherence). This extension may be applied to the [`tile.boundingVolume`](../../specification/schema/tile.schema.json) or the [`content.boundingVolume`](../../specification/schema/content.schema.json) objects.

> **Implementation Note**: When mapping the sphere to the cube, S2 provides three projection methods: linear, quadratic and tangential. This extension assumes an implementation uses the quadratic projection, since it is reasonably accurate and efficient.

Expand Down
10 changes: 5 additions & 5 deletions extensions/3DTILES_implicit_tiling/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ The following constraints apply to implicit root tiles:

* The tile must omit the `children` property
* The tile must not have the `3DTILES_metadata` extension
* The `content.uri` must not point to an [external tileset](../../specification#external-tilesets)
* The `content.uri` must not point to an [external tileset](../../specification/README.md#external-tilesets)
* The `content` must not have an associated `boundingVolume` property

## Subdivision Scheme
Expand Down Expand Up @@ -160,7 +160,7 @@ Implicit tiling only requires defining the subdivision scheme, refinement strate
>
> Let the extent of the root bounding volume along one dimension *d* be *(min<sub>d</sub>, max<sub>d</sub>)*. The number of bounding volumes along that dimension for a given level is *2<sup>level</sup>*. The size of each bounding volume at this level, along dimension *d*, is *size<sub>d</sub> = (max<sub>d</sub> - min<sub>d</sub>) / 2<sup>level</sup>*. The extent of the bounding volume of a child can then be computed directly as *(min<sub>d</sub> + size<sub>d</sub> * i, min<sub>d</sub> + size<sub>d</sub> * (i + 1))*, where *i* is the index of the child in dimension *d*.

The computed tile `boundingVolume` and `geometricError` can be overridden with [tile metadata](#tile-metadata), if desired. Content bounding volumes are not computed automatically but they may be provided by [content metadata](#content-metadata). Tile and content bounding volumes must maintain [spatial coherence](../../specification/#bounding-volume-spatial-coherence).
The computed tile `boundingVolume` and `geometricError` can be overridden with [tile metadata](#tile-metadata), if desired. Content bounding volumes are not computed automatically but they may be provided by [content metadata](#content-metadata). Tile and content bounding volumes must maintain [spatial coherence](../../specification/README.md#bounding-volume-spatial-coherence).

## Tile Coordinates

Expand Down Expand Up @@ -301,7 +301,7 @@ Subtrees may also store metadata for tile content. Content metadata exists only

Content bounding volumes are not computed automatically by `3DTILES_implicit_tiling` but may be provided by properties with semantics `CONTENT_BOUNDING_BOX`, `CONTENT_BOUNDING_REGION`, `CONTENT_BOUNDING_SPHERE`, `CONTENT_MINIMUM_HEIGHT`, and `CONTENT_MAXIMUM_HEIGHT`.

If the tile content is assigned a [`group`](../3DTILES_metadata#content-group-properties) — such as with the `3DTILES_metadata` extension — all contents in the implicit tree are assigned to that group.
If the tile content is assigned a [`group`](../3DTILES_metadata/README.md#content-group-properties) — such as with the `3DTILES_metadata` extension — all contents in the implicit tree are assigned to that group.

#### Subtree Metadata

Expand Down Expand Up @@ -333,7 +333,7 @@ Content availability (`contentAvailability`) is an array of content availability

Availability may be represented either as a bitstream or a constant value. `bitstream` is an integer index that identifies the buffer view containing the availability bistream. `constant` is an integer indicating whether all of the elements are available (`1`) or all are unavailable (`0`). `availableCount` is an integer indicating how many `1` bits exist in the availability bitstream.

Availability bitstreams are packed in binary using the format described in the [Booleans](../../specification/Metadata#booleans) section of the 3D Metadata Specification.
Availability bitstreams are packed in binary using the format described in the [Booleans](../../specification/Metadata/README.md#booleans) section of the 3D Metadata Specification.

> **Example:** The JSON description of a subtree where each tile is available, but not all tiles have content, and not all child subtrees are available:
>
Expand Down Expand Up @@ -393,7 +393,7 @@ Subtree metadata (`subtreeMetadata`) is encoded in JSON according to the [JSON F

Binary property values are stored in a **property table**. A property table must specify its class (`class`), which refers to a class ID in the `3DTILES_metadata` extension of root tileset JSON, a dictionary of properties (`properties`), where each key is a property ID correspond to a class property and each value is the index of the buffer view containing property values, and a count (`count`) for the number of elements in the property table. The property table may provide value arrays for only a subset of the properties of its class, but class properties marked `required: true` must not be omitted.

A property may override the [`minimum` and `maximum` values](../../specification/Metadata#minimum-and-maximum-values) and the [`offset` and `scale`](../../specification/Metadata#offset-and-scale) from the property definition in the class, to account for the actual range of values that is stored in the property table.
A property may override the [`minimum` and `maximum` values](../../specification/Metadata/README.md#minimum-and-maximum-values) and the [`offset` and `scale`](../../specification/Metadata/README.md#offset-and-scale) from the property definition in the class, to account for the actual range of values that is stored in the property table.

Array offsets (`arrayOffsets`) is required for variable-length arrays and string offsets (`stringOffsets`) is required for strings. For variable-length arrays of strings, both are required. `arrayOffsetType` describes the storage type for array offsets and `stringOffsetType` describes the storage type for string offsets. Allowed types are `UINT8`, `UINT16`, `UINT32`, and `UINT64`. The default is `UINT32`.

Expand Down
10 changes: 5 additions & 5 deletions extensions/3DTILES_metadata/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ Metadata in 3D Tiles enables additional use cases and functionality for the form

### Overview

[*Properties*](#class-property) describe attributes or characteristics of an *Entity* (tileset, tile, group, or content). [*Classes*](#class), provided by [*Schemas*](#schema), are templates defining the data types and meanings of properties. Each entity is a single instance of that class with specific values. Additionally, [*Statistics*](#statistics) may provide aggregate information about the distribution of property values within a particular class, and [*Semantics*](#semantics) may define usage and meaning of particular properties.
[*Properties*](#class-property) describe attributes or characteristics of an *Entity* (tileset, tile, group, or content). [*Classes*](#class), provided by [*Schemas*](#schema), are templates defining the data types and meanings of properties. Each entity is a single instance of that class with specific values. Additionally, [*Statistics*](#statistics) may provide aggregate information about the distribution of property values within a particular class, and [*Semantics*](../../specification/Metadata/Semantics/README.md) may define usage and meaning of particular properties.

### Schema

Expand Down Expand Up @@ -241,7 +241,7 @@ Set of categorical types, defined as `(name, value)` pairs. Enum properties use

Enums are defined as entries in the `schema.enums` dictionary, indexed by enum ID. Enum IDs must be [identifiers](../../specification/Metadata/README.md#identifiers) as defined in the 3D Metadata Specification.

> **Example:** A "quality" enum defining quality level of data within a tile. An "Unspecified" enum value is optional, but when provided as the `noData` value for a property (see: [3D Metadata → No Data Values](../../specification/Metadata#required-properties-and-no-data-values)) may be helpful to identify missing data.
> **Example:** A "quality" enum defining quality level of data within a tile. An "Unspecified" enum value is optional, but when provided as the `noData` value for a property (see: [3D Metadata → No Data Values](../../specification/Metadata/README.md#required-properties-no-data-values-and-default-values)) may be helpful to identify missing data.
>
> ```jsonc
> {
Expand Down Expand Up @@ -371,7 +371,7 @@ While [classes](#class) within a schema define the data types and meanings of pr

Each property value assigned must be defined by a class property with the same property ID, with values matching the data type of the class property. An entity may provide values for only a subset of the properties of its class, but class properties marked `required: true` must not be omitted.

Most property values are encoded as JSON within the entity. One notable exception is metadata assigned to implicit tiles and contents, stored in a more compact binary form. See [Implicit Tiling - Metadata](../3DTILES_implicit_tiling/#metadata).
Most property values are encoded as JSON within the entity. One notable exception is metadata assigned to implicit tiles and contents, stored in a more compact binary form. See [Implicit Tiling - Metadata](../3DTILES_implicit_tiling/README.md#metadata).

### Tileset Properties

Expand Down Expand Up @@ -433,7 +433,7 @@ Property values may be assigned to individual tiles, including (for example) spa

A `3DTILES_metadata` extension on a tile object must specify its class (`class`). Within a `properties` dictionary, values for properties are given, encoded as JSON types according to the [JSON Format](../../specification/Metadata/README.md#json-format) specification.

Metadata assigned to implicit tiles is stored in a more compact binary form. See [Implicit Tiling - Metadata](../3DTILES_implicit_tiling/#metadata).
Metadata assigned to implicit tiles is stored in a more compact binary form. See [Implicit Tiling - Metadata](../3DTILES_implicit_tiling/README.md#metadata).

> **Example:**
>
Expand Down Expand Up @@ -564,7 +564,7 @@ Property values may be assigned to individual tile contents, including (for exam

A `3DTILES_metadata` extension on a content object must specify its class (`class`). Within a `properties` dictionary, values for properties are given, encoded as JSON types according to the [JSON Format](../../specification/Metadata/README.md#json-format) specification.

Metadata assigned to implicit tile content is stored in a more compact binary form. See [Implicit Tiling - Metadata](../3DTILES_implicit_tiling/#metadata).
Metadata assigned to implicit tile content is stored in a more compact binary form. See [Implicit Tiling - Metadata](../3DTILES_implicit_tiling/README.md#metadata).

> **Example:**
>
Expand Down
Loading