CLI Naming Scripting Guide

info

This is the legacy documentation for the Naming Scripting Functionality. For the new RapidPipeline 3D Processor version of this documentation click here.

This documentation summarizes all information to get started with RapidCompact’s (re)- naming scripting functionality and CLI settings.

Flattening with scene depth preservation

caution

This guide requires the basic understanding of the flattening process and flattening mode settings within the RapidCompact (legacy) CLI. Get started with flattening in the legacy CLI Tutorials.

The setting flattening:preservedSceneDepth can be used to specify how many levels of the scene hierarchy should be preserved:

If flattening:mode is none, the setting has no effect
If the value for the setting is 0, the setting has no effect
For flattening modes other than none, the nodes below the given level are flattened with the requested mode

When flattening, separate meshes are created for each material. This means that in some cases a node may have children to contain the multiple meshes, one per material.

Read more about flattening and preserving scene depth in the RapidCompact (legacy) CLI Documentation.

note

Note: flattening settings only have an effect if flattening is performed by either:

--flatten command, or
--compact (-c) command (+ default setting: "flattening:mode": "auto")

Renaming Nodes

When utilizing RapidCompact's flattening and baking workflows (via compact), merged mesh nodes often inherit standard naming (e.g. node1).

In order to customize this behavior with certain rules (adding suffixes, prefixes, metadata, inheriting naming from parent nodes etc.), the node naming script can be useful.

The setting compact:nodeNamingScript allows to compute a name for nodes containing meshes created during flattening using a script.

info

As of CLI v6.12.0, this only applies to nodes containing meshes that were created during flattening.

The setting is used in the same way as the export:textureNamingScript (see further below):

A JavaScript script can be set in the setting value directly
- e.g.: -s compact:nodeNamingScript "script_code"
If the value of the setting starts with @, rpdx (the CLI) tries to load the script from a file path defined after the @

When the script is executed

The script runs at the end of the flattening operation, for each new Node containing newly created flat meshes.

In the case of flattening none, the script is not applied since no new nodes are created.

Properties available in the Script

The following properties are made accessible in the node naming script:

node.parentName - the name of the parent of the current node
node.isOpaque - true if the materials used by the mesh under this node are all considered opaque
node.meshGroupIdx - the index of this mesh in the respective group (see Mesh Groups)
node.meshGroupSize - the number of meshes in the respective group (see Mesh Groups)

Mesh Groups

Meshes are currently divided into two groups - opaque and non-opaque.

Each mesh has an index within the group which starts with 0 and is less than the number of meshes in the group.

There is no way to tell the order of the meshes (how indices are assigned).

Example:

Opaque Group:
- mesh1, mesh2
Non-opaque Group:
- mesh3, mesh4
- mesh1 will have group index 0 and mesh 2 group index 1.
- mesh3 will have group index 0 and mesh 4 group index 1.

Node Renaming Example

Model: MosquitoInAmber.gltf
Source: https://github.com/KhronosGroup/glTF-Sample-Models/tree/main/2.0/MosquitoInAmber

Model Model by Loïc Norgeot and mosquito scan by Geoffrey Marchal for Sketchfab licensed under CC BY 4.0

Input scene graph

Definitions:

__root__    = node is the internal asset root, not part of the original asset.
[T]         = the node has a transformation
[M]         = the node contains a mesh (mesh node)
[ ]         = the node does not contain a mesh

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        RootNode (model correction matrix) []
            0a89b95064be46e6943aaad2c83817a2.fbx [T]
                RootNode [T]
                    2_mosquito_lr [T]
                        2_mosquito_lr_original.o_material_0_0 [M]
                    5_amber_lr [T]
                        5_amber_lr_PBR_0 [M]
                    6_eclats [T]
                        6_eclats_eclats_0 [M]

Example script 1:

'mesh_' + node.parentName + (node.isOpaque ? '_opaque_' : '_transparent_') + node.meshGroupIdx

