Command-Line Interface

You need a Studio license to use this feature. It is included in Transmutr v1.1.0 and higher.

This feature is currently under development. Please report any issue to [email protected]

General usage

The CLI (short for Command-Line Interface) is a very powerful tool that allows users to easily process large sets of models. To use the CLI, first open a terminal and type the path to the location where Transmutr.exe is stored.

If you installed Transmutr per user (the "Only for me" option in the installer) then it should be located at:

C:/Users/YourUsername/AppData/Local/Programs/Transmutr/

If you installed Transmutr per machine (the "Anyone who uses this computer" option in the installer) then it should be located at:

C:/Program Files/Transmutr/

To simply convert a model, add the convert command followed by the path to the model. This will convert your model to a Sketchup file with the same name, right in the current directory. Please note that the path to transmutr.exe will slightly differ on your system.

C:/Users/Frodo/AppData/Local/Programs/Transmutr/transmutr.exe convert C:/models/tree.obj

Typing the complete path to Transmutr's location is quite verbose. If you prefer to avoid this, you can add the Transmutr's folder to your environment's PATH variable, like in this guide.

In this way, your computer knows where to look for when you only type transmutr.exe instead of the whole path. We use this method in the rest of this documentation to keep things short.

You can specify additional options by adding parameters right betweenconvert and the model's path. For instance, add the --output parameters to specify the destination and the name of the converted model:

transmutr.exe convert --output C:/sketchup/my_converted_tree.skp C:/models/tree.obj

You have control over the same set of settings as in Transmutr's graphical interface. For example, to generate a Sketchup model scaled down by half, with 95% of its geometry simplified, you could type:

transmutr.exe convert --scale 0.5 --simplification 0.95 C:/models/tree.obj

To list all the available parameters, type transmutr.exe convert --help. Please note that some parameters have a shorthand version that you can use to avoid typing long keywords, such as -o instead of --output.

> Transmutr.exe convert --help

Transmutr's Command-Line Interface

Positionals:
  input  Paths to the models to convert, can contain globbing patterns  [array] [required] [default: []]

Options:
  --version                                           Show version number  [boolean]
  --output, -o                                        Output path, must be a directory when converting multiple models  [string]
  --preset, -p                                        Path to a preset configuration to load  [string]
  --copyMaps, --cpm                                   Copy texture maps to the output folder  [boolean]
  --absolutePaths, --absp                             Writes asset paths (material maps, proxies) as absolute  [boolean]
  --relativePathsPrefix, --relpfx                     Adds a custom prefix to relative paths  [string]
  --prefixMaterials, --pfxmtl                         Adds the model name to the material names  [boolean]
  --maxMeshScaleCorrection, --maxsc                   Maximum scale factor when scaling meshes to avoid the tiny faces issue  [number]
  --meshScaleCorrectionMultiplier, --scmult           Multiplier for the scale factor, in case it is too strong or not enough  [number]
  --ply2vrmeshPath, --ply2vr                          Writes asset paths (material maps, proxies) as absolute  [string]
  --scale                                             Scale multiplier  [number]
  --sourceUnit, --su                                  Unit of the input model  [choices: "m", "cm", "mm", "f", "i"]
  --up                                                Up-axis of the input model  [choices: "x", "y", "z", "nx", "ny", "nz"]
  --origin                                            New origin of the output model  [choices: "default", "center", "bottomCenter", "topCenter"]
  --simplification, -s                                Simplification level of the output model, in the [0,1] range  [number]
  --simplificationPreserveNormals, --snorm            Simplification will try to preserve the face normals  [boolean]
  --simplificationPreserveUV, --suv                   Simplification will try to preserve the texture coordinates  [boolean]
  --smoothCoplanar, --smc                             Smooth the coplanar faces  [boolean]
  --proxyEnscape, --pxen                              Create an Enscape proxy, the high-resolution skp model will be generated alongside the output model  [boolean]
  --proxyThea, --pxth                                 Create a Thea proxy, the high-resolution mesh.thea model will be generated alongside the output model  [boolean]
  --proxyVray, --pxvr                                 Create a V-Ray proxy, the high-resolution vrmesh model will be generated alongside the output model  [boolean]
  --proxyPlaceholder, --pxplhdr                       Type of proxy placeholder  [choices: "billboardcross", "billboardfaceme", "boundingboxfaces", "boundingboxwireframe", "simplifiedgeometry", "skpfile"]
  --proxyPlaceholderBillboardFilePath, --pxplhdrbill  Path to the image file to use as a billboard  [string]
  --proxyPlaceholderSkpFilePath, --pxplhdrskp         Path to the SketchUp file to use as a proxy preview  [string]
  --proxyPlaceholderSkpFileFaceMe, --pxplhdrfaceme    Makes the proxy preview SketchUp file always faces the camera (billboard)  [boolean]
  --help                                              Show help  [boolean]

