TLcd3DTilesProcessorBuilder (LuciadLightspeed API documentation)

java.lang.Object
- com.luciad.meshup.TLcd3DTilesProcessorBuilder

```
public class TLcd3DTilesProcessorBuilder
extends Object
```
A builder to run the 3D Tiles Processing Engine, to convert a collection of 3D mesh input data into an OGC 3D Tileset which is optimized for visualization on a map.

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.
This tool takes a collection of mesh input files, and converts the whole collection into a single OGC 3D Tileset. In the process, it will tile and multi-level the data.

Running the processor
To run the processor, you create 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 an ILcdModelReferenceDecoder. 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): see TLcdEPSGModelReferenceDecoder for more info.
- WKT references (<filename>.prj): see TLcdWKTModelReferenceDecoder for more info.
- Luciad encoded model references (<filename>.ref): see TLcdModelReferenceDecoder for more info.
If this fails, the builder's default model reference is returned. Unless set by the user, the default model reference is null, meaning the mesh is unreferenced.

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)
The input format also affects how the engine processes material properties. If the input data is in GLB format and contains PBR (Physically-Based Rendering) material properties, the properties of these materials will be preserved in the OGC 3D Tiles output. If the input is OBJ, on the other hand, only the diffuse color texture will be present in the output.
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

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_TEXTURE_SIZE_PER_TILE` Default value of the texture size.
`static int`	`DEFAULT_VERTEX_COUNT_PER_TILE` Default value for the vertex count.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`TLcd3DTilesProcessorBuilder`	`addInputFiles(String... aMeshPath)` Adds paths pointing to a single file in a supported mesh format.
`TLcd3DTilesProcessorBuilder`	`defaultModelReference(ILcdModelReference aModelReference)` Set a unique reference to be used for all the meshes.
`TLcd3DTilesProcessorBuilder`	`dropSmallComplexParts(boolean aDropSmallComplexParts)` Drop parts of the mesh that are relatively small and complex before simplification.
`TLcd3DTilesProcessorBuilder`	`forcePNGEncoding(boolean aForcePNGEncoding)` Forces `png` encoding for textures.
`TLcd3DTilesProcessorBuilder`	`globalShift(ILcdPoint aGlobalShift)` Set a global shift to be used for every mesh.
`TLcd3DTilesProcessorBuilder`	`globalShiftFactory(Function<String,ILcdPoint> aGlobalShiftFactory)` Set a global shift factory that returns a `point` for a given file.
`TLcd3DTilesProcessorBuilder`	`meshCompression(ELcdOGC3DTilesMeshCompressionType aMeshCompressionType)` Sets the mesh compression algorithm to use in the OGC 3D Tiles encoding.
`TLcd3DTilesProcessorBuilder`	`metadataMapper(ILcd3DTilesProcessorMetadataMapper aMetadataMapper)` Adds a metadata provider to this builder.
`TLcd3DTilesProcessorBuilder`	`modelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)` Set a model reference decoder that returns a reference for a given filepath.
`static TLcd3DTilesProcessorBuilder`	`newBuilder()` Creates a new builder for the 3DTiles processor.
`TLcd3DTilesProcessorBuilder`	`outputPath(String aOutputPath)` Set the folder that the output OGC 3D Tiles tileset is written to.
`TLcd3DTilesProcessorBuilder`	`preserveBorders(boolean aPreserveBorders)` The border of a mesh consists of edges that only connect to a single face.
`Future<Void>`	`process()` Starts the OGC 3D Tiles processing.
`TLcd3DTilesProcessorBuilder`	`simplificationStrategy(ELcdSimplificationStrategy aSimplificationStrategy)` Specifies the simplification algorithm to use.
`TLcd3DTilesProcessorBuilder`	`statusListener(ILcdStatusListener aStatusListener)` Set the status listener to be notified of the task's progress.
`TLcd3DTilesProcessorBuilder`	`textureQuality(float aTextureQuality)` Set the `jpeg` encoding quality.
`TLcd3DTilesProcessorBuilder`	`textureSize(int aTextureSize)` Sets the texture size per tile.
`TLcd3DTilesProcessorBuilder`	`textureToColor(boolean aTextureToColor)` Specifies whether this model's textures should be converted to color.
`TLcd3DTilesProcessorBuilder`	`verticesPerTile(int aVerticesPerTile)` Sets the number of vertices per tile.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_TEXTURE_SIZE_PER_TILE
```
public static final int DEFAULT_TEXTURE_SIZE_PER_TILE
```
    Default value of the texture size. This value will be used if nothing is specified in textureSize(int).
    
    Since:
    
    2023.1
    
    See Also:
    
    Constant Field Values
  - DEFAULT_VERTEX_COUNT_PER_TILE
```
public static final int DEFAULT_VERTEX_COUNT_PER_TILE
```
    Default value for the vertex count. This value will be used if nothing is specified in verticesPerTile(int).
    
    Since:
    
    2023.1
    
    See Also:
    
    Constant Field Values
- Method Detail
  - newBuilder
```
public static TLcd3DTilesProcessorBuilder newBuilder()
```
    Creates a new builder for the 3DTiles processor.
  - addInputFiles
```
public TLcd3DTilesProcessorBuilder addInputFiles(String... aMeshPath)
```
    Adds paths pointing to a single file in a supported mesh format.
    
    Parameters:
    
    aMeshPath - One or more paths to files containing mesh data.
  - textureSize
```
public TLcd3DTilesProcessorBuilder textureSize(int aTextureSize)
```
    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 the verticesPerTile(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
```
public TLcd3DTilesProcessorBuilder verticesPerTile(int aVerticesPerTile)
```
    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 the textureSize(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
```
public TLcd3DTilesProcessorBuilder dropSmallComplexParts(boolean aDropSmallComplexParts)
```
    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:
    
    ILcd3DTilesProcessorMetadataMapper, TLcd3DTilesProcessorDataTypes
  - preserveBorders
```
public TLcd3DTilesProcessorBuilder preserveBorders(boolean aPreserveBorders)
```
    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
```
public TLcd3DTilesProcessorBuilder statusListener(ILcdStatusListener aStatusListener)
```
    Set the status listener to be notified of the task's progress.
    
    Parameters:
    
    aStatusListener - a status listener.
    
    Returns:
    
    the builder
  - textureToColor
```
public TLcd3DTilesProcessorBuilder textureToColor(boolean aTextureToColor)
```
    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.
    
    Comparison between using a texture (left) and using a color (right).
    
    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
```
public TLcd3DTilesProcessorBuilder outputPath(String aOutputPath)
```
    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
```
public TLcd3DTilesProcessorBuilder forcePNGEncoding(boolean aForcePNGEncoding)
```
    Forces png encoding for textures.
    By default, jpeg is used for textured meshes and png 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 prevent jpeg color artifacts.
    
    Parameters:
    
    aForcePNGEncoding - true if textures should be forced encoded to png
    
    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 be null.
    
    Returns:
    
    the builder
    
    Since:
    
    2021.1
  - textureQuality
```
public TLcd3DTilesProcessorBuilder textureQuality(float aTextureQuality)
```
    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.
    
    Example of JPEG artifacts, visible at the edge between the rooftop and the blue sky.
    
    Default is 0.7. Typically, there's no need to go above 0.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 a point 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
```
public TLcd3DTilesProcessorBuilder globalShift(ILcdPoint aGlobalShift)
```
    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
```
public TLcd3DTilesProcessorBuilder defaultModelReference(ILcdModelReference aModelReference)
```
    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
```
public Future<Void> process()
```
    Starts the OGC 3D Tiles processing.
    
    Returns:
    
    a Future that resolves when processing is done

Infrastructure StandardsClass TLcd3DTilesProcessorBuilder

Introduction

Running the processor

Model reference

Orientation of the input data

System requirements

Supported input formats

Limitations

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_TEXTURE_SIZE_PER_TILE

DEFAULT_VERTEX_COUNT_PER_TILE

Method Detail

newBuilder

addInputFiles

textureSize

verticesPerTile

dropSmallComplexParts

metadataMapper

preserveBorders

statusListener

textureToColor

simplificationStrategy

outputPath

forcePNGEncoding

meshCompression

textureQuality

globalShiftFactory

globalShift

modelReferenceDecoder

defaultModelReference

process