Input: NODE (assuming this node is the first node containing an opaque mesh)
Output of Script: mesh_NODE_opaque_0

preservedSceneDepth 5:

Using example script 1 and --compact and flattening:preservedSceneDepth = 5, flattening:mode = byMaterial, atlasing:mode = separateAlpha (default):

rpdx -i MosquitoInAmber.gltf -s flattening:mode byMaterial -s flattening:preservedSceneDepth 5 -s compact:nodeNamingScript "'mesh_' + node.parentName + (node.isOpaque ? '_opaque_' : '_transparent_') + node.meshGroupIdx" -c -e renameNodes-script-1-simple-presDepth5-byMtl/MosquitoInAmber.gltf

Resulting Scene Graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        RootNode (model correction matrix) []
            0a89b95064be46e6943aaad2c83817a2.fbx [T]
                RootNode [T]
                    2_mosquito_lr [T]
                        mesh_2_mosquito_lr_opaque_0 [M]
                    5_amber_lr [T]
                        mesh_5_amber_lr_transparent_0 [M]
                    6_eclats [T]
                        mesh_6_eclats_opaque_0 [M]

Two visible effects on the output data (besides the optimization via compact operation):

the scene graph preserved scene depth level of 5 ensured the same (parent) nodes as in the input
re-naming of the mesh nodes according to the used naming node script
- adding prefix mesh_
- inheriting the respective parent names (e.g. 2_mosquito_lr)
- adding information of the associated material opacity types (opaque vs transparent)
- adding mesh count index (e.g. _0)

preservedSceneDepth 1:

Using example script 1 and --compact and flattening:preservedSceneDepth = 1, flattening:mode = byMaterial, atlasing:mode = separateAlpha (default):

rpdx -i MosquitoInAmber.gltf -s flattening:mode byMaterial -s flattening:preservedSceneDepth 1 -s compact:nodeNamingScript "'mesh_' + node.parentName + (node.isOpaque ? '_opaque_' : '_transparent_') + node.meshGroupIdx" -c -e renameNodes-script-1-simple-presDepth1-byMtl/MosquitoInAmber.gltf

Resulting Scene Graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        mesh_RootNode (gltf orientation matrix)_opaque_0 [M]
        mesh_RootNode (gltf orientation matrix)_opaque_1 [M]
        mesh_RootNode (gltf orientation matrix)_transparent_0 [M]

Visible effects on the output data (besides the optimization via compact operation):

the scene graph preserved scene depth level of 1 preserved only 1 parent node level, in this case: RootNode (gltf orientation matrix)
re-naming of the mesh nodes according to the used naming node script
- adding prefix mesh_
- inheriting the respective parent names (e.g. RootNode (gltf orientation matrix))
- adding information of the associated material opacity types (opaque vs transparent)
- adding mesh count index (e.g. _0)

Example script 2:

assetID = node.parentName.split('_').slice(1,2).join('_'); idx = node.meshGroupIdx + 1; idxstr = node.meshGroupSize > 1 ? ('_' + (idx > 9 ? idx : '0' + idx)) : ''; 'geo_' + (node.isOpaque ? 'opq_' : 'trp_') + assetID + idxstr;

Using example script 2 and --compact and flattening:preservedSceneDepth = 5, flattening:mode = byOpacity, atlasing:mode = separateAlpha (default):

rpdx -i MosquitoInAmber.gltf -s flattening:mode byOpacity -s flattening:preservedSceneDepth 5 -s compact:nodeNamingScript "assetID = node.parentName.split('_').slice(1,2).join('_'); idx = node.meshGroupIdx + 1; idxstr = node.meshGroupSize > 1 ? ('_' + (idx > 9 ? idx : '0' + idx)) : ''; 'geo_' + (node.isOpaque ? 'opq_' : 'trp_') + assetID + idxstr;" -c -e renameNodes-script-2-presDepth1-byOpcty/MosquitoInAmber.gltf

