Specify the JSON structure

[javagl]

The quantized mesh representation relies on a layer.json file that is mentioned in the README, but there is virtually no information about what this file actually is.

There was a thread in the forum which contained an example and a very basic description of the contents. (Some further internal discussion revolved around the role of availability, but that seems to be a broader topic). Essentially, people seem to reverse engineer the CesiumTerrainProvider.js to find out what this JSON may contain. Doing a websearch for "layer.json" cesium makes clear that people are struggling with this file in many ways. From what I've found until now, the layer.json seems to be a subset of the tilejson format, but it's not clear which parts of this are actually supported.

In any case: If it is a tilejson file, then this should be mentioned in the README - in doubt, with a tilejson version number, or details about which parts of tilejson are actually understood by the CesiumTerrainProvider.

[gkjohnson]

I'm currently implementing a QuantizedMesh loader for 3DTilesRendereJS in three.js and was curious about the definition of layer.json myself. I've taken a look through the CesiumTerrainProvider and collected the fields returned by Cesium Ion here, and added some notes on what each field seems to do. There are still some that are not obvious, though, and could do with some documentation and clarification by someone from the Cesium team:

Layer.json definition

// Version of the file format.
// required
version: "1.2.0",

// List of ranges of available tiles per layer. The length of the "available" array defines the number of
// tile layers in the data set. Each range defined in the layer arrays defines the set of tiles that are available
// to be loaded, inclusive.
// The "metadataAvailability" field should be preferred if both fields are present.
available: [ [ { endX: 3, endY: 1, startX: 0, startY: 0 } ], ... ],

// Set of available extensions.
// defaults to []
extensions: [ 'watermask', 'metadata', 'octvertexnormals' ],

// The format of the data set
// required
format: "quantized-mesh-1.0",

// Attribution for the data in the tiles.
// Defaults to "".
attribution: "",

// Projection of the data set, used to infer tile layout in addition to projection.
// Defaults to "EPSG:4326"?
projection: "EPSG:4326",

// Tiling scheme used to determine if 
// Defaults to "tms"?
scheme: "tms",

// The tiles url (can be multiple url templates?)
// required
tiles: ['{z}/{x}/{y}.terrain?v={version}'],

// If this field is present then "availability" is guaranteed to be available in the meta data of each tile at
// the "n*metadataAvailability" layer where "n" starts at 0 counting upwards.
metadataAvailability: 10,

// The maximum number of levels available in the data set if child tile availability to traversed completely.
maxzoom: 19,

// The minimum number of levels available in the data set, thought it's unclear what the behavior should
// be when minzoom is > 0 since availability is always expected on layer 0 tiles.
minzoom: 0,

// The latitude and longitude bounds of the data set.
// This field seems to _not_ be used in CesiumTileProvider.
bounds: [-180, -90, 180, 90 ],

// Description of the tile set.
// This field seems to _not_ be used in CesiumTileProvider.
description: "",

// The name of the data set.
// This field seems to _not_ be used in CesiumTileProvider.
name: "",

Here are some questions I have:

• The fields "bounds", "description", and "name" seem to not be used by CesiumTerrainProvider. Can these fields be ignored? Meaning that "bounds" should be assumed to be -180, -90, 180, 90 in all cases?
• Can "tiles" be an array of multiple url templates? If that was the original intention is it ever actually done in practice?
• Can you explain "maxzoom", "minzoom", and "metadataAvailability"? It seems to be a replacement for the "availability" array but it's not immediately obvious how to interpret it and the Cesium Ion asset Id "1" (the base QMesh terrain layer) seems to define an "available" array and minzoom / maxzoom etc. And they don't seem to agree with eachother given my naive interpretation. Should these fields be ignored?
• Are the rest of my descriptions above correct?

cc @ggetz @lilleyse sorry to ping - I think you guys are the right ones to clarify some of these things?

[lilleyse]

I'm not a quantized-mesh expert, but I think your descriptions are correct.

LayerJsonTerrainProvider.cpp is another good place to look to see how layer.json and quantized-mesh tiles are parsed.

