Tile Converter

The tile-converter is a command line utility (CLI) for two-way batch conversion between I3S and 3D Tiles, both are OGC community standards. It can load tilesets to be converted directly from a URL or file based formats. I3S and 3DTiles are large formats that include different layer types and data formats. See Supported Features page which describes what tile-converter supports.

Installation

The tile-converter is published as an npm module and as a docker image.

Installing @loaders.gl/tile-converter from npm makes the tile-converter command line tool available.

npm i @loaders.gl/tile-converter

Usage

Tile Converter can be run using npx.

Aknowledge available options:

npx tile-converter --help

Install dependencies:

npx tile-converter --install-dependencies

Run conversion:

npx tile-converter --input-type \<I3S\|3DTILES\> --tileset \<tileset\> --name <tileset name> [--output <output folder>] [--no-draco] [--max-depth 4] [--slpk] [--7zExe <path/to/7z.exe>] [--token <ION token>] [--egm <pat/to/*.pgm|none>] [--split-nodes] [--instant-node-writing] [--generate-textures] [--generate-bounding-volumes]

Alternatively, you can use syntax with the equal sign:

npx tile-converter --input-type=\<I3S\|3DTILES\> --tileset=<tileset> --splk=true|false ...

Alternatively, there is a docker image to run:

docker pull visgl/tile-converter

See more details here

Supported Platforms

For tile-converter v4.0 and up:

Operationg Systems: Windows 8.1 or higher, Ubuntu 20.04 or higher

NodeJS 18 or higher is required.

Options

Option	3DTiles to I3S conversion	I3S to 3DTiles conversion	Description
help	*	*	Show the converter tool options list
install-dependencies			Run the script for installing dependencies. Run this options separate from others. It installs "*.pgm" Earth Gravity Model, loader workers, sharp and join-images npm packages
input-type	*	*	"I3S" - for I3S to 3DTiles conversion, "3DTILES" for 3DTiles to I3S conversion
tileset	*	*	"tileset.json" file (3DTiles) / "http://..../SceneServer/layers/0" resource (I3S)
output	*	*	Output folder. This folder will be created by converter if doesn't exist. It is relative to the converter path. Default: "./data" folder
name	*	*	Tileset name. This option is required for naming in the output json resouces and for the output path/\*.slpk file naming
output-version		*	Version of 3D Tiles format. This option is used for I3S to 3DTiles conversion only (optional). Possible values - "1.0", "1.1" (default). More information on the 3D Tiles revisions: https://github.com/CesiumGS/3d-tiles/blob/main/3d-tiles-reference-card-1.1.pdf
max-depth	*	*	Maximal depth of the hierarchical tiles tree traversal, default: infinity
slpk	*		(Deprecated since version 4.3.0) Whether the converter generates *.slpk (Scene Layer Package) I3S output files. Note: For versions 4.3.0 and up *.slpk is the default output without this option specified.
7zExe	*		(Removed since version 4.1.0) location of 7z.exe archiver to create slpk on Windows OS, default: "C:\Program Files\7-Zip\7z.exe". Note: For versions 4.1.0 and up tile-converter uses internal zip module instead.
egm	*	*	location of the Earth Gravity Model (*.pgm) file to convert heights from ellipsoidal to gravity-related format or "None" to not use it, default: "./deps/egm2008-5.pgm". A model file can be loaded from GeographicLib https://geographiclib.sourceforge.io/html/geoid.html
token	*		Token for Cesium ION tileset authentication.
no-draco	*		Disable draco compression for geometry. Default: not set
instant-node-writing	*		Whether the converter should keep JSON resources (3DNodeIndexDocuments and nodePages) on disk during conversion. The default behavior is the converter keeps JSON resources in memory till the end of conversion. Those resources need to be updated during conversion (adding child nodes and neighbor nodes). If this option is set true the converter will keep JSON resources on disk all the time. Use this option for large datasets when the nodes tree is large and "memory overflow" error occurs. Instant node writing saves memory usage at the cost of conversion speed (>2 times slower).
split-nodes	*		The converter will generate a new node for every PBR material in the glTF file. Prevent merge of similar materials that could lead to incorrect visualization. By default, the converter tries to merge PBR materials to create one node for all primitives in a glTF file. Note: can cause refinement issues because "leaf" nodes are generated in the middle of the nodes tree
generate-textures	*		Create compressed KTX2 textures if non-compressed (JPG, PNG) texture is present in the input tileset or generate JPG texture if compressed KTX2 is presented in the input tileset
generate-bounding-volumes	*		Create new OBB and MBS bounding volumes from geometry instead of converting from the source tile bounding volume
metadata-class	*		Set metadata class related to EXT_feature_metadata or EXT_structural_meatadata extensions. See details below
analyze	*	*	Analyze the input tileset content without conversion
quiet	*	*	Skip user prompts during conversion. Tile-converter won't stop to wait for an action from a user. See details below
validate	*		Perform counting of all tiles. Check whether a particular child node fits into the parent one or not. If not, warn about it.
add-hash			Adds a hash file to an .slpk without hash. Provide the slpk name in the --tileset option and updated SLPK path to the --output (optional)

Metadata class selection

This topic is applicable only for source type "3DTILES".

An input glTF resource may contain EXT_feature_metadata or EXT_structural_metadata extensions.

Those extensions provide the structural metadata storage. Metadata - represented as entities and properties - may be closely associated with parts of 3D content, with data representations appropriate for large, distributed datasets. For the most detailed use cases, properties allow vertex- and texel-level associations; higher-level property associations are also supported.

One glTF resource might include more than one metadata class. That means that parts of a mesh might be associated with different sets of properties. For example, a glTF might have bridges and buildings classes. In that case, one part of the mesh is related to bridges properties (eg. construction_year, type) and another part of the mesh is related to buildings properties (eg. construction_year, height, number_of_floors, ownership).

As output (when converting from 3D Tiles to I3S) there is an I3S layer which doesn't support structural metadata and multiple classes by its specification (v1.8). I3S has feature attributes metadata that is the same for every node in the layer. As a result, I3S can consume only one set of properties.

In case when the input 3DTiles dataset has multiple metadata classes, the tile-converter provides a promt to select one class from the list:

If the wanted class is known before the conversion it is possible to skip the prompt with setting metadata-class option. For example:

npx tile-converter --input-type 3DTILES --tileset ..... --metadata-class bridges

Quiet mode

Use --quiet option to avoid user prompts during conversion. In some cases, tile-converter stops and waits for an input from a user, for example, it can ask whether to resume conversion or start a new conversion.

npx tile-converter ..... --quiet

With --quiet option present, tile-converter will not ask a user to make a decision, it will do a default action instead.

Using --add-hash and --quiet together

With --add-hash option tile-converter by default offers to create a new file with hash or modify the existing SLPK. When --quiet option is added, the existing SLPK will be modified.

Resume conversion with --quiet option

Resume conversion is a feature that allows to resume a conversion that was unpredictably stopped, for example when a terminal was closed or a user pressed CTRL+C. By default, when tile-converter detects a previous conversion, it offers to resume it or start a new one. When --quiet option is added, tile-converter will resume. To start a new conversion with --quiet option, remove output folder that was created by tile-converter before.

Metadata class selection with --quiet option

This topic is applicable only for source type "3DTILES".

This case is applicable for the specific type of datasets. See Metadata class selection. When --quiet option is present and multiple metadata classes have been detected, tile-converter will stop. To convert such a dataset with --quiet option, use --metadata-class option to select a metadata class.

Running local server to handle I3S layer

After conversion without --slpk option a new I3S layer is created in output ("data" by default) directory.

Run it with the local web server:

PORT=8080 HTTPS_PORT=4443 I3sLayerPath="./data" DEBUG=i3s-server:* npx i3s-server

See more details here

Show converted layer on a map

open https://loaders.gl/examples/i3s?url=http://localhost:8080/NewLayerName/SceneServer/layers/0

Docker image

The tile converter is available as a docker image in the visgl/tile-converter dockerhub repo. The advantage of docker image is that it has dependencies pre-installed so it is not necessary to call npx tile-converter --install-dependencies.

To download the tile-converter docker image, run:

docker pull visgl/tile-converter

To use converter run:

docker run \
  --rm  \
  -v /path/to/output_folder:/loaders-bundle/data \
  -v /path/to/input-tileset:/loaders-bundle/input-data \
  visgl/tile-converter \
  --input-type 3dtiles \
  --token ... \
  --tileset input-data/tileset.json \
  --name ... \
  --output data \
  --max-depth 3 \
  ...

Docker run arguments:

-v - Create docker volume, linked to internal data folder

--rm - Remove container after conversion

visgl/tile-converter - Image name

To build your own tile-converter docker image:

• Clone loaders.gl project.
• In root folder of the project run:

  yarn bootstrap
  docker build -t [docker_image_name] -f modules/tile-converter/Dockerfile .

• Push docker image to your docker hub