Class TLcd3DTilesProcessorBuilder
Introduction
3D mesh datasets often come as a collection of individual meshes. For example a dataset representing a city could consist out of individual mesh files for each building in the city. In order to visualize such a dataset in a performant way, it is necessary to- Introduce level-of-detail: when zoomed out, the details of every individual building cannot be distinguished so it makes no sense to load all those details.
- Introduce tiling: the view must only load the data that is visible in the current view bounds.
Running the processor
To run the processor, youcreate a builder
, add one or more input files
and an output path
and
start to process
. This returns a Future
.
return TLcd3DTilesProcessorBuilder.newBuilder() .addInputFiles("path/to/input/folder/mesh.obj") .outputPath("path/to/output/folder/") .process() .get();
Model reference
The model reference is obtained from anILcdModelReferenceDecoder
. The default reference decoder set on this
builder is based on all model reference decoders annotated with the LcdService
annotation, and can handle:
- EPSG references (
<filename>.epsg
): seeTLcdEPSGModelReferenceDecoder
for more info. - WKT references (
<filename>.prj
): seeTLcdWKTModelReferenceDecoder
for more info. - Luciad encoded model references (
<filename>.ref
): seeTLcdModelReferenceDecoder
for more info.
Orientation of the input data
The 3D Tiles Processing Engine expects y-up-oriented meshes as input data.
System requirements
Given sufficient time and hard drive space, the 3D Tiles Processing Engine can process mesh datasets of any size.
It is advised to allocate a sufficiently large amount of memory to the heap for caching purposes.
Although the cache will automatically adapt to
the memory available, the process can slow down significantly if the cache is too small.
You can use the -Xmx
argument to set a maximum heap size of 8 gigabytes. That should be enough to handle most datasets.
You also need to consider the required hard drive space.
During the mesh conversion process, temporary files may be stored on the hard drive in a folder named cache
. You can find it at
the location from which you are running the process. The hard drive cache may grow to up to twice the size of the
original dataset.
On top of that, you need to make sure that the hard drive has enough space available for the processed tileset. When it is ready for streaming, the processed dataset may have up to three times the original size in some cases.
Supported input formats
The 3D Tiles Processing Engine currently supports the following input formats:- Wavefront OBJ
- GLB (the binary variant of glTF)
Limitations
GLB files with metallic/roughness maps are supported, but the engine expects the mesh to have only one set of texture coordinates (i.e. the metallic/roughness map must be addressed using the same texture coordinates as the base color map). Also, GLB files with a hierarchical node structure are not supported.- Since:
- 2020.0
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Default value of the texture size.static final int
Default value for the vertex count. -
Method Summary
Modifier and TypeMethodDescriptionaddInputFiles
(String... aMeshPath) Adds paths pointing to a single file in a supported mesh format.defaultModelReference
(ILcdModelReference aModelReference) Set a unique reference to be used for all the meshes.dropSmallComplexParts
(boolean aDropSmallComplexParts) Drop parts of the mesh that are relatively small and complex before simplification.forcePNGEncoding
(boolean aForcePNGEncoding) Forcespng
encoding for textures.globalShift
(ILcdPoint aGlobalShift) Set a global shift to be used for every mesh.globalShiftFactory
(Function<String, ILcdPoint> aGlobalShiftFactory) Set a global shift factory that returns apoint
for a given file.meshCompression
(ELcdOGC3DTilesMeshCompressionType aMeshCompressionType) Sets the mesh compression algorithm to use in the OGC 3D Tiles encoding.metadataMapper
(ILcd3DTilesProcessorMetadataMapper aMetadataMapper) Adds a metadata provider to this builder.modelReferenceDecoder
(ILcdModelReferenceDecoder aModelReferenceDecoder) Set a model reference decoder that returns a reference for a given filepath.static TLcd3DTilesProcessorBuilder
Creates a new builder for the 3DTiles processor.outputPath
(String aOutputPath) Set the folder that the output OGC 3D Tiles tileset is written to.preserveBorders
(boolean aPreserveBorders) The border of a mesh consists of edges that only connect to a single face.process()
Starts the OGC 3D Tiles processing.simplificationStrategy
(ELcdSimplificationStrategy aSimplificationStrategy) Specifies the simplification algorithm to use.statusListener
(ILcdStatusListener aStatusListener) Set the status listener to be notified of the task's progress.textureQuality
(float aTextureQuality) Set thejpeg
encoding quality.textureSize
(int aTextureSize) Sets the texture size per tile.textureToColor
(boolean aTextureToColor) Specifies whether this model's textures should be converted to color.verticesPerTile
(int aVerticesPerTile) Sets the number of vertices per tile.
-
Field Details
-
DEFAULT_TEXTURE_SIZE_PER_TILE
public static final int DEFAULT_TEXTURE_SIZE_PER_TILEDefault value of the texture size. This value will be used if nothing is specified intextureSize(int)
.- Since:
- 2023.1
- See Also:
-
DEFAULT_VERTEX_COUNT_PER_TILE
public static final int DEFAULT_VERTEX_COUNT_PER_TILEDefault value for the vertex count. This value will be used if nothing is specified inverticesPerTile(int)
.- Since:
- 2023.1
- See Also:
-
-
Method Details
-
newBuilder
Creates a new builder for the 3DTiles processor. -
addInputFiles
Adds paths pointing to a single file in a supported mesh format.- Parameters:
aMeshPath
- One or more paths to files containing mesh data.
-
textureSize
Sets the texture size per tile. A small texture size results in smaller tiles but deeper tiling while a larger texture size results in shallower tiling and larger tile-size. This parameter should be carefully chosen together with theverticesPerTile(int)
parameter and should be left to default for most purpose.- Parameters:
aTextureSize
- the squared root of the texture size per tile. A value of 256 results in 256 x 256 textures. Defaults to 1024.- Returns:
- the builder
- Since:
- 2020.1
-
verticesPerTile
Sets the number of vertices per tile. A small value results in smaller tiles but deeper tiling while a larger value results in shallower tiling and larger tile-size. This parameter should be carefully chosen together with thetextureSize(int)
parameter and should be left to default for most purpose.- Parameters:
aVerticesPerTile
- the number of vertices per tile. Defaults to 15000.- Returns:
- the builder
- Since:
- 2020.1
-
dropSmallComplexParts
Drop parts of the mesh that are relatively small and complex before simplification. This can improve the visual appearance of meshes at lower levels of detail with a significant computational cost.- Parameters:
aDropSmallComplexParts
- true if the strategy should be used, true by default.- Since:
- 2020.1
-
metadataMapper
public TLcd3DTilesProcessorBuilder metadataMapper(ILcd3DTilesProcessorMetadataMapper aMetadataMapper) Adds a metadata provider to this builder. The metadata mapper will be used to map the metadata of the output dataset. Set this to null if you want to disable metadata in the output dataset. This defaults to a metadata provider that returns the default values without modification.- Parameters:
aMetadataMapper
- A metadata provider- Returns:
- this builder
- Since:
- 2020.1
- See Also:
-
preserveBorders
The border of a mesh consists of edges that only connect to a single face. If true, 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.
- Parameters:
aPreserveBorders
- true if should preserve borders, false by default.- Returns:
- the builder
- Since:
- 2020.1
-
statusListener
Set the status listener to be notified of the task's progress.- Parameters:
aStatusListener
- a status listener.- Returns:
- the builder
-
textureToColor
Specifies whether this model's textures should be converted to color.
If true, the material's diffuse textures will be converted to a diffuse color that is the average color of the texture. This is useful for models that have many repeating textures (with texture coordinates outside [0, 1]). Rather than tiling deep in order to preserve the detail of the textures, switching to color will greatly improve performance and give a more cartoonish appearance to the tileset.
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.
- Parameters:
aTextureToColor
- true if texture should be converted to color- Returns:
- the builder
-
simplificationStrategy
public TLcd3DTilesProcessorBuilder simplificationStrategy(ELcdSimplificationStrategy aSimplificationStrategy) Specifies the simplification algorithm to use.By default, the process will use
QUADRIC_EDGE_COLLAPSE
.- Parameters:
aSimplificationStrategy
- the simplification algorithm to use.- Returns:
- the builder
-
outputPath
Set the folder that the output OGC 3D Tiles tileset is written to.Any data that is already present is overwritten.
- Parameters:
aOutputPath
- the output path- Returns:
- the builder
-
forcePNGEncoding
Forcespng
encoding for textures.By default,
jpeg
is used for textured meshes andpng
is used for colored meshes.In the case of meshes that are both textured and colored, for example when building roofs are textured, but the walls are of a single color, it is recommended to encode the entire texture atlas to
png
. This will result in heavier tiles but it will preventjpeg
color artifacts.- Parameters:
aForcePNGEncoding
- true if textures should be forced encoded topng
- Returns:
- the builder
-
meshCompression
public TLcd3DTilesProcessorBuilder meshCompression(ELcdOGC3DTilesMeshCompressionType aMeshCompressionType) Sets the mesh compression algorithm to use in the OGC 3D Tiles encoding.- Parameters:
aMeshCompressionType
- The mesh compression you want to use (default: DRACO); Should not benull
.- Returns:
- the builder
- Since:
- 2021.1
-
textureQuality
Set the
jpeg
encoding quality.Setting this option to a low value reduces the size of the individual output tiles, and results in typical JPEG encoding artifacts (the image below shows an example of those typical JPEG artifacts). For most cases, we recommend that you keep the default texture quality value.
Default is
0.7
. Typically, there's no need to go above0.9
.This method has no effect when
forcePNGEncoding(boolean)
is active.- Parameters:
aTextureQuality
- a quality between 0 (low quality) and 1 (high quality).- Returns:
- the builder
-
globalShiftFactory
public TLcd3DTilesProcessorBuilder globalShiftFactory(Function<String, ILcdPoint> aGlobalShiftFactory) Set a global shift factory that returns apoint
for a given file.The global shift is applied in the same reference that the mesh is defined in.
If the factory returns null for a particular file, the global shift set with
globalShift(com.luciad.shape.ILcdPoint)
will be used.If the global shift has not been set, the process will attempt to read the global shift from an ".xyz" file with the same name as the mesh file. This must be a small text file with a single line containing three doubles:
<x> <y> <z>
.- Parameters:
aGlobalShiftFactory
- the factory- Returns:
- the builder
-
globalShift
Set a global shift to be used for every mesh.See
globalShiftFactory(java.util.function.Function<java.lang.String, com.luciad.shape.ILcdPoint>)
for details.- Parameters:
aGlobalShift
- the shift- Returns:
- the builder
-
modelReferenceDecoder
public TLcd3DTilesProcessorBuilder modelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder) Set a model reference decoder that returns a reference for a given filepath.If the decoder returns null for all input files, and the default reference is also null, the resulting tileset is not referenced.
By default, all model reference decoders registered as service will be tried. This means
.prj
,.epgs
or.ref
files with the same name as the meshes are automatically picked-up.- Parameters:
aModelReferenceDecoder
- a reference decoder- Returns:
- the builder.
-
defaultModelReference
Set a unique reference to be used for all the meshes.This reference is used when no reference can be found by the
model reference decoder
.If the model reference decoder returns null, and the default reference is also null, then the resulting tileset is not referenced.
- Parameters:
aModelReference
- the reference- Returns:
- the builder
-
process
Starts the OGC 3D Tiles processing.- Returns:
- a
Future
that resolves when processing is done
-