• "bounds" seem to be ignored LayerJsonTerrainLoader.cpp#L475-L477
• Only the first element of "tiles" is used LayerJsonTerrainLoader.cpp#L676
• maxzoom is the last level with content
• minzoom is the first level with content
• metadataAvailability of 10 means all tiles at level 0, level 10, level 20, etc have the metadata extension
• available is the predecessor to metadataAvailability before availability was partitioned into subtrees. Cesium World Terrain sets it for backwards compatibility reasons, but I think it can be ignored.

[gkjohnson]

Thanks Sean!

"bounds" seem to be ignored LayerJsonTerrainLoader.cpp#L475-L477

My assumption, then, is that this bounds represents the extents of the area covered by the "available" tiles but isn't necessarily used or required for calculating tile positions or downloads.

available is the predecessor to metadataAvailability before availability was partitioned into subtrees. Cesium World Terrain sets it for backwards compatibility reasons, but I think it can be ignored.

Thanks - this is good to know. So basically if "metadataAvailability" then "availability" can be ignored if present. Any idea, then, why the data in "availability" does not match what's specified for "maxzoom"? Here are some of the key fields from the Cesium Ion terrain (asset id 1):

available: (16) [Array(1), Array(1), Array(1), Array(1), Array(1), Array(6), Array(6), Array(6), Array(6), Array(307), Array(307), Array(308), Array(1716), Array(1604), Array(1172), Array(10943)],

// ...

maxzoom: 19,
metadataAvailability: 10,
minzoom: 0,

Notice specifically that "available" is length 16 and "maxzoom" is set to 19. Is it that case that "available" is truncated for the sake of the layer.json file size and not representative of the actual full data set?

metadataAvailability of 10 means all tiles at level 0, level 10, level 20, etc have the availability extension

If minZoom is set to a non-zero value then how are you supposed to get the initial tile availability assuming the tiles at level 0 are supposed to contain the availability array in the content metadata?

---

And a last clarifying question - are there any guarantees about child tile availability if a parent tile is available? Ie it seems possible that even if a parent tile is available that only 2 or the 4 child tiles could be present, which would result in gaps in the data set when refining the data. Is this correct?

[lilleyse]

My assumption, then, is that this bounds represents the extents of the area covered by the "available" tiles but isn't necessarily used or required for calculating tile positions or downloads.

I believe -180, -90, 180, 90 is assumed.

Thanks - this is good to know. So basically if "metadataAvailability" then "availability" can be ignored if present. Any idea, then, why the data in "availability" does not match what's specified for "maxzoom"? Here are some of the key fields from the Cesium Ion terrain (asset id 1):

Yes, if "metadataAvailability" exists then "availability" can be ignored.

Notice specifically that "available" is length 16 and "maxzoom" is set to 19. Is it that case that "available" is truncated for the sake of the layer.json file size and not representative of the actual full data set?

I believe that's correct.

If minZoom is set to a non-zero value then how are you supposed to get the initial tile availability assuming the tiles at level 0 are supposed to contain the availability array in the content metadata?

That's a good question... I'm not sure. Maybe it has never come up in practice.

And a last clarifying question - are there any guarantees about child tile availability if a parent tile is available? Ie it seems possible that even if a parent tile is available that only 2 or the 4 child tiles could be present, which would result in gaps in the data set when refining the data. Is this correct?

Yes this can happen, but the cesium runtimes will clip the parent tile and create child tiles for unavailable sections to avoid refining to empty tiles. This is different behavior than 3D Tiles implicit tiling, which does not expect any sort of clipping / child tile generation to occur.

[gkjohnson]

Yes this can happen, but the cesium runtimes will clip the parent tile and create child tiles for unavailable sections to avoid refining to empty tiles.

Interesting - I was wondering about this. Do you have a brief overview of how this is performed? Is a the parent Quantized Mesh file reparsed with the new child bounds in mind? Or is full geometry clipping being performed (eg split the geometry along two planes to get the four children) with some logic for creating skirts? Is the "cap" geometry split first and then skirts generated from scratch separately for the new geometry?

Apologies if this is obvious from the Cesium source - it wasn't clear to me where exactly this is happening for qmesh. It looks like there are quite few places where triangle splitting may occur.

Thanks again for the insight!

[lilleyse]

Is the "cap" geometry split first and then skirts generated from scratch separately for the new geometry?

