Play
Figure 1. Multileveling

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 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 geo-reference information. That file can be a .epgs file (containing an EPSG code), a .prj files (containing WKT text) or a .ref file (saved by Lucy for example).

You can also set the geo-reference through the API.

If there no geo-reference is found, 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 2GB on a 32bit system and 4GB on a 64-bit system. You can override the maximum heap size in the respective configuration files :

config/samples/meshup/Meshup.vmoptions and config/samples/meshup/Meshup64.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 OBJ file or folder containing OBJ 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

-q or --quality

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

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 OBJ. 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

Colored faces, as opposed to textured faces, have a single color instead of a texture. The 3D Tiles Processing Engine generates tiles in which all colors and textures are merged into a single texture atlas.

If meshes contain both colored and textured faces, you can set the forcePNGEncoding parameter to true to prevent color encoding artifacts. This setting also increases the weight of the tiles, so use this only if you see significant artifacts.

For meshes that have only color and no texture, PNG encoding is used automatically.

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.