Play
Figure 1. Multileveling

The information in this guide is only available if you purchased the Infrastructure Standards component.

What does the 3D Tiles Processing Engine do?

The 3D Tiles Processing Engine is an engine that allows you to tile and multi-level datasets of meshes into a 3D Tiles tileset optimized for streaming.

It includes:

  • A command line sample that supports OBJ or GLB input files, and allows you to georeference input data through .prj or .ref files.

  • An API that is more flexible than the command line engine. It allows you to plug in custom mesh formats and reference factories.

This user guide provides basic pointers to get you started with the command line and the API.

Requirements

System requirements

See the class Javadoc of the TLcd3DTilesProcessorBuilder class for details on Java heap settings and disk caching.

Orientation of the input data

The 3D Tiles Processing Engine expects y-up-oriented meshes as input data.

Input data georeference

By default, the 3D Tiles Processing Engine looks for a file containing georeference information. That file can be an .epsg file containing an EPSG code, a .prj file containing WKT text, or a .ref file, saved by Lucy for example).

You can also set the georeference through the API.

If no georeference is available, the 3D Tiles Processing Engine processes the dataset without a reference.

See TLcd3DTilesProcessorBuilder for more information.

Running the 3D Tiles Processing Engine from the command line

To use the 3D Tiles Processing Engine from the command line, call the meshup script in the samples folder of the release: meshup.bat (Windows) or meshup.sh (Linux/Mac).

The Processing Engine Help documentation will be printed in the console as a result.

By default, the command line sample runs with a maximum heap size of 4GB. You can override the maximum heap size in the configuration file config/vmoptions/samples.meshup.vmoptions.

Command line arguments

The required arguments are the input files and the output folder:

Table 1. Required arguments
Name Description Sample values

-i or --input

The input file or folder containing OBJ or GLB files

C:/city3D/OBJS/, C:/city3D/mesh.obj

-o or --output

The output folder for the processed 3DTiles

C:/city3D/3DTiles/

The optional arguments are:

Table 2. Optional arguments
Name Description Default value Sample values

-R or --recursive

If -i points to a folder, scan it for input files recursively

false

true

-q or --textureQuality

The texture quality (from 0 to 1, use 1 for PNG encoding)

0.7

0.7, 0.9, 1.0

-r or --reference

The file containing the reference of the model (.epsg, .prj or .ref)

none

C:/reference.prj

-f or --forcePNG

If this parameter is set to true, the texture are always encoded to PNG. Enable this if you need transparency support.

false

true

-v or --maxVertices

The maximum number of vertices in a single tile. Default is 15000. Increase this number to end up with a less deep tree, but bigger tiles.

15000

5000, 15000, 30000

-t or --maxTextureSize

The maximum texture size to use per tile. Default is 1024, which indicates a texture of 1024x1024. Increase this value to reduce tile depth.

1024

512, 1024, 4048

-d or --dropSmallParts

Drop small complex parts before simplifying tiles. This increases computational cost, but can simplification increase quality for highly unbalanced meshes.

false

true

-b or --preserveBorders

preserve borders. Disabled by default. This parameter will improve border simplification at a computational cost. Use this when you see holes in the resulting 3DTiles or when meshes are badly distorted near their borders, e.g: the base of a building.

false

true

-s or --strategy

The simplification strategy to use.

QUADRIC_EDGE_COLLAPSE

QUADRIC_EDGE_COLLAPSE, CLUSTERING, DROP_SMALL_PARTS

-c or --forceColor

Convert textures in output mesh to a single averaged color. This option can be used to discard textures from an output mesh. Instead individual textures will be converted to an average color.

false

true

-m or --meshCompression

The mesh compression algorithm to use.

DRACO

NONE

Examples

Use case : The dataset consists of a folder of OBJs referenced according to a .prj file. 
meshup.bat -i c:/Meshes/ -o c:/Meshes/Tileset/ -r c:/Meshes/reference.prj
Use case : The dataset consists of a single OBJ and the file is not referenced
meshup.bat -i c:/Meshes/mesh.obj -o c:/Meshes/Tileset/
Use case : The meshes have both textured faces and colored faces.

PNG texture encoding is required to avoid visual artifacts

meshup.bat -i c:/Meshes/mesh.obj -o c:/Meshes/Tileset/ -q 1.0

Adding a shift to your data

The process will pick up any .xyz file with the same name as an input mesh. If the .xyz file’s first line is a 3D point, it will apply it as a global shift on the corresponding mesh and in the same reference that the mesh is defined in. For more information, see Setting a global shift for the mesh data.

Using the API

Creating OGC 3D Tiles tilesets from mesh data

You access the API through TLcd3DTilesProcessorBuilder.