I believe this. The parent geometry (minus skirts) is clipped into four children, and skirts are generated for each child.

That's what I'm seeing in upsampleQuantizedTerrainMesh.js

[javagl]

People can correct me if I'm wrong, but I think that this is happening in QuantizedMeshTerrainData.upsample, where this upsamplePromise essentially executes upsampleQuantizedTerrainMesh. (Now... is that "obvious"? Let's argue about that 🙂 )

And... people can add details if I'm right. Looking at the comments, the whole process consists of these 4 steps:

Clip triangle on the east-west boundary.
Get the first clipped triangle, if any.
Clip the triangle against the North-south boundary.
If there's another vertex in the original clipped result, it forms a second triangle. Clip it as well.

But more seriously: An overview of what's happening there could be nice. It's not clear what could be the right level of abstraction for such an overview. The "core" of what is happening there could probably be described as "split a geometry at two planes" (which could probably be written with 2 lines of code in some engines). But where things like 'skirts' come into play is not so obvious.

_{EDIT: That was a race condition...}

[gkjohnson]

Thanks for the links! This is all helpful. I think the clipping concept sounds fairly straightforward. And any additional skirts can be derived from the triangle edges that get clipped in the original cap. As I understand it the Cesium Native implementation also splits geometry to allow for higher TMS texture detail to be overlaid, though presumably without skirt generation for generic 3d tiles data sets.

I've also updated my notional "layer.json" definition in the above comment with the definitions for minzoom, maxzoom, and metadataAvailability that have been discussed. If you'd like I can add the above json structure definition to the README in a new Layer Manifest section so it's more clear.

[javagl]

(@lilleyse Once this is reasonably well specified, we/I can create a JSON schema from that)

[lilleyse]

As I understand it the Cesium Native implementation also splits geometry to allow for higher TMS texture detail to be overlaid, though presumably without skirt generation for generic 3d tiles data sets.

Yes, that's correct.

[lilleyse]

I realized there's already a JSON schema for layer.json in Cesium Native:

https://github.com/CesiumGS/cesium-native/blob/main/CesiumQuantizedMeshTerrain/schema/layer.schema.json

We should be able to copy it here and update the code generator to point to a github url. From a quick read, seems to match everything we talked about here.

[gkjohnson]

I realized there's already a JSON schema for layer.json in Cesium Native:

https://github.com/CesiumGS/cesium-native/blob/main/CesiumQuantizedMeshTerrain/schema/layer.schema.json
...
From a quick read, seems to match everything we talked about here.

That's a good resource to know about - one difference may be the description of "available" which seems to imply that it can exist along side and be used with metadata availability as opposed to being used mutually exclusively:

"The tile availability information. The outer array is indexed by tile level. The inner array is a list of rectangles of availability at that level. Tiles themselves may also contain further availability information for their subtree."

And a couple other points:

• Neither the JS nor native Cesium implementations seem to reference "minzoom" so I'm wondering if either the description is wrong or it should be removed from the spec?
• "parentUrl" is new to me from the schema but it's clear to me how to use it.

[javagl]

@kring Was that layer JSON schema from CesiumGS/cesium-native@5ba8b7a#diff-31d3a53d2a137ff7bf6f99804550221f9f9d53754a974fb2e00cfed38b49e8fe dedicatedly created for this commit, or was this taken from another source? (I'm wondering about what could be a "single source of truth" here)

[kring]

Neither the JS nor native Cesium implementations seem to reference "minzoom" so I'm wondering if either the description is wrong or it should be removed from the spec?

As you observed, layer.json is meant to follow tilejson. Or at least that was what I intended a decade ago when all this was created. tilejson has a minzoom, and so layer.json has it as well. But our tilesets never set it to anything other than zero, and our clients wouldn't have known what to do if someone ever did. So yeah, removing it from the spec would be reasonable.

Was that layer JSON schema from CesiumGS/cesium-native@5ba8b7a#diff-31d3a53d2a137ff7bf6f99804550221f9f9d53754a974fb2e00cfed38b49e8fe dedicatedly created for this commit, or was this taken from another source? (I'm wondering about what could be a "single source of truth" here)

I wrote that JSON Schema for that commit. It's the best source of truth we have for layer.json AFAIK, other than the CesiumJS code.