Examples:
  transmutr.exe convert house.dae
  transmutr.exe convert --simplification 0.25 statue.fbx
  transmutr.exe convert --output C:/sketchup/mytree.skp tree.fbx
  transmutr.exe convert --scale 5 --origin bottomCenter models/cornell.obj

Copyright Lindalë 2019

You'll notice that executing transmutr.exe without command actually opens the classical Transmutr graphical interface, which can also be useful.

Convert multiple models

To convert several models in one go, you can type their names one after another:

transmutr.exe convert C:/models/tree.fbx C:/models/sofa.obj C:/models/lamp.3ds

When converting multiple models, the options that you specify apply to all the models.

Please note that options must still be placed right after the convert command and before the paths to the models.

The CLI accepts globbing patterns to provide more flexibility when selecting models. For instance, * is useful to select several files without writing their complete names. Thus, the following command converts all the models in C:/models/trees/ that end with .obj:

transmutr.exe convert C:/models/trees/*.obj

Likewise, ** can help you search for models in several directories. For example, the following command converts all the models named tree.fbx located in any directory under C:/models/:

transmutr.exe convert C:/models/**/tree.fbx

Range operators are also useful to select names with some variations in them. The following command converts any model which name matches tree1.obj, tree2.obj, up to tree9.obj:

transmutr.exe convert C:/models/tree[1-9].obj

Similarly, we can select a range of letters. In this example, we convert any file with a name that matches furniture_a.obj, furniture_b.obj, ..., up to furniture_z.obj:

transmutr.exe convert C:/models/furniture_[a-z].obj

You can also combine different patterns by wrapping them in parentheses, separated by |, following one of the @, +, *, +, or ! operators:

• @ matches exactly one occurrence of the patterns

• ? matches zero or one occurrence

• * matches zero or more occurrences

• + matches one or more occurrences

• ! matches anything that does not match the patterns

For example, the following command converts any file that ends either with the .obj or .fbx extensions:

transmutr.exe convert C:/models/*.@(obj|fbx)

In this other example, we convert any model which name matches treeX.obj where X can be any number with one or more digits:

transmutr.exe convert C:/models/tree+([1-9]).obj

Finally, it's possible to combine different patterns to carry out very specific searches:

transmutr.exe convert C:/models/**/tree_collection_[1-5]/*_highpoly.@(fbx|obj)

Note that the paths and patterns are case-sensitive. So a pattern containing .fbx will not match a filename ending with .FBX .

Using the CLI for scripting

One way in which the CLI can be even more powerful is by including it in a scripting pipeline that automates tasks that would be tedious and time-consuming to perform manually.

This section contains examples that show how such tasks can be handled by combining Transmutr with your own scripts.

Ruby example: generating a library of LODs

In some contexts, it is useful to have several LODs (Level Of Detail) of the same model: for instance a high-resolution model for close-up shots, a medium-resolution model for mid-range shots and a very low-resolution model for distant shots. In this way, we can save performance without degrading visual quality.

In this example, we use a script written in the Ruby programming language to convert hundreds of models to three different LODs each and to sort them in appropriate output folders, all in a few lines of code.

Doing this manually would be a grueling and time-consuming job that would take several hours. Thanks to the CLI, it is now a matter of minutes.

# Each model will be exported with 3 levels of detail
#   - Original quality
#   - Slight simplification (75% triangles)
#   - Heavy simplification (1% triangles)
qualities = [1, 0.75, 0.01]

# Convert the models

for quality in qualities

  # We group models in different folders depending on their simplification level
  # -> Root folder
  #    |-> output
  #      |-> quality_100
  #      |-> quality_75
  #      |-> quality_1

  outputPath = "output/quality_#{(quality * 100).round}/"

  # Generate the command for this specific level of details
  command = "Transmutr.exe convert --simplification #{quality} --output #{outputPath} models/*.obj"

  # Run the command
  process_id = Process.spawn(command)

  # Wait for the command to be finished and check if an error occurred (exit code != 0)
  process_status = Process.wait2 process_id
  if process_status[1] != 0
    print "Something wrong happened!"
  end

end

Sketchup actually supports Ruby scripting, which means that you can run such scripts directly from Sketchup if you wish to. To do so, check out the Ruby console documentation.

.bat example: generating watermarked billboard proxies

Coming soon!