Mesh (3D Tiles)

A mesh as one 3D Tiles tileset (a tileset.json with its tiles, or a single .3tz archive), or as OBJ exports that processing tiles into one. Everything must be in the dataset's coordinate system; nothing is reprojected.

A textured mesh (a city model, a photogrammetry scene, a scan of a station) delivered as a 3D Tiles tileset, as Cesium ion, Bentley ContextCapture, Agisoft Metashape and RealityCapture export it, or as OBJ exports, as Pix4D exports it. A tileset is shown as delivered; OBJ exports are tiled into one.

Folder layout#

Either a folder with the tileset in it:

<dataset bucket>/
└── station/                     any name, or none
    ├── tileset.json             the root of the tileset
    ├── subtrees/                implicit tiling, if your exporter writes it
    │   └── 0/0/0/0.subtree
    └── tiles/
        ├── 0/0/0/0.glb
        └── 1/0/0/0.glb

or one archive:

<dataset bucket>/
└── station.3tz                  a .3tz with tileset.json at its root

The tileset may sit at the top of the bucket or in a folder of any name and depth. Its root file must be called tileset.json; files below it, external child tilesets included, belong to it.

One tileset per dataset. Two tilesets side by side fail the delivery: deliver each as a dataset of its own.

Upload with the file manager, rclone or the aws command line. Some upload tools put a / in front of every name (a folder with no name); those files cannot be read, and the delivery fails.

The tileset#

3D Tiles 1.0 and 1.1 are both read, with an explicit tile tree, implicit tiling, or external child tilesets. Only the root tileset.json is read during indexing; the tiles are not downloaded.

The tiles must be a mesh: glTF (.glb, .gltf) or Batched 3D Model (.b3dm). Point clouds (.pnts) belong in a point cloud dataset, and instanced (.i3dm) and composite (.cmpt) tiles are not shown.

A .3tz is the tileset in one ZIP file, with tileset.json at its root. It is read in place, by ranged reads, so a large archive is fine and is quicker to upload than many small tiles. A folder and an archive of the same tileset are one tileset delivered twice: deliver one of them. A .3tz inside the tileset's folder fails the delivery.

• The delivery must be one tileset: one tileset.json (the shallowest one in the bucket; any below it belong to it) or one .3tz archive. Two tilesets side by side fail the delivery, and so does a delivery whose root file is named anything else, such as scene.json. A tileset folder is packed into one .3tz, which cannot hold another, so a .3tz inside the tileset's folder fails too. A delivery of OBJ exports passes, unless a tileset is delivered beside them: deliver one or the other.
• The root tileset.json must be a 3D Tiles tileset: JSON with an asset.version and a root tile. In a .3tz it is read from the archive's central directory, so the archive must be a ZIP with tileset.json at its root, stored or deflated. A file whose stored name begins with / (an empty folder name, which some upload tools write) is listed but cannot be read, and fails here too.
• The root tile's bounding volume must be a box or a sphere (with the root transform, if any): its outline in plan is the dataset's footprint. A region is longitude and latitude on WGS 84, which places the tileset on the globe, not in the dataset's coordinate system, and fails.
• The tileset must lie where the dataset's coordinate reference system is used. Nothing is reprojected, so the root bounding volume's footprint is compared with that CRS's registered area of use, with a 5% margin. A tileset in earth-centred coordinates (a georeferenced export) or in a local frame lies far outside it and fails. A CRS without a registered area of use is not checked.
• Every tile content the root tileset.json names must be a mesh: glTF (.gltf, .glb) or Batched 3D Model (.b3dm), or an external tileset (.json). Point clouds (.pnts), instanced models (.i3dm) and composite tiles (.cmpt) are not shown and fail. Only the root file is read: content named in external tilesets is not checked.
• Every OBJ export must hold the files its OBJs name. An export is a folder holding .obj files, loose or in a .zip (stored or deflated). Each mtllib an OBJ names must be in the export, and so must each texture (map_Kd) those MTL files name, as JPEG, PNG or TIFF. An export has at most one offset file (*_offset.xyz, three numbers: x y z). A .zip that cannot be read, or holds no .obj, fails too: a .zip in a mesh delivery is read for OBJ exports only.
• Each OBJ export must lie where the dataset's coordinate reference system is used. Its place is its offset (the *_offset.xyz, if any) plus its first OBJ's first vertex, compared with that CRS's registered area of use, with a 5% margin. Nothing is reprojected: an export in a local frame or in another CRS lies far outside and fails. A CRS without a registered area of use is not checked.

OBJ exports#

Instead of a tileset, deliver the textured mesh as OBJ, the way Pix4D and most photogrammetry software export it. Processing turns it into one tileset with coarser levels for viewing from a distance.

<dataset bucket>/
├── Enl-3d_mesh_obj.zip          an export in a .zip (files at its top or in a folder)
└── Enl_2/                       or an export as a folder
    ├── Enl_2_mesh_0.obj
    ├── Enl_2_mesh_0.mtl
    ├── Enl_2_mesh_0.jpg
    ├── …
    └── Enl_2_offset.xyz         the offset, if your software writes one

• An export is a folder holding .obj files, with the .mtl files they name and the textures those name (JPEG, PNG or TIFF), in that folder or below it. A .zip holds one export or more; its files may be stored or deflated. A .zip is only read for OBJ exports.
• Coordinates are the dataset's CRS, in metres, with z up (the third coordinate is the height). Pix4D writes them relative to an offset, in *_offset.xyz: at most one per export. Without one, the vertices are the CRS's coordinates themselves.
• Several exports become one tileset. Exports that overlap are drawn over each other, so deliver an area once.
• A tileset beside OBJ exports fails the delivery: deliver one or the other.

Coordinate reference system#

Nothing is reprojected. The tileset's coordinates, after its root transform, or an OBJ export's, after its offset, must be in the dataset's coordinate system, heights included. In Cesium ion that is a tileset that is not georeferenced; in ContextCapture and Metashape, export in the dataset's CRS (for the Netherlands, RD New with NAP heights) rather than in "ECEF" or "WGS 84".

The root tile's bounding volume must be a box or a sphere. Its outline in plan is the dataset's footprint, and it must lie where the dataset's CRS is used. A tileset in earth-centred coordinates lies thousands of kilometres away and fails. See Coordinates.

Ingest parameters#

None.

What you get back#

A tileset folder becomes one archive. Processing packs it into tileset.3tz, next to its tileset.json, reads the archive back, and then deletes the loose files: afterwards the dataset holds that one file (and any hand-over documents). Nothing is lost: a .3tz is a ZIP file of exactly the files you delivered, which any unzip tool opens. A delivered .3tz is kept as it is. Viewers read the archive directly, and an export copies it as one file.

OBJ exports become a tileset, tileset.3tz at the top of the bucket: every export in one tileset, its finest tiles at the exports' own detail and texture resolution, and coarser levels above them, simplified and with textures made anew, so the whole mesh can be seen from a distance. The OBJ files stay in the bucket: the tiles are made from them, not a copy of them.

One indexed tileset, in a set named mesh, with the footprint of its root bounding volume as the dataset's coverage.

A tileset carries no capture dates. Enter the acquisition period when you submit the delivery, or at checkup; the dataset cannot be accepted without it.

Re-running is safe — see Re-running is safe.

Common failures#