Resulting Scene Graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        RootNode (model correction matrix) []
            0a89b95064be46e6943aaad2c83817a2.fbx [T]
                RootNode [T]
                    2_mosquito_lr [T]
                        geo_opq_mosquito [M]
                    5_amber_lr [T]
                        geo_trp_amber [M]
                    6_eclats [T]
                        geo_opq_eclats [M]

Visible effects on the output data (besides the optimization via compact operation):

the scene graph preserved scene depth level of 5 ensured the same (parent) nodes as in the input
re-naming of the resulting mesh nodes (via flattening byOpacity) according to the used naming node script:
- adding prefix geo_
- adding information of the associated material opacity types (opq vs trp)
- inheriting a specific part of the direct parent nodes (e.g. second part of parent node name, separated by _: mosquito)
- adding mesh count index (e.g. _01) - does not apply here as each mesh node lives separatly under an individual parent node

Renaming Materials

When utilizing RapidCompact's flattening and baking workflows (via compact), merged materials often inherit standard naming (e.g. mat0).

In order to customize this behavior with certain rules (adding suffixes, prefixes, metadata, inheriting naming from parent nodes etc.), the material naming script can be useful.

The setting compact:materialNamingScript allows to compute a name for each baked material using a script.

info

The script is running at the end of the compact operation and only renames materials that were created during compact (e.g. baked materials).

