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