Flattening Modes

< previous page next page >

In this tutorial, we are going to explore how RapidCompact utilizes flattening modes and settings in order to steer the optimization of the scene hierarchy of a given 3D model.

Table of Contents

Flattening Modes

 back to top

To cover all sorts of possible further usage of optimized models, RapidCompact offers four unique flattening modes. Instead of merging all geometry and material information into single nodes (and hence into single drawcalls), you can specify a mode in order to preserve more of the original materials, meshes and/or hierarchy. In order to also more directly flatten the existing scene hierarchy, please refer to the Flattening by Scene Depth Section. The available flattening modes are as follows:

  • auto: Let RapidCompact decide. At this moment this is equal to the flattening mode "byOpacity".

  • byOpacity: Merges all non-transparent meshes and keeps all transparent meshes separate. Will result in 1 - n material nodes (dependant on number of transparent nodes).

  • byMaterial: Merges all meshes that share the same material ID. Will result in the same number of material nodes as in the input.

  • full: Everything is merged. Will also result in one single material node.

  • none: This mode produces the highest number of drawcalls, but preserves all nodes.
  • Notes:
  • Some formats (e.g. OBJ) do not support hierarchies or instances. For these formats, our exporters do their best to at least keep individual meshes separate.

  • The "compact" command may internally perform a flattening operation, unless flattening:mode is explicitly set to "none".

  • Name Type Default Valid Range Quick Description
    flattening:mode String auto {'auto', 'byOpacity', 'byMaterial', 'full', 'none'} mode to be used for flattening

    Not using any flattening has specific benefits and potential downsides as well, also depending on what mode is chosen for the specific input mesh:


  • You can continue to select and process individual nodes and their subtrees within your optimized model.

  • If your input contains instances of meshes, they can now be maintained as instances and stored/rendered efficiently.

  • If your input contains transparent meshes, your renderer will be able to render them in the correct order even after optimization.

  • Potential Downsides:

  • More complex files.

  • More drawcalls, leading to reduced rendering performance if your model has large numbers of nodes and meshes (see the next section if this worries you).

  • Some operations like decimation ( -d ) may behave in unexpected ways, e.g. create cracks between unconnected but aligned meshes. You may choose to flatten meshes before performing decimate or use the compact command instead to prevent this.

  • Flattening, Hierarchy Preservation & Performance

     back to top


    We just saw how the usage of different flattening modes can have benefits and downsides. To get a better picture what that means in terms of performance and materials of a 3D model, we will produce four different versions of the example file:

         rpdx -i FlightHelmet.gltf -s flattening:mode byOpacity -c f:25% -e FlightHelmet-compact-byOpacity.glb
         rpdx -i FlightHelmet.gltf -s flattening:mode byMaterial -c f:25% -e FlightHelmet-compact-byMaterial.glb
         rpdx -i FlightHelmet.gltf -s flattening:mode full -c f:25% -e FlightHelmet-compact-full.glb
         rpdx -i FlightHelmet.gltf -s flattening:mode none -c f:25% -e FlightHelmet-compact-none.glb

    Tip There is also an explicit --flatten command, which you can use if you only want to apply flattening, but not perform any other operation (like --compact). Make sure when working with --compact   to use the setting command -s flattening:mode arg instead of the flattening command --flatten arg . The latter will only make sense if the mesh function itself is not using flattening internally ( --compact will always flatten internally), for example using the --decimate function. After a mesh is flattened once (with --flatten or --compact), the flattening can not be reversed in the same command and the input file has to be duplicated first or re-imported if two or more flattening modes should be used in one single command on one single asset.

    Top-left: flattened "byOpacity"/"auto"; Top-right: flattened "none"; Bottom-left: flattened "full"; Bottom-right: original

    When comparing the results, we can see that each .glb file has a different number of drawcalls and nodes. Also, the result in the bottom left corner lost the transparency because of using the "full" flattening mode (we did already cover that case in the the first section).

    The other results are mostly behaving according to the syntax behind the flattening. The version reduced with "byOpacity" produces two drawcalls from two different meshes so that the transparent glasses and the opaque parts can be rendered correctly. In this case the flattening "none" version has almost the same result due to the structure of the input mesh. This might differ depending on the organization of the input mesh and hierarchy.

    Overall, we can say that using RapidCompact's standard setting (flattening mode "auto") produces results supporting and preserving transparency without compromising the performance too much. Of course, an input file with a lot of unique transparent parts will have more drawcalls than with the "full" flattening mode, but the consequences regarding performance should be still minor and usually the benefits of preserving transparency should outwheigh the additional drawcalls and nodes.

    Hierarchy Preservation:

    Let us take the models produced in the previous section and this time have a look at the glTF hierarchy in the different output files in comparison to the original hierarchy:

    From left to right: flattened "full"; flattened "byOpacity"; flattened "byMaterial"; flattened "none"; original hierarchy

    As you can see, the hierarchies of the generated results give a good overview on how RapidCompact can use a grade of flattening specifically tailored to the needs of each final application. In comparison, the flattening mode "none" will preserve the nodes and naming conventions of the original, whereas the "full" and "byOpactiy" modes will flatten either everything or all opaque nodes, respectively. Like "byOpacity", the "byMaterial" mode will usually produce a different number of nodes than given in the input model. The only difference between these two modes is that "byOpacity" will merge together all nodes that have the same opacity category (transparent or opaque), while "byMaterial" merges together all nodes that have the same material.

    Note Using the flattening mode "none" will preserve Material IDs. However if the input materials are using textures on one or multiple atlases, RapidCompact will always re-bake all materials on a number of atlases defined by the given atlas mode setting (see Atlasing Modes). In case you want to simplify the model, but preserve all original texture maps and UV coordinates, you can also use RapidCompact's UV-Preserving Simplification. In case you have to deal with tiled textures and you might want to preserve the tiling have a look at this tutorial.

    Draw Calls vs. Materials or Atlases:

    Within this tutorial, we have learned how to use RapidCompact's flattening feature to produce assets with a low number of draw calls, fitting the needs of a certain target application - for applications that require separate nodes (for example, to show, hide or transform them individually during runtime), no flattening is necessary, while others can use flattening by opacity or by material to achieve a lower number of draws, hence boosting the rendering performance. Within the next tutorial, we are going to have a look at atlasing modes, which will allow us to configure how RapidCompact creates texture atlases when creating new, optimized materials.

    Flattening by Scene Depth

     back to top

    In addition to the flattening modes, RapidCompact also introduced a setting which can give some more control over the existing scene graph:

    Name Type Default Valid Range Quick Description
    flattening:preservedSceneDepth Int 0 {0 .. inf} number of layers in the scene structure that should not be flattened

    Note The flattening preservedSceneDepth setting is ignored with flattening mode none, as the latter preserves all of the scene structure by default.

    This setting will specify the level of node hierarchy which should be preserved during optimization. A level of 0 turns of the setting and thus does not preserve any hierarchy (RapidCompact Default). To better understand this feature, let us look at an example model:

    The mosquito in amber model from the glTF sample assets is a good example with some nested scene hierarchy. It can be downloaded here.

    Let's get started by importing the asset and performing the following flattening operations:

    rpdx -i MosquitoInAmber.glb -s flattening:mode auto -s flattening:preservedSceneDepth 0 -c -e auto-sceneDepth0.glb

    rpdx -i MosquitoInAmber.glb -s flattening:mode auto -s flattening:preservedSceneDepth 1 -c -e auto-sceneDepth1.glb

    rpdx -i MosquitoInAmber.glb -s flattening:mode auto -s flattening:preservedSceneDepth 5 -c -e auto-sceneDepth5.glb


    From left to right: flattening mode auto (byOpacity) and preservedSceneDepth 0, [..] and preservedSceneDepth 1, [..] and preservedSceneDepth 5

    As you can see, the flattening operations were successful and especially scenDepth 1 and 5 had a very distinguishable effect on the output scene structure. Level 5 brings the structure actually almost in line with the original scene hierarchy (see above).

    However, note how the material names are not preserved as these might be merged depending on opacity. Let`s try with the flattening mode byMaterial again, in order to preserve all Materials and their names:

    rpdx -i MosquitoInAmber.glb -s flattening:mode byMaterial -s flattening:preservedSceneDepth 0 -c -e byMaterial-sceneDepth0.glb

    rpdx -i MosquitoInAmber.glb -s flattening:mode byMaterial -s flattening:preservedSceneDepth 1 -c -e byMaterial-sceneDepth1.glb

    rpdx -i MosquitoInAmber.glb -s flattening:mode byMaterial -s flattening:preservedSceneDepth 5 -c -e byMaterial-sceneDepth5.glb


    From left to right: flattening mode byMaterial and preservedSceneDepth 0, [..] and preservedSceneDepth 1, [..] and preservedSceneDepth 5

    Notice how the material names are preserved now due to the given flattening mode byMaterial.

    < previous page next page >