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:
Name | Description | Sample values |
---|---|---|
|
The input file or folder containing OBJ or GLB files |
|
|
The output folder for the processed 3DTiles |
|
The optional arguments are:
Name | Description | Default value | Sample values |
---|---|---|---|
|
If |
false |
true |
|
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 |
|
|
If this parameter is set to true, the texture are always encoded to PNG. Enable this if you need transparency support. |
false |
true |
|
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 |
|
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 |
|
Drop small complex parts before simplifying tiles. This increases computational cost, but can simplification increase quality for highly unbalanced meshes. |
false |
true |
|
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 |
|
The simplification strategy to use. |
QUADRIC_EDGE_COLLAPSE |
QUADRIC_EDGE_COLLAPSE, CLUSTERING, DROP_SMALL_PARTS |
|
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 |
|
The mesh compression algorithm to use. |
DRACO |
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 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:
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.
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.
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.