The parameters are set to default values that fit most situations.You only need to specify the source folder and file, or the source ILcdModel, and an output folder. 

  return TLcd3DTilesProcessorBuilder.newBuilder()
                                    .addInputFiles("path/to/input/folder/mesh.obj")
                                    .outputPath("path/to/output/folder/")
                                    .process()
                                    .get();
  return TLcd3DTilesProcessorBuilder.newBuilder()
                                    .addInputFiles("path/to/input/folder/mesh1.obj")
                                    .addInputFiles("path/to/input/folder/mesh2.obj")
                                    .outputPath("path/to/output/folder/")
                                    .process()
                                    .get();

Adding a geo-reference

On the builder, you can specify a specific ILcdModelReference or a factory that returns a specific reference given the mesh file name: 

  return TLcd3DTilesProcessorBuilder.newBuilder()
                                    .addInputFiles("path/to/input/folder/mesh1.obj")
                                    .outputPath("path/to/output/folder/")
                                    .defaultModelReference(new TLcdGeodeticReference())
                                    .process()
                                    .get();
  return TLcd3DTilesProcessorBuilder.newBuilder()
                                    .addInputFiles("path/to/input/folder/mesh1.obj")
                                    .outputPath("path/to/output/folder/")
                                    .modelReferenceDecoder(new ILcdModelReferenceDecoder() {
                                      @Override
                                      public ILcdModelReference decodeModelReference(String aModelReference) throws IOException {
                                        return new TLcdGeodeticReference();
                                      }
                                    })
                                    .process()
                                    .get();

If no geo-reference is specified, the 3D Tiles Processing Engine looks for a file containing the reference. That file must have a .epgs, .prj or .ref extension, and the same file name as the mesh, or the name directory.

See TLcd3DTilesProcessorBuilder for more information.

Setting a global shift for the mesh data

It is possible to pass a global shift for the entire dataset or per mesh file. The global shift is applied in the reference of the file itself.

On the builder, either specify a single global shift or a factory that takes a file path as argument.

  TLcd3DTilesProcessorBuilder.newBuilder()
                             .addInputFiles("path/to/input/folder/mesh1.obj")
                             .outputPath("path/to/output/folder/")
                             .globalShift(new TLcdXYZPoint(0, 100, 25))
                             .process()
                             .get();

If these methods are not called, or if the resulting global shift is null, the 3D Tiles Processing Engine tries to retrieve the global shift from the first line of an .xyz file with the same name as the mesh file. For example, the global shift for a mesh.obj file would be in a mesh.xyz file.

The .xyz file should have a single line formatted as <x value> <y value> <z value>, for example:

sample.xyz
0 0 -10

Force PNG encoding

If meshes contain translucent textures, encoding them as JPEG causes the alpha values to be lost. In this case, you can set the forcePNGEncoding parameter to true to make sure the transparency information is preserved in the processed output.

Note that PNG encoding increases the file size of the tiles, so enable it only when strictly necessary.

Setting texture quality

The texture quality value for JPEG encoding is 0.7f by default.You can set it yourself to values between 0.0f and 1.0f through the textureQuality option.

Setting this option to a low value reduces the size of the individual output tiles, and results in typical JPEG encoding artifacts.See the comparison in Figure 2, “Texture Quality setting”, for example.For most cases, we recommend that you keep the default texture quality value.

Play
Figure 2. Texture Quality setting

Selecting the Texture-To-Color option

If you set the textureToColor option to true, the 3D Tiles Processing Engine converts each texture to its average color. This can be useful when textures are low quality, because it tends to give a CAD-like appearance to the models. The resulting tileset will also be lighter, and processing will be significantly faster.

Play
Figure 3. Texture to Color

This option is intended for models that consist of many small textures. If the model has a single, large texture atlas, the result is a model with a single color.

File formats and material properties

The 3D Tiles Processing Engine currently supports two input formats: Wavefront OBJ and GLB (the binary variant of glTF). The output format is always OGC 3D Tiles, which actually uses GLB internally to represent the tile payloads. This has some implications for the way material properties are processed.

The OBJ format stores material properties in external .mtl files, and models materials using conventional ambient, diffuse and specular/shininess parameters.

glTF, on the other hand, allows for materials with a richer set of PBR (Physically-Based Rendering) properties. A material in a glTF/GLB file can not only contain a base color map, but also "metallic" and "roughness" properties (which allow greater control over the perceived "shininess" of a surface), normal maps and ambient occlusion maps.

If the 3D Tiles Processing Engine is used to process OBJ files, only the diffuse color is considered for the 3D Tiles output. If you use GLB files as input, however, then the PBR properties of the source data will be fully carried over into the output. This allows clients to perform much more realistic rendering of the tiled output data.