The setting is used in the same way as the export:textureNamingScript(see further below:

A JavaScript script can be set in the setting value directly
- e.g.: -s compact:nodeNamingScript "script_code"
If the value of the setting starts with @, rpdx (the CLI) tries to load the script from a file path defined after the @

When the script is executed

The script runs at the end of the compact operation, if new materials were baked. It runs for each material.

Properties available in the Script

The following properties are made accessible in the material naming script:

material.parentNodeName - name of the parent of the node containing the mesh using the material
material.isOpaque - self explanatory
material.materialGroupIdx - the index of this material in the respective group (see Material Groups)
material.materialGroupSize - the number of materials in the respective group (see Material Groups)

note

The material may be used by different nodes/meshes, in which case different names for parentNodeName may exist and it is not defined which one will be passed to the script.

Material Groups

Materials are currently divided in two groups - opaque and non-opaque. Each material has an index within the group which starts with 0 and is less than the number of materials in the group. There is no way to tell the order of the materials (how indices are assigned). e.g.: Opaque Group: material1, material2 Non-opaque Group: material3, material4 material1 will have group index 0 and material2 group index 1. material3 will have group index 0 and material4 group index 1.

Material Naming Example

Same example model as in the Node Renaming Section.

Input scene graph and materials

Definitions:

__root__    = node is the internal asset root, not part of the original asset.
[T]         = the node has a transformation
[M]         = the node contains a mesh (mesh node)
[ ]         = the node does not contain a mesh

scene graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        RootNode (model correction matrix) []
            0a89b95064be46e6943aaad2c83817a2.fbx [T]
                RootNode [T]
                    2_mosquito_lr [T]
                        2_mosquito_lr_original.o_material_0_0 [M]
                    5_amber_lr [T]
                        5_amber_lr_PBR_0 [M]
                    6_eclats [T]
                        6_eclats_eclats_0 [M]

materials:

eclats
material
original.o_material_0

associations:

material	associated mesh node(s)
`eclats`	`6_eclats_eclats_0`
`material`	`5_amber_lr_PBR_0`
`original.o_material_0`	`2_mosquito_lr_original.o_material_0_0`

Example script 1:

'mat_' + (material.isOpaque ? '_opaque_' : '_transparent_') + material.materialGroupIdx

If the material is opaque and this is the first opaque material, the script would result in mat_opaque_0.

Using example script 1 and --compact and flattening:preservedSceneDepth = 1, flattening:mode = byMaterial, atlasing:mode = separateAlpha (default):

rpdx -i MosquitoInAmber.gltf -s flattening:mode byMaterial -s flattening:preservedSceneDepth 1 -s compact:materialNamingScript "'mat_' + (material.isOpaque ? '_opaque_' : '_transparent_') + material.materialGroupIdx" -c -e renameMaterials-script-1-presDepth1-byOpcty/MosquitoInAmber.gltf

Results:

scene graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        2_mosquito_lr_original.o_material_0_0 [M]
        5_amber_lr_PBR_0 [M]
        6_eclats_eclats_0 [M]

materials:

mat__opaque_0
mat__opaque_1
mat__transparent_0

associations:

material	associated mesh node(s)
`mat__opaque_0`	`6_eclats_eclats_0`
`mat__opaque_1`	`2_mosquito_lr_original.o_material_0_0`
`mat__transparent_0`	`5_amber_lr_PBR_0`

Visible effects on the output data (besides the optimization via compact operation):

the scene graph preserved scene depth level of 1 preserved only 1 parent node level, in this case: RootNode (gltf orientation matrix)
re-naming of the material nodes according to the used naming node script
- adding prefix mat_
- adding information of the associated material opacity types (_opaque vs _transparent)
- adding material count index (e.g. _0)

Example script 2:

assetID = material.parentNodeName.split('_').slice(1,2).join('_'); idx = material.materialGroupIdx + 1; idxstr = material.materialGroupSize > 1 ? ('_' + (idx > 9 ? idx : '0' + idx)) : ''; 'mat_' + (material.isOpaque ? 'opq_' : 'trp_') + assetID + idxstr;

Using example script 2 and --compact and flattening:preservedSceneDepth = 5, flattening:mode = byMaterial, atlasing:mode = separateAlpha (default):

rpdx -i MosquitoInAmber.gltf -s flattening:mode byMaterial -s flattening:preservedSceneDepth 5 -s compact:materialNamingScript " assetID = material.parentNodeName.split('_').slice(1,2).join('_'); idx = material.materialGroupIdx + 1; idxstr = material.materialGroupSize > 1 ? ('_' + (idx > 9 ? idx : '0' + idx)) : ''; 'mat_' + (material.isOpaque ? 'opq_' : 'trp_') + assetID + idxstr;" -c -e renameMaterials-script-2-presDepth5-byMtl/MosquitoInAmber.gltf

Results:

scene graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        RootNode (model correction matrix) []
            0a89b95064be46e6943aaad2c83817a2.fbx [T]
                RootNode [T]
                    2_mosquito_lr [T]
                        2_mosquito_lr_original.o_material_0_0 [M]
                    5_amber_lr [T]
                        5_amber_lr_PBR_0 [M]
                    6_eclats [T]
                        6_eclats_eclats_0 [M]

materials:

mat_opq_eclats
mat_opq_mosquito
mat_trp_amber

associations:

material	associated mesh node(s)
`mat_opq_eclats`	`6_eclats_eclats_0`
`mat_opq_mosquito`	`2_mosquito_lr_original.o_material_0_0`
`mat_trp_amber`	`5_amber_lr_PBR_0`

Visible effects on the output data (besides the optimization via compact operation):

the scene graph preserved scene depth level of 5 ensured the same (parent) nodes as in the input
re-naming of the material nodes according to the used naming node script
- adding prefix mat_
- adding information of the associated material opacity types (_opq vs _trp)
- materials are inheriting the second part (separated by _ of the individual associated meshes' parent nodes, e.g. eclats)

Renaming Textures

When utilizing RapidCompact's flattening and baking workflows (via compact), exported textures from merged materials often inherit standard naming (e.g. `material0_basecolor.jpg).

In order to customize this behavior with certain rules (adding custom suffixes, prefixes, metadata, inheriting naming from parent nodes etc.), the texture naming script can be useful.

The setting export:textureNamingScript makes it possible to define the names for exported textures by using a script.

The setting itself can be used to specify the script code directly or a name of a file containing the script.

In order to put together the texture name, some global variables about the material and texture are made available to the script.

Global variables available to the script

material.index - index of the material (rpdx internal index, same as default output - "material" + index)
material.isOpaque - true if the material is opaque
material.name - name of the material
texture.width
texture.height
texture.type - basecolor, metallic, roughness, etc. In some cases will be combined e.g.: metallic_roughness
texture.numChannels - number of channels in the texture

info

Other material or texture info could be provided, for example texture.channels containing a string like "rgb".

Texture Renaming Example

Model: FlightHelmet.gltf
Source: https://github.com/KhronosGroup/glTF-Sample-Models/tree/main/2.0/FlightHelmet

Model

This script re-creates the default texture naming behavior:

rpdx -i infile.foo -s export:textureNamingScript "'material' + material.index + '_' + texture.type" -e outfile.bar 

This could also be achieved by creating a file (for example script.js) file with the content:

'material' + material.index + '_' + texture.type 

And run rpdx passing "@script_filepath" instead of the script itself:

rpdx -i infile.foo -s export:textureNamingScript "@script.js" -e outfile.bar

Another example using the script:

material.name + '_' + texture.type + '_' + texture.width + 'x' + texture.height 

And finally inside the rpd_config.json the setting has the following syntax:

"export:textureNamingScript": "material.name + '_' + texture.type + '_' + texture.width + 'x' + texture.height"

Would produce something like the following for the FlightHelmet.gltf sample model using the following command:

rpdx -i FlightHelmet.gltf -s export:textureNamingScript "material.name + '_' + texture.type + '_' + texture.width + 'x' + texture.height" -e output/res.gltf

Complete Renaming Example

Same example model as in the Node Renaming Section.

Model: MosquitoInAmber.gltf
Source: https://github.com/KhronosGroup/glTF-Sample-Models/tree/main/2.0/MosquitoInAmber

Model Model by Loïc Norgeot and mosquito scan by Geoffrey Marchal for Sketchfab licensed under CC BY 4.0

textures

Input scene graph, materials and textures

Definitions:

__root__    = node is the internal asset root, not part of the original asset.
[T]         = the node has a transformation
[M]         = the node contains a mesh (mesh node)
[ ]         = the node does not contain a mesh

scene graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        RootNode (model correction matrix) []
            0a89b95064be46e6943aaad2c83817a2.fbx [T]
                RootNode [T]
                    2_mosquito_lr [T]
                        2_mosquito_lr_original.o_material_0_0 [M]
                    5_amber_lr [T]
                        5_amber_lr_PBR_0 [M]
                    6_eclats [T]
                        6_eclats_eclats_0 [M]

materials:

eclats
material
original.o_material_0

texture maps:

MosquitoInAmber0.jpg
MosquitoInAmber1.jpg
MosquitoInAmber2.jpg
MosquitoInAmber3.jpg
MosquitoInAmber4.jpg

associations:

material	associated mesh node(s)	associated textures
`eclats`	`6_eclats_eclats_0`	`-`
`material`	`5_amber_lr_PBR_0`	`MosquitoInAmber0.jpg`, `MosquitoInAmber1.jpg`, `MosquitoInAmber2.jpg`
`original.o_material_0`	`2_mosquito_lr_original.o_material_0_0`	`MosquitoInAmber3.jpg`, `MosquitoInAmber4.jpg`

Complete script

Example configuration containing all scripts for node, material and texture renaming (can be saved as .json file):

renaiming.json

{
"compact:materialNamingScript": "assetID = material.parentNodeName.split('_').slice(1,2).join('_'); idx = material.materialGroupIdx + 0; idxstr = material.materialGroupSize > 1 ? ('_' + (idx > 9 ? idx : '0' + idx)) : ''; 'mat_' + (material.isOpaque ? 'opq' : 'trp') + assetID + idxstr;",
    
"compact:nodeNamingScript": "assetID = node.parentName.split('_').slice(1,2).join('_'); idx = node.meshGroupIdx + 0; idxstr = node.meshGroupSize > 1 ? ('_' + (idx > 9 ? idx : '0' + idx)) : ''; 'geo_' + (node.isOpaque ? 'opq' : 'trp') + assetID + idxstr;",
    
"export:textureNamingScript": "texture.type + '_' + material.name + '_' + texture.width"
}

note

Reading these naming configurations can be combined with reading other configurations as well, alternatively the longer settings containing the scripts themselves could be added to any existing configuration file as well.

Using complete example script and --compact and flattening:preservedSceneDepth = 1, flattening:mode = byMaterial, atlasing:mode = separateMaterials:

rpdx -i MosquitoInAmber.gltf -s flattening:mode byMaterial -s flattening:preservedSceneDepth 1 -s compact:atlasingMode separateMaterials --read_config renaming.json -c -e completeScript-presDepth1-byMtl/MosquitoInAmber.gltf

Results

scene graph:

__root__ [T]
    RootNode (gltf orientation matrix) [T]
        geo_opq_00 [M]
        geo_opq_01 [M]
        geo_trp [M]

materials:

mat_opq_00
mat_opq_01
mat_trp

texture maps:

normal_mat_opq_00_512.jpg
basecolor_mat_opq_01_1024.jpg
normal_mat_opq_01_1024.jpg
metallic_roughness_mat_trp_2048.jpg
basecolor_mat_trp_2048.jpg
normal_mat_trp_2048.jpg

associations:

material	associated mesh node(s)	associated textures
`mat_opq_00`	`geo_opq_00`	`normal_mat_opq_00_512.jpg`
`mat_opq_01`	`geo_opq_01`	`basecolor_mat_opq_01_1024.jpg`, `normal_mat_opq_01_1024.jpg`, `metallic_roughness_mat_trp_2048.jpg`
`mat_trp`	`geo_trp`	`basecolor_mat_trp_2048.jpg`, `normal_mat_trp_2048.jpg`

textures

Visible effects on the output data (besides the optimization via compact operation):

the scene graph preserved scene depth level of 1 preserved only 1 parent node level, in this case: RootNode (gltf orientation matrix)
reanaming of the exported mesh, material nodes and textures according to the used naming node script:
- adding prefix geo_ for meshes
- adding prefix mat_ for materials
- adding information of the associated material opacity types (_opq vs _trp)
- adding node count index where needed (e.g. _00)
- adding information about texture types (e.g. normal)
- adding information about texture resolution (e.g. 1024)

Flattening with scene depth preservation​

Renaming Nodes​

When the script is executed​

Properties available in the Script​

Mesh Groups​

Node Renaming Example​

Input scene graph​

Example script 1:​

preservedSceneDepth 5:​

preservedSceneDepth 1:​

Example script 2:​

Renaming Materials​

When the script is executed​

Properties available in the Script​

Material Groups​

Material Naming Example​

Input scene graph and materials​

Example script 1:​

Example script 2:​

Renaming Textures​

Global variables available to the script​

Texture Renaming Example​

Complete Renaming Example​

Input scene graph, materials and textures​

Complete script​

Results​

Flattening with scene depth preservation

Renaming Nodes

When the script is executed

Properties available in the Script

Mesh Groups

Node Renaming Example

Input scene graph

Example script 1:

preservedSceneDepth 5:

preservedSceneDepth 1:

Example script 2:

Renaming Materials

When the script is executed

Properties available in the Script

Material Groups

Material Naming Example

Input scene graph and materials

Example script 1:

Example script 2:

Renaming Textures

Global variables available to the script

Texture Renaming Example

Complete Renaming Example

Input scene graph, materials and textures

Complete script

Results