Package com.luciad.meshup

Class TLcd3DTilesProcessorBuilder

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: 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. You can find the cache location at luciad/3dtilesprocessor/cache under the system temporary-file folder, defined by the Java system property java.io.tmpdir. 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 Details

    • 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:

    • 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:

    • DEFAULT_CACHE_BASE_PATH

      public static final Path DEFAULT_CACHE_BASE_PATH
      Default value for the cache base path. This value will be used if nothing is specified in cacheBasePath(java.lang.String).
      Since:
      2026.0

  • Method Details

    • 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:

    • 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

    • tileSetVersion

      public TLcd3DTilesProcessorBuilder tileSetVersion(ELcdOGC3DTilesVersion aTileSetVersion)
      Sets the version of the OGC 3D Tiles tileset to be created.

      See ELcdOGC3DTilesVersion for the supported versions and the differences.

      Parameters:
      aTileSetVersion - the version to use, ELcdOGC3DTilesVersion.VERSION_1_0 by default.
      Returns:
      the builder
      Since:
      2025.0

    • 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 and using a 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

    • cacheBasePath

      public TLcd3DTilesProcessorBuilder cacheBasePath(String aCacheBasePath)
      Set the base folder where the 3D Tiles processor can write temporary files.

      This folder should be writeable for the process. Under normal circumstances, the 3D Tiles processor cleans up the files it creates. In case of errors, any leftover files in the cache after the process stops can be safely deleted.

      The default value for the cache base path can be found in DEFAULT_CACHE_BASE_PATH, this path is dependent on the OS specific temporary files path.

      Parameters:
      aCacheBasePath - the base path for the cache
      Returns:
      the builder
      Since:
      2026.0

    • 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 encoding artifacts
      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

    • preTransformFactory

      public TLcd3DTilesProcessorBuilder preTransformFactory(Function<String,double[]> aPreTransformFactory)
      Set a factory that returns an affine transformation to be applied to a given input file.

      The transformation will be applied before georeferencing happens, so the transformation should be in the reference of your input model.

      A pre-transformation cannot be combined out-of-the-box with a global shift, since the order of operations is important and the results can be surprising when this order is wrong. As such, any ".xyz" file will be ignored when a pre-transformation factory is set, and you'll have to decide how to apply this shift using the pre-transform API. See the next section for more information on how to do this.

      Introducing the global shift in a pre-transform

      Since a global shift is an affine translation, it is possible to chain an existing global shift with another affine transformation. This needs the following steps:
      1. If the global shift is defined in a .xyz file, read the .xyz file to extract the X, Y and Z coordinates.
      2. Create the affine translation matrix, which looks like 
             double[] translationMatrix = new double[] {
        1.0, 0.0, 0.0, X
        0.0, 1.0, 0.0, Y
        0.0, 0.0, 1.0, Z
        0.0, 0.0, 0.0, 1.0
     };
      3. Multiply this matrix in the correct place with your existing transformation. Affine transformation matrices are multiplied in reverse order of application. Thus, if the translation matrix T is to be applied last, after the other transformation O, you will need to calculate the matrix product T * O. If it needs to be applied first, you calculate O * T.
      4. Return the resulting matrix from the factory.
      Parameters:
      aPreTransformFactory - The factory. All matrices created must be affine transformation matrices, thus, the bottom row must have values 0, 0, 0, 1.
      Returns:
      the builder
      Since:
      2026.0

    • 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

    • forkJoinPool

      public TLcd3DTilesProcessorBuilder forkJoinPool(ForkJoinPool aForkJoinPool)
      Specify the ForkJoinPool that will be used to execute async tasks during processing. If no ForkJoinPool is specified, the common pool will be used.
      Parameters:
      aForkJoinPool - the ForkJoinPool to use to perform processing tasks.
      Returns:
      this builder
      Throws:
      NullPointerException - if the provided aForkJoinPool is null.
      Since:
      2025.0

    • process

      public Future<Void> process()
      Starts the OGC 3D Tiles processing.
      Returns:
      a Future that resolves when processing is done