A proposal for a 3D Tiles packaging format specification

[javagl]

There have been several issues that asked about an archive/package format for 3D Tiles datasets (#89, #399, #422, and some issues in related repositories).

An early proposal for a packaging format was given in a comment in one of these issues, which described a format that is based on an SQLite database that just contains a table with a key (a "file name") and a content (a blob with the data of that "file"). Over the years, this format has become a "de facto" standard for tileset packages. This includes support via the tilesetToDatabase function in the 3d-tiles-tools repository. This still carries the note that the specification for the tables in the database is not final.

The following PDF file is an attempt to specify this format in more detail, including some technical constraints and implementation notes:

3DTilesPackageSpecification-1.0.0-2022-12-08.pdf

There are many discussion threads in the linked issues, about generalizing the keys, indexing, adding metadata, or different compression options. But for now, this document is mainly intended to capture something that could reasonably be called "version 1.0.0" of the packaging format specification.

[lilleyse]

One potential change: keys should be relative filesystem paths (Unix style) instead of URIs, so no percent encoded characters. This would align with how .3dtiles files have been produced historically.

[jo-chemla]

Hi there, great to see some discussion and already existing tools to alleviate the burden on filesystems + transfers of big tilesets composed of lots of small files - transfer/copy speed, allocated size on disk, etc.

Just a quick question regarding current state of the implementation and support within the 3dtiles ecosystem of a 3dtiles packaging format. This instructive comment by you Marco on the community forum states that 3d-tiles-tools convert can be used to convert from/to 3tz (~zip), 3dtiles (~sqlite with key unix path and content blob), and standard tilesets.json + hierarchies.

• .3dtiles: A proposal for a specification of the 3DTILES format (an SQLITE-based package format) is in this github thread. The format is already used internally.
• .3tz: There is some support for 3TZ packages in the 3d-tiles-tools. For example, you can use the convert command to convert from/to 3TZ, including a conversion of the ZIP files that you downloaded with the official ‘archives and exports’ functionality into 3TZ. But a direct download of 3TZ is not yet supported.

• I've tried to look up to see whether the cesiumjs library and plugin ecosystem - cesiumjs lib, UE plugin etc - do support any of these 3dtiles/3tz packaging formats but could not find any reference to this. (PS, not easy to look for the ".3dtiles" string as it pops everywhere, but the extension is self-describing). Are you aiming for HTTP2 range-request support for any of these package files - for example based on sql.js-httpvfs for .3dtiles?
• I'm also wondering how the merge and mergeJson of a mix of 3dtiles formats would behave. If I merge a bunch of 3dtiles with a mix of 3tz and standard tileset.json, would the relative references to each individual tileset within the merged mega-tileset just be kept and working? From my point of view, probably but will have to look it up.
• Is the 3tz specification documented by this erikdahlstrom/3tz-specification repo? I assume the .3tz format is not the format the cesium team is aiming for long-term adoption as compared to .3dtiles, is this correct?

Again thanks for your great work. Best,

[javagl]

I've tried to look up to see whether the cesiumjs library and plugin ecosystem - cesiumjs lib, UE plugin etc - do support any of these 3dtiles/3tz packaging formats but could not find any reference to this. (PS, not easy to look for the ".3dtiles" string as it pops everywhere, but the extension is self-describing).

Some aspects of the support for the packaging formats are not documented extensively. And there are a few places where one could consider a broader support on the implementation level.

The .3dtiles format was proposed quite a while ago. It is already used in various places, and essentially already is a 'de facto' standard. But there has not yet been a public, official specification. Such a specification is necessary, so that people can rely on this format, and provide robust implementations. The PDF that is linked in the first comment here is an attempt to create such a specification. But there are still a few corner cases to be sorted out.

Are you aiming for HTTP2 range-request support for any of these package files - for example based on sql.js-httpvfs for .3dtiles?

This is one of the aspects that the 'broader support' refers to. There is some functionality for handling 3DTILES e.g. in the ion asset server and Cesium ion in general. But there are still ongoing efforts for improving the support, specifications, and documentation of all that.

The 3d-tiles-tools contain a basic demo of a 'PackageServer' that can serve tilesets from different sorts of packages (or the file system). But this is only a VERY basic demo. A PR for imporoving that is in https://github.com/CesiumGS/3d-tiles-tools/pull/86 (but that has als been only a 'draft' for a while now).

It's not entirely clear where HTTP2 Range Reqests could come into play here. The only case where I see an "obvious" (potential) fit is when serving something like "slices from a 3TZ file". But there are still some questions that may affect whether this is a viable approach. For example, the general topic of the compression of the entries of such a package. (Roughly: Imagine a file that stores ZSTD compressed entries, but the server wants to deliver GZIP - the server would have to unpack the ZSTD, and re-pack as GZIP, which might not be ideal...)

I'm also wondering how the merge and mergeJson of a mix of 3dtiles formats would behave. If I merge a bunch of 3dtiles with a mix of 3tz and standard tileset.json, would the relative references to each individual tileset within the merged mega-tileset just be kept and working? From my point of view, probably but will have to look it up.

Some of this is not yet extensively tested or specified. But the goal behind that 'package support' in the 3d-tiles-tools was always to "make stuff as transparent and as easy to use as possible". For the merge command, it should not matter whether the --inputs are filesystem, 3TZ, or 3DTILEs (or a mix of that), or what type the --output is: It should 'just work'.

From a quick test, merging filesystem+3DTILES into 3TZ seemed to work, but further consistency checks and validation may be necessary. And there's also the open question about entry compression, at https://github.com/CesiumGS/3d-tiles-tools/issues/56 ...

Is the 3tz specification documented by this erikdahlstrom/3tz-specification repo? I assume the .3tz format is not the format the cesium team is aiming for long-term adoption as compared to .3dtiles, is this correct?

This is the underlying specification for 3TZ, yes. The 3D Tiles Tools do offer some support for 3TZ, based on some code from the creators of 3TZ. And to oversimplify it a bit: 3TZ is just a "ZIP with an index for random-access" (which might be in line with the goal of delivering that data via a server, maybe with range requests...). Beyond that, I cannot say much about the degree of adoption of this format within Cesium. I can say that the 3DTILES format is used in various places, and support for 3TZ is on the radar, but without specific plans or even a timeline.