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:
| Name | Description | Sample values |
|---|---|---|
|
|
The input OBJ file or folder containing OBJ files |
|
|
|
The output folder for the processed 3DTiles |
|
The optional arguments are:
| Name | Description | Default value | Sample values |
|---|---|---|---|
|
|
The texture quality (from 0 to 1, use 1 for PNG encoding) |
0.7 |
0.7, 0.9, 1.0 |
|
|
The file containing the reference of the model ( |
none |
|
Examples
.prj file.
meshup.bat -i c:/Meshes/ -o c:/Meshes/Tileset/ -r c:/Meshes/reference.prj
meshup.bat -i c:/Meshes/mesh.obj -o c:/Meshes/Tileset/
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:
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.
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.
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.